Work with coding agents from the terminal
A terminal coding agent such as Claude Code or Codex can take a Kanera card from pick-up to done: read the card, announce that it is working, report progress, flag when it needs a person, and mark the card complete. This guide sets that loop up with the Kanera CLI, which works for any agent that can run shell commands.
If your agent can connect to Kanera's hosted MCP server, use that instead. Paste the setup prompt from Connect Kanera to your AI agent and the agent gets the same tools over OAuth, with its work labelled via <agent>. The CLI is the route for an agent that has a shell but no MCP connection. The loop below is the same either way; only the transport changes.
Install and sign in
Install the CLI once on the machine the agent runs on. It needs Node 22 or newer.
npm install --global @kanera/cli
kanera auth login
kanera auth login prints a link and a code and opens the link in your browser. Approve the request there after checking the code matches, and the CLI stores a sign-in that renews itself. For an agent that runs unattended, such as in CI, use kanera auth login --with-api-key with a key from Profile settings -> API keys instead, and choose Read-only if it should not change anything. Then confirm what the agent will be able to do:
kanera whoami # the user and the credential's scope
kanera doctor # credentials, connectivity, and the API address in use
For a sandbox or CI job, skip the stored profile and set KANERA_API_KEY instead. See Kanera CLI for named profiles and self-hosted addresses.
Read-only or write
Choose the key's scope for the job, not for convenience.
- Read-only suits an agent that only needs to find and read work: triaging, summarising a card before you start, or answering "what is on my plate?". Kanera refuses every change at the API, whatever the agent tries.
- Write is needed for everything else on this page: opening a run, commenting, and completing cards. Kanera still checks your role on each board, so the agent cannot change a board where you are an Observer.
A refused write exits with code 4, distinct from an ordinary failure, so the agent can stop and tell you rather than retry. Agent security covers how to scope an agent's access.
Install the agent instructions
kanera setup writes instructions that teach the agent how to use the CLI safely: check the key's scope first, discover commands with kanera commands --json instead of guessing, use --quiet or --json when parsing output, and treat destructive tools as needing an explicit request.
kanera setup claude # writes .claude/skills/kanera/SKILL.md in the current directory
kanera setup claude --global # writes ~/.claude/skills/kanera/SKILL.md for every project
kanera setup codex # adds a Kanera section to AGENTS.md in the current directory
kanera skill # prints the skill document, for any other agent
setup claudeinstalls Kanera's Agent Skill, which Claude Code loads when Kanera comes up. It will not overwrite an existingSKILL.md; re-run with--forceto replace it after upgrading the CLI.setup codexcreatesAGENTS.mdif it does not exist, or appends a short Kanera section. It is safe to re-run: when the file already documents Kanera, it changes nothing.kanera setup agentsdoes the same, for any agent that readsAGENTS.md.
The CLI's instructions cover reading and changing work. They do not tell the agent to open runs, so add the project instructions below if you want that.
The work loop
Each step below is a command the agent runs. Card arguments accept a key such as MKT-42, a card id, or a card URL.
1. Pick up work
kanera work --json # your assigned work across every board
kanera work --filters.q "checkout" --json # narrowed by card text
kanera priorities --json # your ranked Up next queue
kanera card MKT-42 --json # the card itself: description, checklists, fields
kanera card history MKT-42 --json # its activity and comments
kanera priorities is useful when you keep an Up next queue: the agent can take the top card rather than choosing for itself.
2. Open a run
Before starting multi-step work, check that nobody else is on the card, then open a run:
kanera runs MKT-42 --json
RUN_ID=$(kanera run start MKT-42 "Fixing the checkout rounding bug" \
--externalUrl "https://github.com/acme/shop/pull/318" \
--quiet | jq -r .id)
The card tile now shows a live chip saying the agent is working, and card detail shows the run with its title and progress note. --externalUrl is optional; give it the pull request, branch, or session log a person can open. See Agent runs and attribution for what everyone else sees.
3. Report progress
Update the run as the work moves. Every update is also a heartbeat, and a run that goes fifteen minutes without one is marked stalled, so on long tasks the agent should update at least every ten minutes.
kanera run update "$RUN_ID" --summary "Reproduced; fix drafted, running the test suite"
The run summary is a status line that each update replaces. For anything the team should keep, comment on the card:
kanera comment MKT-42 "Root cause: totals were rounded per line, not per order. Fix in PR 318."
Comments are not idempotent. If a comment command fails ambiguously, check the card's comments before retrying, or pass the same --idempotencyKey UUID on the retry.
4. Flag a blocker
When the agent needs a decision, an approval, or access it does not have, mark the run blocked and say what it needs:
kanera run update "$RUN_ID" --status blocked \
--summary "Need a decision: round half up or half even?"
kanera comment MKT-42 "Blocked: should order totals round half up or half even? Both are drafted in PR 318."
The chip turns amber and card detail shows Waiting on you. Marking a run blocked does not notify anyone by itself, which is why the comment matters: it reaches the card's watchers and assignees. When the agent resumes, it sets the run back to --status running.
5. Finish
Close the run with an outcome, then complete the card:
kanera run done "$RUN_ID" "Merged PR 318; rounding is per order and the suite is green."
kanera card done MKT-42
The run's closing summary becomes a finished row in the card's activity. If the work did not land, end the run with --status failed or --status cancelled and a summary saying why, and leave the card open. An ended run cannot be changed; if work resumes later, start a new run.
To move the card to another list rather than completing it, use kanera card move; run kanera help cards.move for its anchor arguments.
Who the work is attributed to
How the CLI signed in decides how the agent's work is labelled:
| Credential | Comments and card changes | Run chip label |
|---|---|---|
Browser sign-in with --agent (kanera auth login --agent "Claude Code") | As you, via Claude Code (Kanera CLI on computer name) | Claude Code (Kanera CLI on computer name) |
Browser sign-in without --agent | As you, via Kanera CLI (computer name) | Kanera CLI (computer name) |
| Personal API key | As you, with no via badge | API client |
| Workspace or board API key | As the key's name | The key's name |
A browser sign-in is an OAuth device connection, so the agent's work carries a via badge, groups separately in your notifications, and is kept apart from your own work in Work Done, the same as over MCP. Kanera only sees the CLI, so name the agent when you sign in with --agent (or KANERA_AGENT_NAME). The name is fixed for that sign-in; give each agent its own profile if several share a machine. Over MCP the agent names itself; see Set up Claude or Set up Codex. kanera mcp, the CLI's local MCP server, uses the same stored credential and so the same attribution as the CLI.
Add it to your project instructions
To make the loop the default, add your own section to the repository's CLAUDE.md or AGENTS.md. This text is yours to adapt; Kanera does not generate it.
## Kanera
Work is tracked in Kanera. Use the `kanera` CLI, not the web interface.
- Before starting a card, run `kanera card <key> --json` and `kanera runs <key>`.
If another run is live, stop and tell me.
- Open a run with `kanera run start <key> "<short description>"` and keep its id.
- Update it with `kanera run update <id> --summary "<progress>"` at least every
10 minutes while working.
- If you need a decision from me, set `--status blocked`, and comment on the card saying what you need.
- When done, end the run with `kanera run done <id> "<one-line outcome>"`, comment with a summary
and any pull request link, then run `kanera card done <key>`.
- If you stop without finishing, end the run with `--status failed` or `--status cancelled`.
Never leave a run open when you are not working.
- If a command exits with code 4, the key cannot make that change. Stop and tell me.
Pair it with a write key. With a read-only key, keep only the reading steps.