Sago: The project planner for AI coding agents

You describe what you want in markdown. Sago generates a structured plan. Your coding agent (Claude Code, Cursor, Aider, etc.) builds it.

Sago is a planning and orchestration tool, not a coding agent. It turns your project idea into a structured, verified plan — then gets out of the way and lets a real coding agent do the building.

You → sago init → sago plan → coding agent builds Phase 1 → sago replan → coding agent builds Phase 2 → ...

Why? AI coding agents (Claude Code, Cursor, etc.) are excellent at writing code but bad at planning entire projects from scratch. They lose track of requirements, skip steps, and produce inconsistent architectures. Sago solves the planning problem so the coding agent can focus on what it's good at — writing code.

• Quick start
• How it works
• Using with Claude Code
• Using with other agents
• Mission control
• Trace dashboard
• Commands
• Configuration
• Task format
• Why sago
• Sago vs GSD
• Development
• Acknowledgements
• License

pip install -e .

Requires Python 3.11+.

Create a .env file (or export the variables):

LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
LLM_API_KEY=sk-your-key-here

Any LiteLLM-supported provider works — OpenAI, Anthropic, Azure, Gemini, etc. The LLM is used for plan generation only.

For ChatGPT subscription access via LiteLLM, use the ChatGPT route model (OAuth device flow, no API key required):

LLM_PROVIDER=chatgpt
LLM_MODEL=chatgpt/gpt-5.3-codex

sago init

Sago prompts for a project name and description. It generates the project scaffold:

my-project/
├── PROJECT.md          ← Vision, tech stack, architecture
├── REQUIREMENTS.md     ← What the project must do
├── PLAN.md             ← Atomic tasks with verify commands (after sago plan)
├── STATE.md            ← Progress log (updated as tasks complete)
├── CLAUDE.md           ← Instructions for the coding agent
├── IMPORTANT.md        ← Rules the coding agent must follow
└── .planning/          ← Runtime artifacts (cache, traces)

If you provide a description during init, the AI generates PROJECT.md and REQUIREMENTS.md for you. Otherwise, fill them in yourself.

sago plan

Sago reads your PROJECT.md and REQUIREMENTS.md, detects your environment (Python version, OS, platform), and generates a PLAN.md with:

• Atomic tasks grouped into phases
• Task-level dependency ordering via depends_on
• Verification commands for each task
• A list of third-party packages needed
• Semantic validation (duplicate IDs, dependency cycles, missing fields, etc.)

Sago validates the plan automatically — if it finds structural errors (cycles, invalid dependencies, missing task IDs), it retries once with error feedback. You're shown validation results and asked to accept or reject before the plan is written.

Point your coding agent at the project and tell it to follow the plan:

Claude Code:

cd my-project
claude
# Claude Code reads CLAUDE.md automatically and follows the plan

Cursor / Other agents: Open the project directory. The agent should read PLAN.md and execute tasks in order, running each <verify> command to confirm the task is done.

In a separate terminal, launch mission control:

sago watch

This opens a live dashboard in your browser that shows task completion, file activity, and phase progress — updated every second as your coding agent works through the plan.

After your coding agent finishes a phase, run the phase gate:

sago replan

This reviews the completed work, shows findings (warnings, suggestions), saves the review to STATE.md, shows actionable recommendations (e.g. "task failed 2+ times — consider replanning"), and optionally lets you adjust the plan before the next phase. Just press Enter to skip replanning if the review looks good.

sago status              # quick summary + recommendations
sago status -d           # detailed per-task breakdown
sago lint-plan           # validate plan without running anything

┌─────────────────────────────────────────────────────┐
│  1. SPEC                                            │
│     You write PROJECT.md + REQUIREMENTS.md          │
│     (or describe your idea and sago generates them) │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  2. PLAN (sago)                                     │
│     Sago calls an LLM to generate PLAN.md:          │
│     - Atomic tasks with verification commands       │
│     - Task-level dependencies (depends_on DAG)      │
│     - Environment-aware (Python version, OS)        │
│     - Lists required third-party packages           │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  3. BUILD (your coding agent)                       │
│     Claude Code / Cursor / Aider executes tasks:    │
│     - Runs sago next to get the next task           │
│     - Follows <action> instructions                 │
│     - Runs <verify> commands                        │
│     - Runs sago checkpoint to record progress       │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  4. REVIEW (sago replan)                            │
│     Between phases, reviews completed work:         │
│     - Runs ReviewerAgent on finished phases         │
│     - Shows warnings, suggestions, issues           │
│     - Saves review to STATE.md                      │
│     - Optionally updates the plan with feedback     │
└──────────────────────┬──────────────────────────────┘
                       ▼
              (repeat 3→4 for each phase)
                       ▼
┌─────────────────────────────────────────────────────┐
│  5. TRACK (sago)                                    │
│     sago status shows progress                      │
│     Dashboard shows real-time updates               │
└─────────────────────────────────────────────────────┘

Sago is the project manager. Your coding agent is the developer. The markdown files are the contract between them.

Sago generates a CLAUDE.md file during sago init that Claude Code reads automatically. It tells Claude Code how to follow the plan, execute tasks in order, and record progress via sago checkpoint.

sago init my-project --prompt "A weather dashboard with FastAPI and PostgreSQL"
cd my-project
sago plan
claude

Claude Code picks up CLAUDE.md on startup and understands the task format. The agent runs sago next to get its assignment, executes it, then calls sago checkpoint to record progress. When all tasks in a phase are done, sago automatically detects it and prompts the agent to run sago replan.

sago init my-project --prompt "A weather dashboard with FastAPI and PostgreSQL"
cd my-project
sago plan

Copy the sago workflow instructions into Cursor's rules file so the agent knows how to work:

cp CLAUDE.md .cursorrules

Then open the project in Cursor and use Agent mode. Tell it:

"Run sago next to get the next task. Execute it, run the verify command, then run sago checkpoint to record progress. Repeat."

Cursor's agent will follow the plan the same way Claude Code does.

sago init my-project --prompt "A weather dashboard with FastAPI and PostgreSQL"
cd my-project
sago plan

Feed the plan and project context to Aider:

aider --read PLAN.md --read PROJECT.md --read REQUIREMENTS.md

Then tell it which task to work on:

"Execute task 1.1 from PLAN.md. Create the files listed, follow the action instructions, then run the verify command."

Work through tasks one at a time since Aider works best with focused, single-task instructions.

Sago's output is just markdown files. Any coding agent that can read files and run commands works. The agent needs to:

1. Read PROJECT.md — the project vision, tech stack, and architecture
2. Read REQUIREMENTS.md — what the project must do
3. If PLAN.md has a <dependencies> block, install those packages first
4. Run sago next to get the next task — it shows the task details, dependencies, and context
5. Run each task's <verify> command — it must exit 0 before moving on
6. Run sago checkpoint <task_id> after each task to record progress in STATE.md
7. Repeat from step 4 until all tasks are complete

The CLAUDE.md file generated by sago init contains these instructions in a format most agents understand. Rename or copy it to whatever your agent expects (.cursorrules, .github/copilot-instructions.md, etc.).

While your coding agent builds the project, run mission control in a separate terminal:

sago watch                   # launch dashboard (auto-opens browser)
sago watch --port 8080       # use a specific port
sago watch --path ./my-app   # point to a different project

The dashboard shows:

• Overall progress — progress bar with task count and percentage
• Phase tree — every phase and task with live status icons (done, failed, pending)
• File activity — new and modified files detected in the project directory
• Dependencies — packages listed in PLAN.md
• Per-phase progress bars — at a glance, which phases are done

It polls STATE.md every second — as sago checkpoint records task results, the dashboard updates automatically. No extra dependencies (stdlib HTTP server + os.stat).

To view the planning trace after sago plan:

sago trace                   # opens dashboard for the last trace
sago trace --demo            # sample data, no API key needed

sago init                            # interactive: prompts for name + description
sago init [name]                     # quick scaffold with templates
sago init [name] --prompt "desc"     # generate spec files from a prompt via LLM
sago init -y                         # non-interactive, all defaults
sago plan                            # generate PLAN.md from requirements
sago plan --yes                      # auto-accept plan without confirmation
sago checkpoint 1.1 --notes "done"   # record task completion in STATE.md
sago checkpoint 1.2 -s failed -n "import error"  # record failure
sago checkpoint 2.1 -d "Chose JWT"   # record with key decision
sago next                            # show next actionable task with full details
sago lint-plan                       # validate PLAN.md for structural/semantic issues
sago lint-plan --strict              # treat warnings as errors
sago lint-plan --json                # machine-readable JSON output
sago replan                          # phase gate: review completed work, optionally update plan
sago watch                           # launch mission control dashboard
sago watch --port 8080               # use a specific port
sago status                          # show project progress + recommendations
sago status -d                       # detailed per-task breakdown
sago trace                           # open dashboard for the last trace
sago trace --demo                    # open dashboard with sample data

Create a .env file in your project directory:

LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
LLM_API_KEY=your-key-here
LLM_TEMPERATURE=0.1
LLM_MAX_TOKENS=4096
LOG_LEVEL=INFO

Any LiteLLM-supported provider works. Set LLM_MODEL to the provider's model identifier (e.g., claude-sonnet-4-5-20250929, gpt-4o, gemini/gemini-2.0-flash).

ChatGPT subscription mode is also supported through LiteLLM:

LLM_PROVIDER=chatgpt
LLM_MODEL=chatgpt/gpt-5.3-codex
# No LLM_API_KEY required; LiteLLM handles OAuth device flow and token storage.

Tasks in PLAN.md use XML inside markdown:

<phases>
  <dependencies>
    <package>flask>=2.0</package>
    <package>sqlalchemy>=2.0</package>
  </dependencies>

  <review>
    Review instructions for post-phase code review...
  </review>

  <phase name="Phase 1: Setup">
    <task id="1.1">
      <name>Create config module</name>
      <files>src/config.py</files>
      <action>Create configuration with pydantic settings...</action>
      <verify>python -c "import src.config"</verify>
      <done>Config module imports successfully</done>
    </task>

    <task id="1.2" depends_on="1.1">
      <name>Add database layer</name>
      <files>src/db.py</files>
      <action>Create database module using config...</action>
      <verify>python -c "import src.db"</verify>
      <done>Database module imports successfully</done>
    </task>
  </phase>
</phases>

• <dependencies> — third-party packages needed, with version constraints
• <review> — instructions for reviewing each phase's output
• <task> — atomic unit of work with files, action, verification, and done criteria
• depends_on — optional attribute on <task> listing comma-separated task IDs this task depends on. Omit it to depend on all prior tasks in the phase (sequential by default). Use it to express that a task has no dependencies or only specific ones, enabling parallel execution of independent tasks.

The planning problem. AI coding agents are great at writing code for a well-defined task. But ask them to build an entire project from a vague description and they lose track of requirements, skip steps, pick incompatible dependencies, and produce inconsistent architectures. The gap isn't in code generation — it's in project planning.

Sago fills that gap. It uses an LLM to generate a structured, verified plan with atomic tasks, dependency ordering, and environment-aware dependency suggestions. Then it hands off to whatever coding agent you prefer.

Model-agnostic planning. Sago uses LiteLLM for plan generation, so you're not locked into any provider. Use OpenAI, Anthropic, Azure, Gemini, Mistral — whatever gives you the best plans.

Agent-agnostic execution. Sago doesn't care what builds the code. Claude Code, Cursor, Aider, Copilot, a human — anything that can read markdown and follow instructions. Sago generates the plan; you choose the builder.

Spec-first, always. Every sago project has a reviewable spec (PROJECT.md, REQUIREMENTS.md) and a reviewable plan (PLAN.md) before any code is written. You see exactly what will be built and can adjust before spending time or tokens on execution.

GSD (Get Shit Done) is a great project that inspired sago. Both solve the same core problem — AI coding agents are bad at planning — but they take different approaches.

When to use GSD: You use Claude Code exclusively and want a fully automated pipeline — research, plan, execute, verify — all within Claude Code's sub-agent system. GSD's context rotation (fresh windows per task) is its killer feature for large projects.

When to use sago: You want to use different coding agents (or switch between them), want to use a non-Claude LLM for planning, or prefer an explicit human-in-the-loop workflow where you review the plan and gate phase transitions yourself. Sago is the project manager; you pick the developer.

pip install -e ".[dev]"       # install with dev dependencies

pytest                        # run all tests
pytest tests/test_parser.py -v              # single file
pytest tests/test_parser.py::test_name -v   # single test

ruff check src/               # lint
black src/ tests/             # format
mypy src/                     # type check (strict mode)
skylos src/                   # dead code detection

This project was vibecoded with Claude Code.

Sago takes inspiration from:

• GSD (Get Shit Done) — spec-driven development and sub-agent orchestration for Claude Code
• Claude Flow — multi-agent orchestration platform with wave-based task coordination

Dead code is kept in check by Skylos.

Apache 2.0. See LICENSE.