zjj

project/                          # main jj repo
├── .zjj/
│   ├── state.db                  # SQLite session tracking database
│   ├── config.toml               # project-level configuration
│   └── layouts/                  # generated Zellij layout files (KDL)
├── .beads/
│   └── issues.jsonl              # bead issue tracker (JSONL)
└── ../lewis__workspaces/         # workspace directory (configurable via workspace_dir)
    ├── feature-auth/             # zjj session workspace
    │   ├── .cursorrules          # AI agent discovery (Cursor/Windsurf)
    │   └── .ai-instructions.md   # AI agent discovery (Claude/generic)
    ├── bugfix-123/               # another session workspace
    └── ai-sandbox/               # spawned agent workspace

Creating ──→ Active ──→ Completed
   │            │  ↘        ↑
   │            │   Paused ─┘
   │            ↓
   └──→ Failed ←── Syncing → Synced → Active

CREATE TABLE sessions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE NOT NULL,
    status TEXT CHECK(status IN ('creating','active','paused','completed','failed')),
    workspace_path TEXT NOT NULL,
    branch TEXT,
    created_at INTEGER,          -- unix timestamp
    updated_at INTEGER,          -- unix timestamp (auto-updated via trigger)
    last_synced INTEGER,
    metadata TEXT                 -- JSON blob
);

# 1. Safety checkpoint BEFORE the retry loop
zjj checkpoint create -d "Before merge retry loop"

# 2. Backoff retry loop
WAIT=2
MAX_RETRIES=6
RETRY=0
EXIT_CODE=3

while [ $RETRY -lt $MAX_RETRIES ] && [ $EXIT_CODE -ne 0 ]; do
  # Re-sync onto latest main — stale state is the #1 cause of repeated conflicts
  zjj sync
  SYNC_EXIT=$?
  if [ $SYNC_EXIT -ne 0 ]; then
    echo "Sync conflict — resolve manually in workspace, then retry."
    break
  fi

  # Use zjj retry — retries the last failed command (the done)
  zjj retry
  EXIT_CODE=$?
  [ $EXIT_CODE -eq 0 ] && break

  RETRY=$((RETRY + 1))
  echo "Merge attempt $((RETRY + 1))/$((MAX_RETRIES + 1)) — waiting ${WAIT}s..."
  sleep $WAIT
  WAIT=$((WAIT * 2))
  [ $WAIT -gt 60 ] && WAIT=60
done

# 3. On exhaustion: recover, then flag user
if [ $EXIT_CODE -ne 0 ]; then
  echo "EXHAUSTED: merge retries failed."
  zjj recover --diagnose   # diagnose what's broken without auto-fixing
  echo "Workspace preserved. File a bead. Flag user for manual resolution."
  # DO NOT abort or remove the workspace — it is evidence.
  # Rollback to checkpoint if state is corrupt:
  #   zjj rollback --to <checkpoint-id> <session-name>
fi

zjj init                          # first time only — initialize zjj in a jj repo
zjj add feature-auth              # create isolated workspace + Zellij tab
# You're now in an isolated workspace. Work freely.
zjj done                          # merge back to main, clean up

# 1. Initialize (once per repo)
zjj init

# 2. Create isolated workspace
zjj add feature-auth              # standard layout (claude + beads + status panes)
zjj add quick-fix -t minimal      # minimal layout (just a shell)
zjj add experiment -t full        # full layout (all panes)
zjj add headless --no-open        # create workspace without opening Zellij tab
zjj add feature-x -b zjj-abc12    # associate with bead zjj-abc12

# 3. Work in isolation
# Your workspace is at ../lewis__workspaces/feature-auth/
# All jj commands work normally within the workspace

# 4. Check status
zjj status feature-auth           # detailed session info
zjj list                          # all active sessions
zjj list --state active           # filter by state

# 5. Stay synced with main
zjj sync feature-auth             # rebase workspace onto latest main
zjj sync                          # sync current workspace
zjj sync --all                    # sync all active sessions

# 6. Review changes
zjj diff feature-auth             # full diff against main
zjj diff feature-auth --stat      # summary only

# 7. Complete work
zjj done                          # merge to main + cleanup
zjj done -m "feat: auth system"   # custom commit message
zjj done --squash                 # squash all commits into one
zjj done --dry-run                # preview without executing
zjj done --keep-workspace         # merge but keep workspace alive
zjj done --detect-conflicts       # check for conflicts before merging

workspace_dir = "../{repo}__workspaces"   # {repo} = repo folder name
main_branch = ""                           # auto-detected if empty
default_template = "standard"              # minimal | standard | full | split | review
state_db = ".zjj/state.db"

[watch]
enabled = true
debounce_ms = 100
paths = [".beads/beads.db"]

[hooks]
post_create = []                           # run after zjj add (CWD = workspace)
pre_remove = []                            # run before zjj remove
post_merge = []                            # run after zjj done merges

[zellij]
session_prefix = "zjj"
use_tabs = true                            # tabs (inside Zellij) vs sessions (outside)
layout_dir = ".zjj/layouts"

[zellij.panes.main]
command = "claude"
args = []
size = "70%"

[zellij.panes.beads]
command = "bv"
args = []
size = "50%"

[zellij.panes.status]
command = "zjj"
args = ["status", "--watch"]
size = "50%"

[zellij.panes.float]
enabled = true
command = ""
width = "80%"
height = "60%"

[dashboard]
refresh_ms = 1000
theme = "default"
columns = ["name", "status", "branch", "changes", "beads"]
vim_keys = true

[agent]
command = "claude"                         # default agent for zjj spawn

[agent.env]
# Additional agent environment variables

[session]
auto_commit = false
commit_prefix = "wip:"

[recovery]
policy = "warn"                            # warn | error | ignore
log_recovered = true
auto_recover_corrupted_wal = true
delete_corrupted_database = false

layout {
    pane {
        command "claude"
        cwd "/path/to/workspace"
        focus true
    }
}

┌────────────────────────────┬──────────────┐
│                            │  beads (bv)  │
│   main pane (claude) 70%   │     50%      │
│                            ├──────────────┤
│                            │  jj log 50%  │
│                            │ (--limit 20) │
└────────────────────────────┴──────────────┘

layout {
    pane split_direction="horizontal" {
        pane { command "claude"; cwd "..."; focus true; size "70%" }
        pane split_direction="vertical" {
            pane { command "bv"; cwd "..."; size "50%" }
            pane { command "jj"; args "log" "--limit" "20"; cwd "..."; size "50%" }
        }
    }
}

open → (zjj spawn) → in_progress → (zjj done / agent success) → closed
                           ↓
                    (agent failure) → stays in_progress (retry)

{
  "$schema": "zjj://schema/<type>/<version>",
  "_schema_version": "1.0",
  "schema_type": "single|array",
  "success": true,
  "data": { ... }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR|JJ_COMMAND_ERROR|INVALID_ARGUMENT|...",
    "message": "Human-readable description",
    "exit_code": 1
  }
}

# Set a post_create hook (runs after zjj add)
zjj config hooks.post_create '["echo workspace ready"]'

# Set a pre_remove hook (runs before zjj remove)
zjj config hooks.pre_remove '["echo cleaning up"]'

# Set a post_merge hook (runs after zjj done)
zjj config hooks.post_merge '["echo merged to main"]'

zjj add feature-auth                # stand up isolated workspace
# ... develop in isolation ...
zjj sync                            # stay current with main
zjj diff feature-auth --stat        # review what changed
zjj done -m "feat: auth system"     # merge back to main

# 1. Orient
zjj whereami                        # returns 'main' or 'workspace:<name>'

# 2. Register
zjj agents register --id agent-123  # register as agent

# 3. Isolate
zjj work feature-auth -b zjj-abc12  # create workspace + register agent

# 4. Enter
cd ../lewis__workspaces/feature-auth

# 5. Implement
# ... do work ...
zjj agents heartbeat -c "implementing"  # signal liveness

# 6. Heartbeat (periodically)
zjj agents heartbeat

# 7. Complete
zjj done                            # merge to main + cleanup
zjj agents unregister                # unregister agent

zjj add approach-a                  # first approach
zjj add approach-b                  # second approach (independent)
zjj diff approach-a --stat          # compare approach A
zjj diff approach-b --stat          # compare approach B
zjj done                            # merge winner (from its workspace)
zjj abort -w approach-b             # discard loser

# Agent 1 claims session
zjj claim session:feature-x -t 300

# Agent 2 waits for unlock
zjj wait session-unlocked feature-x -t 300

# Agent 1 completes and yields
zjj done
zjj yield session:feature-x

# Agent 2 proceeds
zjj work feature-y

# Add workspaces to queue for ordered processing
zjj queue --add feature-x --bead zjj-001 --priority 1
zjj queue --add feature-y --bead zjj-002 --priority 2

# Agent processes queue
zjj queue --next                    # get next pending entry
# ... work ...
zjj done

# Check queue status
zjj queue --stats

zjj list --all                      # see everything including stale
zjj clean --dry-run                 # preview what would be removed
zjj clean                           # remove stale sessions
zjj doctor                          # health check
zjj doctor --fix                    # auto-fix issues

zjj init                    # initializes both jj and zjj

zjj list                    # verify it exists
zjj remove <name> -f        # force remove if stale
zjj add <name>              # recreate

zjj clean --dry-run         # preview stale sessions
zjj clean                   # remove them

zjj sync <name>             # rebase onto latest main

zjj doctor                  # diagnose issues
zjj doctor --fix            # auto-fix where possible
zjj introspect              # check dependency versions

zjj focus <name>            # try to focus the tab
zjj attach <name>           # attach to the session

zjj checkpoint create       # safety snapshot
zjj sync                    # re-sync
zjj retry                   # retry the done
# If still failing after 6 retries:
zjj recover --diagnose      # diagnose without fixing

zjj query can-run            # check system readiness
zjj introspect               # verify agent dependency
zjj spawn <bead> --agent-command=<path>  # specify full path

zjj recover --diagnose       # diagnose issues
zjj integrity validate <ws>  # validate workspace
zjj integrity repair <ws>    # repair workspace
zjj rollback --to <cp> <session>  # rollback to checkpoint

# 1. File beads for remaining work (NOT gh issues — beads are the single source of truth)
br create "[process] Follow-up: description" --type task --priority 2 --labels "smell:process"

# 2. Verify workspace state
zjj status                    # all sessions accounted for
zjj diff <name> --stat        # review changes

# 3. Sync and complete — if zjj done fails with exit code 3, use exponential backoff
zjj sync                      # rebase onto latest main
zjj done -m "description"     # merge to main + cleanup
# Or if not ready to merge:
jj describe -m "WIP: description"
jj git push --change @ --allow-new

# 4. Verify — sessions AND directories
zjj list                      # no orphaned sessions
zjj clean --dry-run           # no stale sessions
# Verify workspace directories are actually gone from disk:
WORKSPACE_BASE=$(zjj config workspace_dir 2>/dev/null || echo "../lewis__workspaces")
[ -d "$WORKSPACE_BASE" ] && ls "$WORKSPACE_BASE"/  # should be empty or non-existent

# 5. Hand off
# Provide summary of work completed, sessions created/closed, next steps