cruo-agent

cruo-agent

Run a Cruo agent. It watches your board, picks up the cards you assign it, and works them — on your machine, under your own Claude account.

npx cruo-agent login cruo_pat_…    # the token Cruo showed you once
npx cruo-agent --dry-run           # what would it pick up? starts no model
npx cruo-agent                     # let it work

What this actually is

Three things people tend to run together, kept apart because they fail differently:

• The agent is a member of your workspace — a row and a token. It signs in to nothing, and nothing runs because it exists.
• The supervisor is this program. It watches the board with a plain database query, so sitting idle costs nothing, and starts a harness when there is work.
• The harness is Claude Code, started fresh for one card and gone when that card is done. Nothing carries over between cards but the board itself.

Cruo runs no model of its own and never bills you for inference.

Getting a token

Cruo → Settings → Members → Add an agent. The token is shown once; Cruo stores a hash. If you lose it, issue another from the key button on its row.

Then assign the agent a card. That is the whole of the setup — an agent is a member, so it appears in the assignee list like anyone else.

Where the token comes from

In order: CRUO_TOKEN in the environment, then --token, then whatever cruo login stored in ~/.cruo/config.json (mode 0600).

There is no cruo <token> form on purpose. A credential in a positional argument shows up in ps output, where every other user on the machine can read it, and in your shell history, where it stays. --token is there for a CI runner that injects secrets its own way, and it warns.

Letting it write code

By default the harness gets the board and nothing else, which is right for an agent whose work is judgement over your issues. An agent that writes code needs a checkout and the tools to use it:

npx cruo-agent --worktree --allow 'mcp__cruo,Read,Glob,Grep,Edit,Write,Bash(git:*)'

--worktree gives every card its own checkout, cut fresh from origin/main — never the tree you are working in, and never whatever you have half-finished. It carries tracked files only, so an agent cannot read a .env you have not committed. When the run ends the checkout is deleted and the branch survives.

Run it from the repository the agent should work on. If that repository needs installing before its tests will run, add --prepare 'npm ci' or whatever your equivalent is — a fresh checkout has your source and none of your dependencies.

Common options

flag
--once	one pass, then exit
--dry-run	show what it would pick up; starts no model
--limit <n>	work at most n issues this pass
--interval <seconds>	how often to poll (default 20)
--worktree	a checkout per card
--allow <tools>	what the harness may use
--push	publish the branch after a run that commits
--harness-timeout <seconds>	kill a run that wedges (default 600)
--max-attempts <n>	give up on a card after n unproductive runs (default 3)

The full list, and what each is for: https://cruo.space/agents

Running it somewhere that is not your laptop

The same command works on a server, and that machine needs no privileged access to Cruo: the supervisor trades its token for a short-lived session, so the only secret on the box is the agent's own token — scoped to one workspace, in one product, revocable from Settings.

The harness still runs under your Claude account, on that box.

The name

The package is cruo-agent; the command it installs is cruo. npm refuses the bare name as too close to cron and crc, and a bin's name is independent of its package's — so npm i -g cruo-agent gives you cruo, and npx cruo-agent works without one.