# 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.

> Kandown documentation — https://kandown.dev/docs/agents/overview

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

```bash
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.

```bash
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.

| URL | What you get |
|---|---|
| `/llms.txt` | The install command and a linked index of every page |
| `/llms-full.txt` | The entire documentation in one request |
| any docs URL + `.md` | That 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

- [Project instructions](/docs/agents/instructions.md) — teaching agents your project's specifics
- [Launching agents](/docs/agents/launching.md) — handing a task to Claude Code, Codex, Goose and others
- [MCP server](/docs/agents/mcp.md) — driving the board over the Model Context Protocol