19 KiB
Gitgram TimeMachine
Git versions code. We version reality.
🕐 Like macOS Time Machine, but for AI coding! When AI makes a mistake, go back in time and fix it.
Time Machine for AI-Assisted Development - Capture and restore your complete workspace state including files, terminal commands, AI tool interactions, and runtime environments through supported integrations.
Quick Start - Time Machine Experience
# AI broke something? One command to fix:
aitm undo
# Go back to when tests were passing:
aitm back-to "when tests passed"
# Go back 30 minutes:
aitm back-to "30 minutes ago"
# Find when something broke:
aitm why "tests failing"
# Binary search for breaking change:
aitm bisect --test "npm test"
The Problem
AI-assisted development creates a new kind of failure:
- AI Temporal Confusion: AIs don't understand "when" things happened or development rhythm
- Lost Conceptual Context: AIs forget what concepts are active, completed, or blocked
- No Causal Understanding: AIs can't connect state changes to their causes
- Changes include: code, context, tool outputs, environment drift, terminal operations
- When something breaks, you need to recover the entire state, not just files
- Git can't answer:
- "What exact terminal commands were run right before it broke?"
- "What context did the AI have at that moment?"
- "What environment (Node/Python/Docker image) was it using?"
- "Can we restore the full working state instantly and reproduce the break deterministically?"
What We Built
Gitgram TimeMachine is a stateful, event-sourced layer that captures:
- File system state via manifest + content-addressable storage
- Terminal commands + outputs + exit codes (for managed sessions)
- AI tool interactions via MCP protocol integration
- Deterministic runtime via Docker capsules with pinned image digests
Then it exposes time travel as an API so AI agents and developers can:
- ✅ Restore any checkpoint (atomic, safe, with backup)
- ✅ Compare any two moments (diffs computed on demand)
- ✅ Automatically bisect regressions
- ✅ Rehydrate AI context from checkpoints
- ✅ Run in deterministic Docker capsules
NEW: AI Time & Concept Realization - Solves AI temporal confusion:
- ✅ AIs understand "when" things happened
- ✅ AIs track active vs completed concepts
- ✅ AIs get focus recommendations based on context
- ✅ AIs learn from development workflow patterns
Why It's Different Than Git
| Capability | Git | Gitgram TimeMachine |
|---|---|---|
| Captures untracked files | ❌ | ✅ |
| Terminal command history | ❌ | ✅ (managed sessions) |
| AI context rehydration | ❌ | ✅ |
| Deterministic environment | ❌ | ✅ (Docker capsules) |
| Atomic restore with backup | ❌ | ✅ |
| Content deduplication | ❌ | ✅ |
| MCP protocol for AI tools | ❌ | ✅ |
Installation
npm install -g @gitgram/timemachine
Authentication
Gitgram TimeMachine uses API keys for authentication (like OpenAI/ChatGPT):
1. Get Your API Key
- Sign up at timemachine.gitgram.app
- Go to Dashboard → API Keys
- Click "Create New Key"
- Copy your key (shown only once!)
2. Login with CLI
# Login with your API key
aitm login --api-key aitm_xxxxxxxxxxxxx
# Or use browser-based login
aitm login
# Check your auth status
aitm whoami
# Logout
aitm logout
3. Use the API Directly
curl -H "X-API-Key: YOUR_API_KEY" \
https://timemachine-api.gitgram.app/api/checkpoints
Public adoption evidence
GET /v1/adoption/summary reports aggregate cloud adoption and maintainer evidence from first-party persisted records. Schema version 2 gives separate windows for product adoption and OSS coverage plus explicit fresh, stale, or unmeasured coverage health. A completed coverage batch can report zero; absent coverage returns null with unmeasured; query failures return HTTP 503 with unavailable.
Maintainers ingest external contribution coverage and linked restore cases through transactional, idempotent routes protected by a dedicated rotating collector secret. Public responses exclude account, repository, project, checkpoint, restore, contributor, and contribution identifiers. See the methodology and collector runbook.
The public /maintainers workflow reads the same aggregate through a same-origin, no-store proxy. It runtime-validates the response, separates loading and service failure from measured zero, preserves unmeasured nulls, labels stale coverage, and offers a manual refresh. It never sends ADOPTION_INGESTION_SECRET to the browser; collection remains a server-side operator task documented in the runbook.
Quick Start
# Initialize in your project
cd your-project
aitm init
# AI automatically creates checkpoints via MCP
# (when using Claude Code, Cursor, etc.)
# View your timeline
aitm timeline
# See where you are
aitm where
# Go back in time
aitm restore <checkpoint-id>
# or
aitm back "before refactor"
New! AI-Friendly Commands
For Users (CLI)
aitm timeline # Visual timeline with before/after pairs
aitm where # Show current state and recent history
aitm back [query] # Go back (ID, description, or time)
aitm show_changes # What changed since last checkpoint
For AI (MCP Tools)
// AI automatically uses these:
where_am_i() // 🧭 Show current state
go_back({ to: "before user store" }) // ⏪ Natural language restore
show_changes() // 📊 What changed
undo_last() // ↩️ Quick undo
// NEW: AI Time & Concept Realization
ai_realize_concepts() // 🧠 Understand conceptual context
ai_realize_time() // ⏰ Understand temporal context
ai_suggest_focus() // 🎯 Get focus recommendations
ai_analyze_transitions() // 🔄 Analyze workflow patterns
CLI Commands
Setup & Project Management
aitm init # Initialize project tracking (opt-in, per project)
aitm status # Show pending changes since last checkpoint
aitm whoami # Show authenticated user
Checkpoints
aitm checkpoint "desc" # Manual checkpoint
aitm list # List all checkpoints (--json for tools)
aitm show <id> # Show checkpoint details
aitm diff <from> [to] # Compare checkpoints (--json available)
aitm preview <id> # Preview what restore would change
Restore & Time Travel
aitm restore <id> # Restore to checkpoint (atomic, with backup)
aitm rewind --to <id> # Restore + generate context file for AI
aitm resume # Start Claude with restored context injection
aitm undo # Undo last restore (from backup)
Natural Language Time Travel (NEW!)
aitm when "tests started failing" # Find when something happened
aitm back-to "when tests passed" # Natural language restore
aitm back-to "2 hours ago" # Time-based restore
aitm back-to last-green # Restore to last green state
aitm what-changed --since "1 hour ago" # Show what changed
aitm why "tests failing" # Analyze why something broke
File Operations
aitm file-history <file> # Show checkpoint history for file
aitm get-file <id> <file> # Get file content at checkpoint
aitm restore-file <id> <file> # Restore single file from checkpoint
aitm blame <file> # Show which checkpoint introduced lines
AI Tool Wrappers
aitm claude # PTY-based Claude wrapper with transcript capture
aitm run -- <command> # Run command with auto-checkpoint (before/after)
Search & Discovery
aitm search <query> # Search checkpoint names (--natural for NL)
aitm conversation # Show conversation history
aitm bisect --test "npm test" # Binary search for breaking change
aitm stats # Storage statistics
aitm kb-search <query> # Unified knowledge base search (cloud)
Cloud Sync
aitm login # Authenticate with cloud API
aitm logout # Clear cloud credentials
aitm sync # Sync checkpoints to cloud
aitm cloud # View cloud status and data
aitm pull <checkpoint-id> # Pull checkpoint from cloud
MCP Server
aitm mcp # Run MCP server for AI tools
Maintenance
aitm gc # Garbage collection (reclaim storage)
aitm verify <project-id> # Verify checkpoint/blob integrity
Docker Capsules (Deterministic Environments)
Available via MCP tools - see API.md for details.
AI Tool Integration (MCP)
Gitgram TimeMachine integrates with AI coding assistants via the Model Context Protocol (MCP). When an MCP-compatible tool calls our tools, we capture those interactions.
Transport
- Default: stdio (
aitm mcp) - Optional: HTTP/SSE can be added for custom clients, but stdio is the supported v1 path.
Compatibility Matrix
| Tool | MCP Support | Real-time Capture | Context Rehydration |
|---|---|---|---|
| Claude Code | ✅ Yes | ✅ Tool calls recorded | ✅ Via restore |
| Cursor | ✅ Yes (experimental) | ✅ Tool calls recorded | ✅ Via restore |
| Claude Desktop | ✅ Yes | ✅ Tool calls recorded | ✅ Via restore |
| Other MCP clients | ✅ Yes | ✅ Tool calls recorded | ✅ Via restore |
Note: We capture MCP tool calls in real-time. "Chat restore" means providing historical context to the AI, not modifying the tool's internal conversation UI.
Setup for Claude Code
# One-line setup (recommended)
claude mcp add --transport stdio aitm -- npx -y @gitgram/timemachine-mcp
# Or with user-wide scope
claude mcp add --scope user --transport stdio aitm -- npx -y @gitgram/timemachine-mcp
Setup for Cursor
// .cursor/mcp.json
{
"mcpServers": {
"aitimemachine": {
"command": "npx",
"args": ["-y", "@gitgram/timemachine-mcp"]
}
}
}
MCP Tools Available
AI-Friendly Navigation (NEW!)
where_am_i- Show current state and recent timelinego_back- Natural language restore ("before user store", "30 minutes ago")show_changes- Show what changed since last checkpointundo_last- Quick undo to previous checkpoint
AI Time & Concept Realization (NEW!)
ai_realize_concepts- Understand current conceptual context (active/completed/blocked concepts)ai_realize_time- Understand temporal context (time patterns, velocity, intervals)ai_suggest_focus- Get AI-driven focus recommendations with reasoningai_analyze_transitions- Analyze development state transitions and patterns
Checkpoint Management
before_action- Create "before" checkpoint (auto-called by AI)after_action- Create "after" checkpoint with change summarycheckpoint- Manual checkpoint creationlist_timepoints- List all checkpointsrestore- Restore to checkpointpreview_restore- Preview what restore will do
File Operations
tm_get_file_at- Get file content at checkpointtm_file_history- Get history of a file across checkpoints
Docker Capsules (Deterministic Execution)
tm_capsule_upsert- Create/update Docker capsule with pinned digesttm_capsule_exec- Execute command in capsule
Search & Discovery
tm_search- Search checkpoint namestm_timeline- Get timeline of eventstm_stats- Get storage statistics
Advanced
tm_rewind_to_last_green- Auto-rewind to last passing statetm_prompt_debug_regression- Generate debug prompt for regressionstm_prompt_postmortem- Generate incident postmortemtm_prompt_repro_steps- Generate reproduction steps
Production & Maintenance
tm_gc_run- Garbage collection (mark & sweep to reclaim storage)tm_integrity_check- Verify checkpoint and blob integrity
Architecture
Content-Addressable Storage (CAS)
- SHA-256 based - Files stored by content hash
- Massive deduplication - Only unique content stored once
- Sharded storage -
blobs/aa/bb/aabbcc... - Efficient - Perfect for large projects with many similar files
Manifest-Based Checkpoints
Each checkpoint is:
- Manifest - List of files with their hashes
- Pointers - Chat head, terminal head, capsule digest
- Immutable - Checkpoints never change
- Lightweight - Only manifests stored, blobs reused
Atomic Restore Process
To ensure safety, restore operations are atomic and always create backups:
- Acquire lock - Prevent concurrent operations via
.tm_lock - Build in temp - Materialize files from CAS to
.tm_internal/tmp_restore/ - Verify integrity - Check all blobs exist and hashes match manifest
- Backup current - Save current workspace to
.tm_internal/backups/(timestamped) - Atomic swap - Move files from temp to workspace (Windows-safe strategy)
- Release lock - Allow other operations
- Cleanup - Remove temp directories
Safety guarantees:
- Never partially restore (all-or-nothing)
- Always backup before restore
- Windows-compatible file operations
- Project-level locking prevents conflicts
Docker Capsules (Deterministic Environments)
Capsules provide deterministic execution environments:
- Pin image digest (not tag) - Guarantees exact same base image
- Mount workspace - Project files available inside container
- Capture outputs - Store stdout/stderr as blobs
- Reproducible execution - Re-run commands in identical environment
Use cases:
- Reproduce build/test failures exactly
- Verify behavior across different Node/Python versions
- Isolate environment-specific issues
Storage Structure
~/.aitimemachine/
├── blobs/ # Content-addressable storage
│ ├── aa/ # Sharded by hash prefix (first 2 chars)
│ │ ├── bb/ # Second level shard (chars 3-4)
│ │ │ └── aabbcc... # File contents (SHA-256 hash)
│ └── ...
├── events.db # SQLite database (projects, checkpoints, events)
└── .tm_lock # Global lock file
<project-root>/.tm_internal/ # Per-project metadata
├── tmp_restore/ # Temp directory for atomic restore
├── backups/ # Current state backups (timestamped)
└── .tm_lock # Project-level lock file
Ignore Patterns
By default, Gitgram TimeMachine excludes common build artifacts and dependencies to optimize storage:
Default exclusions:
node_modules/**,.venv/**,venv/**.git/**,.svn/**dist/**,build/**,target/**,.next/***.pyc,__pycache__/**.DS_Store,Thumbs.db
Security: We do NOT automatically exclude secrets. You should:
- Never commit
.envfiles with real credentials - Use
.gitignorepatterns for sensitive files - Review checkpoint contents before sharing
To customize patterns, modify ignoreGlobs in the project configuration.
Examples
Scenario: Restore to Working State
# Search for the checkpoint you want
aitm search "before refactor"
# List all checkpoints
aitm list
# Go back in time (creates backup automatically)
aitm restore cp_abc123def456
Scenario: Using from AI Tools
When an AI assistant uses our MCP tools:
- Tool calls are automatically recorded as events
- File changes are captured in checkpoints
- On restore, we provide "context rehydration" data to the AI
- AI can request debug prompts, postmortems, etc.
Context Rehydration: When restoring a checkpoint, the AI receives:
- Checkpoint metadata (name, timestamp, scope)
- List of files at that point
- Event timeline up to that checkpoint
- Suggested next steps
This allows the AI to understand "where we are" after a restore.
Production Features (Current)
Safety & Integrity
- ✅ Project locking - Prevents concurrent operations via
.tm_lock - ✅ Atomic operations - Never partially restore (all-or-nothing)
- ✅ Backup before restore - Always creates timestamped backup
- ✅ Verify blobs - Check hashes match before restore
- ✅ Windows-safe operations - Cross-platform compatibility
Performance
- ✅ Content deduplication - SHA-256 based CAS stores unique content once
- ✅ Sharded storage - Fast lookups via aa/bb/hash directory structure
- ✅ SQLite WAL mode - Concurrent reads, safe writes
- ✅ Indexed queries - Fast checkpoint and event lookups
Limitations
- ⚠️ Terminal capture - Only managed sessions (not all system terminals)
- ⚠️ Chat capture - Only via MCP tool calls (not native tool UI access)
- ⚠️ No auto-discovery - Projects must be initialized with
aitm init
Completed Features (v2.0)
Natural Language Time Travel (NEW!)
- ✅ Natural language queries - "when tests started failing", "2 hours ago"
- ✅ Smart restore -
back-tocommand with natural language support - ✅ Change analysis -
what-changedandwhycommands - ✅ Git bisect for checkpoints -
bisectto find breaking changes - ✅ File blame - Track which checkpoint introduced each line
Cloud & Collaboration
- ✅ Cloud sync - Sync checkpoints, sessions, and blobs to cloud API
- ✅ API key authentication - Secure API key based auth
- ✅ Push/pull - Push local checkpoints to cloud, pull from cloud
- ✅ Webhooks - Real-time notifications on checkpoint events
- ✅ SSE events - Server-sent events for live updates
Advanced Features
- ✅ Auto-checkpoint rules - Create checkpoints on "tests pass", "build success"
- ✅ PTY Claude wrapper - Transcript capture with session tracking
- ✅ Context injection - Rewind to checkpoint and inject context for AI
- ✅ JSON output - All commands support
--jsonfor tool integration
Roadmap (Future)
Phase 3 - Enhanced Features
- 🔜 Export/import - Share checkpoints via compressed archives
- 🔜 Team sharing - Collaborate on checkpoints
- 🔜 Incremental scanning - Optimize for large monorepos
- 🔜 Web dashboard - Browser-based checkpoint explorer
API Documentation
See the online documentation for complete MCP tool reference.
License
MIT