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.
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 --agent "Claude Code" # use your agent's own product name
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.
Both setup targets include the work loop: when asked to carry out a card, the agent starts a run, keeps progress visible, comments its outcome, and moves the card to the appropriate list before its final reply. Read-only questions, exploratory plans, draft-only requests, and explicit limits do not authorize these writes. Existing installations keep their old instructions: after upgrading, refresh the Claude skill with --force, or update the existing Kanera section in AGENTS.md using the current kanera skill output. Adapt the project instructions below for your workflow.
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 substantive work, read the relevant comments and board configuration, check that nobody else is on the card, then open a run. Resume your own live run for the same task; report another agent's live run before doing overlapping work:
kanera comments MKT-42 --json
kanera board <boardId> --json # lists and their actual IDs
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.
Record the card's original list ID, name, and workflow meaning before moving it. Use kanera card move to place it in the available list that represents active work in this board's workflow. Runs do not move cards. Resolve the list from the board's configuration and skip the move if it is already there; kanera help cards.move describes the required anchor arguments. Do not assume every board uses the Agent Workflow template.
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."
Give each intended comment or run creation a fresh --idempotencyKey UUID and reuse it only when retrying that write after an ambiguous failure. If a response was lost without a key, check the card before retrying to avoid duplicates.
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. Choose a list that reflects the blocker in this board's workflow. When the agent resumes, it sets the run back to --status running and moves the card back to the active list.
If another card is the prerequisite, also create a card dependency: kanera card block API-42 WEB-18 means API-42 blocks WEB-18. A blocked run describes the agent’s status; it does not create this relationship. Use kanera work --filters.blockedOnly true to find waiting cards, and kanera deps WEB-18 to read its direct prerequisites and transitive upstream/downstream chain.
5. Finish
Before the final reply, post a durable outcome comment with what changed or was found, verification and its results (including failures or skipped checks), relevant PR/commit/artifact links, and remaining work or decisions. Mark only checklist items actually completed. Then end the run and route the card:
kanera comment MKT-42 "Rounding is now per order. Focused regression checks pass; full suite not run. PR 318 is ready for review; merge and deployment remain."
kanera run done "$RUN_ID" "Implementation ready for review in PR 318"
kanera card move MKT-42 <destinationListId> --anchor '{"side":"after","id":null}'
kanera card MKT-42 --json
The run's closing summary becomes a finished row in activity; it does not replace the outcome comment, move the card, or complete it. A successful run may cover only part of a card. Complete the card only when the agreed workflow permits it and its criteria are met.
Before moving the card, re-read it and its board. Consider the original list, the currently available lists and their meanings, what was completed, and what remains. Choose the list that best represents the card's actual state in this board's workflow. Returning to the original list may be appropriate, but is not automatic. Do not assume list names or choose from list order or the in-progress setting alone. Explain the choice in the outcome comment.
If the assigned work could not be completed, explain what remains and end the run with --status failed or --status cancelled. Keep blocked only when genuinely waiting to resume; do not leave stopped work running. An ended run cannot be changed; if work resumes later, start a new run.
Verify the resulting card list, outcome comment and run status from the write results and a fresh read. Account for automations and a teammate's intervening move. If no destination is clear, leave the current list unchanged, save the run/comment updates you can and ask only for the missing routing choice. If a write is refused, report the restriction and which tracking steps remain unsaved; do not imply success. The final reply should link the card and state its resulting list and run status.
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
The current kanera setup claude and kanera setup codex instructions include this loop. To make your project's acceptance policy explicit, adapt this section in CLAUDE.md or AGENTS.md:
## Kanera card work
Use connected Kanera MCP tools when available, otherwise the Kanera CLI.
When asked to carry out a card, keep it updated as part of the assignment:
- Read the card, relevant comments and board lists; record the original list ID/name/meaning and check for another live agent run.
- Start a run before substantive work and move to the board's active list.
- Keep progress current at milestones and at least every ten minutes.
- When blocked, update the run, comment what you need and move to the waiting list.
- Before the final reply, comment changes, checks/results, relevant links and remaining work.
- End the run appropriately. Re-read the card and board; consider the original list, available lists
and their meanings, completed work and remaining work. Choose the list that reflects the card's
actual state in this board's workflow, without assuming names or automatically restoring its
original list. Explain the choice in the comment. If unclear, leave the list unchanged and ask.
Complete the card only when the agreed workflow permits it and its criteria are met.
- Verify the saved comment, run status and card list; report any tracking writes that failed.
- Read-only or exploratory requests cause no tracking writes; explicit user limits win.
Pair it with a write key. With a read-only key, keep only the reading steps.