samocode

---

What this is

You give samocode a real engineering task — research a codebase, plan a refactor, implement a feature, run tests, clean up. It runs an AI CLI in a loop, walking your task through investigation → requirements → planning → implementation → testing → quality phases. It pauses to ask you questions when it needs to (_qa.md), waits for plan approval, and notifies you on Telegram when something needs your attention. You come back two hours later, your branch has the work done, with commits, tests, and a summary.

It's open-source, runs Claude or Codex as the orchestration provider (Gemini available as a second-opinion subagent), and runs locally — no SaaS, no proxy, your code never leaves your machine.

Not an engineer? See docs/eli10.md for a friendly walkthrough.

When this is useful

• "Add JWT auth to this Express app, write tests, make sure CI passes." (90 min unattended)
• "Investigate how rate-limiting currently works in this codebase, then design a new sliding-window approach." (45 min unattended)
• "Refactor this 800-line file into focused modules, keep the test suite green." (2 hours unattended)
• "Run the linter on the whole repo, fix every issue except the ones in legacy/." (30 min unattended)

If your task is "I need to think about this with the AI for 10 minutes" — use Claude / Cursor / Aider directly. samocode is for the cases where you'd rather walk away.

Quick start (60 seconds)

pip install samocode

Create .samocode in your project root:

MAIN_REPO=~/your-project
WORKTREES=~/your-project/worktrees/
SESSIONS=~/your-project/_sessions/

Run a session:

samocode \
  --config ~/your-project/.samocode \
  --session add-jwt-auth \
  --task "Add JWT-based authentication to the Express API"

samocode creates a worktree, spawns the AI CLI, walks the task through phases, and signals when it's done or needs you. Watch progress in ~/your-project/_sessions/26-XX-XX-add-jwt-auth/_overview.md.

To hack on samocode itself, clone the repo instead:

git clone https://github.com/Yuvasee/samocode ~/samocode
cd ~/samocode && ./install.sh && pip install -r requirements.txt

install.sh links samocode skills into both ~/.claude/skills and ~/.codex/skills. Claude-only slash commands and agent files are linked into ~/.claude; Codex provider runs read the phase agent files directly from the installed samocode package.

→ See examples/ for runnable scenarios.

How it works

Three layers, each with a single responsibility:

Parent session       Worker (Python)         Child AI CLI
─────────────       ───────────────         ────────────
You + your CLI  →   spawns provider CLI  →  reads _overview.md
monitors progress   reads _signal.json      executes one action
relays Q&A          decides loop/stop       writes _signal.json

Each iteration is stateless: the child CLI starts fresh, reads _overview.md, executes one action, writes a signal, exits. The Python worker is intentionally dumb — it just spawns the CLI and reads signals. All decisions happen in the child agent.

Phases:

init → investigation → requirements → planning → implementation → testing → quality → done
                            ↑              ↑
                       human gate     human gate
                       (answer Q&A)   (approve plan)

→ See ARCHITECTURE.md for deeper dive.

vs alternatives