Kata

https://www.katatracker.com
Admin
Kata is a lightweight, local-first issue tracker designed for humans and AI coding agents to manage...
Tokens:46,578
Snippets:456
Trust Score:4.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Check Kata installation with kata version and --help

Source: https://www.katatracker.com/docs/get-started/install

Verifies the installation by printing the version and help output. Use after installing with `go install` or a release binary.

```sh
kata version   # or kata --version
kata --help
```

--------------------------------

### Install Kata to a custom GOBIN with make install

Source: https://www.katatracker.com/docs/get-started/install

Overrides the install directory for `make install` by setting `GOBIN` to `/usr/local/bin`. Use when you want the binary in a system-wide location.

```sh
make install GOBIN=/usr/local/bin
```

--------------------------------

### Install docs toolchain with make docs-install

Source: https://www.katatracker.com/docs/get-started/install

Installs the documentation toolchain into a local virtual environment. Run this before building or previewing the site.

```sh
make docs-install
```

--------------------------------

### Install Kata with go install

Source: https://www.katatracker.com/docs/get-started/install

Installs the Kata CLI, daemon, and TUI from the module source. Go does not run the browser asset toolchain, so `kata ui` requires a release binary or a clone built with `make install` to embed the compiled browser bundle. The binary is written to `$(go env GOBIN)` when set, otherwise to `$(go env GOPATH)/bin`.

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

--------------------------------

### Quickstart: initialize, create, list, close, and browse issues

Source: https://www.katatracker.com/docs

Quickstart workflow: initialize a project, create an issue, list open work, close a verified issue with a message and commit SHA, then browse via TUI or browser UI.

```bash
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
```

--------------------------------

### Install kata on Linux with curl

Source: https://www.katatracker.com/docs

Install kata on Linux using the provided installation script.

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

--------------------------------

### Build Kata from a clone on macOS or Linux

Source: https://www.katatracker.com/docs/get-started/install

Builds and installs Kata from a clone on macOS or Linux. `make install` honors `GOBIN` and defaults to `~/.local/bin`.

```sh
git clone https://github.com/kenn-io/kata.git
cd kata
make install
```

--------------------------------

### Install kata on Windows with PowerShell

Source: https://www.katatracker.com/docs

Install kata on Windows using PowerShell.

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

--------------------------------

### Install kata on macOS with Homebrew

Source: https://www.katatracker.com/docs

Install kata on macOS using Homebrew.

```bash
brew install kata
```

--------------------------------

### Start a kata session and list agents

Source: https://www.katatracker.com/docs/workflows/agents

Run from the workspace or pass --workspace. Lists agent-related items.

```sh
kata quickstart
kata list --agent
```

--------------------------------

### Initialize with agent guidance using kata init --with-agents

Source: https://www.katatracker.com/docs/get-started/quickstart

Initializes a workspace and also writes a marker-delimited block where coding agents look for workspace guidance, pointing them at kata quickstart and the close discipline. If AGENTS.md and/or a real, non-symlinked CLAUDE.md already exist, kata refreshes each of those files; if neither exists, kata creates AGENTS.md. The block is idempotent: re-running refreshes kata's section in place and leaves the rest of each file untouched. The flag is off by default, so a plain kata init still writes only .kata.toml.

```sh
kata init --with-agents
```

--------------------------------

### Start Kata MCP stdio server

Source: https://www.katatracker.com/docs/workflows/agents

Starts Kata as a stdio MCP server bound to the current workspace's project. Use this for agents with an MCP client that can launch a stdio subprocess.

```sh
kata mcp serve
```

--------------------------------

### Open the Web UI with kata ui

Source: https://www.katatracker.com/docs/guide/web-ui

Starts or discovers the local daemon and opens its Inbox in the browser.

```sh
kata ui
```

--------------------------------

### Configure GitHub App credential in config.toml

Source: https://www.katatracker.com/docs/operations/github-sync

Configure a GitHub App installation credential in <KATA_HOME>/config.toml for shared or hosted daemons. The App needs only read access: Metadata: read and Issues: read. App entries are matched exactly by normalized (host, owner).

```toml
[[github_sync.app]]
host = "github.com"
owner = "example-org"
app_id = 12345
installation_id = 67890
private_key_path = "/var/lib/kata/github-app.pem"
```

--------------------------------

### Restore JSONL backup into Postgres with kata import DSN

Source: https://www.katatracker.com/docs/operations/backup-restore

Restore a JSONL backup into a Postgres database by passing a DSN as the target. A missing kata schema is installed before the snapshot is replayed. An initialized target is refused unless --force is set; forced replay replaces all kata-owned state atomically and retains unrelated schemas. In a split-role deployment, --target must use the schema-owner credential. Stop every daemon using that database and schema before restore; each serving daemon holds a database advisory lease for its lifetime, and replay requires the exclusive counterpart. Postgres credentials are redacted from command output and errors.

```sh
kata import --input backups/kata-20260531.jsonl \
  --target 'postgres://kata_schema_owner@db.example/kata?sslmode=verify-full&sslrootcert=system'
```

--------------------------------

### Start Kata MCP HTTP server with bearer token

Source: https://www.katatracker.com/docs/workflows/agents

Starts Kata as a Streamable HTTP MCP server. Requires an environment-sourced bearer token set via KATA_MCP_HTTP_TOKEN. The listener binds to 127.0.0.1:8080 and reads the token from the specified environment variable.

```sh
export KATA_MCP_HTTP_TOKEN='<random bearer token>'
kata mcp serve \
  --http 127.0.0.1:8080 \
  --http-token-env KATA_MCP_HTTP_TOKEN
```

--------------------------------

### Start Kata MCP server with stdio transport

Source: https://www.katatracker.com/docs/reference/mcp

Start the Kata MCP server with stdio transport. The default uses the current workspace's project; use --workspace or --project to select one explicitly, --projects for a fixed allowlist, --all-projects for every project visible to the daemon, and --enable-token-admin to add daemon credential administration. With stdio, JSON-RPC uses stdin/stdout and no status text or logs are written to stdout.

```sh
# The current workspace's project (default)
kata mcp serve

# One explicit project
kata --workspace /path/to/repository mcp serve
kata --project example-project mcp serve

# A fixed project allowlist
kata mcp serve --projects example-project,shared-project

# Every project visible to the selected daemon
kata mcp serve --all-projects

# Add explicit daemon credential administration
kata mcp serve --all-projects --enable-token-admin
```

--------------------------------

### Get spoke instance UID with kata federation identity

Source: https://www.katatracker.com/docs/operations/federation

Get the spoke instance UID from the spoke daemon. Run from the spoke worktree before enrolling. The output has the shape `instance: <spoke-instance-uid>`.

```sh
cd <spoke-worktree>
kata federation identity
```

--------------------------------

### Run kata with --workspace flag

Source: https://www.katatracker.com/docs/guide/concepts

Use the --workspace flag to run a command from a different directory. This example lists issues in the project at ~/code/product.

```sh
kata --workspace ~/code/product list
```

--------------------------------

### Get spoke instance UID with kata federation identity

Source: https://www.katatracker.com/docs/operations/federation

Get each spoke's instance UID from that spoke daemon. The output is needed for the --spoke-instance flag when enrolling the spoke.

```sh
kata federation identity
```

--------------------------------

### Session-start hook: mark attention ok

Source: https://www.katatracker.com/docs/operations/agent-orchestration

Session-start hook that marks the issue in-progress and healthy. It runs when the agent session starts and sets the attention to 'ok'.

```sh
# runs when the agent session starts
kata meta set "$KATA_REF" work.attention ok
```

--------------------------------

### GET /quarantine/list

Source: https://www.katatracker.com/docs/operations/federation

Lists all active quarantine records for the federation spoke.

```APIDOC
## [GET] /quarantine/list

### Description
Lists active quarantine records for the federation spoke.

### Method
GET

### Endpoint
/quarantine/list

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **quarantines** (array) - List of quarantine records

#### Response Example
{
  "quarantines": []
}
```

--------------------------------

### GET /quarantine/show/{id}

Source: https://www.katatracker.com/docs/operations/federation

Shows details of a specific quarantine record, including the retained error and event range.

```APIDOC
## [GET] /quarantine/show/{id}

### Description
Shows details of a specific quarantine record.

### Method
GET

### Endpoint
/quarantine/show/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The quarantine record identifier.

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - The quarantine record identifier.
- **error** (string) - The retained error message.
- **event_range** (object) - The retained event range.

#### Response Example
{
  "id": "123",
  "error": "issue.updated references unknown issue",
  "event_range": {}
}
```

--------------------------------

### Build and preview docs with make docs-build and make docs-serve

Source: https://www.katatracker.com/docs/get-started/install

Builds the site with make docs-build and previews it locally with make docs-serve. These are separate commands for building and serving the documentation.

```sh
make docs-build
```

```sh
make docs-serve
```

--------------------------------

### Check for kata updates

Source: https://www.katatracker.com/docs/get-started/install

Check for newer kata releases after installation. Works for all installation methods. For package-managed installations, this is the only update form available.

```sh
kata update --check
```

--------------------------------

### Update kata from release assets

Source: https://www.katatracker.com/docs/get-started/install

Install an available kata update from GitHub release assets. Verifies the downloaded archive against SHA256SUMS before replacing the installed binary. For ordinary release archive or installer-based installations.

```sh
kata update
```

--------------------------------

### Initialize and enable federation for a hub project

Source: https://www.katatracker.com/docs/operations/federation

Create or register the hub project explicitly with kata init, then enable federation explicitly with kata federation enable. Enrollment auto-creates and auto-enables the project if not already present or federated.

```sh
kata init --project fedlab
```

```sh
kata federation enable --project fedlab
```

--------------------------------

### Build Kata on Windows with go build

Source: https://www.katatracker.com/docs/get-started/install

Builds the Kata binary on Windows using PowerShell or `cmd.exe`. The resulting `kata.exe` must be moved to a directory on `PATH`.

```powershell
git clone https://github.com/kenn-io/kata.git
cd kata
go build -o kata.exe ./cmd/kata
```

--------------------------------

### Enable host storage with kata mcp serve --all-projects

Source: https://www.katatracker.com/docs/reference/mcp

Enable JSONL storage access on the daemon host. Requires the --all-projects daemon-wide scope; --storage-target is repeatable and accepts alias=path-or-DSN pairs. Tool calls select an alias, not a direct path or DSN.

```sh
kata mcp serve --all-projects \
  --storage-root /srv/kata/exchange \
  --storage-target restore=restore.db
```

--------------------------------

### Adopt an existing project with kata federation join --adopt-existing

Source: https://www.katatracker.com/docs/operations/federation

Adopts an existing non-federated spoke project into the hub. Requires `--push` and an enrollment token created with adoption enabled. The spoke and hub project names do not have to match; run `kata federation enroll --adopt-existing` first, then select the spoke project with `--project` and the hub with the hub selector. Adoption preserves current local issue state but removes pre-adoption local events and queues fresh snapshots for the hub.

```sh
kata federation join --project fedlab \
  --hub-url http://100.64.0.5:7787 \
  --hub-project-id 1 \
  --token ... \
  --actor wesm \
  --push \
  --adopt-existing
```

--------------------------------

### Join a spoke project to a hub with kata federation join

Source: https://www.katatracker.com/docs/operations/federation

Joins a spoke project to a hub using the enrollment token printed by `enroll`. The hub must be reachable and the token must include `pull`. Creates a spoke replica bound to the hub project UID and replay horizon, stores hub URL/project/token locally, and enables push only when `--push` is present. `--actor` is required and should be copied from the printed join command.

```sh
kata federation join --project fedlab \
  --hub-url http://100.64.0.5:7787 \
  --hub-project-id 1 \
  --token ... \
  --actor wesm \
  --push
```

--------------------------------

### Expected enrollment output

Source: https://www.katatracker.com/docs/operations/federation

Expected output from `kata federation enroll`. The printed join command includes `--adopt-existing` when the hub project already exists; otherwise it is omitted. If the spoke project name differs, replace `--project <hub-project>` with `--project <spoke-project>` and use `--adopt-existing` when creating the enrollment.

```text
enrolled <spoke-instance-uid> for <hub-project>
join: kata federation join --project <hub-project> --hub-url <hub-api-url> --hub-project-id <hub-project-id> --token <enrollment-token> --capabilities pull,push,lease --actor <actor> --push --adopt-existing
```

--------------------------------

### Create a project by name

Source: https://www.katatracker.com/docs/guide/workspaces-projects

Creates a project by name without binding the current directory. Talks to the daemon only; does not write .kata.toml, .gitignore, or agent guidance files, and does not attach a git alias. Use for projects that do not map one-to-one to a repository workspace, then run kata init --project research later from any workspace that should resolve to the same project.

```sh
kata projects create research
```

--------------------------------

### Example of imported issue title with prefix

Source: https://www.katatracker.com/docs/operations/github-sync

Shows the default title format for imported issues, which includes the GitHub issue number as a prefix.

```text
[GitHub #123] Original issue title
```

--------------------------------

### Versioned backup with Git and kata export

Source: https://www.katatracker.com/docs/operations/backup-restore

Creates a local Git repository and exports a full JSONL snapshot, then commits it. Stop the daemon before exporting to avoid concurrent writes, and restart it afterward. Schedule with cron, launchd, or a systemd timer and push to a private remote for off-host storage.

```sh
mkdir -p ~/kata-backups
cd ~/kata-backups
git init -q
kata daemon stop
kata export --output snapshot.jsonl
kata daemon start
git add snapshot.jsonl
git commit -q -m "snapshot $(date -u +%FT%TZ)"
```

--------------------------------

### kata federation operator commands

Source: https://www.katatracker.com/docs/operations/federation

Use these commands to manage federation: identity, enable, enroll, join, list enrollments, revoke, leave, rebind, status, and lease operations. The enroll command creates the project on the hub if it does not exist, then enables federation and creates the enrollment. The status command reports local bindings, enabled/push state, cursors, pending push depth, sync timestamps, enrollment counts, lease counts, quarantine counts, reset blockers, and recent lease violations.

```sh
kata federation identity
kata federation enable --project <project>
kata federation enroll --project <project> --spoke-instance <uid> --hub-url <url> \
  --actor <actor> [--allow-insecure]
kata federation join --project <project> --hub-url <url> --hub-project-id <id> \
  --token <token> --actor <actor> [--push]
kata federation enroll --project <project> --spoke-instance <uid> \
  --hub-url <http-hostname-url> --actor <actor> --allow-insecure
kata federation join --project <project> --hub-url <http-hostname-url> \
  --hub-project-id <id> --token <token> --actor <actor> --allow-insecure [--push]
kata federation join --project <existing-project> --hub-url <url> \
  --hub-project-id <id> --token <token> --actor <actor> --push --adopt-existing
kata federation enrollments list
kata federation revoke <enrollment-id>
kata federation leave <project> [--delete [--force]] [--local-only] [--hub <name>]
kata federation rebind <project> --hub <name>
kata federation rebind --all --hub <name>
kata federation status
kata federation status --json
kata federation lease acquire <issue-ref> [--ttl 30m]
kata federation lease renew <issue-ref> --ttl 30m
kata federation lease release <issue-ref>
```

--------------------------------

### Operating loop: kata next, claim, comment, close

Source: https://www.katatracker.com/index.md

Shows the core CLI workflow for an agent: list an unowned issue, claim it, add a comment, and close it with a commit reference. Each command returns an OK status with details.

```sh
# the operating loop, at local speed
kata next --unowned --agent      # OK next issue=abc4 priority=1 title="fix login race"
kata claim abc4 --agent          # OK claim abc4
kata comment abc4 --body "root cause: double submit in Safari callback"
kata close abc4 --done --message "Fixed the race; tests pass." --commit 4f2a91c
```

--------------------------------

### Poll or stream events with kata events

Source: https://www.katatracker.com/docs/workflows/agents

Use the first command for periodic polling of events, starting from cursor 0 and limiting to 100 events. The second command streams events live. Both require the --agent flag; add --json for newline-delimited JSON output.

```sh
kata events --after 0 --limit 100 --agent
```

```sh
kata events --tail --agent
```

--------------------------------

### Run MCP server over HTTP with non-loopback listener

Source: https://www.katatracker.com/docs/reference/mcp

Run the MCP server over HTTP on a non-loopback listener. Requires --trust-private-network and a literal non-public IP or wildcard bind; public IPs and DNS hostnames are rejected. Use only on an operator-trusted private network or behind an HTTPS reverse proxy. The listener also serves unauthenticated GET and HEAD at /healthz with readiness text and caching disabled.

```sh
kata mcp serve --all-projects \
  --http 0.0.0.0:8080 \
  --http-token-env KATA_MCP_HTTP_TOKEN \
  --trust-private-network
```

--------------------------------

### Disposable validation run with kata sync

Source: https://www.katatracker.com/docs/operations/github-sync

Run a disposable validation against a real repository. Sets up a temporary KATA_HOME and workspace, writes a config.toml with GitHub token environment and host, then initializes, enables sync, runs sync twice, checks status, lists issues, and shows an imported issue. The first 'once' validates fetching; the second should report mostly unchanged issues.

```sh
validation_home="$(mktemp -d)"
validation_ws="$(mktemp -d)"

export KATA_HOME="$validation_home"
export KATA_AUTHOR=github-sync-validation
export KATA_GITHUB_TOKEN="$EXAMPLE_GITHUB_TOKEN"

cat >"$KATA_HOME/config.toml" <<'EOF'
[github_sync]
token_env = "KATA_GITHUB_TOKEN"
token_host = "github.com"
EOF

cd "$validation_ws"
kata init --project github-sync-validation
kata sync github enable --repo example-org/example-repo --interval 24h
kata sync github once
kata sync github status --json
kata sync github once
kata list --status all --limit 20
kata show <imported-ref> --json

```

--------------------------------

### Configure stdio client for kata mcp serve

Source: https://www.katatracker.com/docs/reference/mcp

Configure a stdio MCP client to launch the Kata MCP server. The server binds to the current workspace's project by default, and the daemon's API version must be at least 0.11.0.

```json
{
  "command": "kata",
  "args": ["mcp", "serve"]
}
```

--------------------------------

### List and show projects

Source: https://www.katatracker.com/docs/guide/workspaces-projects

Lists all projects and shows details for a specific project. Use kata projects show <project> before destructive or structural operations to know which project and aliases are affected.

```sh
kata projects list
kata projects show product
```

--------------------------------

### Run one GitHub sync immediately

Source: https://www.katatracker.com/docs/operations/github-sync

Runs a single sync immediately, useful for a first test or manual catch-up. The daemon polls enabled bindings on their interval.

```sh
kata sync github once
```

--------------------------------

### Join spoke to hub with kata federation join

Source: https://www.katatracker.com/docs/operations/federation

Run from the spoke worktree to join an existing spoke project to a hub. Requires the enrollment token printed by `kata federation enroll` and the spoke instance UID from `kata federation identity`. Includes `--adopt-existing` because the hub project already exists; omit it for a new empty spoke replica.

```sh
cd <spoke-worktree>

kata federation join --project <spoke-project> \
  --hub-url <hub-api-url> \
  --hub-project-id <hub-project-id> \
  --token <enrollment-token> \
  --capabilities pull,push,lease \
  --actor <actor> \
  --push \
  --adopt-existing
```

--------------------------------

### Initialize local shared project with kata init

Source: https://www.katatracker.com/docs/workflows/sharing

Initializes a local shared project with the specified project name. This is the default shape for agent coordination on one workstation, where all workspaces commit the same .kata.toml project name and use the same local KATA_HOME database.

```sh
kata init --project product
```

--------------------------------

### Rejoin a left project with kata federation join

Source: https://www.katatracker.com/docs/operations/federation

Use to rejoin a local project that has left a hub project. The local project retains the hub project's UID, so this command rebinds the existing local project instead of creating a second replica. Pull restarts from the hub's replay horizon and deduplicates already-applied events; a push-enabled rejoin re-offers local-origin events from the beginning. Rejoin with the same actor the enrollment is bound to; events authored as a different actor are rejected and quarantined.

```sh
kata federation join --project <spoke-project> --hub-url <url> \
  --hub-project-id <id> --token <fresh-enrollment-token> --actor <actor> --push
```
Tokens:
Raw