Agent hooks

Report agent activity to Kanban cards in real-time using lifecycle hooks.

Hooks let agents report their current activity back to Kanban cards as they work. Each card shows the agent’s latest tool call, command, or message — so you can monitor hundreds of agents at a glance without opening each terminal.

Agents call kanban hooks ingest or kanban hooks notify from within their lifecycle hooks. Kanban updates the card’s activity display immediately.

Kanban sets KANBAN_TASK_ID and KANBAN_WORKSPACE_ID automatically when starting a task session. Hook commands read these variables from the environment — you don’t need to pass them manually.

Hook events

Every hook call targets one of three events:

activity

The agent reports what it is currently doing — a tool call, a running command, or a message. Kanban updates the card’s activity display without changing its column.

to_review

The agent signals it has finished and is ready for review. Kanban moves the card to the Review column. Pass --final-message to show a summary on the card.

to_in_progress

The agent signals it has resumed work (for example, after a user sends a follow-up message). Kanban moves the card back to the In progress column.

Commands

kanban hooks notify

Best-effort ingest that never throws or exits non-zero. Use this inside agent lifecycle hooks where a failure must not interrupt the agent.

kanban hooks notify --event <event> [payload]

kanban hooks ingest

Ingest with error reporting. Exits non-zero if the call fails. Use this in scripts where you want to know about failures.

kanban hooks ingest --event <event> [payload]

Passing the payload

You can supply hook metadata in three ways:

• Stdin — pipe JSON directly: echo '{...}' | kanban hooks notify --event activity
• Positional argument — pass a JSON string: kanban hooks notify --event activity '{...}'
• Base64 — encode the JSON and pass it with --metadata-base64 <base64>

Kanban infers as much as it can from the raw payload (tool name, hook event name, command snippet). You can also set fields explicitly with flags.

Metadata flags

--activity-text

Short summary shown on the card. Truncated to 200 characters. Example: "Using Bash: npm test".

--tool-name

Name of the tool being called. Example: "Bash", "computer".

--final-message

The agent’s last message when transitioning to review. Shown on the card after the task moves to the Review column.

--hook-event-name

The original lifecycle hook name from the agent framework. Example: "PreToolUse", "PostToolUse", "Stop".

--notification-type

The notification type from the agent. Example: "permission_prompt".

--source

Which agent sent the event. Example: "claude", "codex", "gemini", "cline", "droid".

Agent integrations

Claude Code

Claude Code fires lifecycle hooks at key points: PreToolUse, PostToolUse, Stop, and Notification. Wire them up in your Claude Code hooks config (.claude/settings.json or the global equivalent).

Pass --hook-event-name with the Claude hook name so Kanban can infer the right activity text automatically.

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "kanban hooks notify --event activity --source claude" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "kanban hooks notify --event to_in_progress --source claude" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "kanban hooks notify --event to_review --source claude" }]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "kanban hooks notify --event to_review --source claude" }]
      }
    ]
  }
}

Claude Code passes the full hook payload to each hook command via stdin. Kanban reads it automatically.

Gemini CLI

Use kanban hooks gemini-hook as the Gemini hook binary. It reads the payload from stdin, emits {} to stdout (required by Gemini’s hook protocol), and fires Kanban notifications asynchronously in the background — so it never blocks the agent.

.gemini/settings.json

{
  "hooks": {
    "BeforeAgent": [{ "hooks": [{ "type": "command", "command": "kanban hooks gemini-hook" }] }],
    "AfterAgent":  [{ "hooks": [{ "type": "command", "command": "kanban hooks gemini-hook" }] }],
    "BeforeTool":  [{ "hooks": [{ "type": "command", "command": "kanban hooks gemini-hook" }] }],
    "AfterTool":   [{ "hooks": [{ "type": "command", "command": "kanban hooks gemini-hook" }] }],
    "Notification":[{ "hooks": [{ "type": "command", "command": "kanban hooks gemini-hook" }] }]
  }
}

The gemini-hook subcommand maps Gemini’s hook events to Kanban events automatically:

Gemini event	Kanban event
BeforeAgent	to_in_progress
AfterAgent	to_review
BeforeTool, AfterTool, Notification	activity

OpenAI Codex

Use kanban hooks codex-wrapper to wrap the Codex binary. The wrapper passes all arguments and signals through to the real Codex process, monitors Codex’s session log, and emits activity events as Codex works.

kanban hooks codex-wrapper --real-binary /usr/local/bin/codex [codex args...]

To use the wrapper, point your Kanban agent command at kanban hooks codex-wrapper instead of calling codex directly, and pass the path to the real Codex binary with --real-binary.

When KANBAN_TASK_ID and KANBAN_WORKSPACE_ID are set, the wrapper automatically enables Codex’s session log recording and polls the log to emit activity, to_review, and to_in_progress events in real-time.