AI工作流

Install

kata is a single Go binary with no runtime dependencies and builds on macOS, Linux, and Windows. Pre-built release binaries are not published yet; install from source using one of the options below. All paths require Go 1.26 or later (<https://go.dev/dl/>).

`go install` (any platform)

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

Go places kata in $(go env GOBIN), falling back to $(go env GOPATH)/bin (typically ~/go/bin on Unix, %USERPROFILE%\go\bin on Windows). Add that directory to your PATH.

Build from a clone (macOS / Linux)

make install                            # installs to ~/.local/bin
make install GOBIN=/usr/local/bin       # or set GOBIN to install elsewhere

Add the install directory to your PATH if it isn't already. GOBIN from the environment is also honored (export GOBIN=/opt/bin && make install).

Build from a clone (Windows)

PowerShell or cmd.exe:

```powershell go build -o kata.exe ./cmd/kata

Quick Start

go install go.kenn.io/kata/cmd/kata@latest   # or see Install for other options

cd your-repo
kata init                                         # bind this workspace to a kata project
kata create "fix login race"                      # returns the issue's short_id, e.g. abc4
kata list                                         # list open issues
kata show abc4                                    # inspect by short_id
kata close abc4 --done --message "Fixed the issue and verified the relevant tests pass." --commit <sha>
kata tui                                          # browse and triage interactively

See Install for go install, build-from-source, and Windows instructions; see Working with kata for a longer walkthrough.

Agent Quickstart

This is the short version to give any coding agent, regardless of whether that agent supports skills, memories, or custom instructions. It is also shipped with the CLI:

kata quickstart
kata agent-instructions   # alias

Session setup:

- Run from the project workspace, or pass --workspace <path>. - Set KATA_AUTHOR once at session start. - Default to --agent for ordinary kata reads and mutations in agent logs. - Use --json only when your script needs complete structured data, for example when piping into jq.

Per-task guidelines:

- Never create a project implicitly. If the workspace is not initialized, report that kata init is needed. - Search before creating; pass an idempotency key when you do create. - Prefer updating existing issues over opening duplicates. - Close only when the work is actually complete. - Do not run delete or purge unless the user explicitly asks for that exact destructive action and issue ref.

Use relationships deliberately. The link types mean:

Example session (using abc4 as a placeholder for the issue's actual short_id, which kata create --agent and kata search --agent both return):

```sh

Configuration

Useful environment variables:

- KATA_HOME: data directory. Defaults to ~/.kata. - KATA_DB: explicit SQLite database path. - KATA_AUTHOR: default actor for mutations. - KATA_HTTP_TIMEOUT: per-request CLI timeout for non-streaming daemon calls (any time.ParseDuration string, e.g. 30s, 2m). Defaults to 5s. Bump this for bulk imports where create requests can exceed the default. - KATA_SERVER: opt-in remote daemon URL (e.g. http://100.64.0.5:7777). When set, the client skips local discovery and auto-start entirely. See "Remote daemon" below. - XDG_RUNTIME_DIR: runtime socket parent on Unix.

The workspace binding file is intentionally secret-free:

version = 1

[project]
name = "product"

Commit .kata.toml when multiple agents, clones, or worktrees should resolve to the same kata project.

Sharing and multi-user workflows

Today kata is local-first:

• one local daemon;
• one local SQLite database;
• no authentication;
• trusted same-user CLI and TUI clients.

Multiple checkouts or repositories can share one kata project when they use the same .kata.toml project name and run kata init in each checkout. That shares the issue ledger — short_ids, labels, links, and events — across those workspaces in the same local database.

If a repository rename accidentally creates a second project, merge the old source into the surviving target, for example:

kata projects merge old-repo new-repo --rename-target new-repo

Future shared mode should be a distinct deployment:

• a shared kata server reachable over HTTPS, SSH tunnel, or a private network;
• authenticated users and service tokens;
• server-derived actor identity;
• server-side hooks and backups;
• the same project, issue, event, and relationship model.

The local daemon should not be exposed directly to a LAN or public network.