Skip to content

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.

Install Quickstart

Two ways to supervise

kata TUI showing a simulated issue hierarchy

kata tui keeps triage in the terminal. kata ui opens the same ledger in a full browser workspace:

kata Web UI showing a synthetic project and issue hierarchy

Both images are generated from disposable synthetic data by the docs screenshot workflow. See the Web UI guide for projects, collections, issue editing, relationships, recurrences, and configured-daemon switching.

Install

brew install kata

Or install the ordinary release archive:

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

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

If you already use Homebrew on Linux or WSL 2:

brew install kata

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

The release installers detect your OS and CPU architecture, download the latest GitHub release archive, and verify it against SHA256SUMS before installing. Confirm the install with:

kata version

Prefer go install, .deb/.rpm packages, or building from source? See Install.

Stable

Since v0.14.0, kata releases preserve backward compatibility across upgrades.

Why kata

  • Built for agents

    Stable short refs, --json and --agent output, idempotent creates, a claim flow, semantic-aware search, 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 daemon serves the browser app directly.

  • 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.

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

# close only when the work is verified
kata close abc4 --done \
  --message "Fixed the login race; tests pass." --commit <sha>

kata tui                               # browse and triage interactively
kata ui                                # open the browser application

kata create prints each issue's short id; use it in later commands. Working with coding agents? kata init --with-agents drops kata's operating contract into AGENTS.md/CLAUDE.md, and kata quickstart prints the full agent contract. See the Quickstart for the complete walkthrough.

How it works

The kata CLI resolves a project from your workspace, .kata.toml, or --project, then talks to a local daemon, starting one automatically when needed. The daemon owns a SQLite database under KATA_HOME, applies mutations, and records an event stream that both the CLI/TUI and hooks read. Search is lexical by default and can opt into semantic search with a local or hosted OpenAI-compatible embeddings endpoint. Optional GitHub sync can mirror upstream GitHub issues into kata, and federation can replicate selected projects through a hub. Your repo commits only the small .kata.toml binding, so issue history stays out of code history. Private-network remote daemon modes are explicit: operators can use bearer auth on trusted private HTTP or opt a single-user private IP into tokenless writes. See Concepts and Architecture for the full model.

Go applications can also run kata in-process through the listener-free go.kenn.io/kata service. The host application mounts the same HTTP API and owns the listener, authentication boundary, and process lifecycle; see Embedding kata in Go.

When to use kata

Reach for kata when work should stay close to the machine doing it:

  • coding agents need to discover, claim, update, and close work from the CLI;
  • you want an instant terminal loop instead of a browser session;
  • work spans local clones, worktrees, experiments, or non-git directories;
  • task state should survive chat compaction without becoming a markdown plan;
  • closes should carry evidence and an audit trail.

kata is not a SaaS issue tracker. Linear, Jira, GitHub Issues, and ClickUp are shared online systems for roadmaps, dashboards, and cross-team reporting; kata is a local ledger for the work itself. They coexist. See Comparisons for the trade-offs.

Next steps