kanban hooks

Runtime hook helpers for integrating agents with the Kanban board.

The kanban hooks command provides subcommands for emitting hook events into the Kanban runtime from agent integrations. Use these commands inside agent hooks (Claude Code, Gemini CLI, Codex) to update task state and activity on the board in real time.

Synopsis

kanban hooks <subcommand> [options]

Environment variables

All hooks subcommands read the following environment variables automatically:

Variable	Description
KANBAN_TASK_ID	The ID of the task currently being worked on.
KANBAN_WORKSPACE_ID	The ID of the Kanban workspace.

Kanban sets these variables in the agent’s environment when it launches a task session. You do not need to set them manually in normal usage.

---

hooks ingest

Ingest a hook event into the Kanban runtime. Exits with a non-zero code if the event fails to deliver.

Use hooks ingest in situations where you want explicit error reporting — for example, in a CI script or a hook that must confirm delivery.

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

--event · string · required

The event type to emit. Accepted values:

• to_review — signal that the agent has finished and the task is ready for review
• to_in_progress — signal that the agent has resumed or started working
• activity — report an activity update (tool use, command, message) shown on the task card

--source · string

A short identifier for the hook source, e.g. claude, codex, gemini. Shown alongside the activity on the task card. Maximum 64 characters.

--activity-text · string

A short summary of the current activity, displayed on the task card. Maximum 200 characters.

--tool-name · string

The name of the tool currently being used by the agent.

--final-message · string

The agent’s final message when transitioning to review. Shown as the task’s last activity.

--hook-event-name · string

The original lifecycle event name from the agent hook system (e.g. PreToolUse, PostToolUse, Stop).

--notification-type · string

The notification type from the agent, e.g. permission_prompt.

--metadata-base64 · string

A base64-encoded JSON object containing metadata fields. Use this as an alternative to passing individual flags when the payload is constructed programmatically.

[payload] · string

An optional positional JSON payload argument. If stdin is not a TTY, the payload can also be piped in via stdin. The order of precedence is: --metadata-base64 > stdin JSON > positional argument.

Example — signal task ready for review:

kanban hooks ingest \
  --event to_review \
  --source claude \
  --final-message "Refactoring complete. All tests pass."

Example — report tool activity:

kanban hooks ingest \
  --event activity \
  --source claude \
  --tool-name Bash \
  --activity-text "Running: npm test"

Example — pipe a JSON payload from stdin:

echo '{"hook_event_name": "PostToolUse", "tool_name": "Write"}' | \
  kanban hooks ingest --event activity --source claude

---

hooks notify

Same as hooks ingest but never throws — errors are silently swallowed. Use hooks notify inside agent hooks where a delivery failure must not interrupt the agent’s workflow.

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

Accepts the same options as hooks ingest.

Example — best-effort notification inside a Claude Code hook:

kanban hooks notify --event activity --source claude --activity-text "Writing file"

Prefer hooks notify over hooks ingest in agent hook scripts. If the Kanban server is not reachable, the hook completes silently instead of failing the agent session.

---

hooks gemini-hook

A Gemini CLI hook entrypoint. Configure this as the hook binary in your Gemini CLI config and Kanban will receive board notifications whenever Gemini acts on a task.

kanban hooks gemini-hook

This subcommand:

1. Reads a JSON payload from stdin (required by the Gemini hook protocol).
2. Writes {} to stdout immediately (also required by Gemini).
3. Maps Gemini lifecycle events to Kanban hook events:
   • BeforeAgent → to_in_progress
   • AfterAgent → to_review
   • BeforeTool, AfterTool, Notification → activity
4. Fires the Kanban notification asynchronously so it does not block the agent.

Gemini CLI config example:

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

KANBAN_TASK_ID and KANBAN_WORKSPACE_ID must be set in the environment when gemini-hook runs. Kanban sets these automatically when it launches a Gemini task session.

---

hooks codex-wrapper

A wrapper around the Codex binary that watches the Codex session log and emits Kanban hook notifications as events occur.

kanban hooks codex-wrapper [agentArgs...] --real-binary <path>

--real-binary · string · required

The absolute path to the actual codex binary. The wrapper passes all other arguments and stdin/stdout through to this binary unchanged.

[agentArgs...] · string[]

Any additional arguments to forward to the Codex binary (e.g. the task prompt, model flags, or Codex-specific options).

The wrapper:

1. Sets CODEX_TUI_RECORD_SESSION=1 so Codex writes a session log.
2. Polls the session log file and translates Codex events (task_started, task_complete, approval_request, exec_command_begin, etc.) into Kanban hook events.
3. Forwards all signals (SIGINT, SIGTERM) to the child Codex process.
4. Exits with the same exit code as Codex.

Example — configure Kanban to launch Codex through the wrapper:

In your Kanban config, set the Codex command to:

kanban hooks codex-wrapper --real-binary /usr/local/bin/codex

All additional arguments (such as the task prompt) are forwarded automatically by Kanban.

---

Claude Code integration example

Add the following to your Claude Code hooks configuration (.claude/settings.json) to send Kanban notifications from every Claude hook event:

{
  "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" }]
      }
    ]
  }
}

Kanban infers the activityText and other metadata fields automatically from the hook payload that Claude Code pipes to the command’s stdin.

The KANBAN_TASK_ID and KANBAN_WORKSPACE_ID environment variables are injected by Kanban when it starts the Claude Code agent. You do not need to set them in the hook command itself.