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 ( {
    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) {
        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  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  |
| `newCommit(msg)` | Create new commit | Promise |
| `log(limit)` | Show commit history | Promise |
| `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 |  {
    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  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/VALIDATIONFIXESv2.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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aegntic
• Source: aegntic/cldcde
• License: MIT
• Homepage: https://cldcde.cc

Install and usage instructions live in the source repository linked above.