# Agentic Jujutsu

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

- Skill: `majiayu000/agentic-jujutsu-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/agentic-jujutsu-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/agentic-jujutsu-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/majiayu000/agentic-jujutsu-2

---


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

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

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

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

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

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

```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
  }
}

// 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<JjResult>   |
| `newCommit(msg)`           | Create new commit       | Promise<JjResult>   |
| `log(limit)`               | Show commit history     | Promise<JjCommit[]> |
| `diff(from, to)`           | Show differences        | Promise<JjDiff>     |
| `branchCreate(name, rev?)` | Create branch           | Promise<JjResult>   |
| `rebase(source, dest)`     | Rebase commits          | Promise<JjResult>   |

### 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

```javascript
// ✅ 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

```javascript
// ✅ 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

```javascript
// ✅ 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

```javascript
// ✅ 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

```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

- **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