Skip to content
kandown
GitHub—npm—

AI agents

View raw

For AI agents

How agents get full board context in one command, why stdout is data-only, and how to wire Kandown into an agent loop.

This is the part that makes Kandown different from a task list with an AI feature bolted on, so it is worth two minutes.

The design assumption is simple: an agent is another user of the board, not an integration. It gets the same context you do, through an interface built for how agents actually work — one command that returns everything, and output you can pipe.

One command for context

kandown work

That prints, as plain Markdown on stdout:

  1. The agent rules — served from the installed CLI, so they are never a stale copy frozen into your repository at init time.
  2. Your project instructions — optional, from .kandown/instructions.md. Stack quirks, "always use pnpm", commit-message language, token-efficiency preferences.
  3. A live board digest — column counts, tasks per column with blocked-by annotations, and a computed next actionable task: unblocked, closest to done, highest priority.

One call, full context.

kandown init adds a single line to your AGENTS.md / CLAUDE.md pointing at it — a pointer, not a block of rules copied in to go stale. That distinction is the whole point: rules that live in the CLI are upgraded when the CLI is upgraded.

Tuning the output

The Settings page has an Agent → kandown work output configurator:

  • toggle each block on or off,
  • switch to a concise, token-efficient mode,
  • hide individual digest fields,
  • see an estimated token count as you go,
  • or take full control with a raw template using {{baseRules}}, {{projectInstructions}} and {{boardDigest}}.

Tip

If you run agents in a tight loop, the concise mode plus a trimmed digest is usually worth the few minutes it takes to configure. The token count updates live, so you can see what you are buying.

The output contract

This is the part that makes Kandown safe to script:

stdout carries data only — ids, JSON, tables. Everything decorative (✓ Created…, warnings, errors) goes to stderr.

So $(kandown create …) captures exactly one id, and --json | jq never chokes on a checkmark. Exit code 0 on success, non-zero on failure.

kandown list --json | jq '.[] | select(.priority=="P1")'

ID=$(kandown create "Refactor auth middleware" -p P1 -t backend)
kandown move "$ID" "In progress"

kandown commit -m "tasks: add auth refactor"

No network, ever

The task commands and kandown daemon never contact the npm registry. They stay instant and work offline — which matters in CI, and matters a great deal for an agent making dozens of calls in a loop.

The update check that does exist is skipped whenever stdout is not a terminal, so it can never fire in an automated context. Set KANDOWN_NO_UPDATE=1 if you want it gone entirely.

Keeping the board honest

A board an agent writes to is only useful if what it writes is true. Two mechanisms help:

  • report: lines on subtasks and the task report field are where an agent records what it actually did. A completed task should read as a work log, not a row of ticks.
  • The dependency gate refuses to move a blocked task to the terminal column, from any interface. An agent cannot mark work done that depends on work that is not.

Reading these docs as an agent

This documentation is published as plain Markdown as well as HTML, so an agent does not have to parse a React page to follow an instruction.

URLWhat you get
/llms.txtThe install command and a linked index of every page
/llms-full.txtThe entire documentation in one request
any docs URL + .mdThat page's Markdown source — /docs/agents/mcp → /docs/agents/mcp.md

All three are generated from the same source as the pages themselves on every deploy, so they cannot fall behind what the site says.

Where to go next

Edit this page on GitHub →