{
  "markdown": "# Agent Workspace\n\nAn experiment toward an agent-native equivalent of the capabilities Neovim provides a human: durable orientation, semantic navigation, immediate feedback, bounded attention, and reversible change.\n\nThis is not intended to be another editor or a wrapper that renames existing tools. It is a **stateful coordination layer** over native authorities such as Git, LSP, tree-sitter, test runners, Clearhead, Pi, and Neovim.\n\n## Why\n\nCoding agents can read files, edit text, and run commands, but they commonly hold the relationships between those operations only in a transient context window. They lose:\n\n- why a location was visited;\n- which revision an observation describes;\n- whether evidence became stale after an edit;\n- how findings relate to an intended change;\n- what must be restored after restart;\n- which tool is authoritative for a claim.\n\nThe workspace makes those relationships explicit and inspectable.\n\n## Shape\n\n```text\n                        Clearhead / objectives\n                                 │\n                    ┌────────────▼────────────┐\n                    │      Agent Workspace     │\n                    │  events + projections    │\n                    │  provenance + freshness  │\n                    │  transactions + evidence │\n                    └──┬───────────┬────────┬──┘\n                       │           │        │\n                  MCP server    Pi ext.   Neovim\n                 (any client)             projection\n                       └───────────┼────────┘\n                 ┌─────────────────▼───────────────┐\n                 │  Git · LSP · syntax · tests      │\n                 │  analyzers · command runners     │\n                 └──────────────────────────────────┘\n```\n\nThe native tools remain authoritative. The workspace owns coordination state\nand preserves each provider's provenance and native result. Clients reach the\nsame kernel-owned state through whichever surface fits them: an MCP server (the\nharness-agnostic path — Claude Code, Cursor, Zed, …), the Pi extension, or a\nthin Neovim projection.\n\n## Proposed MVP layers\n\n1. **Kernel** — append-only events, materialized state, Git revision binding, checkpoints, and restart recovery.\n2. **Repository model** — semantic locations, observations, working sets, jump history, and staleness detection.\n3. **Work model** — findings, dispositions, validation evidence, and reversible change transactions.\n4. **Adapters** — narrow integrations for Git plus one structural provider and one validation provider.\n5. **Projections** — a harness-agnostic MCP surface (Claude Code, Cursor, …) and the Pi tool surface, then a thin Neovim projection of the same state.\n\nSee [the initial design outline](knowledge/design/initial-design.md) and [the active MVP charter](.clearhead/charters/workspace-mvp.md).\n\n## Project state\n\nClearhead is authoritative for planned work:\n\n```sh\nclearhead read charters\nclearhead read actions\nclearhead query index unscheduled\n```\n\nThe executable contract is recorded in the\n[executable contract](knowledge/specifications/executable-contract.md). The walking skeleton and its\nagent-facing MVP are complete: revision-aware observations and claims, bounded\nworking sets, persistent findings, evidence-gated reversible transactions,\ncheckpoint/delta recovery, and the MCP, Pi, and Claude Code surfaces all share\nkernel-owned semantics and have been exercised on live repositories.\n\nEvaluation has since moved outside this repository. The kernel installs\nindependently and resolves project-scoped state from an external local store\nkeyed by Git identity; foreign-repo dogfooding (on a separate `plot` project)\nconfirmed that a cold agent trusts a narrow current claim without defensively\nreconstructing it, and that the fused `record_belief` write verb lands first-try.\nThe write loop is now reachable as a native tool — over MCP for any client, and\nas a Pi custom tool — instead of raw CLI. The storage, ownership, and Clearhead\nauthority boundaries are in the\n[external-workspace decision](knowledge/decisions/external-workspace-and-clearhead-boundary.md);\nmeasurements are in the\n[self-hosted field report](knowledge/evaluations/dogfood-cold-resume.md) and the\n[foreign-repo write-API field report](knowledge/evaluations/plot-foreign-dogfood.md);\nimplementation choices settled by running code are in the\n[OKF knowledge bundle](knowledge/index.md), especially the\n[implementation notes](knowledge/implementation/implementation-notes.md).\n\nA residual surfaced while writing these docs: with the active-claim set grown,\nthe Claude Code `SessionStart` wake status now exceeds the harness's inline\npreview budget (`orient_session_drive.py` flags it). That is the predicted\nkernel-owned *bounded wake projection* slice — cap active-claim cardinality in\nthe wake surface, not just headline length — and it is the next hardening step\nbefore the Neovim projection.\n\n## Interfaces\n\nAn interface is a *thin transport*: it moves reads and beliefs to the kernel and\nprojects kernel state back, but owns no semantics. Every client speaks the same\nvocabulary:\n\n- **observation** — a file, or a byte range within one, captured at a Git\n  revision. Ambient reads become observations automatically.\n- **belief → claim** — you *record a belief* (the write act, citing the files it\n  rests on); the kernel stores it as a *claim* (the tracked entity) bound to\n  those observations.\n- **freshness** — the kernel's verdict on whether a claim's cited inputs still\n  hold. `current` means \"the parts I checked are unchanged\"; `stale` outranks\n  your remembered belief and means re-verify before acting.\n- **checkpoint → delta** — a named line drawn in the log, and the change since\n  it. Together they are the cold-resume surface.\n- **objective / working set / finding / transaction** — the bound goal, the\n  ranked locations under attention, an outstanding issue, and a reversible\n  evidence-gated change.\n\nBoth surfaces below bound their projections identically — compact JSON, capped\ncardinality with explicit omission counts, `full` on demand — because those\nlimits are kernel semantics, not adapter-local summaries.\n\n### Claude Code\n\nWired in `.claude/settings.json` and `.mcp.json` as three organs, none of which\nreplaces a native tool:\n\n- **Sense** — a `PostToolUse(Read)` hook forwards each read window to the\n  kernel's harness-agnostic `observe-read`.\n- **Proprioception** — a `SessionStart` hook pushes the bounded `status` and\n  `delta` into the model's opening context, so a cold session wakes oriented.\n- **Write** — an MCP server (`agent-workspace mcp`) exposes the write loop over a\n  harness-agnostic stdio server: `workspace_record_belief` (fused observe+claim),\n  `workspace_bind_objective`, `workspace_supersede_claim`, `workspace_retire_claim`\n  (retire a claim without a replacement), and `workspace_checkpoint`. The same\n  server also serves the bounded read projections.\n\nPer-repo setup — install the kernel with the (opt-in) MCP subcommand onto your\n`PATH`, then let `.mcp.json` wire the server:\n\n```sh\ncargo install --path . --features mcp\n```\n\nThe hooks and the MCP server both snapshot at session start, so **restart Claude\nCode after wiring** for the tool to appear.\n\n### Pi\n\nThe project-local extension at `.pi/extensions/agent-workspace/` is an official\nMCP SDK client plus a Pi-specific read-capture hook. At load it starts\n`agent-workspace mcp`, discovers the server's tools and schemas, and registers\nthem as Pi tools with only Pi-specific labels and prompt guidance added locally.\nThere is no parallel TypeScript implementation of workspace verbs. Build the\nMCP-enabled kernel, then start Pi from the repository (or `/reload` a trusted\nsession):\n\n```sh\ncargo build --features mcp\npi\n```\n\nA bounded native `read` forwards its chrome-stripped model-visible text to the\ndiscovered `workspace_observe_read` MCP tool; the kernel — not the extension —\nmaps lines to a UTF-8 byte selector and validates drift, sensitivity, and\ncontainment, while the adapter separately preserves the full model-visible byte\ncount. Failed, truncated, drifted, out-of-repository, workspace-internal, and\nsensitive-path reads fail closed; native payload retention remains off. The\nextension keeps one lazy MCP client per repository root and closes clients on\nPi session shutdown.\n\n## Principles\n\n- Preserve authority rather than hiding tool differences.\n- Bind observations and evidence to revisions and inputs.\n- Prefer progressive disclosure over repository ingestion.\n- Make stale state visible instead of silently reusing it.\n- Put mutations inside inspectable, reversible transactions.\n- Keep the substrate shared while giving humans and agents native interfaces.\n- Prove one end-to-end workflow before generalizing.\n",
  "bytes": 8752,
  "sha": "3510dcc617ffdb9b4146e9644eb14aea75527115b5bd058aff2309721459e530",
  "repo_slug": "ca-mantis-shrimp/agent-workspace",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_ca_mantis_shrimp_agent_workspace_knowled_edd87a90/readme"
}