Quickstart¶

Install kata, enter a workspace, bind it to a kata project, and create your first issue:

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

cd your-repo
kata init
kata create "fix login race"
kata list
kata show abc4

kata create prints the issue's short ID. Use that short ID in later commands. In examples, abc4 means "replace this with the short ID that kata returned".

Close only after the work is complete and verified:

kata close abc4 --done \
  --message "Fixed the login callback race and verified the browser test passes." \
  --commit <sha>

Open the TUI when a human wants to browse or triage:

kata tui

Press ? inside the TUI for keybindings.

Initialize a workspace¶

kata init

kata init writes .kata.toml with a project binding. In a git workspace, kata derives the default project name from the git remote. For a non-git workspace or an explicit shared project name:

kata init --project product

Commit .kata.toml when multiple agents, clones, or worktrees should resolve to the same kata project. The file is intentionally secret-free.

Create and inspect issues¶

kata create "fix login race" \
  --body "Safari can double-submit the callback." \
  --label auth \
  --owner alice \
  --priority 1

kata list
kata show abc4
kata comment abc4 --body "Reproduced on macOS."

Priorities run from 0 to 4; 0 is highest. Omit priority when it is not useful.

Use relationships¶

Relationships are attached to kata create and kata edit. They are framed from the issue being created or edited:

kata create "ship callback fix" --blocked-by abc4
kata edit abc4 --blocks d4ex
kata edit d4ex --related j7m2

Meanings:

--parent is at most one and replaces the existing parent on edit. The other relationship flags are repeatable.

Find ready work¶

kata ready lists open issues with no open predecessor blocking them:

kata ready
kata ready --unowned
kata ready --label backend --no-label blocked

Use kata claim in multi-agent work:

kata claim abc4

The claim fails if another actor already owns the issue unless --force is used.

Set actor identity¶

Actor precedence is:

--as > $KATA_AUTHOR > $USER > git config user.name > anonymous

For an agent session:

export KATA_AUTHOR=codex-wesm-laptop
kata whoami

Output modes¶

Use human output at a terminal. Use --agent for concise logs that are easy for coding agents to quote. Use --json only when a script needs the full response:

kata list --agent
kata list --json | jq .

--format human|json|agent is equivalent to the dedicated switches.

Close with evidence¶

Closing asserts completion. If work is incomplete, add context instead:

kata label add abc4 needs-review
kata comment abc4 --body "Attempted the schema change; migration test still fails."

When work is done, close with a reason, a substantive message, and evidence:

kata close abc4 --done \
  --message "Fixed Safari callback double-submit; verified the browser regression test passes." \
  --commit <sha> \
  --test "go test ./e2e -run TestCallback"

Other close reasons are --wontfix, --duplicate-of <ref>, --superseded-by <ref>, and --audit-no-change.

Close issues as soon as each one is complete and verified. Do not save a batch of sibling closes for the end of a run: the daemon refuses more than three sibling closes by one actor under one parent within 60 seconds.