kekkai 0.1.3

Minimal CLI wrapper that launches Claude Code in isolated jj workspaces

Kekkai

A minimal CLI that launches AI coding agents (Codex, Claude) in isolated jj workspaces.

Installation

# Install globally with uv (recommended)
uv tool install kekkai

# Or use uvx for one-off usage
uvx kekkai

Requirements

• Codex CLI or Claude Code installed and in PATH
• Jujutsu (jj) installed and in PATH
• Must be run from inside a jj repository
• Watchman (highly recommended for real-time snapshotting and a full experience, see Watchman Setup)

Quick Start

# Launch Codex (default) in a new isolated workspace
kekkai feature-auth

# Launch Claude instead
kekkai feature-auth --agent=claude

# List existing agent workspaces
kekkai list

# Create a new revision from an agent workspace (run from root workspace)
kekkai look feature-auth

Use --agent=codex|claude to select the agent.

When you run kekkai <name> (default agent: codex):

1. Creates an isolated jj workspace as a sibling directory (<repo>-<name>/)
2. Launches the selected agent with full terminal experience
3. On exit, prompts whether to keep or delete the workspace

Multi-Agent Workflow

Run multiple agents in parallel by opening multiple terminals:

# Terminal 1
kekkai feature-auth

# Terminal 2
kekkai bugfix-login

# Terminal 3
kekkai refactor-api

Monitor all agents from your main workspace:

jj log

Managing Agent Changes

From your main workspace, you can create a new revision directly from an agent's working copy:

kekkai look feature-auth

Then use jj to integrate agent work:

# See all changes across workspaces
jj log

# Squash an agent's changes into current revision
jj squash --from <agent-revision>

# Rebase agent work onto latest
jj rebase -s <agent-revision> -d @

# Cherry-pick specific changes
jj new <agent-revision>

see jjui for a more user-friendly interface.

Watchman Setup

Without Watchman, jj only captures changes when you run a jj command. With Watchman, snapshotting is automatic and you can monitor agent progress in real-time.

1. Install Watchman
2. Enable in ~/.config/jj/config.toml:

# ~/.config/jj/config.toml
[fsmonitor]
backend = "watchman"
watchman.register-snapshot-trigger = true

# highly recommend auto updating stale snapshots as well
[snapshot]
auto-update-stale = true

3. Verify: jj debug watchman status

Development

git clone https://github.com/yum0e/kekkai
cd kekkai
uv run kekkai --help
uv run --with pytest pytest tests/ -v