COdo Documentation

COMPLETE REFERENCE — v1.17.7 (2026 STABLE)

COdo is a terminal-native AI coding assistant — a fork of OpenCode with enhanced workflow management, structured skill systems, and a multi-agent orchestration layer. It runs entirely in the command line (TUI) and helps developers write code, debug issues, and ship projects through natural language conversations with AI.

COdo is built on the principle of augmented engineering intelligence. It doesn't replace the developer — it acts as a force multiplier. Every feature is designed around four core tenets:

• Context Preservation: Manage and optimize the context fed to the LLM at every step.
• Explicit over Implicit: Structured planning and specification before implementation.
• Verification & Iteration: Check at every stage — from planning to post-implementation testing.
• Composable Workflows: Break complex tasks into smaller, manageable, verifiable steps.

Quick Start

Install & Launch

Install COdo globally via npm, then run it in any project directory:

TERMINAL

$ npm install -g @codo-ai/cli
$ codo

The TUI launches immediately. No config required for a first run — COdo will prompt you to configure your AI provider on first startup.

Your First Workflow

Here's a practical workflow for starting a new feature with COdo:

Installation

Requirements

• Node.js 18+ or Bun runtime
• npm, pnpm, or yarn
• A terminal emulator (any OS)
• An AI provider API key (Anthropic, OpenAI, etc.)

Global Install via npm

BASH

$ npm install -g @codo-ai/cli

Verify Installation

BASH

$ codo --version
COdo v1.17.7

Launch

BASH

$ codo                    # in any project directory
$ codo --model claude-3-5-sonnet-20241022  # specify model

Source

The source code is available at github.com/Mosalah4351/COdo and the package on npmjs.com/@codo-ai/cli.

Configuration

Workspace Config

Project-specific configuration lives at .codo/opencode.jsonc:

JSONC

{
  "model": "claude-sonnet-4-5",
  "provider": "anthropic",
  "maxTokens": 8192,
  "contextWindow": 200000,
  "tools": {
    "webSearch": true,
    "codeExecution": true
  }
}

User Config

Global user settings live at ~/.config/COdo/. Provider API keys can be set as environment variables:

BASH

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

MCP Servers

Model Context Protocol servers are configured at .kiro/settings/mcp.json. MCP servers extend COdo with additional tools (web search, filesystem access, APIs, etc.).

Skills Locations

• .codo/skills/ — workspace-level skills (project-specific)
• ~/.codo/skills/ — global skills (available everywhere)

/workflow

THE ORCHESTRATION ENGINE

The /workflow command is the entry point to COdo's structured execution environments. It selects and activates a predefined workflow that dictates how COdo approaches your task — a high-level strategy orchestrating AI behavior.

Usage

TERMINAL

/workflow gsd       # Long-running project mode
/workflow gstack    # Virtual engineering team
/workflow speckit   # Spec-first development
/workflow vibemode  # Pure reactive mode (default)

When a workflow is selected, /skills filters to show only that workflow's skills plus universal skills. A checkmark (✓) appears next to the active workflow.

GSD — GET SHIT DONE

GSD is a terminal-native, autonomous workflow engine for long-running, complex projects. It structures work into Milestones, Slices, and Tasks. All state persists in a local .planning/ directory — making it resilient to context loss and perfect for multi-session sprints.

When you invoke /workflow gsd, COdo initializes the GSD context, asks you to define a project goal, generates PLAN.md files and tasks, and begins execution. GSD can self-correct: if a task fails, it debugs, re-plans, and continues.

The 5-Step Phase Loop

Directory Structure

.planning/
├── STATE.md          # Living project memory — read first every session
├── ROADMAP.md        # Phased execution plan
├── PROJECT.md        # Project context and goals
├── REQUIREMENTS.md   # Locked requirements
├── phases/           # Per-phase SPEC, PLAN, and SUMMARY files
│   └── 01-foundation/
│       ├── 01-SPEC.md
│       ├── 01-01-PLAN.md
│       └── 01-VERIFICATION.md
├── codebase/         # Architecture, stack, conventions
├── todos/
├── debug/
└── research/

GSD Skill Reference

Phase & Planning:

Audit, Review & QA:

Session & Context:

Utilities & Shipping:

GSTACK — VIRTUAL ENGINEERING TEAM

Gstack is Garry Tan's (Y Combinator CEO) opinionated collection of 23+ specialist role-based tools that transform COdo into a virtual engineering team. It enforces a full sprint order: Think → Plan → Build → Review → Test → Ship → Reflect.

Activating /workflow gstack gives access to specialist personas. A single developer using Gstack has access to:

• A CEO who rethinks the product and finds 10-star solutions
• An Eng Manager who locks in architecture and data flow
• A Senior Designer who catches AI-generated slop in the UI
• A QA Lead who opens real browsers and runs acceptance tests
• A Security Officer who runs OWASP + STRIDE audits
• A Release Engineer who ships clean PRs

Sprint Skills in Order

Phase	Skill	Role	What it does
THINK	/office-hours	YC Office Hours	Six forcing questions that reframe your product before any code is written.
THINK	/plan-ceo-review	CEO / Founder	Rethink the problem. Find the 10-star product hiding in the request.
THINK	/plan-eng-review	Eng Manager	Lock in architecture, data flow, diagrams, edge cases, tests.
THINK	/plan-design-review	Senior Designer	Rates design dimensions 0–10. AI slop detection. Interactive Q&A.
BUILD	/careful	Cautious Engineer	Careful implementation with explicit verification at each step.
BUILD	/design-html	Frontend Dev	Translates design specs to production-ready HTML/CSS.
REVIEW	/qa	QA Lead	Opens real browser, runs acceptance tests, logs failures.
REVIEW	/cso	Security Officer	OWASP + STRIDE security audit. Threat modelling and mitigations.
REVIEW	/investigate	Inspector	Root-cause analysis of any bug or unexpected behavior.
SHIP	/ship	Release Engineer	Prepares and ships clean PR with changelog and review summary.

SPECKIT — SPEC-FIRST DEVELOPMENT

Speckit is a toolkit for Spec-Driven Development (SDD). The core assertion: define what to build before building it. Instead of jumping straight to code, Speckit guides you through creating a formal specification that becomes the blueprint for implementation.

Speckit Command Sequence

Additional Speckit Commands

Command	Description
/speckit.clarify	Clarifies underspecified areas before planning begins
/speckit.analyze	Cross-artifact consistency and coverage analysis
/speckit.checklist	Generates custom quality checklists for your spec

VIBEMODE — PURE REACTIVE

Vibemode is the un-workflow. It strips away all structure, planning, and verification. COdo operates as a pure, reactive coding assistant — you give it a prompt, it generates code. No persistent state, no milestone tracking, no planning overhead.

When to Use Vibemode

• Rapid Prototyping & Spikes: Test concepts, write quick scripts, explore APIs
• Single-File Changes: Small, isolated fixes or generating a single function
• Non-Code Tasks: Writing docs, analysis, ad-hoc queries
• Learning & Exploration: Understanding a library or concept interactively

/goal

OUTCOME-ORIENTED DEVELOPMENT

While a workflow defines the process of how you build something, /goal defines the outcome of what you're trying to achieve. It's a mechanism for tracking high-level objectives and ensuring generated code actually moves the project toward a defined target.

Commands

Command	Description
/goal set "description"	Sets the primary focus. COdo pins this as a north star for all subsequent tasks.
/goal list	Displays all active and completed goals for the project.
/goal status	Summary of progress toward the current goal based on completed tasks and code changes.

Best Scenarios

• Keeping Focus: Prevents scope creep — COdo keeps suggestions aligned with the goal.
• Measuring Progress: Turns open-ended work into verifiable outcomes.
• Team Collaboration: Provides a shared, unambiguous definition of success.
• Generating Acceptance Criteria: COdo can derive testable criteria from the goal statement.

Example

TERMINAL

/goal set "Improve dashboard load time by 50% with code-splitting and lazy loading"

[GOAL SET] Tracking: "Improve dashboard load time by 50%..."
# COdo now prioritizes this goal in all suggestions

Compose Agent

THE MULTI-AGENT SYNTHESIZER

compose is COdo's advanced feature for orchestrating complex, multi-step tasks spanning multiple files, modules, or workflow stages. It defines a DAG (Directed Acyclic Graph) of operations — managing execution flow, handling dependencies, and parallelizing independent tasks.

Compose is particularly powerful when combined with GSD or Gstack, allowing the AI to tackle frontend, backend, and database changes simultaneously.

All 15 Compose Skills

Best Scenarios

• Complex Multi-File Refactors: When a change touches many interconnected parts.
• End-to-End Feature Implementation: Full user story from database to UI.
• Debugging Complex Issues: When a bug's root cause is buried in a chain of dependencies.
• Implementing Review Feedback: When feedback requires changes across multiple files and tests.

/scraper

INTELLIGENT DATA EXTRACTION

/scraper is COdo's tool for extracting structured and unstructured data from websites, local files, and APIs. Unlike a simple curl, it's an intelligent extraction utility that understands the context of the request and transforms raw data into a usable format for the AI.

Usage

TERMINAL

/scraper <URL or file> <what to extract>

# Examples:
/scraper https://react.dev/blog react 19 changelog
/scraper https://aws.amazon.com/ compare services with gcp
/scraper file:companies.csv enrich with employee count

Capabilities

• Web Scraping: Extracts text, links, and data from HTML pages. Handles dynamic content.
• API Consumption: Fetches from REST or GraphQL APIs and formats responses for AI.
• Local File Ingestion: Reads .md, .txt, .csv, .json, etc. into context.
• Contextual Summarization: Summarizes, extracts entities, or answers questions from scraped data.

Legal-First Approach

COdo's scraper always checks robots.txt and Terms of Service before fetching. If access is blocked, it generates a local Python script using requests/BeautifulSoup or Playwright that you can run yourself.

Decision Logic

Signal	Action
"no automated access" in ToS	STOP — inform user, suggest API alternative
CAPTCHA detected	Generate headless=False Playwright script
HTTP 403 / 429	Generate local fallback script
More than 50 pages needed	STOP — suggest bulk export or official API
Normal static HTML	Fetch and parse directly

Best Scenarios

• Research & Context: Get up to speed on library changes without leaving your terminal.
• Comparative Analysis: Side-by-side comparison of docs, features, or APIs.
• Data Enrichment: Populate CSVs or databases from public sources.
• Pre-Task Recon: Feed latest API docs into context before writing integration code.

Architecture

Stack Overview

Layer	Technology	Purpose
TUI Framework	Solid.js	Reactive terminal UI rendering
Runtime	Bun	Fast TypeScript execution
Layout Engine	Yoga	Terminal layout calculations
Database	SQLite via Drizzle ORM	Session and history persistence
Async Model	Effect-TS	Composable async operations
AI Layer	Multi-provider	Anthropic, OpenAI, local LLMs

Package Structure

packages/
├── tui/                 # Terminal UI
│   └── src/
│       ├── app.tsx      # Main entry + command registration
│       └── component/
│           ├── prompt/  # Input + slash command handling
│           └── dialog-skill.tsx  # Skills browser
│
└── opencode/            # Core engine
    └── src/
        ├── session/     # Session management (V2 resumable)
        ├── agent/       # LLM interaction layer
        └── config/      # Configuration management

Session Flow

How a message travels through the COdo engine:

User types message
    ↓
Prompt handling checks for / commands
    ↓
Command transforms input (e.g., /scraper, /workflow)
    ↓
Session.prompt() admits durable input
    ↓
SessionExecution schedules processing
    ↓
SessionRunner loads history + tools
    ↓
LLM streams response
    ↓
Tool calls executed (parallel where possible)
    ↓
Results stored (SQLite) + rendered (TUI)

Skill System

Skills are modular capabilities that extend what COdo can do. They are Markdown files with YAML frontmatter loaded into the agent's context when invoked.

Skill Format

MARKDOWN

---
name: skill-name
description: "What it does (workflow-tag)"
compatibility: "COdo (with tools)"
---

# Skill Instructions

Your skill instructions here. These become part of the agent's context
when this skill is activated...

Locations

• .codo/skills/ — workspace-level (project-specific)
• ~/.codo/skills/ — global (available in all projects)

Workflow Filtering

When a workflow is active, /skills shows only relevant skills. Filtering uses:

• Name prefix: gsd-, gstack-, speckit-
• Description tags: (gsd), (gstack), (speckit)
• Vibemode: Shows only universal skills (no workflow tags)

Synergies

The true power of COdo is realized when features are combined:

Quick Reference Matrix

Contributing

Development Setup

BASH

git clone https://github.com/Mosalah4351/COdo
cd COdo
bun install

# Run the TUI in dev mode
cd packages/opencode
bun dev

# Type-check
bun typecheck

# Run tests (must be run from packages/opencode, not repo root)
bun test

Branch Naming

• Default branch: dev (not main)
• ✅ Short, 2–3 word, hyphen-separated: session-recovery, fix-scroll
• ❌ No prefix conventions: not feat/session-recovery

Commit Style

Conventional commits: type(scope): message

feat(tui): add workflow selector with checkmarks
fix(core): resolve session timeout on long sessions
docs: update workflow reference

Contact

Questions and contributions welcome. Reach out to Mosalah4351@gmail.com or open a GitHub issue at github.com/Mosalah4351/COdo.

COdo is developed by Mohamed Salah — Computer Science student and open-source developer.