agent-r

agent-r is a local TypeScript CLI that orchestrates three Codex roles:

• strategy: read-only planning, task breakdown, self-check
• implementation: workspace-write execution for one task at a time
• checker: read-only independent completion review

The CLI persists state in SQLite plus run artifacts under .agent-r/, so a long-running effort can be resumed across invocations.

run prints the run id immediately after creating the run, before any agent work starts.

Commands

npm install
npm run dev -- run "Build a plugin system" --repo /path/to/repo

npm run build
./dist/index.js run "Build a plugin system" --repo /path/to/repo --progress human
./dist/index.js resume <run-id> --repo /path/to/repo --progress quiet
./dist/index.js status <run-id> --repo /path/to/repo --watch
./dist/index.js inspect <run-id> --repo /path/to/repo
./dist/index.js logs <run-id> --repo /path/to/repo --agent strategy

run and resume stream progress to stdout by default. Use --progress quiet to suppress it or --progress jsonl for machine-readable event lines.

Config

Place agent-r.config.toml in the target repo if you want to override defaults.

[state]
dir = ".agent-r"
max_task_attempts = 3
max_cycles_per_run = 40
max_replans = 12
max_tasks = 200
session_refresh_turns = 20

[codex]
command = "codex"

[roles.strategy]
sandbox = "read-only"
search = true

[roles.implementation]
sandbox = "workspace-write"
search = false

[roles.checker]
sandbox = "read-only"
search = false