Insitu
Situated identity for agents. Who you are here.
Insitu stores reusable stanzas (sections of standing guidance) and composes them into a protocol for the project you are standing in. materialize writes that protocol into files the host already injects at session start. You author with list_stanzas and the size summaries. Agents use resolve_protocol to inspect and to pull available stanzas.
It does not model repos, components, or system facts. That is a dev-context tool (ContextForge, in the reference setup). The two are meant to run side by side.
Status
Design locked 2026-08-17 (DESIGN.md v0.5). The read path, roles (§6.1), validate / where_used, and materialize are implemented. Mutation tools wait until after first dogfood. Live next-step: STATUS.md.
Installation
Requires Python 3.11+ and uv.
cd insitu
uv sync
uv run pytest
uv run insitu
uv run insitu starts the MCP server on stdio.
Vault root
One vault per process, in this order:
INSITU_HOME--vault /path/to/vault~/.insitu
A fresh vault is just folders on disk (stanzas/, projects/, optional config/surfaces.yaml). examples/vault/ in this repo is a fictional sample you can point at:
uv run insitu --vault examples/vault
Do not copy a personal vault into this public repo.
Add the MCP server to a host
See install/mcp.json.examples.md for Cursor, Claude Code, and Grok snippets. Typical shape:
{
"mcpServers": {
"insitu": {
"command": "uv",
"args": ["run", "--directory", "/path/to/insitu", "insitu"],
"env": { "INSITU_HOME": "/path/to/your/vault" }
}
}
}
Copy the three routers (once, user-global)
Routers tell the host that Insitu exists. They are not the project protocol.
| Host | Copy from | Copy to |
|---|---|---|
| Cursor | install/routers/cursor.mdc |
~/.cursor/rules/insitu-router.mdc |
| Claude | install/routers/claude.md |
~/.claude/rules/insitu-router.md |
| Grok | install/routers/grok.md |
~/.grok/rules/insitu-router.md |
Optional: paste install/AGENTS.md into a constitution file by hand. materialize never writes AGENTS.md, CLAUDE.md, or CLAUDE.local.md.
Enable host adapters in the vault with config/surfaces.yaml (grok, claude, cursor). Then from a project checkout call materialize. That writes PROTOCOL.md plus the adapter files under .grok/rules/, .claude/rules/, and .cursor/rules/.
Intended use
# you, after a vault or map change
materialize # PROTOCOL.md + host adapters (.grok/.claude/.cursor rules)
# agent, live / on demand
resolve_protocol # inspect weight, refresh, compare to the materialized header
get_stanza ... # pull an available stanza
# you, registering a new project
list_stanzas # what exists, and how heavy each piece is
link_stanza ... # after the write path exists
get_project # how heavy is this project's protocol?
Develop
uv sync
uv run pytest
uv run insitu
Python 3.11+, FastMCP. See AGENTS.md if you are an agent working in this repo.
License
MIT. See LICENSE.
