jjj CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

jjj (Jujutsu Juggler) is a distributed project management and code review system built for Jujutsu (jj). It implements Popperian epistemology (Problems → Solutions → Critiques) as a Kanban-style workflow with no central server, no database, and offline-first operation.

Key insight: jj's stable Change IDs persist across rebases/squashes, allowing metadata to survive history rewrites that would orphan Git commit-based metadata.

Build Commands

Rust CLI

cargo build                    # Debug build
cargo build --release          # Release build
cargo test                     # Run all tests
cargo test <test_name>         # Run specific test
cargo run -- <command>         # Execute jjj command
cargo fmt                      # Format code
cargo clippy                   # Lint

VS Code Extension

cd vscode
npm install
npm run compile                # TypeScript compilation
npm run watch                  # Watch mode
npm run test                   # Run mocha tests
npm run lint                   # ESLint
npm run package                # Create .vsix
npm run install-ext            # Install locally

Documentation

cd docs-site && npm run dev    # Serve locally
cd docs-site && npm run build  # Build docs

Architecture

Core Model

• Problems: Things to solve (can form DAG via parent_id). Support tags for categorization.
• Solutions: Conjectures attached to jj Change IDs (not commit hashes). Support tags for categorization.
• Critiques: Error-elimination feedback that blocks solution approval
• Milestones: Time-based goals grouping problems

Storage: Shadow Graph

All metadata lives in an orphaned jjj bookmark, never touching the working copy. Sync via jj git push -b jjj.

problems/{uuid}.md
solutions/{uuid}.md
critiques/{uuid}.md
milestones/{uuid}.md
config.toml
events.jsonl