@tokenfactory/acc-runner

Local runner for Agent Control Center. Subscribes to ACC over Supabase Realtime; on a task assignment, spawns your local claude CLI with the rendered prompt, streams logs back, and opens a PR via gh when done.

Status: internal beta. Ships with ACC v0.2.0-internal.

Install

pnpm add -g @tokenfactory/acc-runner
# or
npm i -g @tokenfactory/acc-runner

Requires:

• Node.js 20.6+
• claude (Claude Code CLI) in $PATH
• gh (GitHub CLI) in $PATH, authenticated (gh auth login)
• git, configured with user.email
• A local clone of the target repo (default ~/work/TechArch)

Run acc-runner doctor after install to verify all the above.

Configuration

The CLI reads from environment variables — set these in your shell profile so acc-runner watch finds them.

| Variable | Required | Notes | | ------------------------- | :------: | ----------------------------------------------------- | | ACC_PUBLIC_URL | ✓ | e.g. https://acc.techarch.dev | | ACC_SUPABASE_URL | ✓ | Mirror of the SPA's VITE_SUPABASE_URL | | ACC_SUPABASE_ANON_KEY | ✓ | Same anon key the SPA uses | | ACC_REPO_PATH | | Defaults to ~/work/TechArch | | ACC_TARGET_REPO | | Defaults to tokenfactory-pvt-ltd/TechArch | | ACC_INTEGRATION_BRANCH | | Defaults to acc/integration |

Quickstart

acc-runner login          # device-code OAuth in your browser
acc-runner doctor         # verify env (all green)
acc-runner watch          # long-running; receives + executes tasks

Then, in ACC, assign a task to this machine and click Start. The CLI will:

1. Transition the task to running
2. git fetch && git checkout -B acc/T-XX-<slug>
3. Pipe the rendered prompt into claude --print
4. Stream stdout/stderr to acc.task_events (visible in the History tab)
5. git push and open a PR titled [T-XX] <task title>

Commands

acc-runner login

Device-code OAuth flow. Stores a JWT in your OS keychain (acc-runner service) and registers this machine in acc.runners.

acc-runner logout

Clears the keychain entry and marks this runner offline.

acc-runner watch

Subscribes to a Realtime broadcast channel scoped to your runner. Sends a heartbeat every 4s. Cancellation is honored via task_cancelled broadcasts (sends SIGTERM to the in-flight claude child).

acc-runner doctor

Runs every environment check and prints a green/red list. Exits 0 if all pass, 1 otherwise. Suitable for CI.

acc-runner version

Prints the CLI version and the protocol version it speaks. The server exposes a minimum-protocol-version pin at /api/runner/min-version; the CLI refuses to start if behind.

Troubleshooting

**✗ Not signed in. Run \acc-runner login` first.** — keychain entry was cleared or never created. Run acc-runner login`.

✗ keychain read/write (FAIL) — on Linux, install libsecret. On macOS, ensure your login keychain is unlocked. On Windows, run from a session with credential manager access.

✗ register_runner failed — the migration that ships the acc.register_runner RPC may not be applied to your environment yet. Coordinate with the operator who ran supabase db push.

Task transitions to failed immediately — check the History tab for the underlying error. Common causes: git fetch permission denied (push auth), claude --print returned non-zero, or the rendered prompt lacked acceptance criteria.

Security notes

• The CLI never reads or writes your git credentials, gh credentials, or Anthropic API keys. It calls binaries you already have authenticated.
• The Supabase JWT is short-lived; the CLI stores it in your OS keychain via keytar, never in plaintext on disk.
• Heartbeat interval is 4s — do not tighten this. The server expects to see it; tighter intervals consume the Realtime budget.

Runner sandbox

acc-runner spawns claude --print --dangerously-skip-permissions so non-interactive task execution doesn't hang on per-edit approval prompts. The permission boundary is enforced by acc-runner's surrounding context, not by claude itself:

• cwd boundary: the spawn is bounded to $ACC_REPO_PATH (default ~/work/TechArch). Claude cannot read or edit files outside this repo.
• allowed/forbidden globs: the task's acc.tasks.allowed and acc.tasks.forbidden arrays are rendered into the prompt; claude is instructed which paths it may or may not touch.
• operator-controlled install: the operator deliberately runs acc-runner watch on their own laptop. The runner is not a daemon and exits when the operator stops it.

For tasks that need stricter control over which tools claude may use, the runner additionally supports the --allowed-tools flag via the future task.tool_allow_list field (v0.3 follow-up).

License

Proprietary. Not for redistribution.