kata カタ

The issue tracker built for coding agents and the humans steering them.

Coding agents need somewhere durable to track work: not a chat thread, not a markdown to-do list. kata gives them a local task ledger they can drive from the CLI: create, claim, relate, and close issues with evidence. Humans supervise the same work in a terminal UI. By default, issue state lives in a local SQLite database, so your repo stays clean and no hosted tracker is required. When a team of humans and agents needs to share, you can opt into a remote daemon on a private network or a hosted daemon. Go applications can instead mount kata's listener-free HTTP service in-process; see Embedding kata in Go. MCP clients can start Kata's native server over stdio or Streamable HTTP with kata mcp serve. It binds the current workspace's project by default, and can serve a fixed allowlist or the complete daemon catalog on request. Section loaders progressively expose Kata's typed issue, administration, automation, and event workflows. See the MCP reference.

The documentation in docs/ is the definitive guide, published with Zensical at https://katatracker.com/.

Privacy-first fork. This branch strips every feature that talks to a service outside your machines: telemetry, self-update checks, external sync integrations, federation, and hosted embeddings. SQLite is the only storage backend. See the changelog for the full list.

Install

macOS:

brew install kata

Linux, or macOS without Homebrew:

curl -fsSL https://katatracker.com/install.sh | bash

Linux and WSL 2 users who already use Homebrew can also run brew install kata.

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://katatracker.com/install.ps1 | iex"

The installer detects your OS and CPU architecture, downloads the latest GitHub release archive, and verifies it against SHA256SUMS before installing. Confirm the install with:

kata version

To upgrade a release-archive install, rerun the installer. Homebrew installs use brew upgrade kata; Linux .deb and .rpm packages are published for amd64 and arm64 and remain owned by the system package manager. Prefer to build from source? kata needs Go 1.27 or later:

go install go.kenn.io/kata/cmd/kata@latest

Module-source installs include the CLI, daemon, and TUI but not the compiled browser bundle. Install a release binary, or build from a clone with make install, to use kata ui.

Go installs to $(go env GOBIN), falling back to $(go env GOPATH)/bin (often ~/go/bin); put that directory on your PATH. See Install for package downloads, manual release downloads, and build-from-source steps.

flowchart TB
  arrive{"Work arrives"} --> search["Search first:<br/>kata search #34;#60;terms#62;#34; --agent<br/>Reuse an open issue, else create one.<br/>If create refuses a look-alike, reuse it;<br/>--force-new only if the work truly differs.<br/>No bound workspace: refs are #60;project#62;##60;id#62;,<br/>or pass --project #60;project#62;."]
  search --> route{"Work it, or delegate it?"}

  subgraph workside[" "]
    direction TB
    claim["Claim and mark it tracked:<br/>kata claim #60;ref#62;<br/>kata meta set #60;ref#62; work.attention ok"]
    branch["If the work happens on a dedicated branch, stamp it once:<br/>kata meta set #60;ref#62; work.branch #60;branch#62;<br/>or bind at creation:<br/>kata create ... --meta work.branch=#60;branch#62; --idempotency-key #60;key#62;"]
    live["Keep state current:<br/>kata meta set #60;ref#62; work.attention stuck#124;needs-human#124;ok<br/>kata meta set #60;ref#62; work.attention_msg #34;#60;why#62;#34;<br/>stuck = blocked; needs-human = input/review; ok = unblocked.<br/>Record progress:<br/>kata comment #60;ref#62; -m #34;#60;what changed#62;#34;<br/>Request attention:<br/>kata notify #60;ref#62; --to #60;actor#62;[/#60;teammate#62;] --message #60;reason#62;"]
    claim --> branch --> live
  end

  subgraph delegateside[" "]
    direction TB
    fanout["Tracked children: --parent #60;ref#62;, --meta work.branch=#60;branch#62;,<br/>--idempotency-key #60;key#62;, --json; capture .issue.short_id.<br/>Subagents: distinct KATA_TEAMMATE and<br/>KATA_INBOX_USER=#60;actor#62;/#60;teammate#62;; keep the actor.<br/>Read requests: kata inbox --for #60;actor#62;[/#60;teammate#62;].<br/>After handling: kata notify #60;ref#62; --to #60;actor#62;[/#60;teammate#62;] --clear."]
    join["Join with kata wait #60;refs#62; --until attention --any<br/>Matches needs-human or stuck; a close also completes the wait,<br/>and the reported reason distinguishes which. Use --timeout so a<br/>wrapper can tell timeout from satisfaction."]
    coord["Read delegated work.*; never write it."]
    fanout --> join --> coord
  end

  route -->|work it| claim
  route -->|delegate it| fanout
  route -->|record only| park
  live --> done
  coord --> done

  done{"Verified complete?"}
  done -->|yes| close["kata close #60;ref#62; --done --message #34;#60;scope and verification, 40+ chars#62;#34;<br/>--evidence commit:#60;sha#62; #124; pr:#60;url#62; #124; test:#60;cmd#62; #124; reviewed-paths:#60;path#62;<br/>(or --commit, --pr, --test, --reviewed)"]
  done -->|duplicate, superseded or dropped| retire["kata close #60;ref#62; --message #34;#60;why#62;#34;<br/>--duplicate-of #60;ref#62; #124; --superseded-by #60;ref#62; (20+ chars)<br/>#124; --wontfix (60+ chars)"]
  done -->|no| park{"Park it?"}
  park -->|start date known| schedule["kata schedule #60;ref#62; #60;date-or-time#62;<br/>sets scheduled_on; clear with -"]
  park -->|start date unknown| someday["kata meta set #60;ref#62; someday true --json-value<br/>clear with kata meta unset #60;ref#62; someday"]
  park -->|needs review| review["kata label add #60;ref#62; needs-review --comment #34;#60;what remains#62;#34;"]

Quickstart

cd your-repo
kata init                              # bind this workspace to a kata project
kata create "fix login race"           # prints a short id, e.g. abc4
kata list                              # see open work
kata show abc4                         # inspect by short id
kata tui                               # browse and triage interactively
kata tui abc4                          # open an issue directly in the TUI
kata ui                                # open the same ledger in a browser

kata create prints each issue's short id; use it in later commands. Close only when the work is complete and verified:

kata close abc4 --done \
  --message "Fixed the login race and verified the relevant tests pass." \
  --commit <sha>

Reply to a specific comment, then read the thread it belongs to:

kata comment abc4 --reply c:xbzxrq -m "This builds on the finding."
kata show abc4 --thread c:xbzxrq

The TUI and Web UI show nonzero counts for authorized direct relations on original comments. Open a count to inspect chronological evidence with its author, time, handle, and body, then jump to it and return focus. The TUI uses a keyboard picker; Web controls are accessible. Replies show their outgoing relation. Partial counts stay explicit. Conflicting assertions stay visible together without scores, automatic resolution, or hiding. Pending, removed, moved, and edited targets remain visible.

Use --confirm, --refute, or --supersede when the response has that meaning. See Reply to a finding for handles and retries. Reply notifications and coordinator broadcasts are planned. For work that needs ownership or tracked completion, a comment-sized task becomes a child issue.

For agent-heavy workspaces, kata init --with-agents also writes a managed kata briefing into agent guidance files. It refreshes existing real AGENTS.md and CLAUDE.md files, or creates AGENTS.md when neither exists, without overwriting the rest of either file. Codex-only workspaces can instead use kata init --with-codex-hooks to install dynamic contract context and the work.attention SessionStart lifecycle into .codex/hooks.json.

Why kata

• Built for agents. Stable short refs, --json and --agent output, idempotent creates, lexical search, a claim flow, and predictable failure modes agents can script against.
• Made for humans too. kata tui and kata ui browse, triage, and supervise agent-written work over the same data. The browser app is served by the daemon and needs no separate backend.
• Local-first, repo-clean. One Go binary, no runtime dependencies. Issue state lives in SQLite under KATA_HOME; your repo commits only a small, secret-free .kata.toml.
• Auditable by design. Closing an issue is an explicit completion claim with a reason, message, evidence, and actor attribution, on top of editable comments and durable events.

How kata compares

kata is intentionally small. It is not a project-management suite, a git workflow engine, or an agent worker pool. It is a durable task ledger that humans and agents can both operate.

It is also not a SaaS issue tracker. Linear, Jira, GitHub Issues, ClickUp, and similar tools are shared online systems for planning, dashboards, assignment, and cross-team reporting. kata is local-first, instant from the CLI/TUI, and designed around agent-first ergonomics: stable refs, predictable output, idempotent creates, claim flows, and evidence-based closes. See Comparisons with SaaS issue trackers for the matrix.

Beads keeps issue state in a project-local .beads/ Dolt database with native history, branching, and push/pull. git-bug stores issues as git objects under custom refs and syncs them over git push and git pull. kata makes a different bet: the ledger is a local service next to your workspaces, not data carried in the repository. That keeps the workspace clean, works the same in non-git directories, and keeps issue history out of code history. The trade-off is that kata does not ride git remotes for sharing; the remote daemon covers that instead.

Moving from Beads? See Migrating from Beads. kata import --source-format beads drives the bd CLI and merges your issues into a kata project.

Documentation

The docs site is the definitive reference:

• Get started: Quickstart · Install · Changelog
• Guide: Concepts · Workspaces and projects · Migrating from Beads
• Reference: CLI · Model Context Protocol · Configuration
• Workflows: Agent workflows · Sharing models
• Operations: Remote daemon · Hosted mode · Containers · Backup and restore
• Development: Embedding kata in Go · Contributing

For coding agents

Run kata quickstart (alias kata agent-instructions) for the operating contract: search before creating, pass an idempotency key on create, prefer --agent output, claim work with kata claim, and close only when the work is verified. Close each verified issue promptly with valid evidence and a substantive message. Agent workflows is the same contract in long form.

On main, install the contract in every coding-agent session on this machine:

kata agent-hook install

For Codex, open Codex and run /hooks to trust the new hook. See Contract in every session for all 18 targets, runtime requirements, attention capabilities and additional Codex homes. Contract and available attention hooks are enabled by default; use --contract-only to opt out of attention, or kata init --agent-hooks=codex,pi for project setup. These commands require Kata 0.19.0 or later.

Print the shorter managed briefing without changing the repository:

kata quickstart --format contract
# equivalent alias; selectors are accepted for user-local integrations
kata agent-instructions --format contract --workspace /path/to/workspace
kata quickstart --format contract --project example-project

Contract output is marker-free, has no terminal framing, works without an initialized workspace, and performs no workspace mutation. It is rendered from the same canonical body that kata init --with-agents places between its managed markers, so static and session-injected guidance cannot drift.

If you want silence outside Kata workspaces, use this alternative Claude Code SessionStart command instead of the every-session installer:

if test -f "$CLAUDE_PROJECT_DIR/.kata.toml"; then
  kata quickstart --format contract --workspace "$CLAUDE_PROJECT_DIR"
fi

For a Codex SessionStart response without a stdin payload, run kata agent-contract-hook. To replace the prompt, use kata agent-contract-hook --source ./agent-prompt.txt; a missing file uses the built-in contract and an empty file supplies an empty prompt.

Codex SessionStart hooks require structured JSON rather than plain contract stdout. For workspace hooks, use kata init --with-codex-hooks; see the init reference for contract deduplication and the separate attention lifecycle.

Contributing

See Contributing for the repository layout and local checks (make test, make lint, make vet, make nilaway). Licensed under the terms in LICENSE.