Undone Ai

---

1. Overview & Problem Space

Autonomous AI coding agents (Claude Code, Cursor Composer, OpenHands, Aider, Windsurf) execute multi-step, batch file modifications across complex codebases. During an extended session, an agent may perform dozens of sequential transformations across multiple files.

When an agent introduces a defect, architectural mistake, or security regression midway through execution (e.g., at Step #5 of a 20-step refactoring chain):

• Traditional Version Control (git reset --hard) operates at the whole-tree commit level, discarding all subsequent constructive modifications (the other 15 valid steps).
• Linear Editor Undo Buffers (Cmd+Z) operate strictly within single-file active memory, lacking cross-file dependency awareness, session durability, and branch isolation.

Undone provides an independent, local-first content-addressed temporal audit and surgical revert layer. Powered by Content-Addressed Storage (CAS), Myers $O(ND)$ Shortest Edit Script diffing, Base-Hunk 3-Way Temporal Rebase, and TypeScript Compiler API AST Dependency Graphs, Undone enables surgical single-file inversions that isolate and revert a flawed historical action while preserving 100% of non-overlapping subsequent modifications.

---

2. Core Capabilities

┌────────────────────────────────────────────────────────────────────────┐
│                        UNDONE CORE ARCHITECTURE                        │
├──────────────────────────────────┬─────────────────────────────────────┤
│  1. Content-Addressed Storage    │  2. Myers O(ND) SES Diff Engine     │
│  SHA-256 cryptographic objects   │  Minimal Shortest Edit Script path  │
├──────────────────────────────────┼─────────────────────────────────────┤
│  3. Base-Hunk 3-Way Rebase       │  4. TypeScript Compiler AST DAG     │
│  Surgical non-overlapping merge  │  Transitive impact & cycle tracking │
├──────────────────────────────────┼─────────────────────────────────────┤
│  5. Temporal State Reconstruction│  6. Model Context Protocol (MCP)    │
│  Byte-exact historical snapshots │  Atomic Agent Action Session window │
└──────────────────────────────────┴─────────────────────────────────────┘

2.1 Base-Hunk 3-Way Temporal Rebase

Reverts the change introduced in historical step $T_k$ on top of CurrentTip (which contains subsequent modifications $T_{k+1} \dots T_n$):

• Base = $T_k.\text{newContent}$ (State introduced by target step)
• Target = $T_k.\text{oldContent}$ (Pre-mutation state before step)
• CurrentTip = $\text{DiskContent}(F)$ (Latest file content containing subsequent edits)
• Result: Merges non-overlapping hunks cleanly; injects standard 3-Way conflict markers (<<<<<<< / ======= / >>>>>>>) only if subsequent edits touched the exact same region.

2.2 Formal TypeScript Compiler AST & Transitive DAG

Uses the official TypeScript Compiler API (ts.createSourceFile) for structural syntax tree analysis across .ts, .tsx, .js, .jsx, .mjs, and .cjs files:

• Extracts exported functions, classes, interfaces, type aliases, enums, multi-variable declarations, and default exports;
• Traces barrel re-exports (export * from './module', export { a } from './module'), namespace imports (* as X), type-only imports (import type), and CommonJS require();
• Computes arbitrary-depth transitive breakage cascades with cycle detection (visited: Set<string>).

2.3 Cryptographic Content-Addressed Storage (CAS)

• Immutable Object Store (.undone/objects/xx/yyyy...): Stores deduplicated content blobs indexed by their raw SHA-256 digest;
• Cryptographic Verification: Post-decompression SHA-256 assertions guarantee zero silent corruption or truncated payloads;
• Pure Metadata Ledger (.undone/ledger.json): Compact audit journal referencing immutable hash pointers.

2.4 Byte-Exact Temporal Workspace Reconstruction

• Reconstructs the entire repository file tree at any historical tick with zero state bloat;
• Computes arbitrary cross-tick diffs (e.g. Tick 3 vs Tick 28) across the timeline.

2.5 Optional Zero-Dependency Acceleration Kernel

• Unified IKernel interface contract establishes clean algorithm boundaries;
• Transparent fallback to pure TypeScript ensures zero required external dependencies (runs out-of-the-box on any machine without Rust or native compilation toolchains).

---

3. Quick Start & Installation

Option A: Zero-Config Auto-Installer (Recommended)

Automatically detects installed AI Agent configurations on your machine and injects the Undone MCP server:

npx -y undone-ai init

Supported agents:

• Claude Desktop (claude_desktop_config.json)
• Cursor IDE (.cursor/mcp.json)
• Claude Code CLI (.claude.json)

Option B: Global CLI Installation

npm install -g undone-ai

---

4. MCP Server Integration

Undone exposes standard Model Context Protocol (MCP) endpoints over stdio, allowing any MCP-compliant agent to automatically create atomic checkpoints and execute surgical rollbacks.

Manual Configuration

Add Undone to your agent's MCP configuration file:

{
  "mcpServers": {
    "undone": {
      "command": "npx",
      "args": ["-y", "undone-ai", "mcp"]
    }
  }
}

Exposed MCP Tools

Tool Name	Description
undone_session_begin	Opens an atomic Action Session transaction window, grouping multi-file agent edits into a single logical frame.
undone_session_end	Commits the active Action Session into an atomic Action Frame with CAS snapshots.
undone_checkpoint	Records an instant atomic frame snapshot of specified or all modified files.
undone_surgical_undo	Executes a 3-way inverse Myers delta rebase to revert a specific file at a target historical tick while preserving subsequent non-overlapping edits.
undone_status	Queries CAS storage metrics, total indexed files, deduplication savings, and active timeline tick.

---

5. CLI Command Reference

undone init

Scans your system for AI coding agent environments and automatically writes MCP configurations.

npx undone-ai init

undone watch [path]

Starts the background file watcher daemon and launches the interactive visual studio (port 4141 by default).

npx undone-ai watch .

Open http://localhost:4141 to inspect the real-time spatial tree, scrub the timeline, and perform 1-click surgical reverts.

undone wrap <command>

Wraps any CLI-based AI agent (such as Claude Code CLI or Aider) as a managed subprocess, automatically recording an atomic session frame upon completion.

npx undone-ai wrap claude

undone mcp [path]

Runs the standard Model Context Protocol server over stdio for direct IDE integration.

npx undone-ai mcp .

undone status [path]

Displays local Content-Addressed Storage statistics, compression ratios, deduplication savings, and frame counts.

npx undone-ai status

undone log [path]

Outputs a chronological visual audit trail of all recorded frames and file modifications directly to the terminal.

npx undone-ai log

---

6. Interactive Web Studio

When running undone watch, Undone serves a live web studio on http://localhost:4141:

• Spatial File Tree: Visual directory hierarchy with addition/deletion badges and frame-touch indicators;
• Timeline Scrubber: Interactive timeline slider to scrub between historical action frames;
• Side-by-Side & Unified DiffLens: High-fidelity diff viewer with formal AST exported/imported symbol inspection;
• Surgical Revert Modal: Preview inverse patches, pre-flight DAG breakage warnings, and 3-way conflict forecasts before executing disk writes;
• Interactive Tutorial Sandbox: Built-in interactive sandbox scenario with 1-click switching to explore Undone's capabilities.

Keyboard Shortcuts

Key	Action
Space	Play / Pause automated timeline playback
← / J	Step backward one frame
→ / L	Step forward one frame
Esc	Dismiss modals / drawers

---

7. Repository Layout

undone/
├── bin/
│   └── undone.js                 # Universal CLI & Daemon runner
├── crates/
│   └── undone-core/              # Rust Native Kernel (Optional Accelerator)
│       ├── Cargo.toml
│       └── src/
│           ├── lib.rs            # Library interface
│           ├── diff.rs           # Myers O(ND) algorithm
│           ├── cas.rs            # Content-addressed storage (zstd)
│           └── ast.rs            # Multi-language token parser
├── src/
│   ├── adapters/
│   │   ├── agentProfiles.ts      # Agent metadata & avatars
│   │   └── mcpServer.js          # Standard MCP JSON-RPC Server
│   ├── components/               # React Web Studio components
│   │   ├── DiffLens.tsx          # AST-aware diff viewer
│   │   ├── SpatialFileTree.tsx   # Visual repository tree
│   │   ├── SurgicalModal.tsx     # 3-Way Rebase & DAG confirmation dialog
│   │   └── TimelineScrubber.tsx  # Interactive timeline controller
│   ├── core/
│   │   ├── kernel.ts             # IKernel interface contract & CasIntegrityError
│   │   ├── kernelBridge.ts       # Unified bridge with transparent fallback
│   │   ├── patchEngine.ts        # Myers diff & Base-Hunk 3-way rebase
│   │   ├── dagEngine.ts          # TypeScript Compiler API AST & DAG BFS
│   │   ├── temporalReconstructor.ts # Historical snapshot reconstructor
│   │   ├── cas.ts                # CAS store with SHA-256 verification
│   │   └── engine.ts             # Visual tree & surgical planning coordinator
│   ├── App.tsx                   # Studio application root
│   └── main.tsx
├── package.json
└── README.md

---

8. License

This project is licensed under the MIT License.