Agentic Jujutsu

by ruvnet60de638630abNo license74K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated today

Quantum-resistant, self-learning version control for AI agents with ReasoningBank intelligence and multi-agent coordination

Instructions onlySoftware DevelopmentAI & Agents
AI-generated overview

Documents an AI-agent version control library with self-learning trajectories, pattern discovery, and multi-agent coordination.

What it does
This skill describes agentic-jujutsu, a version control wrapper for AI agents that tracks operations as learning trajectories, discovers successful operation patterns, and returns AI suggestions for similar tasks. It also covers multi-agent concurrent commits, operation statistics, and quantum-resistant fingerprinting and encryption. The document is reference material with JavaScript API examples rather than an executable workflow.
When to use it
Use it when multiple AI agents need to modify code concurrently without locks or conflicts, or when you want version control operations to feed a self-learning suggestion system. It is also relevant when quantum-resistant integrity verification or trajectory encryption is required.
Requirements
The documented library is installed via npx agentic-jujutsu and used from JavaScript with require('agentic-jujutsu'). Encryption uses a key generated with Node's crypto module. The skill itself ships no scripts and is instructions only.

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

bash
npx agentic-jujutsu

Basic Usage

javascript
const { JjWrapper } = require('agentic-jujutsu');
const jj = new JjWrapper();
// Basic operationsawait jj.status();await jj.newCommit('Add feature');await jj.log(10);
// Self-learning trajectoryconst 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 suggestionsconst 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:

javascript
// Start learning trajectoryconst 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 trajectoryjj.addToTrajectory();
// Finalize with success score (0.0-1.0) and critiquejj.finalizeTrajectory(0.95, 'Deployment successful, no issues');
// Later: Get AI-powered suggestions for similar tasksconst 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:

javascript
// Get discovered patternsconst 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:

javascript
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:

javascript
// Agent 1: Developerconst 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:

javascript
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 trajectoriesconst crypto = require('crypto');const key = crypto.randomBytes(32).toString('base64');jj.enableEncryption(key);

6. Operation Tracking with AgentDB

Automatic tracking of all operations:

javascript
// Operations are tracked automaticallyawait jj.status();await jj.newCommit('Fix bug');await jj.rebase('main');
// Get operation statisticsconst 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 operationsconst 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:

javascript
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:

javascript
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:

javascript
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:

javascript
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    }}
// Usageconst agent = new SelfImprovingAgent();
// Agent improves over timefor (let i = 1; i <= 10; i++) {    console.log(`\n--- Attempt ${i} ---`);    await agent.performTask('Deploy application');}

API Reference

Core Methods

MethodDescriptionReturns
new JjWrapper()Create wrapper instanceJjWrapper
status()Get repository statusPromise<JjResult>
newCommit(msg)Create new commitPromise<JjResult>
log(limit)Show commit historyPromise<JjCommit[]>
diff(from, to)Show differencesPromise<JjDiff>
branchCreate(name, rev?)Create branchPromise<JjResult>
rebase(source, dest)Rebase commitsPromise<JjResult>

ReasoningBank Methods

MethodDescriptionReturns
startTrajectory(task)Begin learning trajectorystring (trajectory ID)
addToTrajectory()Add recent operationsvoid
finalizeTrajectory(score, critique?)Complete trajectory (score: 0.0-1.0)void
getSuggestion(task)Get AI recommendationJSON: DecisionSuggestion
getLearningStats()Get learning metricsJSON: LearningStats
getPatterns()Get discovered patternsJSON: Pattern[]
queryTrajectories(task, limit)Find similar trajectoriesJSON: Trajectory[]
resetLearning()Clear learned datavoid

AgentDB Methods

MethodDescriptionReturns
getStats()Get operation statisticsJSON: Stats
getOperations(limit)Get recent operationsJjOperation[]
getUserOperations(limit)Get user operations onlyJjOperation[]
clearLog()Clear operation logvoid

Quantum Security Methods (v2.3.0+)

MethodDescriptionReturns
generateQuantumFingerprint(data)Generate SHA3-512 fingerprintBuffer (64 bytes)
verifyQuantumFingerprint(data, fp)Verify fingerprintboolean
enableEncryption(key, pubKey?)Enable HQC-128 encryptionvoid
disableEncryption()Disable encryptionvoid
isEncryptionEnabled()Check encryption statusboolean

Performance Characteristics

MetricGitAgentic Jujutsu
Concurrent commits15 ops/s350 ops/s (23x)
Context switching500-1000ms50-100ms (10x)
Conflict resolution30-40% auto87% auto (2.5x)
Lock waiting50 min/day0 min (∞)
Quantum fingerprintsN/A<1ms

Best Practices

1. Trajectory Management

javascript
// ✅ Good: Meaningful task descriptionsjj.startTrajectory('Implement user authentication with JWT');
// ❌ Bad: Vague descriptionsjj.startTrajectory('fix stuff');
// ✅ Good: Honest success scoresjj.finalizeTrajectory(0.7, 'Works but needs refactoring');
// ❌ Bad: Always 1.0jj.finalizeTrajectory(1.0, 'Perfect!'); // Prevents learning

2. Pattern Recognition

javascript
// ✅ Good: Let patterns emerge naturallyfor (let i = 0; i < 10; i++) {    jj.startTrajectory('Deploy feature');    await deploy();    jj.addToTrajectory();    jj.finalizeTrajectory(wasSuccessful ? 0.9 : 0.5);}
// ❌ Bad: Not recording outcomesawait deploy(); // No learning

3. Multi-Agent Coordination

javascript
// ✅ Good: Concurrent operationsconst 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 locksfor (const agent of agents) {    await agent.waitForLock(); // Not needed!    await agent.commit();}

4. Error Handling

javascript
// ✅ Good: Record failures with detailstry {    await jj.execute(['complex-operation']);    jj.finalizeTrajectory(0.9);} catch (err) {    jj.finalizeTrajectory(0.3, `Failed: ${err.message}. Root cause: ...`);}
// ❌ Bad: Silent failurestry {    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

javascript
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

javascript
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

javascript
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

javascript
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

javascript
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

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 and attribution

Source:ruvnet/rufloin.claude/skills/agentic-jujutsuat commit60de638

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from ruvnet/ruflo

Cron Schedule

ruvnet

Schedules persistent background workers using CronCreate with recommended cron intervals for recurring tasks.

DevOps & Cloud74Kupdated today

Autopilot Predict

ruvnet

Predicts the next task to work on using Ruflo autopilot MCP tools and learned patterns.

AI & Agents74Kupdated today

Autopilot Loop

ruvnet

Runs one autonomous autopilot iteration: checks status, executes the predicted task, logs it, and schedules the next wake.

AI & Agents74Kupdated today

Worker Integration

ruvnet

Coordinates background workers with specialized agents, mapping triggers to agents and tracking performance.

AI & Agents74Kupdated today

Worker Benchmarks

ruvnet

Runs performance benchmarks for the agentic-flow worker system and reports latency, throughput and memory metrics.

Software Development74Kupdated today

Swarm Advanced

ruvnet

Guides advanced Claude Flow swarm orchestration patterns for research, development, testing and analysis workflows.

AI & Agents74Kupdated today

More in Software Development

Playground

anthropics

Featured

Builds self-contained interactive HTML playgrounds with controls, live preview, and copyable prompt output.

Software Development37Kupdated today

M5 Onboard

anthropics

Featured

Provisions M5Stack ESP32 boards by detecting them on USB, flashing UIFlow 2.0 firmware, and installing a MicroPython app bundle.

Software Development37Kupdated today

Cardputer Buddy

anthropics

Featured

Guides iterating on a Cardputer-Adv MicroPython app bundle: adding apps, pushing files over USB-serial, tailing logs, and running REPL commands.

Software Development37Kupdated today

Web Design Guidelines

vercel-labs

Featured

Reviews UI code against Web Interface Guidelines fetched from a remote source and reports findings as file:line entries.

Software Development32Kupdated 5 weeks ago

Vercel React Native Skills

vercel-labs

Featured

React Native and Expo best-practice rules covering list performance, animation, navigation, UI patterns, state, and monorepo setup.

Software Development32Kupdated 5 weeks ago

Vercel React Best Practices

vercel-labs

Featured

Vercel's React and Next.js performance guidelines, organized as 70 rules for writing, reviewing, and refactoring code.

Software Development32Kupdated 5 weeks ago