Kody ADE — Autonomous Development Engine

The free, autonomous coding agent. Comment @kody on a GitHub issue. Get back a planned, built, verified, and reviewed PR.

Kody wraps Claude Code with a 7-stage autonomous pipeline — research, plan, build, test, review, fix, ship — with quality gates between every stage. If verify catches a bug, it gets fixed before review ever sees it. No blind retries, no context drift, no babysitting.

• Repo-aware prompts — bootstrap analyzes your codebase and generates customized instructions for every stage, not generic "write clean code" prompts
• Quality gates — runs your repo's typecheck, tests, and lint between stages + AI code review in a fresh session
• AI failure diagnosis — classifies errors as fixable/infrastructure/pre-existing before retrying
• Self-improving — learns conventions, remembers architectural decisions, discovers existing patterns
• Runs anywhere — locally from your terminal or via GitHub Actions
• Anthropic-compatible models — Anthropic natively, or other providers (MiniMax, Gemini, etc.) via LiteLLM proxy

Why Kody? → · Full comparison →

Quick Start

Prerequisites: A GitHub repo + an Anthropic API key (or compatible provider key).

For local CLI usage, you also need: Node.js >= 22, Claude Code CLI, GitHub CLI, git.

1. Set up GitHub

Add your API key as a secret — via GitHub web UI or CLI:

gh secret set ANTHROPIC_API_KEY --repo owner/repo

Then in GitHub: Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"

2. Initialize

Copy the workflow template to .github/workflows/kody.yml and add a kody.config.json to your repo root. Or use the CLI to auto-generate both:

npm install -g @kody-ade/engine
cd your-project
kody-engine init

3. Bootstrap

Create a new GitHub issue (e.g., "Setup Kody") and comment:

@kody bootstrap

This analyzes your codebase with an LLM and generates:

• Project memory (.kody/memory/ — architecture and conventions)
• Customized step files (.kody/steps/ — repo-aware prompts for every stage)
• Tools template (.kody/tools.yml — configure external tools like Playwright, see Tools)
• GitHub labels for lifecycle tracking (14 labels)

4. Use

Comment on any GitHub issue:

@kody

Kody picks up the issue and works through the pipeline autonomously:

You'll see labels updating in real-time, progress comments at each stage, and a pipeline summary when done:

The result is a PR with a rich description, passing quality checks, and Closes #N:

If the task is HIGH-risk, Kody pauses after planning and asks for approval before writing code.

Switch to a different model (optional)

// kody.config.json
{ "agent": { "provider": "minimax" } }

# .env
MINIMAX_API_KEY=your-key-here   # or OPENAI_API_KEY, GEMINI_API_KEY, etc.

Kody auto-starts the LiteLLM proxy. Full LiteLLM guide →

Which command should I use?

flowchart TD
    Start(("What do you\nneed to do?")):::start

    Start --> NewIssue{"New issue\n→ PR?"}
    Start --> ExistingPR{"Existing\nPR?"}
    Start --> Question{"Have a\nquestion?"}
    Start --> Setup{"Setup /\nOnboarding?"}

    Question --> Ask["**@kody ask**\nResearch codebase and reply\nNo code changes, no PRs"]:::cmd

    NewIssue -->|"Simple/medium"| Kody["**@kody**\nFull pipeline: taskify → plan →\nbuild → verify → review → ship"]:::cmd
    NewIssue -->|"Complex multi-area"| Decompose["**@kody decompose**\nParallel sub-tasks: analyze →\nsplit → parallel build → merge → ship"]:::cmd

    ExistingPR --> PRWhat{"What's wrong?"}

    PRWhat -->|"Need a code review"| Review["**@kody review**\nStandalone PR review with\nstructured findings + verdict"]:::cmd
    PRWhat -->|"Human gave feedback"| Fix["**@kody fix**\nRe-run from build with\nPR feedback as context"]:::cmd
    PRWhat -->|"CI is failing"| FixCI["**@kody fix-ci**\nFetch CI logs, diagnose,\nand push a fix"]:::cmd
    PRWhat -->|"Merge conflicts"| Resolve["**@kody resolve**\nMerge default branch,\nAI-resolve conflicts, verify"]:::cmd
    PRWhat -->|"Previous run failed\nor was paused"| Rerun["**@kody rerun**\nResume from failed/paused stage\n*--from stage* to pick stage"]:::cmd

    Setup -->|"First time"| Init["**kody-engine init**\nGenerate workflow + config"]:::setup
    Init --> Bootstrap
    Setup -->|"After major refactor"| Bootstrap["**@kody bootstrap**\nRegenerate memory +\nstep files + labels"]:::setup

    Kody -.->|"Paused with\nquestions or\nrisk gate?"| Approve["**@kody approve**\nResume after pause"]:::cmd

    classDef start fill:#1a1a2e,stroke:#e94560,color:#fff,stroke-width:2px
    classDef cmd fill:#0f3460,stroke:#53d8fb,color:#fff,stroke-width:1px
    classDef setup fill:#1a1a2e,stroke:#e9b44c,color:#fff,stroke-width:1px

Commands

| Command | What it does | |---------|-------------| | @kody | Run full pipeline on an issue | | @kody decompose | Parallel sub-tasks for complex issues — analyze, split, build in parallel, merge, verify, review, ship (details) | | @kody compose | Retry merge + verify + review + ship after a decompose build succeeded | | @kody review | Review any PR — structured findings + GitHub approve/request-changes (falls back to comment if self-review blocked) | | @kody fix | Re-run from build with human PR feedback + Kody's review as context | | @kody fix-ci | Fix failing CI checks (auto-triggered with loop guard) | | @kody resolve | Merge default branch into PR, AI-resolve conflicts, verify, push | | @kody rerun | Resume from failed or paused stage | | @kody rerun --from <stage> | Resume from a specific stage | | @kody ask | Research the codebase and reply with an answer — no code changes, no PRs | | @kody approve | Resume after questions or risk gate | | @kody bootstrap | Regenerate project memory and step files |

kody-engine init [--force]          # Setup repo: workflow + config + watch
kody-engine bootstrap [--force] [--provider=claude --model=opus-4-6]  # Generate memory + step files + labels + activity log
kody-engine run --issue-number 42 --local --cwd ./project
kody-engine run --task "Add retry utility" --local
kody-engine review --pr-number 42   # Standalone PR review
kody-engine fix --issue-number 42 --feedback "Use middleware pattern"
kody-engine fix-ci --pr-number 42
kody-engine resolve --pr-number 42   # Merge + resolve conflicts
kody-engine --ask "How does auth work?" # Ask a question about the codebase
kody-engine decompose --issue-number 42  # Parallel sub-tasks for complex issues
kody-engine compose --task-id <id>  # Retry compose after decompose
kody-engine rerun --issue-number 42 --from verify
kody-engine watch [--dry-run]       # Run health monitoring locally
kody-engine serve                  # Start LiteLLM proxy + dev server (infra only)
kody-engine serve claude           # Above + launch Claude Code CLI
kody-engine serve vscode           # Above + launch VS Code with proxy routing

Full CLI reference with all flags and options →

Key Features

• Repo-Aware Step Files — auto-generated prompts with your repo's patterns, gaps, and acceptance criteria (details)
• Standalone PR Review — @kody review on any PR for structured code review with GitHub approve/request-changes (details)
• Shared Sessions — stages share Claude Code sessions, no cold-start re-exploration (details)
• Risk Gate — HIGH-risk tasks pause for human approval before building (details)
• AI Failure Diagnosis — classifies errors as fixable/infrastructure/pre-existing/abort before retry (details)
• Question Gates — asks product/architecture questions when the task is unclear (details)
• Auto Fix-CI — CI fails on a PR? Kody fetches logs, diagnoses, and pushes a fix (details)
• Parallel Decomposition — complex tasks auto-split into independent sub-tasks that build in parallel, then merge and verify (details)
• Pattern Discovery — searches for existing patterns before proposing new ones (details)
• Decision Memory — architectural decisions extracted from reviews persist across tasks (details)
• Auto-Learning — extracts coding conventions from each successful run (details)
• Retrospective — analyzes each run, identifies patterns, suggests improvements (details)
• Kody Watch — periodic health monitoring: pipeline health, security scanning, config validation every 30 min (setup guide)
• Anthropic-Compatible Models — route through LiteLLM to use other providers like MiniMax, Gemini, etc. (setup guide · model test results)

Local Development (kody serve)

Start the same infrastructure that GitHub Actions uses, but locally and persistent:

kody-engine serve              # LiteLLM proxy + dev server + project memory
kody-engine serve claude       # Above + Claude Code CLI session
kody-engine serve vscode       # Above + VS Code with proxy routing

What it does:

• Reads kody.config.json and starts the LiteLLM proxy with your model routing (e.g., MiniMax, OpenAI)
• Adds Claude model aliases so Claude Code works seamlessly through the proxy
• Starts your dev server if configured
• Writes .claude/kody-context.md with project memory + passive learning instructions
• Launches Claude Code CLI (with --dangerously-skip-permissions and full TTY) or VS Code with ANTHROPIC_BASE_URL set

Options:

kody-engine serve claude --provider minimax --model MiniMax-M1   # Override model
kody-engine serve --cwd /path/to/project                        # Target different project

Memory is shared: anything you ask Claude Code to remember (via .kody/memory/) is picked up by pipeline runs too.

Architecture

flowchart TB
    subgraph trigger ["Trigger"]
        direction LR
        Comment["@kody comment\non GitHub issue"]
        Dispatch["workflow_dispatch\n(manual)"]
        CLI["kody-engine run\n(local CLI)"]
    end

    subgraph ci ["GitHub Actions"]
        direction LR
        Parse["**parse**\nValidate author\nExtract mode + task ID"]
        Orchestrate["**orchestrate**\nCheckout, install deps,\nstart LiteLLM proxy"]
        Parse --> Orchestrate
    end

    Entry["**entry.ts**\nPreflight checks → fetch issue →\ncreate runners → build context"]

    subgraph pipeline ["Pipeline  (pipeline.ts)"]
        direction TB

        subgraph explore ["Session: explore"]
            direction LR
            Taskify["**1 Taskify**\nClassify, scope,\ndetect complexity\n*→ task.json*"]
            Plan["**2 Plan**\nTDD plan with\ndeep reasoning\n*→ plan.md*"]
            Taskify --> Plan
        end

        subgraph build_session ["Session: build"]
            direction LR
            Build["**3 Build**\nImplement via\nClaude Code tools"]
            Autofix["**Autofix**\nAI-diagnosed\nerror fixes"]
            ReviewFix["**6 Review-Fix**\nFix Critical +\nMajor findings"]
        end

        subgraph verify_loop ["Quality Gate"]
            Verify["**4 Verify**\ntypecheck + tests + lint"]
            Diagnose{"Fail?"}
            Verify --> Diagnose
            Diagnose -->|"fixable"| Autofix
            Autofix --> Verify
            Diagnose -->|"infra/pre-existing"| Skip["Skip\n(mark passed)"]
            Diagnose -->|"abort"| Abort["Stop pipeline"]
        end

        subgraph review_session ["Session: review  (fresh — no build bias)"]
            Review["**5 Review**\nPASS/FAIL verdict\n+ findings\n*→ review.md*"]
        end

        Ship["**7 Ship**\nPush branch → create PR\n→ comment on issue"]

        explore --> build_session
        Build --> verify_loop
        Skip --> review_session
        Diagnose -->|"pass"| review_session
        review_session -->|"FAIL"| ReviewFix
        ReviewFix -->|"retry review\n(max 2)"| review_session
        review_session -->|"PASS"| Ship
    end

    subgraph support ["Support Systems"]
        direction LR
        Memory["**.kody/memory/**\narchitecture.md\nconventions.md\nobserver-log.jsonl"]
        Steps["**.kody/steps/**\nRepo-customized\nprompts per stage"]
        State["**status.json**\nStage states +\nsession IDs"]
    end

    subgraph outputs ["Outputs"]
        direction LR
        PR["Pull Request\nwith Closes #N"]
        Labels["GitHub Labels\nkody:planning → kody:done"]
        Artifacts["Task Artifacts\n.kody/tasks/id/"]
        Learn["Auto-Learn\n+ Retrospective"]
    end

    QuestionGate{"Questions?\nPause for\nhuman input"}
    RiskGate{"HIGH risk?\nPause for\napproval"}

    Comment --> ci
    Dispatch --> Orchestrate
    CLI --> Entry
    Orchestrate --> Entry
    Entry --> pipeline

    Taskify -.-> QuestionGate
    Plan -.-> RiskGate
    QuestionGate -.->|"@kody approve"| Plan
    RiskGate -.->|"@kody approve"| Build

    pipeline <-..-> support
    Ship --> outputs

Full architecture docs →

Documentation

Understand Kody: About · Architecture · Tech Stack · Features · Pipeline · Comparison

Set up & use: CLI · Configuration · Bootstrap · Decompose · Tools · Watch · LiteLLM

Reference: FAQ · Model Compatibility

Demo Video

The demo video is auto-recorded with Playwright from a real pipeline run:

npx tsx demo/record.ts                    # record (opens browser)
ffmpeg -i demo/videos/kody-demo.webm \
  -c:v libx264 -crf 20 demo/videos/kody-demo.mp4  # convert
cp demo/videos/kody-demo.{webm,mp4} docs/assets/   # deploy

Terminal GIFs can also be generated using VHS — tape files are in assets/tapes/.

License

MIT