{"_id":"@codemeall/harness-bridge","_rev":"3-231de3c230459b05762a971d0ecd4b4a","name":"@codemeall/harness-bridge","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@codemeall/harness-bridge","version":"0.1.0","license":"MIT","_id":"@codemeall/harness-bridge@0.1.0","maintainers":[{"name":"codemeall","email":"mdab.aziz01@gmail.com"}],"bin":{"harness-bridge":"dist/cli.js"},"dist":{"shasum":"b7d56848f94f5c5feaa92454297542de8ef4274f","tarball":"https://registry.npmjs.org/@codemeall/harness-bridge/-/harness-bridge-0.1.0.tgz","fileCount":45,"integrity":"sha512-1Ge6chuwKY6VU+wA1FLdYDyYcGnRmMY9ZLCwqRR/BKHWA05cyNZ1GYLlZotOk+XiJgdv26xKgMLZ70L+tRUb3g==","signatures":[{"sig":"MEUCIE3qdxZnVMZIupdoyQ3ltH5X/Xsho655bQ+yFyxVzoMzAiEAm1e5RwpBluX0OM318I57ovUo3Hj2W/TFIHAAD/2NYOI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":177113},"type":"module","engines":{"node":">=20"},"gitHead":"f2e43bd36f45db0430357709551c51e5a9d222ef","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"codemeall","email":"mdab.aziz01@gmail.com"},"_npmVersion":"10.9.8","description":"MCP-first local tooling for Harness Bridge markdown handoffs.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^3.25.76","yaml":"^2.8.1","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.4","typescript":"^5.8.3","@types/node":"^22.15.29"},"_npmOperationalInternal":{"tmp":"tmp/harness-bridge_0.1.0_1779876255168_0.8761559093963749","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@codemeall/harness-bridge","version":"0.1.1","license":"MIT","_id":"@codemeall/harness-bridge@0.1.1","maintainers":[{"name":"codemeall","email":"mdab.aziz01@gmail.com"}],"bin":{"harness-bridge":"dist/cli.js"},"dist":{"shasum":"297cc3c68334f8dc6441890d371eca82a1cca514","tarball":"https://registry.npmjs.org/@codemeall/harness-bridge/-/harness-bridge-0.1.1.tgz","fileCount":45,"integrity":"sha512-bhaDBOGq9rBjD04/m0Qd5PxWyPp7f6ZMYZ/Sm05F/DoEdOD2T9IwCVecMepjZsi0FMGQw9I/TxZdVbGM3AhGFA==","signatures":[{"sig":"MEYCIQCKIcq++5QhiXh8abOlOLi8JXj2eo27IwQPCPrlrdSixwIhAMY2PGZlKa0sfxI22WU5AqmZZN0XAMZbidfMxGDCuT5i","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":177300},"type":"module","engines":{"node":">=20"},"gitHead":"1a3cb430746e8ba85b901dc00559bce1aade22de","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"codemeall","email":"mdab.aziz01@gmail.com"},"_npmVersion":"10.9.8","description":"MCP-first local tooling for Harness Bridge markdown handoffs.","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^3.25.76","yaml":"^2.8.1","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.4","typescript":"^5.8.3","@types/node":"^22.15.29"},"_npmOperationalInternal":{"tmp":"tmp/harness-bridge_0.1.1_1779877678216_0.4305723244741442","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@codemeall/harness-bridge","version":"0.1.2","description":"MCP-first local tooling for Harness Bridge markdown handoffs.","type":"module","bin":{"harness-bridge":"dist/cli.js"},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","typecheck":"tsc -p tsconfig.json --noEmit"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","yaml":"^2.8.1","zod":"^3.25.76"},"devDependencies":{"@types/node":"^22.15.29","typescript":"^5.8.3","vitest":"^3.1.4"},"engines":{"node":">=20"},"license":"MIT","_id":"@codemeall/harness-bridge@0.1.2","gitHead":"d11d3e46b7e0f1e5b7154da2e7eda2592a54900b","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-dJ0RsXPsl+eYJfW5o5+e3xvExBZATZ9NG0SENuMwG7LD8kp/fjrU3VhuYWdk3yoSwk/rT74+DIvmFZaUHwGuGg==","shasum":"9fa6ae9f704e0a190d3f082bae250a1a171948cc","tarball":"https://registry.npmjs.org/@codemeall/harness-bridge/-/harness-bridge-0.1.2.tgz","fileCount":45,"unpackedSize":184265,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEgLFhse2iY4XCkVQ/3tawf3G3aaoGg4luoVjCHmT2RmAiBkUdiSu4zeHh3p28A0Z3VFBuovYlqv6wkuxOHY2jwg+Q=="}]},"_npmUser":{"name":"codemeall","email":"mdab.aziz01@gmail.com"},"directories":{},"maintainers":[{"name":"codemeall","email":"mdab.aziz01@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/harness-bridge_0.1.2_1779879148062_0.9785990224786607"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-27T10:04:14.902Z","modified":"2026-05-27T10:52:28.301Z","0.1.0":"2026-05-27T10:04:15.381Z","0.1.1":"2026-05-27T10:27:58.366Z","0.1.2":"2026-05-27T10:52:28.198Z"},"license":"MIT","description":"MCP-first local tooling for Harness Bridge markdown handoffs.","maintainers":[{"name":"codemeall","email":"mdab.aziz01@gmail.com"}],"readme":"# Harness Bridge\n\n> Hand off AI coding agent context between sessions and providers — through a single committed markdown file.\n\n**The problem.** Your AI coding agent is mid-task and the session ends — token limit hit, the tool crashed, or you want to move the work to a different provider. The next session starts cold. It re-asks what you're doing, re-decides things the previous session already settled, and silently drops the open questions you were deferring. You either retell the whole story or accept the regression.\n\n**The fix.** The agent maintains a tiny markdown file at `.harness/bridge.md` while it works. When any session ends, a new session — same provider or different — reads that file, grounds itself in your repo's git state, restates what's going on, waits for your confirmation, and continues exactly where the previous one left off.\n\n**What you install.** Recommended: configure the local MCP server so your coding agent can call bridge tools directly. If your agent does not support MCP, use the prompt-only fallback. In both modes, `.harness/bridge.md` stays the source of truth.\n\n**Related product.** LLM Wiki is a separate markdown knowledge-base workflow for long-lived research, design rationale, and decisions. Harness Bridge tracks the current task; LLM Wiki tracks the durable context around the work. See [`docs/llm-wiki.md`](./docs/llm-wiki.md).\n\n---\n\n## Table of contents\n\n- [Harness Bridge core](#harness-bridge-core)\n- [What a bridge looks like](#what-a-bridge-looks-like)\n- [How it works in 30 seconds](#how-it-works-in-30-seconds)\n- [Install](#install)\n- [Use it](#use-it)\n- [Common scenarios](#common-scenarios)\n- [Bridge prompt reference](#bridge-prompt-reference)\n- [Related product: LLM Wiki](#related-product-llm-wiki)\n- [Provider support (bridge)](#provider-support-bridge)\n- [MCP integration](#mcp-integration)\n- [MCP usage guide](./docs/mcp-usage.md)\n- [FAQ (bridge)](#faq-bridge)\n- [What it is / what it isn't](#what-it-is--what-it-isnt)\n- [Uninstall (bridge)](#uninstall-bridge)\n- [Project status & roadmap](#project-status--roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Harness Bridge core\n\nHarness Bridge is the core handoff workflow in this repo. If your goal is reliable handoff between AI sessions while coding in a project repo, start here.\n\n---\n\n## What a bridge looks like\n\nA real bridge file mid-task. This is the actual artifact — readable by you, by your AI agent, and diffable in git.\n\n```markdown\n---\nschema: harness-bridge/v1\ngenerated_by: claude-code\ngenerated_at: 2026-05-20T14:08:00Z\nlast_updated: 2026-05-20T15:42:00Z\ncadence: checkpoint\nrepo: example-api\nbranch: feat/rate-limit\nhead: 7f3a2c1\ndirty: false\n---\n\n# Bridge — Add token-bucket rate limiter to public API\n\n## Goal\nPublic API endpoints currently have no rate limiting; abuse from a single token\ncan degrade service for everyone. We're adding a per-token token-bucket limiter\nwith configurable defaults (60/min, burst 20) and per-route overrides.\n\n## Plan\n- [x] Define RateLimiter interface\n- [x] In-memory TokenBucket for unit tests\n- [x] Redis-backed TokenBucket\n- [~] **Wire middleware into src/server.ts** — interface plugged in; per-route overrides pending\n- [ ] Add per-route overrides\n- [ ] Integration test against real Redis\n- [ ] Document config\n\n## Next action\nOpen src/routes/index.ts and pipe each route's `rateLimit` metadata into the\n`rateLimitMiddleware()` call already wired in src/server.ts:42. Start with\nPOST /v1/messages which needs 10/min, burst 3.\n\n## Decisions & rationale\n- **Token bucket over fixed window** — smoother for legit bursts.\n- **Redis over in-memory for prod** — multiple replicas; in-memory is per-process.\n\n## Open questions\n- 429 vs 503 on limit hit? — defer; default to 429.\n\n## Files touched\n- src/middleware/rate-limit/* — new module\n- src/server.ts — wired at line 42; default config only\n- tests/rate-limit.test.ts — in-memory covered; Redis pending\n```\n\nSee [`examples/`](./examples/) for three more realistic bridges (mid-feature, mid-bugfix with `dirty: true`, and one recovered from a crashed session's transcript).\n\n---\n\n## How it works in 30 seconds\n\n```\n┌─────────────────┐   writes & updates    ┌──────────────────────┐\n│  Session A      │ ──────────────────▶  │  .harness/bridge.md  │\n│  (Claude Code,  │                       │  (committed in git)  │\n│   any provider) │                       └──────────┬───────────┘\n└─────────────────┘                                  │\n       ╳ session ends                                │ reads & resumes\n       (limit / crash / switch)                      ▼\n                                          ┌──────────────────────┐\n                                          │  Session B           │\n                                          │  (same or different  │\n                                          │   provider)          │\n                                          └──────────────────────┘\n```\n\nThe agent updates the bridge **at checkpoints** as it works — after a completed task item, a recorded decision, a batch of file edits. So even if a session dies without warning, the most recent state is already on disk, ready for the next session to read.\n\nWhen the on-disk bridge isn't enough (stale, missing, or suspect), a separate **recovery flow** reads the producing session's transcript and rebuilds the bridge from there.\n\n---\n\n## Install\n\nThe easiest path is MCP. You configure the server once per agent/editor, then initialize each repo with a normal instruction like \"Use Harness Bridge to initialize this repo.\"\n\n### Option A — MCP (recommended)\n\nConfigure Harness Bridge as a local stdio MCP server:\n\n```bash\nnpx -y @codemeall/harness-bridge mcp\n```\n\nYou normally do not run that command by hand; add it to your agent's MCP config so the agent starts it when needed. See [`docs/mcp-usage.md`](./docs/mcp-usage.md) and [`providers/mcp.md`](./providers/mcp.md) for Claude Code, Cursor, Codex, Gemini CLI, and Antigravity setup.\n\nAfter MCP is connected, open your target repo in the agent and say:\n\n```text\nUse Harness Bridge to initialize this repo for handoffs.\n\nTitle: <one-line task title>\nGoal: <2-4 sentences describing what we are trying to finish and why>\n```\n\nThe agent calls `bridge_init`, creates `.harness/bridge.md`, and can install the maintainer snippet into the right provider instructions file when requested.\n\n### Option B — prompt fallback\n\nUse this when your agent cannot use MCP. Open your AI coding agent in the target repo and paste the contents of [`prompts/init.md`](./prompts/init.md) as your first message. The agent will:\n\n1. Create `.harness/` at the repo root.\n2. Append the maintainer snippet to your provider's instructions file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, or create `.cursor/rules/harness-bridge.md`).\n3. Scaffold a starter `.harness/bridge.md`.\n\nReview the diff. Commit when ready.\n\n### Option C — manual\n\n1. Open [`prompts/maintainer.md`](./prompts/maintainer.md).\n2. Copy everything between `--- begin snippet ---` and `--- end snippet ---`.\n3. Paste it into your provider's instructions file:\n   - Claude Code → append to `CLAUDE.md` at your repo root.\n   - Codex → append to `AGENTS.md`.\n   - Gemini CLI → append to `GEMINI.md`.\n   - Cursor → save as a new file `.cursor/rules/harness-bridge.md`.\n4. Create an empty `.harness/` directory. The agent will populate `bridge.md` on its first non-trivial task.\n\n---\n\n## Use it\n\nOnce installed, the everyday loop is short:\n\n### 1. Just work\n\nStart a session, give it a task. The agent maintains `.harness/bridge.md` at checkpoints as it goes. You can ignore the file most of the time — `git diff .harness/bridge.md` shows what it's tracking if you ever want to peek.\n\n### 2. End a session (planned or not)\n\nIf you're closing the session deliberately and want a clean handoff, say:\n\n```text\nProduce a Harness Bridge handoff.\n```\n\nWith MCP, the agent calls `bridge_produce`. In prompt-only mode, paste [`prompts/producer.md`](./prompts/producer.md). Either way, this is a touch-up pass that verifies nothing slipped past the last checkpoint.\n\nIf the session dies unexpectedly, you can skip this. The bridge is already current to the last checkpoint.\n\n### 3. Resume in a new session\n\nIn a fresh session — same provider or a different one — say:\n\n```text\nConsume the Harness Bridge and restate where we are.\n```\n\nWith MCP, the agent calls `bridge_consume`. In prompt-only mode, paste [`prompts/consumer.md`](./prompts/consumer.md). The agent will:\n\n1. Read `.harness/bridge.md`.\n2. Run `git status` / `git log` to ground itself in real state.\n3. **Restate the goal, what's done, what's next — in its own words.**\n4. **Wait for your confirmation.**\n5. Then continue execution and resume maintaining the bridge.\n\nThe restate-and-wait step is non-negotiable. It's the cheapest way to catch a misread before it becomes 5,000 tokens of wrong-direction work.\n\n---\n\n## Common scenarios\n\n### \"I want to switch from Claude Code to Codex mid-task.\"\n\n1. In the source session, say `Produce a Harness Bridge handoff` to finalize the bridge.\n2. Commit. (Or just stage — the file's on disk either way.)\n3. Open Codex in the same repo. Say `Consume the Harness Bridge and restate where we are`. Confirm the restate. Continue.\n\n### \"My session crashed and I didn't run the producer prompt.\"\n\nIf you were using checkpoint cadence (the default), the bridge is already current to the last checkpoint — usually a few minutes ago.\n\n1. Open a new session. Say `Consume the Harness Bridge and restate where we are` (or paste `prompts/consumer.md` in prompt-only mode).\n2. The restate will show you what state the bridge was in at last checkpoint. If that's close enough to where the session actually died, just continue.\n3. If the bridge is missing the last few minutes, ask the agent to run recovery in `since` mode (or paste `prompts/recover.md` in prompt-only mode) — it tops up the bridge from the dead session's transcript.\n\n### \"The bridge is gone (or was never created).\"\n\nUse the recovery flow in `full` mode. With MCP, ask the agent to recover the bridge from transcript evidence. In prompt-only mode, paste `prompts/recover.md` with mode `full`. The agent reads the session transcript from disk and reconstructs the bridge from scratch.\n\n### \"I don't trust this bridge — did the previous session actually do what it says?\"\n\nAsk the agent to verify the bridge against transcript evidence. In prompt-only mode, paste `prompts/recover.md` with mode `verify`. The agent diffs the bridge against the transcript and reports discrepancies. Read-only — it won't modify the file.\n\n### \"I want to slow down bridge updates — this task is exploratory and I don't want the overhead.\"\n\nTell the agent: *\"Use lazy cadence for this task.\"* The agent will update the bridge only on explicit request, or when context fills past ~70%.\n\n### \"I want to speed up bridge updates — this task is critical.\"\n\nTell the agent: *\"Use aggressive cadence — this is critical.\"* The agent will update after every turn. Expect ~12–18% session token overhead in exchange for near-instant death survivability.\n\n---\n\n## Bridge prompt reference\n\nHarness Bridge uses six operational prompts:\n\n| Prompt | When to use it | Purpose |\n|---|---|---|\n| [`prompts/init.md`](./prompts/init.md) | First-time setup in a project repo | Installs bridge maintainer instructions and scaffolds `.harness/bridge.md` |\n| [`prompts/maintainer.md`](./prompts/maintainer.md) | Manual setup only | Source of the maintainer snippet used by `init` |\n| [`prompts/producer.md`](./prompts/producer.md) | End of a session (optional but recommended) | Finalize handoff before switching session/provider |\n| [`prompts/consumer.md`](./prompts/consumer.md) | Start of a new session | Read bridge, restate state, confirm, and resume |\n| [`prompts/recover.md`](./prompts/recover.md) | Bridge is stale/missing/suspect | Rebuild or verify bridge from transcript |\n| [`prompts/uninstall.md`](./prompts/uninstall.md) | Remove Harness Bridge from a repo | Removes `.harness/` and maintainer snippet |\n\nRelated LLM Wiki prompt:\n\n| Prompt | Feature | Purpose |\n|---|---|---|\n| [`prompts/vault-init.md`](./prompts/vault-init.md) | LLM Wiki | Bootstraps a separate long-lived knowledge vault |\n\n---\n\n## Related product: LLM Wiki\n\nLLM Wiki is a separate markdown knowledge-base workflow for long-lived research, product thinking, design rationale, and decisions. It uses a vault with `raw/` sources, agent-maintained `wiki/` pages, and a schema in `CLAUDE.md` / `AGENTS.md`.\n\nUse Harness Bridge when you need a future coding session to resume the current task. Use LLM Wiki when you need future sessions to remember the durable context around many tasks.\n\n| Product | Stores | Lifespan | Path |\n|---|---|---|---|\n| Harness Bridge | Current in-flight task state | Per task / per handoff | `.harness/bridge.md` inside a project repo |\n| LLM Wiki | Research, decisions, design rationale, syntheses | Long-lived | A vault directory with `raw/` and `wiki/` |\n\nRead the LLM Wiki guide in [`docs/llm-wiki.md`](./docs/llm-wiki.md).\n\n## Provider support (bridge)\n\n| Provider | Maintainer auto-loads from | Continuous updates | Consumer | Recovery |\n|---|---|---|---|---|\n| Claude Code | `CLAUDE.md` | ✅ | ✅ | ✅ |\n| Codex | `AGENTS.md` | ✅ | ✅ | ✅ |\n| Cursor | `.cursor/rules/harness-bridge.md` | ✅ | ✅ | ⚠️ manual transcript export |\n| Gemini CLI | `GEMINI.md` | ✅ | ✅ | ✅ |\n| Gemini Web | pasted at session start | ✅ | ✅ | ❌ no transcript access |\n\nThe transport layer is plain markdown files, so any agent that can read and edit local files can use Harness Bridge — even tools not listed above. Provider docs in [`providers/`](./providers/) cover transcript locations and known quirks per agent.\n\n## MCP integration\n\nHarness Bridge includes a local stdio MCP server and CLI package.\n\nWith npm:\n\n```bash\nnpx -y @codemeall/harness-bridge mcp\n```\n\nWith a Git checkout:\n\n```bash\ngit clone <repo-url>\ncd harness-bridge\nnpm install\nnpm run build\nnode /absolute/path/to/harness-bridge/dist/cli.js mcp\n```\n\nThe MCP server exposes deterministic local tools for bridge status, init, checkpoint, produce, consume, recover, and validation while keeping `.harness/bridge.md` as the source of truth. It also exposes the canonical `prompts/*.md` files as MCP prompts/resources.\n\nThe same server also exposes the separate LLM Wiki tools — `vault_init` and `vault_status`. See [`docs/llm-wiki.md`](./docs/llm-wiki.md) for LLM Wiki setup and daily usage.\n\nSee [`providers/mcp.md`](./providers/mcp.md), [`docs/mcp-usage.md`](./docs/mcp-usage.md), and [`templates/`](./templates/) for Claude Code, Cursor, Codex, Gemini CLI, and Antigravity setup snippets.\n\nFor end-to-end setup and daily workflow examples, read [`docs/mcp-usage.md`](./docs/mcp-usage.md).\n\n---\n\n## FAQ (bridge)\n\n### Does this cost extra tokens?\n\nA small amount — roughly **3–6% of session tokens** at default (`checkpoint`) cadence. The maintenance lives in small `Edit` calls that patch one section at a time, not full file rewrites. In exchange you get near-immunity to losing state when a session dies. For comparison, redoing five minutes of lost work after a crash typically costs more than a week of checkpoint overhead.\n\nYou can switch to `lazy` cadence (~1–2% overhead) for exploration sessions, or `aggressive` (~12–18%) for critical work.\n\n### Why a single file? Why not a directory?\n\nBecause the win comes from a **fixed path** the consumer prompt can target without ambiguity. One file → one `Read`. A directory adds complexity (which file is current? which has the next action?) for no real gain when the schema fits in 50–80 lines.\n\nIf a bridge ever grows long enough to need splitting, the schema's wrong — bridges are reference cards, not journals.\n\n### Does the bridge contain sensitive information?\n\nBridges can contain your goal, decisions, file paths, and short notes. They **must not** contain secrets — the maintainer rules explicitly forbid API keys, tokens, env values, etc. If you'd be uncomfortable with the bridge in a public commit, add `.harness/` to `.gitignore` in that repo.\n\n### What if two agents try to edit the bridge at the same time?\n\nv1 assumes **serial handoffs**: one agent works, then another. Concurrent multi-agent edits are an open problem deferred to v2. If you accidentally run two sessions against the same bridge simultaneously, git merge-conflict semantics apply — it's a markdown file like any other.\n\n### Why not just use the conversation transcript directly?\n\nYou can — recovery mode reads transcripts. But transcripts are dense, full of dead ends, and often massive (tens of thousands of tokens). The bridge is the **distilled state** the next agent actually needs: ~30 lines instead of ~30K. Transcripts are the backup; the bridge is the primary source.\n\n### Is this an MCP server / CLI / extension?\n\nThe original workflow is a documented convention plus markdown files. The MCP server and CLI let developer agents use the same workflow without copy-pasting every operational prompt.\n\n### Will this work in [tool not listed]?\n\nProbably. If the tool can read and edit local files and has a way to load instructions on session start, the convention applies. Provider files in [`providers/`](./providers/) document the four officially-tested integrations; the schema itself is provider-agnostic.\n\n### Why is it called \"Harness Bridge\"?\n\nLineage from the original concept note. The name is preserved through v1; we may revisit it for v2 if it proves limiting.\n\n---\n\n## What it is / what it isn't\n\n**Harness Bridge is:**\n- A schema for one markdown file (`harness-bridge/v1`).\n- Six short prompts that drive the agent's behavior.\n- A set of provider-specific notes for where to install and where to find transcripts.\n- Provider-agnostic by design.\n\n**Harness Bridge isn't:**\n- A retrieval system. It doesn't index your codebase or build embeddings.\n- An agent memory layer. It captures one task's state, not your long-term knowledge.\n- A hosted service or background daemon. The optional CLI/MCP server runs locally when invoked by you or your agent.\n- A replacement for `CLAUDE.md` / `AGENTS.md`. It appends a section to those files; it doesn't take them over.\n\n---\n\n## Uninstall (bridge)\n\nUse [`prompts/uninstall.md`](./prompts/uninstall.md) when you want to remove Harness Bridge from a repo. It removes both install artifacts:\n\n1. The `.harness/` directory and `bridge.md`.\n2. The `## Harness Bridge — keep .harness/bridge.md current` section from your provider's instructions file (or deletes `.cursor/rules/harness-bridge.md`).\n\nPast bridges remain in git history. If you need to scrub history because past bridges contained sensitive content, use `git filter-repo` (or BFG Repo Cleaner) separately.\n\nRe-installation is always possible via `prompts/init.md`.\n\n---\n\n## Project status & roadmap\n\n- **Status:** `harness-bridge/v1` (pre-release).\n- **License:** [MIT](./LICENSE).\n- **Changelog:** [`CHANGELOG.md`](./CHANGELOG.md).\n- **Conformance:** see [`SPEC.md`](./SPEC.md) §10.\n\n### Deferred to v2\n\nThese are real ideas, deliberately out of scope until v1 proves the schema:\n\n- Slash-command wrappers per provider (`/bridge-init`, `/bridge-save`, etc.).\n- Automated round-trip test harness driving headless agents.\n- Multi-agent concurrent edit support and state reconciliation.\n- Multi-hop chains (agent A → B → C).\n- Bridge linter and GitHub Action for schema validation.\n- Encryption / automated secret scanning of bridge content.\n\n---\n\n## Contributing\n\nThis is v1 — the schema is intentionally small and the surface is intentionally documentation-only. The most useful contributions right now:\n\n- **Run [`tests/round-trip.md`](./tests/round-trip.md)** against a provider and file any gaps you find.\n- **Try the everyday flow** (init → work → die → resume) on a real project and report friction.\n- **Propose schema additions in an issue first** — schema changes need to stay tight.\n\nWhen opening an issue, please include your provider, the prompt you pasted, and the bridge file (with secrets redacted) so the failure is reproducible.\n\n---\n\n## License\n\n[MIT](./LICENSE) — use freely in personal and commercial projects.\n","readmeFilename":"README.md"}