# Launching agents

Handing a task to Claude Code, Codex, Gemini CLI, Goose, Aider or OpenCode — and wiring your own tooling through the agent hook.

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

## From the board

Select a task in the terminal UI and press <kbd>a</kbd>. Kandown assembles the task context and
launches the agent you choose on it.

| Agent | Binary | Launch mode |
|---|---|---|
| Claude Code | `claude` | interactive session |
| OpenAI Codex | `codex` | interactive session |
| Gemini CLI | `gemini` | `-p` initial prompt |
| Goose | `goose` | `run --text`, non-interactive |
| Aider | `aider` | `--message` initial prompt |
| OpenCode | `opencode` | TUI, context written to `/tmp` |

Each entry launches differently because each CLI expects a different shape of input — an
interactive session where that is the natural mode, a one-shot prompt where it is not. Only agents
whose binary is on your `PATH` are offered.

## Your own tooling

Anything else — an IDE, a bot, an internal queue, a webhook into your own orchestrator — connects
through the **agent hook**. Press <kbd>g</kbd> in the terminal UI (or use *Send to Agent* in the
web board) and Kandown posts the task to your endpoint.

```bash
export KANDOWN_AGENT_HOOK_URL="https://example.internal/agents/kandown"
export KANDOWN_AGENT_HOOK_LABEL="Send to Orchestrator"
export KANDOWN_AGENT_HOOK_HEADERS='{"Authorization":"Bearer $TOKEN"}'
```

| Variable | Effect |
|---|---|
| `KANDOWN_AGENT_HOOK_URL` | Endpoint that receives the task |
| `KANDOWN_AGENT_HOOK_LABEL` | Custom label for the button |
| `KANDOWN_AGENT_HOOK_HEADERS` | JSON object of extra headers |

> **Warning**
> The hook is the one part of Kandown that makes an outbound network request, and it does so only
> when you press the key. Point it somewhere you trust — the task body goes with it.

## In a loop, without the UI

The board does not have to be involved at all. `kandown work` plus the task commands are enough to
drive an agent from a script:

```bash
#!/usr/bin/env bash
set -euo pipefail

CONTEXT=$(kandown work)
NEXT=$(kandown list --json | jq -r '[.[] | select(.status=="Todo")][0].id // empty')

[ -z "$NEXT" ] && { echo "nothing actionable" >&2; exit 0; }

kandown move "$NEXT" "In progress"
claude -p "$CONTEXT

Work on task $NEXT. Update the task file as you go."
```

Two properties make this reliable: task commands never touch the network, and stdout is data-only,
so the `$( … )` captures above hold exactly what you expect. See
[the output contract](/docs/agents/overview.md#the-output-contract).