kra is a local CLI for ticket-driven development workflows on your filesystem.
It creates an isolated workspace per task, attaches only the repositories you need as Git worktrees, and closes work safely into archive/ when done.
It is useful standalone for workspace lifecycle operations, and becomes more valuable with cmux by aligning ticket, kra workspace, and cmux workspace in a 1:1:1 operating model.
The default workspace template starts with notes/, artifacts/, and workspace.md; you can extend it with your own files and directories.
<KRA_ROOT> stores active/archived task workspaces and its root-local repo pool under
<KRA_ROOT>/.kra/repo-pool/; $KRA_HOME (default: ~/.kra/) stores global config and root context metadata.
Tip
Looking for a more inventory-driven workspace tool? gion may fit better if you often spin up review, issue, or reproduction environments across multiple repos and want to reconcile them safely with a declarative plan/apply flow.
kra is built around filesystem-based workspace management under <KRA_ROOT>.
Ticket System Filesystem (KRA_ROOT) cmux
--------------- -------------------------- -----------------------
PROJ-1234 ---> workspaces/PROJ-1234/ ---> workspace: PROJ-1234
├─ repos/
│ (no repo attached)
├─ workspace.md
├─ notes/
└─ artifacts/
PROJ-1235 ---> workspaces/PROJ-1235/ ---> workspace: PROJ-1235
├─ repos/
│ └─ backend/
├─ workspace.md
├─ notes/
└─ artifacts/
PROJ-1236 ---> workspaces/PROJ-1236/ ---> workspace: PROJ-1236
├─ repos/
│ ├─ api/
│ ├─ web/
│ └─ infra/
├─ workspace.md
├─ notes/
└─ artifacts/
<KRA_ROOT> stores active/archived task workspaces and the root-local repo pool, while $KRA_HOME
(default: ~/.kra/) stores global config and root context metadata.
kra ws create <ID>: creates<KRA_ROOT>/workspaces/<ID>/kra ws close --id <ID>: archives to<KRA_ROOT>/archive/<ID>/kra ws reopen --id <ID>: moves<ID>fromarchive/back toworkspaces/kra ws purge --id <ID>: permanently removes an archived workspace
kra init
kra ws create TASK-1234
kra ws open --id TASK-1234 --command "claude"When using cmux, kra ws open creates or reuses the corresponding cmux workspace and sends a cmux notification from that workspace. Use the notification action in cmux to jump to the workspace; kra ws open does not automatically steal focus. Pass --command "<cmd>" to send a startup command to the workspace terminal after it has opened in the workspace directory.
In single-target open, if cmux capabilities are unavailable, kra falls back to directory-open behavior; with shell integration, it can also sync parent shell cwd.
cmux Workspace Groups organize a KRA root and its workspaces, while kra ws task sync explicitly reconciles structured tasks with cmux native Todo. kra no longer creates or installs cmux Dock controls. Existing user-authored .cmux/dock.json files are preserved but unmanaged.
For an existing root and active workspaces, run kra root migrate --apply to migrate the legacy pool,
normalize existing worktree links for host/isolation use, and add missing workspace handoff files
without overwriting custom files.
For day-to-day operations (repo add, ws add-repo, ws close, ws task, ws doc open), see:
docs/user/guides/INSTALL.mddocs/user/guides/COMMANDS.mddocs/user/guides/CONFIG.mddocs/user/guides/TASKS.mddocs/user/guides/WORKSPACE_DOCS.md
If you use kra ws close or the directory fallback path of kra ws open, enable shell integration to sync your parent shell cwd.
This prevents staying in a deleted directory after closing a workspace from inside that workspace path.
Setup and details:
docs/user/guides/SHELL_INTEGRATION.md
Manage a task workspace through explicit state transitions (create, close, reopen, purge), while preserving task outputs in archive/ on close.
Example:
kra ws close --id TASK-1234Guide: docs/user/guides/WORKSPACE_LIFECYCLE.md
When using cmux, kra ws open creates or reuses the corresponding cmux workspace and sends a cmux notification from it. Follow the notification action to jump to the workspace. kra ws close closes mapped cmux workspace(s) on a best-effort basis after archive operations.
Conceptual mapping is shown in "Filesystem Model (At a Glance)".
Example:
kra ws open --id TASK-1234Guide: docs/user/guides/CMUX.md
Register repositories in the current root's repo pool, then attach and remove only the repositories needed per task as worktrees so each workspace keeps only the required repo context.
Example:
kra ws add-repo --id TASK-1234Details:
docs/user/guides/REPO_WORKTREE.md
Keep structured tasks inside each workspace, update statuses with kra ws task, inspect them with kra ws status, and explicitly reconcile their state with cmux native Todo using kra ws task sync.
Example:
kra ws task add --current --title "Draft docs"
kra ws task status --current TASK-001 doingGuide: docs/user/guides/TASKS.md
Open workspace-local Markdown in the cmux Markdown viewer and keep related documents collected into one docs pane slot per workspace.
Example:
kra ws doc open --current notes/Guide: docs/user/guides/WORKSPACE_DOCS.md
brew tap tasuku43/tap
brew install kramise can install kra from GitHub Releases.
# pin a version
mise use -g github:tasuku43/kra@v0.1.0
# track latest
mise use -g github:tasuku43/kra@latestVerify:
kra version(orkra --version)
- Download the archive for your OS/arch from GitHub Releases.
- Extract it and place
kraon yourPATH. - Verify with
kra version(orkra --version).
Requirements:
- Go 1.24+
- Git
go build -o kra ./cmd/kra
./kra versionTicket providers are designed to be extensible; current documented support is Jira.
You can always create a workspace with a plain ID:
kra ws create TASK-1234To create/import from Jira (kra ws create --jira <ticket-url>, kra ws import jira), configure:
- base URL:
KRA_JIRA_BASE_URL, or.kra/config.yaml/~/.kra/config.yaml->integration.jira.base_url
- credentials (env-only):
KRA_JIRA_EMAILKRA_JIRA_API_TOKEN
Then choose one of these entry points:
# Single issue -> one workspace
kra ws create --jira https://jira.example.com/browse/PROJ-123
# Config-first import (defaults in config.yaml -> flags can be omitted)
kra ws import jira
# Multiple issues -> plan/apply import
kra ws import jira --sprint --space PROJ
# or
kra ws import jira --jql "project = PROJ AND statusCategory != Done"Details:
docs/user/guides/COMMANDS.mddocs/user/guides/CONFIG.md
- Install guide:
docs/user/guides/INSTALL.md - Command reference:
docs/user/guides/COMMANDS.md - Config guide:
docs/user/guides/CONFIG.md - Workspace lifecycle guide:
docs/user/guides/WORKSPACE_LIFECYCLE.md - cmux integration guide:
docs/user/guides/CMUX.md - Workspace task guide:
docs/user/guides/TASKS.md - Workspace docs viewer guide:
docs/user/guides/WORKSPACE_DOCS.md - Shell integration guide:
docs/user/guides/SHELL_INTEGRATION.md - Repo/worktree guide:
docs/user/guides/REPO_WORKTREE.md - Automation JSON guide:
docs/user/guides/AUTOMATION_JSON.md - Docs index:
docs/README.md - Developer specs (implementation contracts):
docs/dev/spec/README.md
- Contributing:
CONTRIBUTING.md - Support:
SUPPORT.md - Security:
SECURITY.md - Code of Conduct:
CODE_OF_CONDUCT.md - License:
LICENSE - Maintainer:
@tasuku43