kata
The issue tracker built for coding agents and the humans steering them.
코딩 에이전트는 작업 추적을 위한 내구성이 있는 공간이 필요합니다. 채팅 스레드나 마크다운 할 일 목록으로는 부족합니다. kata는 에이전트가 CLI(Command Line Interface)를 통해 관리할 수 있는 로컬 작업 원장(local task ledger)을 제공합니다: 이슈 생성, 소유권 주장(claim), 관련성 부여(relate), 그리고 증거와 함께 종결 처리까지 가능합니다. 인간 사용자는 터미널 UI에서 동일한 작업을 감독합니다. 기본적으로 이슈 상태는 로컬 SQLite 데이터베이스에 저장되므로, 리포지토리는 깨끗하게 유지되며 별도의 호스팅 트래커가 필요하지 않습니다. 인간 팀과 에이전트가 공유해야 할 경우, 원격 데몬(remote daemon) 또는 연합(federation)을 선택할 수 있습니다. 공유 데몬의 경우 KATA_DSN 설정을 통해 Postgres를 사용할 수 있습니다. 프로덕션 Postgres 배포에서는 별도의 스키마 소유자(schema-owner) 및 런타임 역할(runtime roles)을 사용할 수 있습니다. 자세한 내용은 operator ceremony를 참조하십시오.
Go 애플리케이션의 경우, kata의 리스너가 없는 HTTP 서비스(listener-free HTTP service)를 인프로세스(in-process)로 마운트할 수 있습니다. 자세한 내용은 Embedding kata in Go를 참조하십시오.
MCP 클라이언트는 kata mcp serve 명령어를 사용하여 stdio 또는 Streamable HTTP를 통해 Kata의 네이티브 서버를 시작할 수 있습니다. 기본적으로 현재 작업 공간의 프로젝트를 바인딩하며, 요청에 따라 고정된 허용 목록(fixed allowlist)이나 전체 데몬 카탈로그를 제공할 수 있습니다. 섹션 로더는 kata의 타입 지정 이슈, 관리, 자동화 및 이벤트 워크플로우를 점진적으로 노출합니다. MCP reference를 참조하십시오.
The documentation in docs/ is the definitive guide, published with Zensical at https://katatracker.com/.
Stable: Since v0.14.0, kata releases preserve backward compatibility across upgrades.
The latest release is 0.20.0. It adds an Attention inbox to the terminal UI, requests for replies to specific comments, participant broadcasts, and events for reached schedules. See Updating Kata for installation and federation upgrade guidance.
Install
macOS:
Linux, or macOS without Homebrew:
curl -fsSL https://katatracker.com/install.sh | bash
Linux 및 WSL 2 사용자로 이미 Homebrew를 사용하는 경우, brew install kata도 실행할 수 있습니다.
Windows PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://katatracker.com/install.ps1 | iex"
설치 프로그램은 사용자의 OS와 CPU 아키텍처를 감지하고, 최신 GitHub 릴리스 아카이브를 다운로드한 다음, SHA256SUMS를 통해 이를 검증하여 설치합니다. 다음 명령어로 설치를 확인하세요:
릴리스-아카이브 빌드는 kata update으로 자체 업데이트됩니다. Homebrew 설치는 brew upgrade kata를 사용하며, Linux의 .deb 및 .rpm 패키지는 amd64와 arm64용으로 게시되며 시스템 패키지 관리자가 소유합니다. 소스에서 빌드하는 것을 선호합니까? kata는 Go 1.27.3 이상이 필요합니다:
go install go.kenn.io/kata/cmd/kata@latest
모듈-소스(Module-source) 설치에는 CLI, 데몬, TUI가 포함되지만 컴파일된 브라우저 번들은 포함되지 않습니다. kata ui를 사용하려면 릴리스 바이너리를 설치하거나 make install을 사용하여 클론에서 빌드하세요.
Go는 $(go env GOBIN)에 설치되며, $(go env GOPATH)/bin (일반적으로 ~/go/bin)으로 폴백됩니다. 해당 디렉토리를 PATH에 추가해야 합니다. 패키지 다운로드, 수동 릴리스 다운로드 및 소스에서 빌드하는 단계는 Install를 참조하세요.
flowchart TB
arrive{"작업 도착"} --> search["먼저 검색: <br/>kata search #34;#60;terms#62;#34; --agent<br/>열려 있는 이슈를 재사용하거나, 새로 생성합니다.<br/>만약 생성이 유사한 항목을 거부하면, 그것을 재사용합니다;<br/>--force-new는 작업이 실제로 다른 경우에만 사용합니다.<br/>바운드 워크스페이스 없음: refs는 #60;project#62;##60;id#62;,<br/>또는 --project #60;project#62;를 전달합니다.]
search --> route{"작업 처리, 또는 위임?"}
...
빠른 시작(Quickstart)
cd your-repo
kata init
kata create "fix login race"
...
kata create는 각 이슈의 짧은 ID를 출력하므로, 이후 명령어에서 이를 사용하세요. 작업이 완료되고 검증될 때만 닫으세요:
kata close abc4 --done \
--message "Fixed the login race and verified the relevant tests pass." \
--commit <sha>
특정 댓글에 답글을 달고, 해당 댓글이 속한 스레드를 읽어보십시오:
kata comment abc4 --reply c:xbzxrq -m "This builds on the finding."
kata show abc4 --thread c:xbzxrq
TUI와 Web UI는 원본 댓글에 대해 승인된 직접 관계의 0이 아닌 개수를 표시합니다. 개수를 열어 작성자, 시간, 핸들(handle), 본문과 함께 연대기적 증거를 검사한 다음, 해당 위치로 이동하여 포커스를 되돌립니다. TUI는 키보드 피커를 사용하며, 웹 컨트롤은 접근 가능합니다. 답글은 나가는 관계(outgoing relation)를 보여줍니다. 부분적인 개수는 명시적으로 유지됩니다. 상충되는 주장들은 점수 부여, 자동 해결 또는 숨김 없이 함께 보이게 됩니다. 보류 중이거나(Pending), 제거되었거나(removed), 이동했거나(moved), 편집된 대상은 계속 표시됩니다.
응답이 그러한 의미를 가질 때 --confirm, --refute, 또는 --supersede를 사용합니다.
핸들(handle)과 재시도에 대해서는 발견에 답글 달기를 참조하십시오. 답글 알림 및 코디네이터 브로드캐스트가 계획되어 있습니다. 소유권이나 추적된 완료가 필요한 작업의 경우, 댓글 크기의 작업이 자식 이슈(child issue)가 됩니다.
에이전트(agent) 중심의 작업 공간에서는 kata init --with-agents가 관리되는 kata 브리핑을 에이전트 가이드 파일에 작성합니다. 이 명령어는 기존의 실제 AGENTS.md 및 CLAUDE.md 파일을 새로 고치거나, 둘 다 존재하지 않을 경우 AGENTS.md를 생성하며, 어느 파일의 나머지 부분도 덮어쓰지 않습니다. Codex 전용 작업 공간에서는 대신 kata init --with-codex-hooks를 사용하여 동적 계약 컨텍스트(dynamic contract context)와 work.attention 세션 시작 라이프사이클(SessionStart lifecycle)을 .codex/hooks.json에 설치할 수 있습니다.
왜 kata인가
- 에이전트를 위해 구축됨(Built for agents). 안정적인 짧은 참조(stable short refs),
--json 및 --agent 출력, 반복 실행 가능한 생성(idempotent creates), 의미론적 인식 검색(semantic-aware search), 클레임 플로우(claim flow) 그리고 에이전트가 스크립팅할 수 있는 예측 가능한 실패 모드까지 지원합니다.
- 인간을 위해서도 제작됨(Made for humans too).
kata tui와 kata ui를 사용하여 동일한 데이터에 대해 에이전트가 작성한 작업을 탐색(browse), 분류(triage), 감독할 수 있습니다. 브라우저 앱은 데몬(daemon)에 의해 서비스되며 별도의 백엔드가 필요하지 않습니다.
- 로컬 우선 및 레포지토리 클린(Local-first, repo-clean). 하나의 Go 바이너리이며 런타임 종속성이 없습니다. 이슈 상태는
KATA_HOME 아래의 SQLite에 저장되며, 레포지토리는 작고 비밀 정보가 없는 .kata.toml 파일만 커밋합니다.
- 설계상 감사 가능(Auditable by design). 이슈를 닫는 것은 수정 가능한 댓글과 영구적인 이벤트 위에 이유, 메시지, 증거, 행위자 귀속을 포함하는 명시적 완료 클레임입니다.
kata 비교 방식
kata는 의도적으로 작습니다. 이는 프로젝트 관리 스위트(project-management suite)가 아니며, git 워크플로우 엔진이나 에이전트 작업 풀(agent worker pool)도 아닙니다. 인간과 에이전트 모두가 작동할 수 있는 영구적인 작업 원장(durable task ledger)입니다.
또한 SaaS 이슈 트래커도 아닙니다. Linear, Jira, GitHub Issues, ClickUp 및 유사 도구들은 계획, 대시보드, 할당, 교차 팀 보고를 위한 공유 온라인 시스템입니다. kata는 로컬 우선이며 CLI/TUI에서 즉각적으로 사용 가능하고, 에이전트 중심의 인체공학(agent-first ergonomics)을 기반으로 설계되었습니다: 안정적인 참조, 예측 가능한 출력, 반복 실행 가능한 생성, 클레임 플로우, 그리고 증거 기반의 종료 기능입니다. 매트릭스는 SaaS 이슈 트래커와의 비교를 참고하십시오.
Beads는 프로젝트 로컬의 .beads/ Dolt 데이터베이스에 네이티브 히스토리(history), 브랜칭(branching), 푸시/풀(push/pull) 기능과 함께 이슈 상태를 유지합니다. git-bug는 이슈를 커스텀 레퍼런스(custom refs) 아래의 git 객체로 저장하고, 이를 git push와 git pull을 통해 동기화합니다.
kata는 다른 접근 방식을 취합니다: 원장(ledger)을 저장소에 포함된 데이터가 아니라 워크스페이스 옆의 로컬 서비스로 만듭니다. 이 방식은 워크스페이스를 깔끔하게 유지하고, git이 아닌 디렉토리에서도 동일하게 작동하며, 이슈 히스토리를 코드 히스토리와 분리합니다. 단점은 kata가 공유를 위해 git 원격(git remotes)을 사용하지 않는다는 것이며, 대신 리모트 데몬(remote daemon)과 페더레이션(federation)이 이 역할을 담당합니다.
Beads에서 이동하나요? Migrating from Beads를 참조하세요.
kata import --source-format beads는 bd CLI를 실행하여 사용자의 이슈들을 kata 프로젝트로 병합합니다.
문서 (Documentation)
docs 사이트가 최종 참고 자료입니다:
Remote daemon ·
Federation ·
Hosted mode ·
Containers ·
PostgreSQL ·
Backup and restore
코딩 에이전트를 위해 (For coding agents)
운영 계약(operating contract)을 위해 kata quickstart를 실행하거나 (별칭: kata agent-instructions) 다음 사항들을 준수해야 합니다. 생성 전에 검색하고, 생성 시 멱등성 키(idempotency key)를 전달하며, --agent 출력을 선호하고, kata claim으로 작업을 주장하며, 작업이 검증되었을 때만 종료합니다. 각 검증된 이슈는 유효한 증거와 실질적인 메시지를 포함하여 즉시 닫아야 합니다. 에이전트 워크플로우에는 이 계약의 장문 버전이 담겨 있습니다.
main 브랜치에서, 이 머신상의 모든 코딩 에이전트 세션마다 다음 명령어를 설치합니다:
Codex를 사용하는 경우, Codex를 열고 /hooks를 실행하여 새 후크(hook)에 대한 신뢰를 부여하십시오. 모든 18개 대상(targets), 런타임 요구 사항, 어텐션 기능(attention capabilities) 및 추가적인 Codex 홈(homes)에 대해서는 모든 세션에서의 계약을 참조하십시오. 계약과 사용 가능한 어텐션 후크는 기본적으로 활성화되어 있습니다. 어텐션을 제외하려면 --contract-only를 사용하거나, 프로젝트 설정을 위해 kata init --agent-hooks=codex,pi를 사용합니다. 이 명령어들은 Kata 0.19.0 이상을 요구합니다.
저장소(repository)를 변경하지 않고 더 짧은 관리형 브리핑(managed briefing)을 출력하려면:
kata quickstart --format contract
kata agent-instructions --format contract --workspace /path/to/workspace
...
계약 출력물은 마커가 없고, 터미널 프레이밍이 없으며, 초기화된 작업 공간 없이 작동하고, 작업 공간을 변경하지 않습니다. 이는 kata init --with-agents가 관리 마커 사이에 배치하는 것과 동일한 정규 본문에서 렌더링되므로, 정적이고 세션 주입형 가이드라인이 이탈(drift)할 수 없습니다.
Kata 작업 공간 외부에서 침묵을 원한다면, 모든 세션 설치 프로그램 대신 이 대체 Claude Code SessionStart 명령어를 사용하세요:
if test -f "$CLAUDE_PROJECT_DIR/.kata.toml"; then
kata quickstart --format contract --workspace "$CLAUDE_PROJECT_DIR"
fi
stdin 페이로드 없이 Codex SessionStart 응답을 얻으려면 kata agent-contract-hook을 실행하세요. 프롬프트를 대체하려면 kata agent-contract-hook --source ./agent-prompt.txt를 사용하세요. 파일이 누락된 경우 내장 계약(built-in contract)을 사용하며, 빈 파일을 제공하면 빈 프롬프트가 공급됩니다.
Codex SessionStart 훅은 일반 계약 표준 출력(stdout) 대신 구조화된 JSON을 필요로 합니다. 작업 공간 훅의 경우, kata init --with-codex-hooks를 사용하세요. 계약 중복 제거 및 별도의 어텐션 라이프사이클에 대해서는 init 참조를 참고하세요.
기여 (Contributing)
리포지토리 레이아웃 및 로컬 검사(make test, make lint, make vet, make nilaway)는 Contributing를 참조하세요. 라이선스는 LICENSE에 명시된 조건에 따릅니다.