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

kata TUI showing a simulated issue hierarchy

The image above is generated from disposable simulated data by the docs screenshot workflow.

Install

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

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

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

Pre-1.0

kata publishes versioned pre-1.0 releases. The CLI, daemon, and TUI are usable, but command contracts and UI details can still change before a stable release.

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 browses, triages, and supervises agent-written work over the same data. No raw JSON required.

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