{"id":44820123,"url":"https://github.com/tasuku43/kra","last_synced_at":"2026-06-10T07:00:38.617Z","repository":{"id":336681516,"uuid":"1149839644","full_name":"tasuku43/kra","owner":"tasuku43","description":"Ticket-driven local workspaces with per-task Git worktrees and optional cmux workspace mapping.","archived":false,"fork":false,"pushed_at":"2026-05-25T00:45:00.000Z","size":1905,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T02:32:51.227Z","etag":null,"topics":["cli","cmux","developer-tools","git-worktree","jira","task-management","workspace"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tasuku43.png","metadata":{"files":{"readme":"README.backup.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-04T15:27:30.000Z","updated_at":"2026-05-25T00:43:41.000Z","dependencies_parsed_at":"2026-03-16T03:02:26.373Z","dependency_job_id":"63418e16-2870-4539-9bef-adbda005c4e8","html_url":"https://github.com/tasuku43/kra","commit_stats":null,"previous_names":["tasuku43/gionx"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/tasuku43/kra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tasuku43%2Fkra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tasuku43%2Fkra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tasuku43%2Fkra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tasuku43%2Fkra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tasuku43","download_url":"https://codeload.github.com/tasuku43/kra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tasuku43%2Fkra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34140775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cmux","developer-tools","git-worktree","jira","task-management","workspace"],"created_at":"2026-02-16T19:53:00.948Z","updated_at":"2026-06-10T07:00:38.596Z","avatar_url":"https://github.com/tasuku43.png","language":"Go","funding_links":[],"categories":["Feature Dimensions"],"sub_categories":["7. Worktrees \u0026 Workspace Management"],"readme":"# kra\n\n`kra` is a local CLI for AI-agent-oriented, ticket-driven workspace operations.\nIt standardizes task workspaces on the filesystem through template-driven workspace scaffolding and per-workspace Git worktrees for the repositories each task actually needs.\nThe default template includes `notes/` and `artifacts/`, and you can define your own structures (for example `AGENTS.md`, `CLOUD.md`, and custom directories) to provide a predictable workspace scaffold for multi-repo execution and continuous accumulation of intermediate outputs.\n\n`kra` works standalone for workspace lifecycle operations, and becomes even more valuable when paired with `cmux` for agent runtime/workspace integration.\nTicket providers are designed to be extensible; currently, Jira is supported.\n\n`\u003cKRA_ROOT\u003e` stores task workspaces and `archive/`, while `$KRA_HOME` (default: `~/.kra/`) stores shared state such as config and the repo pool.\n\n## One-minute mental model\n\n- `kra ws create TASK-1234` creates a task workspace under `workspaces/TASK-1234/`.\n- `kra ws add-repo --id TASK-1234` attaches only the needed repositories as worktrees under `repos/`.\n- `kra ws open --id TASK-1234` opens that task-scoped execution context (and can align with `cmux` runtime workflow).\n- `kra ws close --id TASK-1234` moves task outputs to `archive/` and removes workspace worktrees from active area.\n\n## Shell integration\n\nIf you want `kra` to synchronize your parent shell `cwd` (for example fallback `cd` behavior in `ws open`), enable shell integration:\n\n```sh\n# zsh\neval \"$(kra shell init zsh)\"\n\n# bash\neval \"$(kra shell init bash)\"\n\n# fish\neval (kra shell init fish)\n```\n\nTo persist this, add the corresponding `eval ...` line to your shell rc file (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`).\n`kra shell init \u003cshell\u003e` prints shell code to stdout; review it first if you prefer.\n\nWithout shell integration, `kra` still runs commands but cannot mutate your parent shell `cwd`.\n\n## cmux integration\n\n`kra` provides an operational framework for using `cmux` in ticket-driven, filesystem-based workflows.\n\nIn this model, `kra` acts as the glue across:\n\n- ticket\n- filesystem task workspace (`workspaces/\u003cid\u003e/`)\n- `cmux` runtime workspace\n\nThis gives you an operational 1:1:1 mapping across ticket, task workspace, and runtime workspace, so agents can run in a consistent task-scoped workspace and continuously write intermediate outputs as work progresses.\n\n`kra` works standalone for workspace lifecycle operations, but this `kra` + `cmux` operating model is where the overall system value becomes strongest.\n\n`ws open` / `ws close` behavior with `cmux`:\n\n- `kra ws open --id \u003cid\u003e`:\n  - if no `cmux` mapping exists for the workspace, `kra` creates/selects a `cmux` workspace and persists the mapping.\n  - if a mapping already exists and runtime workspace is reachable, `kra` reuses it (switch/select) instead of creating another one.\n  - single-target open (for example `kra ws open --id \u003cid\u003e` or `--current`; `--current` resolves workspace from current directory) falls back to shell `cd` synchronization when `cmux` capabilities are unavailable.\n- `kra ws close --id \u003cid\u003e`:\n  - after archive/workspace close operations, `kra` closes the mapped `cmux` workspace on a best-effort basis.\n  - `cmux` close failures do not roll back successful archive results.\n\nNote:\n\n- `kra` workspace and `cmux` workspace mapping is 1:1.\n\n## worktree management\n\n`kra` lets you manage Git worktrees per task workspace with `kra ws add-repo` / `kra ws remove-repo`.\nYou can attach only the repositories needed for the current task, exactly when they become necessary.\n\nRepositories are attached under:\n\n- `workspaces/\u003cid\u003e/repos/\u003calias\u003e/`\n\nThis keeps execution context task-scoped and avoids mixing temporary task outputs into a single long-lived repository.\n\nWhen work spans multiple repositories, this model lets you build a task-scoped, monorepo-like execution surface quickly, so agents can use the right repository context at the right time without long setup cycles.\n\n## Why kra exists\n\nAI-agent-driven work now produces large volumes of intermediate outputs, not only code changes but also investigations, analyses, logs, and notes.\nThose artifacts need a temporary but structured home before they are distilled into final deliverables.\nIn practice, people often dump them into ad hoc locations first, such as random local directories or inside an active repository, and later struggle with cleanup and traceability.\n\nIn AI-agent-driven workflows that span multiple repositories and task contexts, common problems include:\n\n- Non-code outputs end up in inconsistent locations, making task-scoped recovery harder.\n- Task context is difficult to keep organized in a way that supports fast resume.\n- After task switching, the exact repo/branch combination for a task is easy to lose.\n- Manual workspace rebuilds drift over time (missing repos, extra repos, wrong branch context).\n\n`kra` addresses this by making the filesystem workspace the unit of execution and traceability.\nExternal ticket systems remain the source of truth for task management, while `kra` provides a repeatable local operating model.\n\n## What it gives you\n\n- A template-driven workspace scaffold for each task:\n  - start with the default template (`notes/`, `artifacts/`)\n  - replace or extend it with your own structure (`AGENTS.md`, `CLOUD.md`, custom directories/files)\n- Per-task, per-workspace multi-repo worktree management:\n  - add only repositories required for that task\n  - keep them under `workspaces/\u003cid\u003e/repos/\u003calias\u003e/` for a predictable local execution surface\n- An operational bridge between planning and runtime:\n  - anchor ticket context to a filesystem workspace\n  - pair that workspace with `cmux` runtime workspace(s) as an operational model\n- State-first lifecycle operations with explicit transitions:\n  - create, open, close, reopen, purge with clear state rules\n  - move completed workspaces to `archive/` by default instead of destructive deletion\n- Guardrails for risky operations:\n  - evaluate workspace risk (`dirty`, `unpushed`, `diverged`, `unknown`)\n  - apply confirmation gates for destructive flows\n- Automation-ready output contracts:\n  - use a shared JSON envelope (`ok`, `action`, `workspace_id`, `result`, `error`) across supported commands\n\n## Quickstart (5 minutes)\n\n```sh\n# 1) initialize a root (interactive)\nkra init\n\n# 2) create a workspace from your ticket id (interactive)\nkra ws create TASK-1234\n\n# 3) register repositories into the repo pool\nkra repo add git@github.com:org/backend.git git@github.com:org/frontend.git\n\n# 4) attach needed repositories to the workspace (interactive selector + prompts)\nkra ws add-repo --id TASK-1234\n\n# 5) open workspace context\nkra ws open --id TASK-1234\n\n# 6) inspect current state\nkra ws dashboard\n\n# 7) close when done (moves notes/artifacts to archive/, removes worktrees)\nkra ws close --id TASK-1234\n```\n\n`kra init`, `kra ws create`, and `kra ws add-repo` will guide you with prompts in this quickstart flow.\nWith shell integration enabled, `kra ws open` can synchronize your shell `cwd`; without it, `kra` still runs but cannot mutate parent shell `cwd`.\nYou can also use interactive selection for workspace-targeted commands (for example: `kra ws open --select`, `kra ws close --select`).\n\nAfter this flow, your task context and artifacts remain reviewable under `archive/\u003cid\u003e/`, while active workspace area stays clean.\n\n### Resulting layout (example)\n\n```text\n# before close\n\u003cKRA_ROOT\u003e/\n├─ workspaces/\n│  └─ TASK-1234/\n│     ├─ notes/\n│     ├─ artifacts/\n│     └─ repos/\n│        ├─ backend/   (git worktree)\n│        └─ frontend/  (git worktree)\n└─ archive/\n\n# after close\n\u003cKRA_ROOT\u003e/\n├─ workspaces/\n└─ archive/\n   └─ TASK-1234/\n      ├─ notes/\n      ├─ artifacts/\n      └─ .kra.meta.json (includes repos_restore metadata)\n```\n\n## Workspace lifecycle semantics\n\nState model:\n\n- `create` -\u003e `active`\n- `close` -\u003e `archived`\n- `reopen` -\u003e `active`\n- `purge` -\u003e terminal cleanup\n\n`close` behavior (important):\n\n- `kra` removes worktrees under `workspaces/\u003cid\u003e/repos/`, then moves remaining workspace outputs (`notes/`, `artifacts/`, `.kra.meta.json`) to `archive/\u003cid\u003e/` (not copied).\n- Non-clean repo risk (`dirty`, `unpushed`, `diverged`, `unknown`) triggers a safety gate before applying.\n\nRisk labels:\n\n- `dirty`: workspace worktree has local file changes.\n- `unpushed`: local branch is ahead of upstream.\n- `diverged`: local and upstream both advanced.\n- `unknown`: risk state could not be determined.\n\n`reopen` behavior (important):\n\n- `kra ws reopen` restores workspace-side repository attachments from `repos_restore` in `.kra.meta.json`.\n- In normal operation, `close` and `reopen` are the standard round-trip between active and archived work.\n\nFor command-specific details, see:\n\n- `docs/dev/spec/commands/ws/close.md`\n- `docs/dev/spec/commands/ws/reopen.md`\n- `docs/dev/spec/commands/ws/purge.md`\n- `docs/dev/spec/concepts/workspace-lifecycle.md`\n\n## Repo pool, alias, and branch model\n\n`kra` separates repository registration from workspace attachment:\n\n1. `kra repo add` registers repositories into the shared repo pool.\n2. `kra ws add-repo --id \u003cid\u003e` selects from that pool and attaches worktrees into the workspace.\n\nOperational notes:\n\n- `repo pool` stores managed bare repositories and root-level registration state.\n- Physical shared pool location is `$KRA_HOME/repo-pool/` (default: `~/.kra/repo-pool/`; `$KRA_HOME` default is `~/.kra/`).\n- `kra repo add` creates/updates shared bare mirrors in this pool, and `ws add-repo` uses them to create workspace worktrees.\n- Worktree alias is derived from repository identity and must be unique per workspace.\n- `ws add-repo` prompts for `base_ref` and `branch` (with defaults), so branch context is explicit and reproducible per task.\n\nSee:\n\n- `docs/dev/spec/commands/repo/add.md`\n- `docs/dev/spec/commands/ws/add-repo.md`\n\n## cmux minimal recipe\n\n`kra` works standalone, but if you use `cmux`, a minimal operating recipe is:\n\n1. Create and prepare workspace (`ws create`, `repo add`, `ws add-repo`).\n2. Open task context with `kra ws open --id \u003cid\u003e`.\n3. Run your agent against that task workspace context.\n4. Close with `kra ws close --id \u003cid\u003e` when done.\n\nIn this flow, `kra` handles workspace-side coordination and mapping policy.\nIf `cmux` capabilities are unavailable in a single-target open flow, `kra ws open` falls back to shell `cd` synchronization.\n\n## Boundaries\n\n`kra` is intentionally focused.\n\n- It is not a replacement for Jira or other external ticket systems.\n- It is not an agent runtime/session manager.\n  - `kra` does not manage agent sessions; it maps/coordinates workspace context and performs best-effort `cmux` workspace selection/cleanup.\n- It is not a GUI planning tool.\n\n## Installation\n\n### Homebrew (stable releases)\n\n```sh\nbrew tap tasuku43/kra\nbrew install kra\n```\n\n### GitHub Releases (manual)\n\n1. Download an archive for your OS/arch from GitHub Releases.\n2. Extract and place `kra` on your `PATH`.\n3. Verify with `kra version`.\n\n### Jira setup (minimum)\n\nJira integration is optional. You can always create a workspace with a plain ID:\n\n```sh\nkra ws create TASK-1234\n```\n\nTo create from Jira (`kra ws create --jira \u003cticket-url\u003e`), configure:\n\n- `KRA_JIRA_BASE_URL`\n- `KRA_JIRA_EMAIL`\n- `KRA_JIRA_API_TOKEN`\n\nSee `docs/dev/spec/commands/ws/create.md` and `docs/dev/spec/commands/ws/import/jira.md` for exact behavior.\n\n### Build from source\n\nRequirements:\n\n- Go 1.24+\n- Git\n\n```sh\ngo build -o kra ./cmd/kra\n./kra version\n```\n\n## JSON envelope example\n\n`ws create` accepts both positional workspace ID (`kra ws create TASK-1234`) and explicit `--id`.\n\nExample (`kra ws create --format json --id TASK-1234 --title \"API retry hardening\"`):\n\n```json\n{\n  \"ok\": true,\n  \"action\": \"ws.create\",\n  \"workspace_id\": \"TASK-1234\",\n  \"result\": {\n    \"created\": 1,\n    \"path\": \"\u003cKRA_ROOT\u003e/workspaces/TASK-1234\"\n  },\n  \"error\": null\n}\n```\n\n## User guides\n\n- Start here: `docs/user/START_HERE.md`\n- Install guide: `docs/user/guides/INSTALL.md`\n- Command reference: `docs/user/guides/COMMANDS.md`\n\n## Development and operations references\n\n- Product concept: `docs/concepts/product-concept.md`\n- Specs: `docs/dev/spec/README.md`\n- Releasing: `docs/dev/ops/RELEASING.md`\n\n## Contributing\n\nSee `CONTRIBUTING.md`.\n\n## Support\n\nSee `SUPPORT.md`.\n\n## Security\n\nSee `SECURITY.md`.\n\n## Code of Conduct\n\nSee `CODE_OF_CONDUCT.md`.\n\n## License\n\nSee `LICENSE`.\n\n## Maintainer\n\n- @tasuku43\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftasuku43%2Fkra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftasuku43%2Fkra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftasuku43%2Fkra/lists"}