README
¶
git-kura
git-kura is a keyed worktree resolver for Git.
It maps issue, ticket, task or feature keys to deterministic Git worktrees for humans, AI coding agents, and reviewers.
Walkthrough
git kura open fizz-feature # create a worktree and a branch in a repository
cd $(git kura get fizz-feature) # move to the worktree
# edit, save and commit in the worktree
cd $(git kura get fizz-feature --root) # move to the repository root
git merge fizz-feature # merge changes to main stream
git kura close fizz-feature # clean up worktree and branch
When multiple AI coding agents may share a worktree, acquire a cooperative guard at the start of work and release it at the end:
cd $(git kura get fizz-feature) # move to the worktree
git kura guard acquire # claim the worktree before working in it
# edit, save and commit in the worktree
git kura guard release # release the worktree when done
git kura guard acquire exits with code 8 (guard-active:) when another agent already holds the worktree. See docs/commands.md for the full guard and seal command reference.
Quick Start
curl -fsSL https://raw.githubusercontent.com/tooppoo/git-kura/main/install.sh | sh
Installs git-kura into ~/.local/bin. See docs/installation.md for version pinning, custom install directories, checksum verification, and other installation methods.
Why Kura?
When using Git worktrees with multiple AI coding agents, it is easy to lose track of which worktree belongs to which task.
For example, one agent may implement a change in a task-specific worktree while another tool or reviewer needs to inspect that exact worktree later. If the review target is selected manually, the workflow becomes fragile.
Kura solves this by making the task key the source of truth.
task key
-> branch name
-> worktree path
The same key should always resolve to the same workspace.
Concept
Kura（蔵） is built around four ideas:
- Keyed workspaces: any stable key — an issue number, ticket ID, task name, feature slug, or review target — can identify one workspace.
- Worktree isolation: each key gets its own Git worktree and branch.
- A small local kura: Kura（
蔵） keeps keyed worktrees and metadata in a repository-local store, so the right workspace can be put away, found, and cleaned up without relying on memory. - Deterministic resolution: humans, scripts, AI coding agents, and reviewers can resolve the same key to the same workspace without guessing.
Kura is intentionally small. It is not a Git client, an AI agent manager, a pull request tool, an issue tracker client, or a project management tool. Its job is to provide a stable mapping between a key and a local Git worktree.
Usage
See docs/commands.md for the command reference and docs/output-format.md for structured output formats.
Installation
See docs/installation.md for options such as --version, --install-dir, and --require-signature.
Documentation
License
Apache License 2.0
Directories