samocode

Walk-away AI coding sessions, locally orchestrated. Drives Claude or Codex through full SDLC phases with human gates, so you can hand off multi-hour engineering work and walk away.

Quick start · How it works · vs alternatives · Examples

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
samocode install

The install command makes the bundled skills/agents available and creates the default global model-profile config without overwriting an existing one.

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 && pip install -e . && samocode install

The editable install runs the checkout's code and assets directly (worker/cli.py is the entry point), so pulling updates needs no reinstall; re-run pip install -e . only after pyproject.toml changes.

samocode install creates the user-global model config when absent, prints its path and profile table, and installs skills into both ~/.claude/skills and ~/.codex/skills. Claude-only slash commands and phase-agent files go into ~/.claude; Codex runs those same packaged phase-agent instructions through prompt injection. From a repo checkout the installer uses symlinks (so edits go live); from a pip install it auto-detects and copies — use --copy only to force copying from a checkout.

Re-running a symlink install refreshes Samocode-owned links and preserves foreign links/files. In copy mode, existing skills and commands are still treated as user-owned and skipped. Packaged Claude phase-agent files are the narrow exception: they are Samocode-managed, so a stale real file is moved to <name>.bak and refreshed. This is required to keep their model: inherit routing contract current.

samocode uninstall removes only samocode-owned symlinks. Copy-mode installs are real files samocode cannot prove it created, so they are left in place and reported as skipped — delete them manually if needed.

After a pip install, run samocode install once to make the skills, agents, and commands available to your provider (it auto-copies from a packaged install).

Upgrading from the old install.sh? Skills that were removed or renamed (e.g. adhd, gemini) leave dangling symlinks in ~/.claude/skills and ~/.codex/skills. Remove them manually: rm ~/.claude/skills/adhd ~/.codex/skills/gemini (ignore "No such file" errors).

→ See examples/ for runnable scenarios.

Use samocode skills standalone

samocode's skills (investigation, planning, implementation, quality, testing, samocode-remote for driving a worker on another host over SSH, and more) are plain Agent Skills — a SKILL.md per directory — so any compatible agent can use them without the orchestrator. Install them cross-agent in one line:

npx skills add Yuvasee/samocode

This discovers every skill in the repo and links them into your agent skill directories (~/.claude/skills, ~/.codex/skills, and others — the skills CLI is multi-agent aware). Add --copy to copy instead of symlink, or -a '*' --skill '*' -y to install all skills to all detected agents non-interactively. Preview without installing:

npx skills add Yuvasee/samocode --list

This installs skills only — not the orchestrator, agents, or slash commands. For the full samocode loop, use pip install samocode (above); for self-install of all assets from a checkout, use samocode install.

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   resolves phase/profile  executes one action
relays Q&A          validates signal/retry  writes _signal.json

Each iteration is stateless: the child CLI starts fresh, reads _overview.md, executes one action, writes a signal, and exits. The worker deterministically owns state, routing, retries, and lifecycle; the child owns the engineering decisions for that action.

Phases:

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

→ See ARCHITECTURE.md for deeper dive.

vs alternatives

Tool	Style	Session length	Human gates	Provider
samocode	External orchestrator over AI CLI	Hours–days, multi-phase	Built-in (Q&A + plan approval)	Claude / Codex
Aider	Interactive pair-programming	Minutes–hours	Per-message	Any LLM via API
Cursor Background Agents	SaaS unattended runs	Hours	Limited	Cursor's own
Devin	Closed SaaS	Hours	Limited	Cognition's own
LangGraph	Embeddable graph framework	App-defined	Code-defined	Any
CrewAI	Embeddable role-based multi-agent	App-defined	Code-defined	Any
AutoGen	Embeddable conversational multi-agent	App-defined	Code-defined	Any
Claude Agent SDK	SDK for embedding Claude agents	App-defined	Code-defined	Claude

TL;DR positioning: samocode is the open-source, local-first version of "set the AI on this task and walk away" tooling, with explicit phase separation and human gates.

Configuration

`.samocode` File (per project, all required)

Key	Description
`MAIN_REPO`	Main git repository path
`WORKTREES`	Where git worktrees are created
`SESSIONS`	Where session folders are stored

Environment Variables (`.env`, optional)

Variable	Default	Description
`SAMOCODE_PROVIDER`	`claude`	Provider: `claude` or `codex`
`CLAUDE_PATH`	`claude`	Path to Claude CLI
`CLAUDE_MODEL`	`opus`	Claude model (legacy only — ignored when a global config exists)
`CLAUDE_TIMEOUT`	`1800`	Claude timeout per iteration (seconds)
`CODEX_PATH`	`codex`	Path to Codex CLI
`CODEX_MODEL`	empty	Codex model, legacy only (empty = use `~/.codex/config.toml`)
`CODEX_TIMEOUT`	`1800`	Codex timeout per iteration (seconds)
`TELEGRAM_BOT_TOKEN`	-	Telegram notifications
`TELEGRAM_CHAT_ID`	-	Telegram notifications

Global model routing (`config.toml`)

Samocode routes every iteration through a semantic profile (light, standard, strong, max, or custom) that resolves to a concrete model and optional reasoning effort for the one selected provider. The user-global config lives at $XDG_CONFIG_HOME/samocode/config.toml (fallback ~/.config/samocode/config.toml) and is created from defaults by samocode install — it is never overwritten.

Install reports whether the file was created or preserved and shows the active defaults, for example:

Global config:
  Path: /Users/you/.config/samocode/config.toml
  Status: created
  Default: provider=claude profile=standard
  PROVIDER   PROFILE    MODEL                        EFFORT
  claude     standard   claude-sonnet-4-6            high
  claude     strong     claude-opus-4-8              high
  codex      standard   gpt-5.6-terra                medium
  codex      strong     gpt-5.6-sol                  medium

Without it, samocode runs in legacy mode using CLAUDE_MODEL/CODEX_MODEL. With a valid config, profile model/effort is authoritative and those env vars are ignored. The config is loaded once at process startup; restart Samocode after editing it. Provider precedence is --provider → SAMOCODE_PROVIDER → config default → legacy Claude. Requires Python 3.11+.

→ Full concepts, default table, profile syntax, overrides, and migration: docs/model-routing.md

Phase reference

Phase	What happens
init	Create worktree + session infrastructure
investigation	Explore the codebase via `dive` skill
requirements	Q&A with you via `_qa.md` (human gate)
planning	Create phased plan, wait for approval (human gate)
implementation	Execute plan phases iteratively
testing	Verify by fresh agent (not ad-hoc tests); read-only worktree, auto-escalates one profile rung on an environment block
quality	Ordinary review/fixes, then a Code Clarity fix loop and final Comment Hygiene cleanup (max 3 fix batches per loop)
pr-readiness	Final-head gate after regression tests; validates review debt and the clarity → hygiene provenance chain
done	Generate summary, signal complete

Signal protocol

The child agent writes _signal.json to control the loop:

Signal	Effect	Example
`continue`	Next iteration	`{"status": "continue", "phase": "implementation"}`
`done`	Stop, success	`{"status": "done", "summary": "..."}`
`blocked`	Stop, notify human	`{"status": "blocked", "reason": "...", "needs": "human_decision"}`
`waiting`	Pause for input	`{"status": "waiting", "for": "qa_answers"}`

Plan approval gate: when the planning phase signals {"status": "waiting", "for": "plan_approval"}, review the plan and then run:

samocode approve --config ~/project/.samocode --session my-task

This atomically advances the session to the implementation phase and consumes the pending signal. Do not manually edit _overview.md.

samocode approve exits with a code describing the outcome (also in --help):

Code	Meaning
0	Approved: this call advanced the phase and consumed the signal
1	Rejected: precondition failed (no gate, wrong/absent signal, etc.)
3	Lock contended: another approval is in progress; retry
4	State/IO fault: overview-write fault (may be transient), lock I/O (not retryable), or the phase moved off the gate target (an external writer may have moved it); not advanced by this call — read stderr to disambiguate
5	Advanced but signal retained: phase advanced; retained `_signal.json` is inert, cleanup optional
6	Already advanced: another approval reached the gate target; this call made no change

(argparse reserves exit code 2 for CLI usage errors.)

Testing escalation & worktree guard

The testing phase has two automatic safeguards, both fully audited:

Environment escalation. If testing blocks on the environment ({"status": "blocked", "needs": "environment"} — e.g. a missing browser binary or an unreachable dev service), the worker reruns testing once on the next-stronger profile (default strong → max) with an explicit recovery contract, instead of stopping. The provider never changes, it is one attempt per phase entry, and there is no escalation from max. Product/test failures and human_decision/error_resolution blocks stay terminal. Each escalation writes a Flow Log line, a routing log line (source=escalation), a signal-history row (status=escalation), and one Telegram notification.
Read-only worktree. Testing may not mutate tracked files. The worker snapshots HEAD and tracked status around every testing iteration; a tracked-file edit, format, or commit is rejected as Blocked: workflow_error (worktree_mutated) with a diff summary logged. The testing agent may only touch untracked/temporary/user-level files; restore any tracked file a build touched (git checkout -- <path>) before signaling. A non-git working directory skips the guard with a notice.

Check the final-polish gate

Any agent or human can re-run the exact pr-readiness -> done final-polish gate as a read-only diagnostic, without touching workflow state:

samocode check final-polish \
  --config ~/project/.samocode \
  --session my-task

It resolves the project + session, re-runs the same validate_final_polish the gate uses, prints every error one per line to stderr, and exits 0 when the gate would pass or 1 otherwise. It takes no lock, writes nothing, and has no Phase/Blocked precondition, so it is safe to run mid-session. Unlike recover final-polish --check (which inspects recoverability under the session lock), this only reports gate pass/fail; the quality and pr-readiness agents run it after every report/ledger write so vocabulary or provenance drift surfaces early instead of at the final gate.

Supported final-polish recovery

If deterministic lifecycle validation blocks a legacy session with Blocked: workflow_error, first inspect the exact state without mutation:

samocode recover final-polish \
  --config ~/project/.samocode \
  --session my-task \
  --check

If the command reports that the state is recoverable, apply the bounded recovery:

samocode recover final-polish \
  --config ~/project/.samocode \
  --session my-task \
  --apply

This is not a general phase editor. It accepts only a rejected pr-readiness -> done event whose implementation plan is complete, whose non-history final-polish evidence and current HEAD are valid, and whose only defect is missing lifecycle provenance. It snapshots the overview, signal, full history, and plan under _recovery/; leaves _signal_history.jsonl unchanged; and resets the authoritative phase to completed implementation. The next normal run must record a fresh implementation -> testing -> quality -> testing -> pr-readiness sequence.

samocode run also checks late-phase provenance before clearing signals or invoking an AI provider. Never hand-edit _overview.md, _signal.json, or _signal_history.jsonl to bypass that check.

Recover a completed quality step rejected by the iteration limit

samocode recover phase-limit --config ~/project/.samocode --session my-task --check
samocode recover phase-limit --config ~/project/.samocode --session my-task --apply
samocode run --config ~/project/.samocode --session my-task

Use the updated samocode version for both recovery and subsequent runs. This recovery supports only quality -> testing with Blocked: workflow_error, a retained continue -> testing signal, and a latest iteration_limit_exceeded rejection. It requires an exceeded quality count, valid incoming lifecycle provenance, a completed implementation plan, settled Code Clarity, passing Comment Hygiene at the clean current HEAD, and resolved review debt. It does not require a regression report that has not run yet.

Apply takes the process lease and session lock, revalidates the state, and saves control files plus quality evidence under _recovery/. An atomic overview marker commits the receipt-backed transition to testing. The original history remains byte-identical; lifecycle validation incorporates the audited transition without resetting the epoch or iteration counts. A crash before that marker leaves an inert snapshot; after it, the transition is committed even if clearing the stale signal fails (exit 5). Repeating apply after success is rejected. Missing or inconsistent committed receipts block startup.

Other phase-limit cases remain blocked; this command cannot skip incomplete work, raise limits, bypass approval, or mark a session done.

Session Structure

_sessions/26-01-08-my-task/
├── _overview.md              # Session state
├── _qa.md                    # Q&A (when waiting for human)
├── _signal.json              # Flow control
├── _logs/                    # Iteration logs (JSONL)
├── 01-08-10:00-dive-*.md     # Investigation docs
├── 01-08-11:00-plan-*.md     # Plans
└── ...                       # Other artifacts

Commands

Standalone utilities, work without the orchestrator:

Command	Description
`/dive`	Investigate a topic
`/task`	Define task with Q&A
`/create-plan`	Create implementation plan
`/do`, `/do2`	Execute task (single / dual-agent)
`/dop`, `/dop2`	Execute plan phase (single / dual-agent)
`/cleanup`	Code cleanup analysis
`/multi-review`	Multi-perspective code review
`/merge`	Guarded merge from `origin/main` or another source branch
`/prcomments`	Investigate and triage PR review comments
`/pr-readiness`	Final-head PR readiness gate before summary/merge
`/session-start`, `/session-continue`, `/session-archive`	Session management

Examples

→ examples/

These are scaffolds for the next polish phase — none exist yet.

hello-agent/ — minimal session (creates a single file)
add-feature/ — full pipeline on a small Express app
refactor/ — multi-file refactor with tests
research-only/ — investigation-only, no code changes
provider-codex/ — same task, Codex provider

Examples are scaffolds for the next polish phase — not all are present yet.

Providers

Today: Claude and Codex are supported orchestration providers. Claude uses native agent selection; Codex uses provider-specific prompt injection for the same phase agents and falls back to inline multi-pass workflows where Claude would use Task subagents. Gemini is available as a second-opinion reviewer in the /multi-review skill, not as an orchestration provider.

On the roadmap: Gemini orchestration support and deeper provider-specific agent optimizations.

Roadmap

Monitor process for crash recovery (see IDEAS.md §1)
Stall detection
Handoff pattern for context refresh
Parallel worker support
Gemini orchestration support

Contributing

Issues and PRs are welcome.

Recommended Claude Code plugins

This repo's .claude/settings.json recommends revdiff. When you open the repo in Claude Code, you'll be prompted to install it (skippable). It's used for inline diff review.

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.claude		.claude
_sessions/26-06-06-install-via-skills		_sessions/26-06-06-install-via-skills
agents		agents
commands		commands
docs		docs
skills		skills
tests		tests
worker		worker
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
.samocode		.samocode
ARCHITECTURE.md		ARCHITECTURE.md
CLAUDE.md		CLAUDE.md
IDEAS.md		IDEAS.md
LICENSE		LICENSE
README.md		README.md
TECH_DEBT.md		TECH_DEBT.md
main.py		main.py
package-lock.json		package-lock.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
uv.lock		uv.lock
workflow.md		workflow.md

Navigation Menu

Repository navigation

About

Repository files navigation

samocode

What this is

When this is useful

Quick start (60 seconds)

Use samocode skills standalone

How it works

vs alternatives

Configuration

`.samocode` File (per project, all required)

Environment Variables (`.env`, optional)

Global model routing (`config.toml`)

Phase reference

Signal protocol

Testing escalation & worktree guard

Check the final-polish gate

Supported final-polish recovery

Recover a completed quality step rejected by the iteration limit

Session Structure

Commands

Examples

Providers

Roadmap

Contributing

Recommended Claude Code plugins

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

samocode

What this is

When this is useful

Quick start (60 seconds)

Use samocode skills standalone

How it works

vs alternatives

Configuration

.samocode File (per project, all required)

Environment Variables (.env, optional)

Global model routing (config.toml)

Phase reference

Signal protocol

Testing escalation & worktree guard

Check the final-polish gate

Supported final-polish recovery

Recover a completed quality step rejected by the iteration limit

Session Structure

Commands

Examples

Providers

Roadmap

Contributing

Recommended Claude Code plugins

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`.samocode` File (per project, all required)

Environment Variables (`.env`, optional)

Global model routing (`config.toml`)