# 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 or
federation; a shared daemon can use Postgres by setting `KATA_DSN`.
Production Postgres deployments can use separate schema-owner and runtime roles;
see the [operator ceremony](docs/operations/postgres.md).
Go applications can instead mount kata's listener-free HTTP service in-process;
see [Embedding kata in Go](docs/development/embedding.md).
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](docs/reference/mcp.md).
The documentation in [`docs/`](docs/) is the definitive guide, published with
Zensical at <https://katatracker.com/>.
> **Stable:** Since v0.14.0, kata releases preserve backward compatibility
> across upgrades.
The latest release is [0.20.0](docs/changelog.md#0200). It adds an Attention
inbox to the terminal UI, requests for replies to specific comments,
participant broadcasts, and events for reached schedules. See
[Updating Kata](docs/get-started/install.md#updating-kata) for installation
and federation upgrade guidance.
## Install
macOS:
```sh
brew install kata
```
Linux, or macOS without Homebrew:
```sh
curl -fsSL https://katatracker.com/install.sh | bash
```
Linux and WSL 2 users who already use
[Homebrew](https://docs.brew.sh/Homebrew-on-Linux) can also run
`brew install kata`.
Windows PowerShell:
```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:
```sh
kata version
```
Release-archive builds update themselves with `kata update`. 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.3 or later**:
```sh
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](docs/get-started/install.md) for package downloads, manual release
downloads, and build-from-source steps.
```mermaid
flowchart TB
arrive{"Work arrives"} --> search["Search first:<br/>kata search #34;#60;terms#62;#34; --agent<br/>Same work: reuse the open issue, else create one.<br/>Related work: link each hit with --parent #60;ref#62; #124; --related #60;ref#62;.<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/>Respond to a comment:<br/>kata comment #60;ref#62; --reply#124;--confirm#124;--refute#124;--supersede c:#60;id#62; -m #34;#60;evidence#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
```sh
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:
```sh
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:
```sh
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](docs/workflows/agents.md#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, semantic-aware 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](docs/guide/comparisons.md) for the
matrix.
[Beads](https://github.com/gastownhall/beads) keeps issue state in a
project-local `.beads/` Dolt database with native history, branching, and
push/pull. [git-bug](https://github.com/git-bug/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
and federation cover that instead.
Moving from Beads? See
[Migrating from Beads](docs/guide/migrating-from-beads.md).
`kata import --source-format beads` drives the `bd` CLI and merges your issues
into a kata project.
## Documentation
The [docs site](docs/) is the definitive reference:
- Get started: [Quickstart](docs/get-started/quickstart.md) ·
[Install](docs/get-started/install.md) ·
[Changelog](docs/changelog.md)
- Guide: [Concepts](docs/guide/concepts.md) ·
[Workspaces and projects](docs/guide/workspaces-projects.md) ·
[Semantic search](docs/guide/semantic-search.md) ·
[Migrating from Beads](docs/guide/migrating-from-beads.md)
- Reference: [CLI](docs/reference/cli.md) ·
[Model Context Protocol](docs/reference/mcp.md) ·
[Configuration](docs/reference/configuration.md)
- Workflows: [Agent workflows](docs/workflows/agents.md) ·
[Gated workflows](docs/workflows/gated-workflows.md) ·
[Sharing models](docs/workflows/sharing.md)
- Operations: [GitHub sync](docs/operations/github-sync.md) ·
[Notion sync](docs/operations/notion-sync.md) ·
[Plane sync](docs/operations/plane-sync.md) ·
[Linear sync](docs/operations/linear-sync.md) ·
[Twenty sync](docs/operations/twenty-sync.md) ·
[Todoist sync](docs/operations/todoist-sync.md) ·
[TickTick sync](docs/operations/ticktick-sync.md) ·
[Forgejo connector](docs/operations/forgejo-connector.md) ·
[Remote daemon](docs/operations/remote-daemon.md) ·
[Federation](docs/operations/federation.md) ·
[Hosted mode](docs/operations/hosted-mode.md) ·
[Containers](docs/operations/containers.md) ·
[PostgreSQL](docs/operations/postgres.md) ·
[Backup and restore](docs/operations/backup-restore.md)
- Development: [Embedding kata in Go](docs/development/embedding.md) ·
[Contributing](docs/development/contributing.md)
## 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](docs/workflows/agents.md) is the same
contract in long form.
On `main`, install the contract in every coding-agent session on this machine:
```sh
kata agent-hook install
```
For Codex, open Codex and run `/hooks` to trust the new hook. See
[Contract in every session](docs/workflows/agents.md#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:
```sh
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 spoke-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:
```sh
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](docs/reference/cli.md#workspace-initialization) for contract
deduplication and the separate attention lifecycle.
## Contributing
See [Contributing](docs/development/contributing.md) for the repository layout
and local checks (`make test`, `make lint`, `make vet`, `make nilaway`).
Licensed under the terms in [LICENSE](LICENSE).