Kanbus

Feature

Lifecycle hooks

Run your own commands before and after Kanbus operations, with a stable JSON payload, so validations, notifications and integrations plug into the CLI without forking it.

Lifecycle hooks make Kanbus command boundaries programmable. A hook is an external command that Kanbus runs before or after an operation, such as creating, updating or listing issues. The engine behaves the same in the Python and Rust CLIs, and in both native and Beads compatibility modes.

Events and phases

Mutating events: issue.create, issue.update, issue.close, issue.delete, issue.comment, issue.dependency, issue.promote, issue.localize.

Read events: issue.show, issue.list, issue.ready.

Before hooks on mutating events fail closed by default: if the hook fails or times out, the command does not run.

After hooks are observers. A failure prints a warning and does not undo a command that already succeeded.

These are Kanbus CLI hooks. They are separate from coding-agent hooks such as the ones that reinject context after compaction.

Configure hooks

Hooks live in a hooks block in .kanbus.yml. Each entry needs an id and a command argument list, and can set blocking, timeout_ms, cwd and env.

hooks:
  enabled: true
  run_in_beads_mode: true
  default_timeout_ms: 5000
  before:
    issue.update:
      - id: validate-update
        command: ["./hooks/validate-update.sh"]
        timeout_ms: 1200
  after:
    issue.create:
      - id: notify-created
        command: ["./hooks/notify-created.sh"]
        env:
          WEBHOOK_URL: "https://example.invalid/hooks"

Every hook receives the same JSON envelope on stdin, with the schema version, phase, event, timestamp, actor, mode details (project root, working directory, runtime) and an operation object with event-specific context such as identifiers and before and after issue snapshots when available.

{
  "schema_version": "kanbus.hooks.v1",
  "phase": "after",
  "event": "issue.create",
  "actor": "dev@example.com",
  "operation": { "issue": { "identifier": "kanbus-a1b2c3", "title": "..." } }
}

Inspect, validate and disable

kbs hooks list
kbs hooks validate
kbs --no-hooks list
KANBUS_NO_HOOKS=1 kbs list

kbs hooks validate rejects unknown events, empty hook lists and duplicate IDs, and checks command and cwd paths. Policy as code guidance runs in the same engine as a built-in provider: --no-guidance turns off only that guidance, while --no-hooks turns off everything.

Learn more