agentjj - Agent-First Version Control

An agent-oriented porcelain for Jujutsu (jj) version control. Designed to make AI agents love version control.

Zero-install: agentjj embeds jj-lib directly - no separate jj installation required.

Git-compatible: Automatically colocates with existing git repos. Git continues to work normally.

Quick Start

bash

# In any git repo - agentjj auto-initializes jj colocated
agentjj orient                  # Get complete repo orientation

# Optional: create agent manifest for permissions/invariants
agentjj init                    # Create .agent/manifest.toml

Core Philosophy

•Everything is JSON - Use --json for machine-parseable output
•Self-documenting - agentjj schema shows all output formats
•Safe by default - Checkpoints and undo for easy recovery
•Batch-friendly - Bulk operations for efficiency
•Context-rich - Get exactly what you need without bloat

Essential Commands

Orient (Start Here)

bash

agentjj orient                  # Complete repo briefing
agentjj --json orient           # As structured JSON

Returns: current state, codebase stats, recent changes, capabilities, quick start guide.

Status & Discovery

bash

agentjj status                  # Current change, operation, files
agentjj suggest                 # What should I do next?
agentjj validate                # Are my changes ready to push?

Reading Code

bash

agentjj read src/main.rs                    # Read file
agentjj symbol src/api.py                   # List all symbols
agentjj symbol src/api.py::process          # Get specific symbol
agentjj context src/api.py::process         # Minimal context to use symbol
agentjj affected src/api.py::process        # Impact analysis

Bulk Operations (10x Efficiency)

bash

agentjj bulk read src/a.rs src/b.rs src/c.rs
agentjj bulk symbols "src/**/*.rs"
agentjj bulk symbols "src/**/*.rs" --public-only
agentjj bulk context src/a.rs::foo src/b.rs::bar

Files & Structure

bash

agentjj files                               # List all files
agentjj files --pattern "src/**/*.rs"       # Filter by pattern
agentjj files --pattern "*.py" --symbols    # Include symbol counts

Checkpoints & Recovery

bash

agentjj checkpoint before-refactor          # Create checkpoint
agentjj checkpoint wip -d "work in progress"
agentjj undo                                # Undo last operation
agentjj undo --steps 3                      # Undo 3 operations
agentjj undo --to before-refactor           # Restore to named checkpoint
agentjj undo --dry-run                      # Preview what would be undone

Changes & Diffs

bash

agentjj diff                                # Show current diff
agentjj diff --explain                      # With semantic summary
agentjj diff --against @--                  # Compare to 2 changes ago

Typed Changes

bash

agentjj change set -i "Add auth" -t behavioral -c feature
agentjj change list
agentjj change show <change_id>

Types: behavioral, refactor, schema, docs, deps, config, test Categories: feature, fix, perf, security, breaking, deprecation, chore

Apply & Push

bash

agentjj apply \
  --intent "Fix null check" \
  --type behavioral \
  --category fix \
  --patch fix.patch

agentjj push                               # Push to remote
agentjj push --pr --title "Fix bug"        # Create PR

Self-Documentation

bash

agentjj schema                             # List all output schemas
agentjj schema --type context              # Show specific schema
agentjj schema --type orient               # See orient output format

JSON Mode

Always use --json for programmatic access:

bash

agentjj --json status
agentjj --json orient
agentjj --json context src/main.rs::main
agentjj --json bulk read file1.rs file2.rs
agentjj --json affected src/api.rs::handler

Errors also return JSON:

json

{"error": true, "message": "Symbol path must be path/to/file::symbol_name"}

Exit codes: 0 = success, 1 = error

Workflow Example

bash

# 1. Orient yourself
agentjj --json orient

# 2. Understand what you're changing
agentjj context src/auth.rs::login
agentjj affected src/auth.rs::login

# 3. Create a checkpoint
agentjj checkpoint before-auth-refactor

# 4. Make changes, then validate
agentjj validate

# 5. Set typed change metadata
agentjj change set -i "Refactor login for OAuth" -t refactor

# 6. Push with PR
agentjj push --pr --title "OAuth login support"

Command Reference

Command	Description
`orient`	Complete repo orientation
`status`	Current state
`suggest`	Recommended next actions
`validate`	Check changes are ready
`read <path>`	Read file content
`symbol <path>`	Query symbols
`context <path>::<name>`	Get symbol context
`affected <path>::<name>`	Impact analysis
`bulk read <paths...>`	Read multiple files
`bulk symbols <pattern>`	Query symbols across files
`bulk context <symbols...>`	Get multiple contexts
`files [--pattern] [--symbols]`	List files
`checkpoint <name>`	Create restore point
`undo [--steps N]`	Revert operations
`diff [--explain]`	Show changes
`change set/list/show`	Typed change metadata
`apply`	Apply intent transaction
`push [--pr]`	Push and optionally create PR
`schema [--type]`	Output schemas
`init`	Initialize agentjj
`manifest show/validate`	Manage manifest

All commands support --json for structured output.

Supported Languages

Symbol extraction: Python, Rust, JavaScript, TypeScript

Pro Tips

•Start with orient - It tells you everything about the repo
•Use --json always - Reliable parsing, never breaks
•Checkpoint before risky changes - Easy recovery
•Use bulk for efficiency - One call, many results
•Check affected before changing - Know the blast radius
•suggest when stuck - Let the tool guide you
•validate before pushing - Catch issues early