Agent workflows¶
kata is designed to survive the parts of agent work that chat does not: context compaction, multiple workers, incomplete attempts, and close discipline.
Session start¶
Run from the workspace, or pass --workspace:
Set actor identity once:
Default to --agent for ordinary reads and mutations in agent logs. Use
--json only when the script needs full structured data.
To make a workspace self-documenting for agents, run kata init --with-agents
once. It writes a marker-delimited kata briefing into existing real AGENTS.md
and CLAUDE.md files, or creates AGENTS.md when neither exists. The block
points back at kata quickstart and carries a short work.* attention
conventions section (see
agent orchestration); re-running
refreshes only kata's block, so a repo initialized before that section shipped
gains it on the next run. If a target file still carries a Beads integration
block, kata leaves it untouched
and writes a <file>.kata-proposed sidecar to adopt or discard — see
--with-agents. If
AGENTS.md is a symlink, kata refuses to manage it before reading the target;
replace it with a regular file before using --with-agents.
Guidance files produce tendency, not contract: an agent can still end a session
without updating its issue. For Claude Code workspaces,
kata init --with-hooks additionally installs the
attention harness hooks
as two command-hook lifecycle entries: SessionStart runs kata attention-hook
start for new, resumed, and cleared sessions (but not context compaction), and
SessionEnd runs kata attention-hook end only for terminal exits rather
than clear/resume transitions. Both use the
launcher-provided KATA_REF and intentionally do nothing when it is absent.
For Codex CLI workspaces, kata init --with-codex-hooks installs the start
half of the same wiring into .codex/hooks.json: a SessionStart command
hook runs kata attention-hook start for new, resumed, and cleared sessions
(but not context compaction), using the same launcher-provided KATA_REF.
Codex has no stable session-end hook event yet, so pair this with a launcher
wrapper that runs kata attention-hook end after the codex invocation exits
— see
agent orchestration
for the recipe.
Use Kata through MCP¶
Agents with an MCP client can start Kata as a project-bound stdio server:
The MCP server exposes the normal search, list, show, ready, label discovery, create, edit, comment, claim, label, metadata, close, and reopen workflows. It fixes the project and actor at startup, requires idempotency keys for create and comment, and omits administrative and destructive deletion tools. See the MCP reference for configuration and exact schemas.
Search before creating¶
If no existing issue fits, create with an idempotency key:
kata create "fix login race" \
--body "Observed double-submit in Safari callback." \
--idempotency-key "login-race-2026-05-31" \
--agent
Prefer updating existing issues over opening duplicates:
kata show abc4 --agent
kata comment abc4 --body "Found another reproduction path." --agent
kata label add abc4 safari --agent
kata edit abc4 --blocks d4ex --agent
Claim work¶
In multi-agent environments, choose one unowned ready issue and claim it:
next applies the shared priority rules and returns at most one candidate. The
claim fails if another actor already claimed the issue; treat that as a
coordination signal and run next again.
Use ready when you want to inspect a filtered queue instead of choosing one
issue:
Use the global list when waiting or blocked work must stay visible across
projects. Unlike ready, list does not remove issues with active blockers:
Release ownership only when you are intentionally giving the work back:
Keep durable notes¶
Record decisions, partial attempts, and remaining work in comments:
kata comment abc4 --body "Verified the daemon rejects public IP listeners; docs still need hosted-mode wording." --agent
This is especially important before a long pause, context compaction, or handoff to another agent.
Use relationships deliberately¶
Create child work under a parent issue:
Connect ordering with --blocks or --blocked-by, not comments:
Use --related only for context.
Close only when verified¶
Do not close because work was attempted. Close only when the requested work is complete and freshly verified:
SHA=$(git rev-parse HEAD)
kata close abc4 --done \
--message "Updated the CLI reference and verified docs-check passes." \
--commit "$SHA" \
--test "make docs-check" \
--agent
Close each issue as soon as its work is verified, not in a batch at the end of a run. By default the daemon allows sibling close bursts when each close carries valid evidence and a substantive message. Operators can enable stricter burst/prose throttling when they want pacing in addition to evidence checks. Successful CLI closes also print a reminder that each close is a completion claim and that the message and evidence should be specific to the issue. Closing as you finish each issue leaves a better audit trail. See Close throttle.
If work is incomplete:
kata label add abc4 needs-review --agent
kata comment abc4 --body "Drafted remote-daemon docs; still need token identity verification." --agent
Poll events during long runs¶
For periodic polling:
Remember the returned cursor and resume from it. If the response says
reset_required, discard cached kata state and resume from the reset cursor.
For live streams:
Use --json for consumers that require newline-delimited JSON.
Destructive commands¶
Agents should not run kata delete or kata purge unless the user explicitly
asks for that exact operation and issue ref. delete is reversible; purge is
not.
Recommended operating loop¶
- Read
kata quickstart. - Search for existing work.
- Claim or create one issue.
- Record the intended approach in a comment for large work.
- Implement and verify.
- Commit repository changes.
- Close the issue with evidence as soon as it is verified.
- Move to the next ready issue.