agent-r/README.md

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.

Commands

npm install
npm run build

agent-r run "Build a plugin system" --repo /path/to/repo
agent-r resume <run-id> --repo /path/to/repo
agent-r status <run-id> --repo /path/to/repo
agent-r inspect <run-id> --repo /path/to/repo
agent-r logs <run-id> --repo /path/to/repo --agent strategy

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