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 && pip install -r requirements.txt && samocode install

samocode install 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. From a repo checkout it symlinks (so edits go live); from a pip install it auto-detects and copies — use --copy only to force copying from a checkout. samocode never clobbers real files or foreign symlinks you own.

Re-run behavior depends on mode: symlink installs are idempotent (re-running refreshes samocode's own links), while copy installs are placed once and skipped on re-run — to update a copy install, run samocode uninstall (or delete the copied files) and install again.

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, 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