agentic-jujutsu

Agentic Jujutsu - AI Agent Version Control

Quantum-ready, self-learning version control designed for multiple AI agents working simultaneously without conflicts.

When to Use This Skill

Use agentic-jujutsu when you need:

• ✅ Multiple AI agents modifying code simultaneously
• ✅ Lock-free version control (23x faster than Git)
• ✅ Self-learning AI that improves from experience
• ✅ Quantum-resistant security for future-proof protection
• ✅ Automatic conflict resolution (87% success rate)
• ✅ Pattern recognition and intelligent suggestions
• ✅ Multi-agent coordination without blocking

Quick Start

Installation

npx agentic-jujutsu

Basic Usage

const { JjWrapper } = require('agentic-jujutsu');

const jj = new JjWrapper();

// Basic operations
await jj.status();
await jj.newCommit('Add feature');
await jj.log(10);

// Self-learning trajectory
const id = jj.startTrajectory('Implement authentication');
await jj.branchCreate('feature/auth');
await jj.newCommit('Add auth');
jj.addToTrajectory();
jj.finalizeTrajectory(0.9, 'Clean implementation');

// Get AI suggestions
const suggestion = JSON.parse(jj.getSuggestion('Add logout feature'));
console.log(`Confidence: ${suggestion.confidence}`);

Core Capabilities

1. Self-Learning with ReasoningBank

Track operations, learn patterns, and get intelligent suggestions:

// Start learning trajectory
const trajectoryId = jj.startTrajectory('Deploy to production');

// Perform operations (automatically tracked)
await jj.execute(['git', 'push', 'origin', 'main']);
await jj.branchCreate('release/v1.0');
await jj.newCommit('Release v1.0');

// Record operations to trajectory
jj.addToTrajectory();

// Finalize with success score (0.0-1.0) and critique
jj.finalizeTrajectory(0.95, 'Deployment successful, no issues');

// Later: Get AI-powered suggestions for similar tasks
const suggestion = JSON.parse(jj.getSuggestion('Deploy to staging'));
console.log('AI Recommendation:', suggestion.reasoning);
console.log('Confidence:', (suggestion.confidence * 100).toFixed(1) + '%');
console.log('Expected Success:', (suggestion.expectedSuccessRate * 100).toFixed(1) + '%');

Validation (v2.3.1):

• ✅ Tasks must be non-empty (max 10KB)
• ✅ Success scores must be 0.0-1.0
• ✅ Must have operations before finalizing
• ✅ Contexts cannot be empty

2. Pattern Discovery

Automatically identify successful operation sequences:

// Get discovered patterns
const patterns = JSON.parse(jj.getPatterns());

patterns.forEach(pattern => {
    console.log(`Pattern: ${pattern.name}`);
    console.log(`  Success rate: ${(pattern.successRate * 100).toFixed(1)}%`);
    console.log(`  Used ${pattern.observationCount} times`);
    console.log(`  Operations: ${pattern.operationSequence.join(' → ')}`);
    console.log(`  Confidence: ${(pattern.confidence * 100).toFixed(1)}%`);
});

3. Learning Statistics

Track improvement over time:

const stats = JSON.parse(jj.getLearningStats());

console.log('Learning Progress:');
console.log(`  Total trajectories: ${stats.totalTrajectories}`);
console.log(`  Patterns discovered: ${stats.totalPatterns}`);
console.log(`  Average success: ${(stats.avgSuccessRate * 100).toFixed(1)}%`);
console.log(`  Improvement rate: ${(stats.improvementRate * 100).toFixed(1)}%`);
console.log(`  Prediction accuracy: ${(stats.predictionAccuracy * 100).toFixed(1)}%`);

4. Multi-Agent Coordination

Multiple agents work concurrently without conflicts:

// Agent 1: Developer
const dev = new JjWrapper();
dev.startTrajectory('Implement feature');
await dev.newCommit('Add feature X');
dev.addToTrajectory();
dev.finalizeTrajectory(0.85);

// Agent 2: Reviewer (learns from Agent 1)
const reviewer = new JjWrapper();
const suggestion = JSON.parse(reviewer.getSuggestion('Review feature X'));

if (suggestion.confidence > 0.7) {
    console.log('High confidence approach:', suggestion.reasoning);
}

// Agent 3: Tester (benefits from both)
const tester = new JjWrapper();
const similar = JSON.parse(tester.queryTrajectories('test feature', 5));
console.log(`Found ${similar.length} similar test approaches`);

5. Quantum-Resistant Security (v2.3.0+)

Fast integrity verification with quantum-resistant cryptography:

const { generateQuantumFingerprint, verifyQuantumFingerprint } = require('agentic-jujutsu');

// Generate SHA3-512 fingerprint (NIST FIPS 202)
const data = Buffer.from('commit-data');
const fingerprint = generateQuantumFingerprint(data);
console.log('Fingerprint:', fingerprint.toString('hex'));

// Verify integrity (<1ms)
const isValid = verifyQuantumFingerprint(data, fingerprint);
console.log('Valid:', isValid);

// HQC-128 encryption for trajectories
const crypto = require('crypto');
const key = crypto.randomBytes(32).toString('base64');
jj.enableEncryption(key);

6. Operation Tracking with AgentDB

Automatic tracking of all operations:

// Operations are tracked automatically
await jj.status();
await jj.newCommit('Fix bug');
await jj.rebase('main');

// Get operation statistics
const stats = JSON.parse(jj.getStats());
console.log(`Total operations: ${stats.total_operations}`);
console.log(`Success rate: ${(stats.success_rate * 100).toFixed(1)}%`);
console.log(`Avg duration: ${stats.avg_duration_ms.toFixed(2)}ms`);

// Query recent operations
const ops = jj.getOperations(10);
ops.forEach(op => {
    console.log(`${op.operationType}: ${op.command}`);
    console.log(`  Duration: ${op.durationMs}ms, Success: ${op.success}`);
});

// Get user operations (excludes snapshots)
const userOps = jj.getUserOperations(20);

Advanced Use Cases

Use Case 1: Adaptive Workflow Optimization

Learn and improve deployment workflows:

async function adaptiveDeployment(jj, environment) {
    // Get AI suggestion based on past deployments
    const suggestion = JSON.parse(jj.getSuggestion(`Deploy to ${environment}`));
    
    console.log(`Deploying with ${(suggestion.confidence * 100).toFixed(0)}% confidence`);
    console.log(`Expected duration: ${suggestion.estimatedDurationMs}ms`);
    
    // Start tracking
    jj.startTrajectory(`Deploy to ${environment}`);
    
    // Execute recommended operations
    for (const op of suggestion.recommendedOperations) {
        console.log(`Executing: ${op}`);
        await executeOperation(op);
    }
    
    jj.addToTrajectory();
    
    // Record outcome
    const success = await verifyDeployment();
    jj.finalizeTrajectory(
        success ? 0.95 : 0.5,
        success ? 'Deployment successful' : 'Issues detected'
    );
}

Use Case 2: Multi-Agent Code Review

Coordinate review across multiple agents:

async function coordinatedReview(agents) {
    const reviews = await Promise.all(agents.map(async (agent) => {
        const jj = new JjWrapper();
        
        // Start review trajectory
        jj.startTrajectory(`Review by ${agent.name}`);
        
        // Get AI suggestion for review approach
        const suggestion = JSON.parse(jj.getSuggestion('Code review'));
        
        // Perform review
        const diff = await jj.diff('@', '@-');
        const issues = await agent.analyze(diff);
        
        jj.addToTrajectory();
        jj.finalizeTrajectory(
            issues.length === 0 ? 0.9 : 0.6,
            `Found ${issues.length} issues`
        );
        
        return { agent: agent.name, issues, suggestion };
    }));
    
    // Aggregate learning from all agents
    return reviews;
}

Use Case 3: Error Pattern Detection

Learn from failures to prevent future issues:

async function smartMerge(jj, branch) {
    // Query similar merge attempts
    const similar = JSON.parse(jj.queryTrajectories(`merge ${branch}`, 10));
    
    // Analyze past failures
    const failures = similar.filter(t => t.successScore < 0.5);
    
    if (failures.length > 0) {
        console.log('⚠️ Similar merges failed in the past:');
        failures.forEach(f => {
            if (f.critique) {
                console.log(`  - ${f.critique}`);
            }
        });
    }
    
    // Get AI recommendation
    const suggestion = JSON.parse(jj.getSuggestion(`merge ${branch}`));
    
    if (suggestion.confidence < 0.7) {
        console.log('⚠️ Low confidence. Recommended steps:');
        suggestion.recommendedOperations.forEach(op => console.log(`  - ${op}`));
    }
    
    // Execute merge with tracking
    jj.startTrajectory(`Merge ${branch}`);
    try {
        await jj.execute(['merge', branch]);
        jj.addToTrajectory();
        jj.finalizeTrajectory(0.9, 'Merge successful');
    } catch (err) {
        jj.addToTrajectory();
        jj.finalizeTrajectory(0.3, `Merge failed: ${err.message}`);
        throw err;
    }
}

Use Case 4: Continuous Learning Loop

Implement a self-improving agent:

class SelfImprovingAgent {
    constructor() {
        this.jj = new JjWrapper();
    }
    
    async performTask(taskDescription) {
        // Get AI suggestion
        const suggestion = JSON.parse(this.jj.getSuggestion(taskDescription));
        
        console.log(`Task: ${taskDescription}`);
        console.log(`AI Confidence: ${(suggestion.confidence * 100).toFixed(1)}%`);
        console.log(`Expected Success: ${(suggestion.expectedSuccessRate * 100).toFixed(1)}%`);
        
        // Start trajectory
        this.jj.startTrajectory(taskDescription);
        
        // Execute with recommended approach
        const startTime = Date.now();
        let success = false;
        
        try {
            for (const op of suggestion.recommendedOperations) {
                await this.execute(op);
            }
            success = true;
        } catch (err) {
            console.error('Task failed:', err.message);
        }
        
        const duration = Date.now() - startTime;
        
        // Record learning
        this.jj.addToTrajectory();
        this.jj.finalizeTrajectory(
            success ? 0.9 : 0.4,
            success 
                ? `Completed in ${duration}ms using ${suggestion.recommendedOperations.length} operations`
                : `Failed after ${duration}ms`
        );
        
        // Check improvement
        const stats = JSON.parse(this.jj.getLearningStats());
        console.log(`Improvement rate: ${(stats.improvementRate * 100).toFixed(1)}%`);
        
        return success;
    }
    
    async execute(operation) {
        // Execute operation logic
    }
}

// Usage
const agent = new SelfImprovingAgent();

// Agent improves over time
for (let i = 1; i <= 10; i++) {
    console.log(`\n--- Attempt ${i} ---`);
    await agent.performTask('Deploy application');
}

API Reference

Core Methods

Method	Description	Returns
new JjWrapper()	Create wrapper instance	JjWrapper
status()	Get repository status	Promise
newCommit(msg)	Create new commit	Promise
log(limit)	Show commit history	Promise<JjCommit[]>
diff(from, to)	Show differences	Promise
branchCreate(name, rev?)	Create branch	Promise
rebase(source, dest)	Rebase commits	Promise

ReasoningBank Methods

Method	Description	Returns
startTrajectory(task)	Begin learning trajectory	string (trajectory ID)
addToTrajectory()	Add recent operations	void
finalizeTrajectory(score, critique?)	Complete trajectory (score: 0.0-1.0)	void
getSuggestion(task)	Get AI recommendation	JSON: DecisionSuggestion
getLearningStats()	Get learning metrics	JSON: LearningStats
getPatterns()	Get discovered patterns	JSON: Pattern[]
queryTrajectories(task, limit)	Find similar trajectories	JSON: Trajectory[]
resetLearning()	Clear learned data	void

AgentDB Methods

Method	Description	Returns
getStats()	Get operation statistics	JSON: Stats
getOperations(limit)	Get recent operations	JjOperation[]
getUserOperations(limit)	Get user operations only	JjOperation[]
clearLog()	Clear operation log	void

Quantum Security Methods (v2.3.0+)

Method	Description	Returns
generateQuantumFingerprint(data)	Generate SHA3-512 fingerprint	Buffer (64 bytes)
verifyQuantumFingerprint(data, fp)	Verify fingerprint	boolean
enableEncryption(key, pubKey?)	Enable HQC-128 encryption	void
disableEncryption()	Disable encryption	void
isEncryptionEnabled()	Check encryption status	boolean

Performance Characteristics

Metric	Git	Agentic Jujutsu
Concurrent commits	15 ops/s	350 ops/s (23x)
Context switching	500-1000ms	50-100ms (10x)
Conflict resolution	30-40% auto	87% auto (2.5x)
Lock waiting	50 min/day	0 min (∞)
Quantum fingerprints	N/A	<1ms

Best Practices

1. Trajectory Management

// ✅ Good: Meaningful task descriptions
jj.startTrajectory('Implement user authentication with JWT');

// ❌ Bad: Vague descriptions
jj.startTrajectory('fix stuff');

// ✅ Good: Honest success scores
jj.finalizeTrajectory(0.7, 'Works but needs refactoring');

// ❌ Bad: Always 1.0
jj.finalizeTrajectory(1.0, 'Perfect!'); // Prevents learning

2. Pattern Recognition

// ✅ Good: Let patterns emerge naturally
for (let i = 0; i < 10; i++) {
    jj.startTrajectory('Deploy feature');
    await deploy();
    jj.addToTrajectory();
    jj.finalizeTrajectory(wasSuccessful ? 0.9 : 0.5);
}

// ❌ Bad: Not recording outcomes
await deploy(); // No learning

3. Multi-Agent Coordination

// ✅ Good: Concurrent operations
const agents = ['agent1', 'agent2', 'agent3'];
await Promise.all(agents.map(async (agent) => {
    const jj = new JjWrapper();
    // Each agent works independently
    await jj.newCommit(`Changes by ${agent}`);
}));

// ❌ Bad: Sequential with locks
for (const agent of agents) {
    await agent.waitForLock(); // Not needed!
    await agent.commit();
}

4. Error Handling

// ✅ Good: Record failures with details
try {
    await jj.execute(['complex-operation']);
    jj.finalizeTrajectory(0.9);
} catch (err) {
    jj.finalizeTrajectory(0.3, `Failed: ${err.message}. Root cause: ...`);
}

// ❌ Bad: Silent failures
try {
    await jj.execute(['operation']);
} catch (err) {
    // No learning from failure
}

Validation Rules (v2.3.1+)

Task Description

• ✅ Cannot be empty or whitespace-only
• ✅ Maximum length: 10,000 bytes
• ✅ Automatically trimmed

Success Score

• ✅ Must be finite (not NaN or Infinity)
• ✅ Must be between 0.0 and 1.0 (inclusive)

Operations

• ✅ Must have at least one operation before finalizing

Context

• ✅ Cannot be empty
• ✅ Keys cannot be empty or whitespace-only
• ✅ Keys max 1,000 bytes, values max 10,000 bytes

Troubleshooting

Issue: Low Confidence Suggestions

const suggestion = JSON.parse(jj.getSuggestion('new task'));

if (suggestion.confidence < 0.5) {
    // Not enough data - check learning stats
    const stats = JSON.parse(jj.getLearningStats());
    console.log(`Need more data. Current trajectories: ${stats.totalTrajectories}`);
    
    // Recommend: Record 5-10 trajectories first
}

Issue: Validation Errors

try {
    jj.startTrajectory(''); // Empty task
} catch (err) {
    if (err.message.includes('Validation error')) {
        console.log('Invalid input:', err.message);
        // Use non-empty, meaningful task description
    }
}

try {
    jj.finalizeTrajectory(1.5); // Score > 1.0
} catch (err) {
    // Use score between 0.0 and 1.0
    jj.finalizeTrajectory(Math.max(0, Math.min(1, score)));
}

Issue: No Patterns Discovered

const patterns = JSON.parse(jj.getPatterns());

if (patterns.length === 0) {
    // Need more trajectories with >70% success
    // Record at least 3-5 successful trajectories
}

Examples

Example 1: Simple Learning Workflow

const { JjWrapper } = require('agentic-jujutsu');

async function learnFromWork() {
    const jj = new JjWrapper();
    
    // Start tracking
    jj.startTrajectory('Add user profile feature');
    
    // Do work
    await jj.branchCreate('feature/user-profile');
    await jj.newCommit('Add user profile model');
    await jj.newCommit('Add profile API endpoints');
    await jj.newCommit('Add profile UI');
    
    // Record operations
    jj.addToTrajectory();
    
    // Finalize with result
    jj.finalizeTrajectory(0.85, 'Feature complete, minor styling issues remain');
    
    // Next time, get suggestions
    const suggestion = JSON.parse(jj.getSuggestion('Add settings page'));
    console.log('AI suggests:', suggestion.reasoning);
}

Example 2: Multi-Agent Swarm

async function agentSwarm(taskList) {
    const agents = taskList.map((task, i) => ({
        name: `agent-${i}`,
        jj: new JjWrapper(),
        task
    }));
    
    // All agents work concurrently (no conflicts!)
    const results = await Promise.all(agents.map(async (agent) => {
        agent.jj.startTrajectory(agent.task);
        
        // Get AI suggestion
        const suggestion = JSON.parse(agent.jj.getSuggestion(agent.task));
        
        // Execute task
        const success = await executeTask(agent, suggestion);
        
        agent.jj.addToTrajectory();
        agent.jj.finalizeTrajectory(success ? 0.9 : 0.5);
        
        return { agent: agent.name, success };
    }));
    
    console.log('Results:', results);
}

Related Documentation

• NPM Package: https://npmjs.com/package/agentic-jujutsu
• GitHub: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentic-jujutsu
• Full README: See package README.md
• Validation Guide: docs/VALIDATION_FIXES_v2.3.1.md
• AgentDB Guide: docs/AGENTDB_GUIDE.md

Version History

• v2.3.2 - Documentation updates
• v2.3.1 - Validation fixes for ReasoningBank
• v2.3.0 - Quantum-resistant security with @qudag/napi-core
• v2.1.0 - Self-learning AI with ReasoningBank
• v2.0.0 - Zero-dependency installation with embedded jj binary

---

Status: ✅ Production Ready License: MIT Maintained: Active