{"_id":"@agent-rewind/mcp","_rev":"6-ca99749b8d979e029175e5c07c603e04","name":"@agent-rewind/mcp","dist-tags":{"latest":"1.1.0"},"versions":{"0.1.0":{"name":"@agent-rewind/mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","ai-agents","claude-code","cursor","rewind","checkpoint","llm-proxy"],"license":"FSL-1.1-ALv2","_id":"@agent-rewind/mcp@0.1.0","maintainers":[{"name":"darkstar616","email":"rgburls@gmail.com"}],"homepage":"https://github.com/DarkStar616/rewind","bugs":{"url":"https://github.com/DarkStar616/rewind/issues"},"bin":{"agent-rewind":"dist/cli.js"},"dist":{"shasum":"7a043129067269b7ad5f4b769a358e374aa7e8a2","tarball":"https://registry.npmjs.org/@agent-rewind/mcp/-/mcp-0.1.0.tgz","fileCount":8,"integrity":"sha512-qfv/UJUi3xykhinhwRb2OBS/T+CJkGrb/ao6/R8aEVsMxL8LhqOfobQZsmOEXD0iok31Y4wzFzRnhmsbLxtvkw==","signatures":[{"sig":"MEQCIFM7QPSOPJXf2JDgbmmb8syKR0zPUKbLMrq+nA03RAZLAiBN7RqzZD+BUhrLJyCbU+kofgQqSrZeHLg8xAtv5xyRTg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":114679},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"6474bd46ee505c684fab9c1167e6f3277d0496a0","scripts":{"build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"darkstar616","email":"rgburls@gmail.com"},"repository":{"url":"git+https://github.com/DarkStar616/rewind.git","type":"git","directory":"packages/mcp"},"_npmVersion":"11.18.0","description":"Rewind CLI + stdio MCP server: whole-workspace checkpoint/rewind, a refuse-and-record effect barrier on a tamper-evident chain, and a token-saving record/replay proxy — for Claude Code, Cursor, and Codex CLI. Run with `npx @agent-rewind/mcp`.","directories":{},"_nodeVersion":"26.6.0","dependencies":{"zod":"^4.4.3","@agent-rewind/core":"^0.1.0","@agent-rewind/gateway":"^0.1.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.0_1787127186880_0.292264216741015","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agent-rewind/mcp","version":"0.1.1","keywords":["mcp","model-context-protocol","ai-agents","claude-code","cursor","rewind","checkpoint","llm-proxy"],"license":"FSL-1.1-ALv2","_id":"@agent-rewind/mcp@0.1.1","maintainers":[{"name":"darkstar616","email":"rgburls@gmail.com"}],"homepage":"https://github.com/DarkStar616/rewind","bugs":{"url":"https://github.com/DarkStar616/rewind/issues"},"bin":{"agent-rewind":"dist/cli.js"},"dist":{"shasum":"ebec70311fb5eaf76c16d43690fc1bede1ca56aa","tarball":"https://registry.npmjs.org/@agent-rewind/mcp/-/mcp-0.1.1.tgz","fileCount":8,"integrity":"sha512-FGWzak4B7nixlbFzm9N8uvMCwwIXsQnCFKVCgWkm8pmlxRTxrlf/HWKt2XfCrOq5Xu43mZUjry3d/XClZ9Jn1g==","signatures":[{"sig":"MEUCIDBk5JEYd9P2YyACCQ/n2NzTPmohuisZucl4ngVlit5LAiEAjzHh4/fNScSSSXj5cRggEJJnvt2UxGHg2HUIYj0y1Qk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":120067},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"b38f54ce178a0b43c871539957c2e6dabde29c44","scripts":{"build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"darkstar616","email":"rgburls@gmail.com"},"repository":{"url":"git+https://github.com/DarkStar616/rewind.git","type":"git","directory":"packages/mcp"},"_npmVersion":"11.18.0","description":"Rewind CLI + stdio MCP server: whole-workspace checkpoint/rewind, a refuse-and-record effect barrier on a tamper-evident chain, and a token-saving record/replay proxy — for Claude Code, Cursor, and Codex CLI. Run with `npx @agent-rewind/mcp`.","directories":{},"_nodeVersion":"26.6.0","dependencies":{"zod":"^4.4.3","@agent-rewind/core":"^0.1.1","@agent-rewind/gateway":"^0.1.1","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.1_1787129958829_0.5485722058234634","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@agent-rewind/mcp","version":"0.1.2","keywords":["mcp","model-context-protocol","ai-agents","claude-code","cursor","rewind","checkpoint","llm-proxy"],"license":"FSL-1.1-ALv2","_id":"@agent-rewind/mcp@0.1.2","maintainers":[{"name":"darkstar616","email":"rgburls@gmail.com"}],"homepage":"https://github.com/DarkStar616/rewind","bugs":{"url":"https://github.com/DarkStar616/rewind/issues"},"bin":{"agent-rewind":"dist/cli.js"},"dist":{"shasum":"812bfb195b08b4d42d9a9a4a1abc820800b81ab3","tarball":"https://registry.npmjs.org/@agent-rewind/mcp/-/mcp-0.1.2.tgz","fileCount":8,"integrity":"sha512-DbhM63dD2ZW41D61Hwg3NYZ5bCB4UVhsmbIWh7dpc2EVwEkE83w+Wtm2Ezh1p1NLax3VLxuVl0hxEYLJVfSZBw==","signatures":[{"sig":"MEUCIQCAKPNfTkzQsduQUjFx+w6tLh9iexFEE7pRbn+Jz6AILgIgP67kW6e2sa35eZROLsBH5W5DV31ALHsaBUY6Oc+GBF0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":120322},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"64f3ec6a4e185c2c12669d506f35d06d0e17fa6e","scripts":{"build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"darkstar616","email":"rgburls@gmail.com"},"repository":{"url":"git+https://github.com/DarkStar616/rewind.git","type":"git","directory":"packages/mcp"},"_npmVersion":"11.18.0","description":"Rewind CLI + stdio MCP server: whole-workspace checkpoint/rewind, a refuse-and-record effect barrier on a tamper-evident chain, and a token-saving record/replay proxy — for Claude Code, Cursor, and Codex CLI. Run with `npx @agent-rewind/mcp`.","directories":{},"_nodeVersion":"26.6.0","dependencies":{"zod":"^4.4.3","@agent-rewind/core":"^0.1.1","@agent-rewind/gateway":"^0.1.1","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.2_1787132241640_0.8674114775993438","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@agent-rewind/mcp","version":"0.1.3","keywords":["mcp","model-context-protocol","ai-agents","claude-code","cursor","rewind","checkpoint","llm-proxy"],"license":"FSL-1.1-ALv2","_id":"@agent-rewind/mcp@0.1.3","maintainers":[{"name":"darkstar616","email":"rgburls@gmail.com"}],"homepage":"https://github.com/DarkStar616/rewind","bugs":{"url":"https://github.com/DarkStar616/rewind/issues"},"bin":{"agent-rewind":"dist/cli.js"},"dist":{"shasum":"53b4cdac92ef6ebdcfb3123a1670376af79abd71","tarball":"https://registry.npmjs.org/@agent-rewind/mcp/-/mcp-0.1.3.tgz","fileCount":8,"integrity":"sha512-IhSHB0F2xTmNAAfzNJ0K9ZY0O8LQj7qquUHXgL0UUJZaIFzOJOX/YwePU/9Vgi5hWD+AxCcjzx/pjUw9gfQ75g==","signatures":[{"sig":"MEQCIBL6iBu0WVme3Ogh8gr2exhla72IKpUbyeFmnc5XY0MfAiAifBIDhWLXq26aSjjMna8S8vuaGL4qhgJq6LMQR0ANfQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":120328},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"94219e07c47e133ad00dce6e4dac2c14b576208e","scripts":{"build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"darkstar616","email":"rgburls@gmail.com"},"repository":{"url":"git+https://github.com/DarkStar616/rewind.git","type":"git","directory":"packages/mcp"},"_npmVersion":"11.18.0","description":"Rewind CLI + stdio MCP server: whole-workspace checkpoint/rewind, a refuse-and-record effect barrier on a tamper-evident chain, and a token-saving record/replay proxy — for Claude Code, Cursor, and Codex CLI. Run with `npx @agent-rewind/mcp`.","directories":{},"_nodeVersion":"26.6.0","dependencies":{"zod":"^4.4.3","@agent-rewind/core":"^0.1.1","@agent-rewind/gateway":"^0.1.1","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.3_1787136884717_0.18283306375275088","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@agent-rewind/mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","ai-agents","claude-code","cursor","rewind","checkpoint","llm-proxy"],"license":"FSL-1.1-ALv2","_id":"@agent-rewind/mcp@1.0.0","maintainers":[{"name":"darkstar616","email":"rgburls@gmail.com"}],"homepage":"https://github.com/DarkStar616/rewind","bugs":{"url":"https://github.com/DarkStar616/rewind/issues"},"bin":{"agent-rewind":"dist/cli.js"},"dist":{"shasum":"a06ef8946aac9d91e17070972a8097c460a67cc8","tarball":"https://registry.npmjs.org/@agent-rewind/mcp/-/mcp-1.0.0.tgz","fileCount":8,"integrity":"sha512-Xuplshzl9nbrM/AElvd1pxXQc680LsBuTm3YLKEUA1+ZlAqQf1zD8WG+q/IR8cZWjY62WDJb2bKamYfaKXL0Sg==","signatures":[{"sig":"MEUCIB26jyeYreatrjDia/4jFnA7x3s7FY6ajmT/yWdkLJIGAiEA/swRrxZdX3UwSIIfjNSljv1s3eXX/tbNe8+02TaICk8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":122244},"type":"module","engines":{"node":">=20.0.0"},"gitHead":"f7d4c306d15c65af0957332baf324dfa379b2d89","scripts":{"build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"darkstar616","email":"rgburls@gmail.com"},"repository":{"url":"git+https://github.com/DarkStar616/rewind.git","type":"git","directory":"packages/mcp"},"_npmVersion":"11.18.0","description":"Rewind CLI + stdio MCP server: whole-workspace checkpoint/rewind, a refuse-and-record effect barrier on a tamper-evident chain, and a token-saving record/replay proxy — for Claude Code, Cursor, and Codex CLI. Run with `npx @agent-rewind/mcp`.","directories":{},"_nodeVersion":"26.6.0","dependencies":{"zod":"^4.4.3","@agent-rewind/core":"^1.0.0","@agent-rewind/gateway":"^1.0.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.0_1787177955346_0.9457987621290909","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@agent-rewind/mcp","version":"1.1.0","description":"Rewind CLI + stdio MCP server: whole-workspace checkpoint/rewind, a refuse-and-record effect barrier on a tamper-evident chain, and a token-saving record/replay proxy — for Claude Code, Cursor, and Codex CLI. Run with `npx @agent-rewind/mcp`.","type":"module","license":"FSL-1.1-ALv2","keywords":["mcp","model-context-protocol","ai-agents","claude-code","cursor","rewind","checkpoint","llm-proxy"],"homepage":"https://github.com/DarkStar616/rewind","repository":{"type":"git","url":"git+https://github.com/DarkStar616/rewind.git","directory":"packages/mcp"},"engines":{"node":">=20.0.0"},"bin":{"agent-rewind":"dist/cli.js"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","prepublishOnly":"npm run build"},"dependencies":{"@agent-rewind/core":"^1.1.0","@agent-rewind/gateway":"^1.1.0","@modelcontextprotocol/sdk":"^1.29.0","zod":"^4.4.3"},"gitHead":"3eca060db407d97b12cbcf0df7d99c1266030a64","_id":"@agent-rewind/mcp@1.1.0","bugs":{"url":"https://github.com/DarkStar616/rewind/issues"},"_nodeVersion":"26.6.0","_npmVersion":"11.18.0","dist":{"integrity":"sha512-5HiwoxZGnEVerw+l00GlAKhM9MFfpxbF/e+wkpdcfyYyfiWGYwIbdtp6GUug7irqy0vbcqcoIeKGW9gzZh8EjA==","shasum":"3c32795c27ae904eb3f59697a484f2b6027b51f7","tarball":"https://registry.npmjs.org/@agent-rewind/mcp/-/mcp-1.1.0.tgz","fileCount":12,"unpackedSize":195057,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD8OMbIqWIlbGx92Xu9xGKz5Y+1rCQwh/p3n8SwHqfmeAIgCJmvb+itvMfuB7XkFmbM3o2g+KldSCf/e06FNbP93J8="}]},"_npmUser":{"name":"darkstar616","email":"rgburls@gmail.com"},"directories":{},"maintainers":[{"name":"darkstar616","email":"rgburls@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_1.1.0_1789028519139_0.9526399659146982"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-19T08:13:06.673Z","modified":"2026-09-10T08:21:59.444Z","0.1.0":"2026-08-19T08:13:07.028Z","0.1.1":"2026-08-19T08:59:18.989Z","0.1.2":"2026-08-19T09:37:21.792Z","0.1.3":"2026-08-19T10:54:44.848Z","1.0.0":"2026-08-19T22:19:15.531Z","1.1.0":"2026-09-10T08:21:59.266Z"},"bugs":{"url":"https://github.com/DarkStar616/rewind/issues"},"license":"FSL-1.1-ALv2","homepage":"https://github.com/DarkStar616/rewind","keywords":["mcp","model-context-protocol","ai-agents","claude-code","cursor","rewind","checkpoint","llm-proxy"],"repository":{"type":"git","url":"git+https://github.com/DarkStar616/rewind.git","directory":"packages/mcp"},"description":"Rewind CLI + stdio MCP server: whole-workspace checkpoint/rewind, a refuse-and-record effect barrier on a tamper-evident chain, and a token-saving record/replay proxy — for Claude Code, Cursor, and Codex CLI. Run with `npx @agent-rewind/mcp`.","maintainers":[{"name":"darkstar616","email":"rgburls@gmail.com"}],"readme":"# @agent-rewind/mcp\n\n**Reversible execution for AI coding agents** — the `agent-rewind` CLI and stdio MCP server.\n\nAgent Rewind gives any coding agent (Claude Code, Cursor, Codex CLI, Cline, Windsurf) three things it\ndoesn't have on its own:\n\n1. **Whole-workspace checkpoint & rewind** — snapshot the entire working tree (including changes made\n   by `bash`, not just file-edit tools) and restore any checkpoint. History survives a rewind.\n2. **A refuse-and-record effect barrier** — the first time an external effect fires (a payment, an\n   email, a provisioning call) it is admitted and recorded; re-firing that spent effect across a\n   rewind is **refused**, and the refusal is recorded too, with a reason the agent can act on.\n3. **A tamper-evident SHA-256 hash chain** — every checkpoint, effect, and refusal is linked on an\n   append-only chain that anyone holding it can independently verify.\n\n> **Honesty:** the default tier is **reversibility, not isolation or security.** It lets an agent undo\n> the workspace and refuses replaying a spent effect. It is *not* a sandbox or a jail — that's a\n> separate opt-in tier. Don't rely on it as a security boundary.\n\n## Install & run\n\nZero install — run straight from npm (requires Node ≥ 20):\n\n```bash\nnpx -y @agent-rewind/mcp mcp     # start the stdio MCP server\n```\n\n### Claude Code\n\n```bash\nclaude mcp add agent-rewind -- npx -y @agent-rewind/mcp mcp\n```\n\n### Cursor / Cline / Windsurf — add to the client's `mcpServers` config\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-rewind\": { \"type\": \"stdio\", \"command\": \"npx\", \"args\": [\"-y\", \"@agent-rewind/mcp\", \"mcp\"] }\n  }\n}\n```\n\n### Codex CLI\n\n```bash\ncodex mcp add agent-rewind -- npx -y @agent-rewind/mcp mcp\n```\n\nOnce added, the server tells your agent the workflow on connect — nothing else to configure.\n\n## How to use it (the workflow)\n\nThree moves, in plain terms:\n\n1. **Checkpoint before risky work.** Ask the agent (or let it decide) to `checkpoint` before a\n   multi-step change. It snapshots the *whole* workspace — including anything `bash` touches — and\n   returns an `id`.\n2. **Agent Rewind to undo.** If it goes wrong, `rewind <id>` restores the entire workspace to that point.\n   History is kept, so you can `replay` forward again.\n3. **Guard real-world effects.** Before an irreversible action (a payment, an email, a deploy), the\n   agent calls `guard_effect` with a stable key. The first call is recorded; a retry of the *same*\n   effect after a rewind is **refused** — so undoing a step can't re-charge a card or re-send an email.\n\nIn Claude Code (installed as a plugin) the guard runs **automatically** via a `PreToolUse` hook — you\ndon't have to remember it.\n\n## Use cases\n\n- **Long multi-step tasks** (big refactors, migrations, upgrades): recover from a bad step at minute 40\n  without redoing the first 39.\n- **Agents that touch the real world** (deploys, DB migrations, payments, emails): a safe undo that\n  can't double-fire the effect on a retry.\n- **Cheaper repetitive runs**: the optional proxy replays identical calls at zero cost and keeps prompt\n  caching healthy (see below).\n- **Safe experimentation**: checkpoint, try a risky approach, rewind if it doesn't pan out.\n\n## MCP tools\n\n`checkpoint`, `list`, `rewind`, `replay`, `guard_effect` (the five MVP tools), plus a `savings`\nreceipt and two `backtrack` tools. The server is stateless — every stateful tool mints or takes back\nan explicit checkpoint-id handle, and all durable state lives under `.rewind/` in the workspace.\n\n## CLI\n\n```\nagent-rewind checkpoint [label] | list | rewind <id> | replay <id> | guard <json>\n       | savings [--json] | cache-report <json> | prune <json> | analyze <json>\n       | gateway [--port <n>] [--upstream <url>] [--profile compat|lean] [--tenant <id>]\n       [--preserve-cache|--no-preserve-cache] [--prune-context|--no-prune-context]\n       [--config <path>] | mcp\n```\n\nA refused `guard` exits **2**, so a `PreToolUse` hook can block the offending tool call.\n\n## Token-saving proxy (optional)\n\nThe default `agent-rewind gateway` preserves the existing request-body behavior (`compat`).\nEnable the existing Anthropic cache planner and duplicate tool-result pruning explicitly:\n\n```bash\nagent-rewind gateway --profile lean --prune-context\n# Immediate opt-out on the next startup:\nagent-rewind gateway --no-preserve-cache --no-prune-context\n```\n\n`lean` enables cache preservation; pruning remains opt-in because it changes model-visible content.\n`--preserve-cache` enables the cache planner independently of the profile. The gateway prints its\nactive configuration and capability limits to stderr before its listening address. `max` fails with\nan actionable message until observation retrieval and its shaping guarantees are implemented.\n\n| Mechanism | Current behavior |\n| --- | --- |\n| Exact record/replay | Reuses recorded equivalent requests without an upstream call. Records are currently in memory and are cleared on restart; replay savings persist. |\n| Cache preservation | Adds an Anthropic prefix breakpoint when the client supplies none; other providers are skipped. Provider policy and usage determine the actual benefit. |\n| Pruning | Collapses repeated Anthropic-format tool results, preserving the first full result. Other formats are skipped. |\n\nThe savings receipt currently reports replay savings only. Enabling cache/pruning does not yet add\nseparate dollar attribution to that receipt. Pruning can reduce request size without reducing the\nprovider bill; assess paired task outcomes and billed cost before enabling it broadly.\n\nFor an Athena-managed tenant, run `agent-rewind gateway --tenant datami --profile lean` in that\ntenant's own working directory/process. The fixed tenant comes from configuration, never an HTTP\nheader; `x-rewind-scope` selects only a validated subordinate scope. Invalid identity returns 403.\nUse one process/store per tenant and never share its store with a legacy gateway. This loopback\nconfiguration is not a remotely authenticated service. All `x-rewind-*` headers are stripped upstream.\n\nConfiguration precedence is profile defaults, file overrides, environment, then explicit CLI flags.\nDuplicate/conflicting CLI flags, unknown options, missing values and invalid configuration fail at\nstartup. Use `--config gateway.json` (or `REWIND_CONFIG`) with this JSON shape:\n\n```json\n{\"profile\":\"lean\",\"port\":8788,\"upstream\":\"https://api.anthropic.com\",\"pruneContext\":false}\n```\n\nFile fields are `profile`, `port`, `upstream`, `preserveCache`, `pruneContext`, and `tenant`. Their environment\nequivalents are `REWIND_PROFILE`, `REWIND_PORT`, `REWIND_UPSTREAM`, `REWIND_PRESERVE_CACHE`, and\n`REWIND_PRUNE_CONTEXT`; `tenant` uses `REWIND_TENANT`. Boolean environment values must be exactly `true` or `false`. Supply provider\nauthentication in request headers; upstream URLs must use a root path and cannot contain credentials, query strings or fragments.\n\nThe executable nine-call mock benchmark reports **28.08% simulated cost savings**, with three\nreplayed calls out of nine. Unique calls report zero. Run `npm run --silent bench:json` from a source\ncheckout for a reproducible artifact with source hashes and denominators. These results are not real\nprovider billing or a general product savings estimate. The historical 120-trial Benchmark B curve is\nunverified: its runner and corpus were not located, so those percentages are withdrawn.\n\n\n## Links\n\n- Full install guide, architecture, and the product breakdown: <https://github.com/DarkStar616/rewind>\n- Licence: **FSL-1.1-ALv2** (Functional Source License 1.1, Apache-2.0 future grant at 2 years).\n# MCP tool profiles (v1.1 development)\n\nUse `rewind mcp --profile lean` or set `REWIND_MCP_PROFILE=lean`. The CLI flag takes precedence.\nUnknown profiles and options fail startup. The default remains `all`.\n\n| Profile | Tools | Approximate initialization tokens |\n| --- | --- | ---: |\n| `lean` | checkpoint, rewind, guard_effect | 691 |\n| `recovery` | lean tools plus list, replay, backtrack_candidates, backtrack_commit | 1,609 |\n| `analytics` | savings | 271 |\n| `all` | All eight existing tools | 1,841 |\n\nMeasured through the MCP SDK on 2026-09-09: serialized tool definitions plus server instructions,\ncharacters divided by four and rounded up. The previous full surface measured 9,359 characters\n(2,340 approximate tokens); the updated lean surface measured 2,762 characters. These are context-size\nestimates, not measured tokenization or dollar savings. Tests enforce the lean budget of 1,000.\nClients may add their own protocol wrappers. Hidden tools cannot be called through that profile.\n\nCheckpoint at meaningful risky boundaries and retain the returned id. The lean profile restores by\nid; switch to recovery for checkpoint discovery and failure memory. Tier 0 provides reversibility,\nnot isolation or security. Text and structured result forms remain available for compatibility.\n\n### Explicit durable ordered tape (v1.1 development)\n\nSet `REWIND_STORAGE_KEY` securely in the process environment to exactly 64 hex\ncharacters (32 random bytes). Keep that key for reopening this tenant's store.\nIt is never accepted as a CLI argument or JSON configuration field.\n\n```sh\nagent-rewind gateway --storage sqlite --tenant athena --epoch trial-1\n# Stop recording, then replay the ordered responses (strict misses return 409):\nagent-rewind gateway --storage sqlite --tenant athena --epoch trial-1 --replay-cursor review-1\n```\n\nStorage defaults to `.rewind/storage`; override with `--storage-directory`.\nEquivalent non-secret environment fields are `REWIND_STORAGE`, `REWIND_TENANT`,\n`REWIND_EPOCH`, `REWIND_REPLAY_CURSOR`, and `REWIND_STORAGE_DIRECTORY`; JSON uses\n`storage`, `tenant`, `epoch`, `replayCursor`, and `storageDirectory`. Existing\nconfiguration precedence applies. A tenant needs its own directory and key.\nThe optional SQLite native driver must be installed successfully; missing driver,\nmissing key, wrong key and corrupt storage fail visibly without memory fallback.\n\nWithout a cursor, every eligible live call is appended as a distinct occurrence,\nincluding identical requests. With a cursor, responses are consumed in order and\nthe cursor resumes across process restarts. Set a unique `x-rewind-request-id`\nfor each logical replay call and reuse it only when retrying that same call to\nrecover the original response without consuming another position. Control headers\nare stripped upstream. Unsupported mutations are refused; GET/HEAD metadata calls\nmay still reach the upstream. Conflicts and storage failures return 503 without a\npaid model fallback. Ordered replay is not yet included in `rewind savings`.\n\nThis remains opt-in: the default memory mode is unchanged. The gateway serializes\ntape requests within one process (queue limit 64). Request/response eligibility is\n512 KiB; oversized recording traffic passes through with an explicit skip log.\nEligible responses are held in full until recording commits, delaying first-token\ndelivery. On crossing the eligibility limit, held bytes are flushed and the rest\nstreams without recording. A client disconnect cancels its upstream request; an\nabsolute 120-second upstream deadline releases stalled work. SDK callers can set\n`tape.upstreamTimeoutMs`. Full request streaming/backpressure and incremental\nterminal staging remain U26 work. Multi-process recording of\nthe same epoch can conflict; run one writer. Physical WAL limits and broader\nstorage lifecycle certification remain separate acceptance work.\n## Bounded traffic analysis (v1.1 development)\n\nRun `rewind analyze --file capture.ndjson --ndjson`, or pipe a capture to\n`rewind analyze --stdin`. JSON arrays and a positional JSON argument remain supported.\nNDJSON is processed incrementally, with limits of 2 MiB per record, 128 MiB total,\n100,000 distinct request keys and 1,000 scopes. JSON arrays use a 16 MiB buffer limit.\n\nThe default attested report contains aggregate counters and a source byte count/hash,\nwithout prompt samples or scope labels. These are hypothetical exact-request repeat\nopportunities, not realized savings. Unknown request headers or upstream origins never\ncount as replay opportunities. Invalid token counts and counter overflow are rejected.\n`--legacy-json` explicitly includes the previous redacted sample and scope breakdown;\nreview captured content before sharing that expanded report. Errors contain bounded\nreasons and source byte counts/hashes, without request excerpts or filesystem paths.\n\n### Compare two requests' cache prefixes (v1.1 development)\n\nSave consecutive messages-style request bodies as JSON, then run:\n\n```sh\nagent-rewind cache-compare previous.json current.json\n```\n\nThe compact report identifies unchanged history, appended messages, appended\ncontent blocks, or divergence and gives a recommendation. `firstChangedPath`\npoints to the relevant message/block or request settings. Prompts and responses\nare not printed. No model call or workspace initialization occurs.\n\nThis is a conservative content comparison adapted from Headroom, not proof of a\nprovider cache hit. All request settings remain significant; object property\norder is ignored. Inputs must be regular UTF-8 JSON files, no more than 2 MiB each,\nwith message arrays. Responses `input`-style bodies are not yet supported by this\ncommand. Invalid or oversized inputs exit 1 with an actionable error.\n\nIn a source checkout before release, use `node packages/mcp/dist/cli.js` in place\nof `agent-rewind` after `npm run build`. Apache-2.0 attribution is shipped under\n`third_party/headroom/` in the MCP package.\n\nUse `--record-only` to explicitly clear a replay cursor inherited from configuration or\n`REWIND_REPLAY_CURSOR`. This makes live upstream calls and requires SQLite mode. It\ncannot be combined with `--replay-cursor`. Explicit `null` configuration values are\nrejected; omit a field to use its default.\n","readmeFilename":"README.md"}