Torpor

# Torpor > Local time travel for AI coding sessions. AI coding agents move fast, until they slowly create a broken future. Torpor records verified checkpoints, branch history, session evidence, and restore-safe project states under `.torpor/`, so you can return to a trusted checkpoint, preserve the failed future as evidence, and continue safely on a new branch. Git is source control. Torpor is recovery for AI coding workflows. ## Why Torpor Exists Imagine you are building a long-term project with AI coding CLIs such as Codex, Claude Code, OpenCode, or other local agents. At first, everything feels fast. You ask the agent to add a feature, fix a bug, rename files, improve the structure, update tests, and clean up old code. Each task looks reasonable when it happens. After many sessions, the project starts acting wrong. The bug is not in one obvious file. It may come from a refactor done three days ago, a helper function changed yesterday, a deleted config file, and a quick fix that made sense at the time. Now the agent is trying to repair a system that already has several layers of past decisions built into it. Git helps when you made clean commits at the right moments. But AI work often moves through messy middle states: prompts, tool calls, partial edits, failed fixes, deleted files, and changes that looked fine until later. When the project breaks, asking the agent to "undo the bad parts" can be risky because the agent may not know exactly where the damage started. Torpor exists for that moment. Instead of deleting the failed future, Torpor keeps it as evidence. You can travel back, continue from safety, and reveal only the parts of the broken future that help the agent understand what to avoid. ## What Torpor Does - Saves branch-aware checkpoints for AI coding sessions. - Creates a trusted zero baseline backed by the normal checkpoint store. - Preserves broken futures as evidence. - Restores trusted checkpoints safely. - Creates continuation branches after travel. - Keeps `.torpor/` above time. - Connects checkpoint, file, branch, travel, and risk evidence through always-on intelligence observations - Verifies manifests, hashes, chunks, packs, archives, and branch metadata. - Supports Codex and Claude wrapper flows. - Exposes MCP tools for AI coding clients. - Captures local session evidence for wrapped CLI sessions. - Reveals failed-future evidence in controlled levels. Use Torpor when: - An AI agent is making real edits across more than one sitting. - The project is large enough that "just ask the agent to undo it" is risky. - You want to preserve a broken future before returning to a trusted checkpoint. - You need branch-aware recovery without deleting the evidence of what failed. - You want local, inspectable checkpoints with hashes, manifests, verification, and restore checks. You probably do not need Torpor for a throwaway one-file experiment. For serious AI-assisted projects, it belongs next to Git because it protects a different layer of work. ## 60-Second Demo See [docs/demo.md](docs/demo.md) for a copy-paste walkthrough. Short version: ```bash cargo install --path . --locked mkdir torpor-demo cd torpor-demo printf 'print("safe version")\n' > app.py torpor setup --mode hybrid torpor doctor torpor zero create torpor save "safe checkpoint" printf 'raise RuntimeError("broken future")\n' > app.py torpor save "broken future" torpor travel --branch main --checkpoint main-0001 cat app.py torpor verify ``` After travel, Torpor keeps the failed future in `.torpor/` and continues from the restored checkpoint on a continuation branch. ## Quickstart ```bash cargo install --path . --locked torpor setup --mode hybrid torpor doctor torpor zero create torpor save "known-good checkpoint" torpor run codex # or torpor run claude torpor checkpoints torpor branches torpor travel torpor reveal torpor verify ``` ## Documentation - [Quickstart](docs/quickstart.md) - [Examples](docs/examples.md) - [Codex setup](docs/codex.md) - [Claude Code setup](docs/claude-code.md) - [MCP](docs/mcp.md) - [Storage and integrity](docs/storage-integrity.md) - [Zero baseline](docs/zero-baseline.md) - [Travel model](docs/travel-model.md) - [Recovery reveal](docs/reveal-model.md) - [Threat model](docs/threat-model.md) - [FAQ](docs/faq.md) - [Why Torpor exists](docs/launch-story.md) - [Vision](VISION.md) - [Architecture](ARCHITECTURE.md) - [Roadmap](ROADMAP.md) - [Changelog](CHANGELOG.md) - [Contributing](CONTRIBUTING.md) - [Code of Conduct](CODE_OF_CONDUCT.md) ## Core Workflow ```text 1. Enable Torpor in a project. 2. Save trusted checkpoints. 3. Keep working with an AI coding agent. 4. If the project becomes broken, travel back. 5. Torpor saves the broken state as an escape checkpoint. 6. Torpor restores the trusted checkpoint. 7. Torpor creates a new continuation branch. 8. The failed future remains available as evidence. ``` ## Example: Escaping A Broken Future ```bash torpor on torpor save "auth system is stable" torpor run codex # later, after the project becomes broken torpor travel # choose: # branch: main # checkpoint: main-0001 torpor reveal --level 2 torpor verify ``` Torpor restores the older checkpoint, creates a new branch, and gives the agent a controlled summary of what went wrong in the escaped future. ## How Torpor Is Different From Git Git is source control. Torpor is AI-session recovery. | Need | Git | Torpor | | --- | --- | --- | | Track source changes | Yes | Yes, as recovery evidence | | Restore files | Yes | Yes, with checkpoint verification | | Preserve failed AI futures | Manual | Yes | | Create continuation branch after rollback | Manual | Yes | | Store AI session evidence | No | Yes | | Reveal failed-future context to an agent | No | Yes | | Treat recovery history as above time | No | Yes | Torpor does not replace Git. Use both. ## Above Time `.torpor/` is above time. That means Torpor never snapshots, restores, rewinds, deletes, or overwrites `.torpor/` as project state. Project files can move through time. `.torpor/` remembers every timeline. ## Checkpoints And Archives Torpor defaults to priority `5` because recovery usually matters more than saving a little disk. In current V2 storage, normal priority `5` checkpoints use verified compressed chunk packs as the restore path. They do not duplicate every save into a full-project archive by default. The zero baseline is the first trusted origin reality for a project: ```bash torpor zero create torpor zero status ``` Zero is backed by a normal verified checkpoint. `.torpor/zero/` stores metadata, a file-state Merkle summary, and a human-readable summary, while the exact bytes still live in Torpor's object store and checkpoint manifests. When you need a portable archive, use: ```bash torpor pin-archive --branch main --checkpoint main-0001 torpor export --branch main --checkpoint main-0001 --archive portable-main-0001.tar.zst ``` Pinned and exported archives use deterministic tar data with zstd level `22`, frame checksums, and long-distance matching. External inspection may require: ```bash zstd --long=31 -d -c .torpor/timelines/<branch>/backups/<checkpoint>/workspace.tar.zst | tar -tf - ``` ## Recovery Reveal After travel, Torpor does not dump the entire failed future into the agent. Instead, it reveals evidence in levels: ```text 1 = minimal summary 2 = summary plus key branch/checkpoint/path facts 3 = deeper task and change summaries 4 = selected file evidence 5 = maximum detailed evidence package ``` This keeps token use controlled while preserving access to deeper evidence. ## Basic Commands ```bash torpor setup torpor doctor torpor on torpor off torpor status torpor zero create torpor zero status torpor save "safe checkpoint" torpor checkpoints torpor branches torpor verify torpor reveal torpor analyze torpor file-history src/app.py torpor travel torpor travel --branch main --checkpoint main-0001 torpor pin-archive --branch main --checkpoint main-0001 torpor export --branch main --checkpoint main-0001 --archive portable-main-0001.tar.zst torpor run codex torpor run claude torpor mcp ``` ## Codex Setup Build Torpor and register the stdio MCP server with Codex: ```bash cargo install --path . --locked codex mcp add torpor -- torpor mcp codex mcp list ``` For the Codex `$torpor` command surface, install the bundled skill: ```bash mkdir -p ~/.codex/skills cp -R plugins/torpor/skills/torpor ~/.codex/skills/torpor ``` Inside Codex: ```text $torpor setup $torpor status $torpor done implemented the requested change $torpor checkpoints $torpor verify ``` ## Claude Code Setup Build Torpor and validate the bundled Claude Code plugin: ```bash cargo install --path . --locked claude plugin validate plugins/torpor ``` Load the plugin while developing from this checkout: ```bash claude --plugin-dir plugins/torpor ``` Inside Claude Code: ```text /torpor:torpor setup /torpor:torpor status /torpor:torpor done implemented the requested change /torpor:torpor checkpoints /torpor:torpor verify ``` MCP-only setup: ```bash claude mcp add torpor -- torpor mcp ``` The MCP server is client-neutral. Any compatible local agent client can launch the same `torpor mcp` command when its MCP configuration points at this binary. Wrapped sessions launched with `torpor run codex` or `torpor run claude` are run through a PTY and recorded as JSON Lines transcripts in the active branch's `sessions/` directory. This does not replace a CLI's built-in resume or session history, but it gives Torpor its own local evidence trail for what happened during wrapped sessions. ## Storage And Integrity Internals Torpor uses verified local storage under `.torpor/`. Current storage includes: - checkpoint manifests - content-addressed chunks - compressed chunk packs - chunk locator indexes - optional portable workspace archives - content hashes - pack hashes - archive hashes - Merkle roots - branch lineage metadata - verification before restore - `torpor verify` Torpor checks: - graph metadata - branch lineage - manifests - chunks - packs - pinned workspace archives - restore-critical paths - `.torpor/` exclusion rules ## Safety Model Torpor is designed to fail closed. If verification fails, Torpor should refuse to trust the checkpoint instead of silently restoring unsafe history. Use Git and normal backups too. Torpor is a recovery layer, not a replacement for every other safety practice. ## Current Status Torpor is early. Implemented pieces include: - `torpor on`, `torpor off`, `torpor status`, and `torpor doctor` - branch-first `.torpor/` storage - verified checkpoints with priorities `1-5` - checkpoint-backed zero baseline with `torpor zero create/status` - content-addressed chunks - compressed chunk packs - optional portable workspace archives through `pin-archive` and `export` - manifests, hashes, and Merkle roots - branch and checkpoint listing - `torpor verify` - `torpor travel` - escape checkpoint before restore - continuation branch after travel - recovery reveal output - `torpor run codex` - `torpor run claude` - PTY transcript capture - stdio MCP server mode - GitHub Actions CI Still early: - UX polish - more real-world testing - more examples - more CLI adapters - stronger docs - installation packages - broader platform validation ## Project Values - Local first - Fail closed - Zero as metadata over verified storage - Branch aware - Honest scope - Agent-friendly - Git-compatible - Recovery before convenience - Evidence before guessing ## Development Checks ```bash cargo test cargo fmt --check cargo clippy --all-targets --all-features -- -D warnings ``` ## Credits Created by Kylne700. Torpor was conceived, directed, and maintained by Kylne700, with AI-assisted development support from OpenAI Codex. See [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md). ## Security Torpor reads, snapshots, verifies, and restores project files. Please report security-sensitive issues responsibly. See [SECURITY.md](SECURITY.md). ## Contributing Contributions that improve restore safety, checkpoint integrity, documentation accuracy, and install clarity are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). ## License Apache-2.0. See [LICENSE](LICENSE).