samocode

Samocode - Autonomous Session Orchestrator

Explain Like I'm 10

Imagine you have a really smart helper (Claude or Codex) that can read code and write code. But it forgets everything after each conversation. So we built a system where:

1. A notebook (_overview.md) keeps track of what's been done and what's next
2. A simple loop (Python script) wakes up the AI CLI, says "read the notebook and do the next thing", then waits
3. The AI reads the notebook, does one piece of work, writes what happened back in the notebook, and goes to sleep
4. The loop wakes it up again, and repeats until the job is done
5. You (through a parent session) watch the progress and answer questions when needed

That's it. The Python loop is intentionally dumb; the child agent makes all the decisions.

---

This is a practical supervised agent loop for real repository work: research, planning, implementation, testing, and quality passes. It can handle large chunks end-to-end, but production review is still recommended.

Installation

cd ~/samocode
./install.sh          # Creates symlinks to ~/.claude/ (skills/commands/agents)
pip install -r requirements.txt

# Optional: configure environment
cp .env.example .env  # Set provider, CLI paths/models, Telegram tokens, etc.

For each project, create a .samocode file in the project root:

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

Quick Start

Start your agent session in the project directory and tell it what to do:

You: "Run samocode with dive into our authentication architecture
      and existing user models. Task: add JWT-based user authentication."

The parent session starts the worker, monitors progress, and reports back. When samocode has questions, parent relays them to you:

Parent: "Questions in _qa.md: Which auth method? Where to store tokens?"
You:    "JWT, httpOnly cookies"

Architecture

Three layers: Parent session (your chat) → Worker (Python loop) → Child AI CLI (per-iteration instances)

Parent Session         Worker (Python)          Child Agent CLI
──────────────        ────────────────         ───────────────
You talk here    →    Spawns provider CLI  →   Reads _overview.md
Monitors progress     Reads signals            Executes one action
Handles Q&A           Sends notifications      Writes signal

The Python worker is intentionally dumb: it invokes the configured provider, reads _signal.json, and decides loop/stop/pause. The child agent performs the real work.

Phases

investigation → requirements → planning → implementation → testing → quality → done
                    ↑              ↑
               HUMAN GATE     HUMAN GATE
              (answer Q&A)   (approve plan)

Phase	What happens
investigation	Explore the codebase
requirements	Q&A with human via _qa.md
planning	Create plan, wait for approval
implementation	Execute plan
testing	Verify the feature works
quality	Code review and cleanup
done	Generate summary

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
CLAUDE_TIMEOUT	1800	Claude timeout per iteration (seconds)
CODEX_PATH	codex	Path to Codex CLI
CODEX_MODEL	empty	Codex model (empty = use ~/.codex/config.toml)
CODEX_TIMEOUT	1800	Codex timeout per iteration (seconds)
TELEGRAM_BOT_TOKEN	-	Telegram notifications
TELEGRAM_CHAT_ID	-	Telegram notifications

Worker CLI

Normally started by parent, but can be run directly:

# New session
python main.py --config ~/project/.samocode --session my-task \
  --dive "current API structure" --task "Redesign the REST API"

# Continue existing session
python main.py --config ~/project/.samocode --session my-task

# Run with Codex provider for this invocation
python main.py --config ~/project/.samocode --session my-task --provider codex

Provider Notes

• Default provider is claude (SAMOCODE_PROVIDER=claude).
• Set SAMOCODE_PROVIDER=codex (or --provider codex) to run iterations with Codex.
• In Claude mode, samocode uses native Claude agent flags.
• In Codex mode, samocode injects the selected phase agent instructions into the iteration prompt.

Signal Protocol

The child agent writes _signal.json to control flow: