Tesserae — Claude Code plugin

Slash commands, hooks, a skill, and MCP auto-registration for Tesserae — the typed-graph project-memory compiler. Lets you drive Tesserae from inside a Claude Code TUI session instead of dropping out to a shell.

Install

Requires tesserae already installed (pip install tesserae or pipx install tesserae).

# In a Claude Code session, from a local checkout
/plugin install /path/to/Tesserae/

For the remote-install form against this repo, check /plugin install --help in your version of Claude Code — the URL+subpath syntax has shifted between releases.

Slash commands

Hooks

All four are opt-out per-project via .claude/tesserae.local.md frontmatter (see "Per-project opt-out" below).

Caveat — the SessionEnd compile is opportunistic, not guaranteed. The hook detaches with setsid where that exists and falls back to nohup otherwise. macOS ships no setsid, and nohup only sets SIGHUP to ignore — it does not leave the session's process group — so a harness that reaps the group on session close can still kill the compile mid-flight. Measured on macOS 26: the nohup'd child keeps its parent shell's pgid.

What a kill leaves behind is recoverable, not untouched. graph.json is written by atomic rename, so it is never half a file — but the generated wiki/ and site/ projections are cleared at the start of the artifact write and rebuilt, and the SQLite store is written after graph.json, so a kill inside that window leaves them missing or one compile behind. The guarantee is that this is never silent: .tesserae/manifest.json marks a document graphed only after the artifacts land, so the next tesserae project compile --changed-only sees the missing marks, prints graph.json is not known to cover every tracked document, and re-extracts the whole corpus — which is also what regenerates wiki/ and site/. Until then SessionStart warns that the graph is stale. Don't rely on a long compile outliving the session that started it — run it in the foreground, or under tesserae engine.

MCP auto-registration

.mcp.json registers a single MCP server named tesserae whose command is tesserae_mcp. After install, the agent gets the existing MCP tools without manual claude_desktop_config.json edits:

• mcp__plugin_tesserae_tesserae__ask — natural-language Q&A
• mcp__plugin_tesserae_tesserae__search_nodes — keyword node lookup
• mcp__plugin_tesserae_tesserae__node_context — node + 1-hop neighbourhood
• mcp__plugin_tesserae_tesserae__list_sessions — Session envelopes for active project
• mcp__plugin_tesserae_tesserae__find_session_findings — Session-derived findings for a given node
• mcp__plugin_tesserae_tesserae__list_projects / activate_project / register_project / unregister_project — multi-project registry navigation

Skill

skills/using-tesserae/SKILL.md auto-loads when your query mentions the typed graph, past-session recall, or any tesserae workflow. Tells the agent which MCP tool to call vs which slash command to suggest, includes a node-type cheat sheet, and lists three common recipes.

Per-project opt-out

Create .claude/tesserae.local.md in your project root:

---
hooks:
  session_start: true        # default on
  session_end: true          # default on
  posttooluse_edit: true     # default OFF — opt in for live wiki updates
  pretooluse_compile: true   # default on
---

Defaults apply when the file (or any individual key) is missing.

Verify install

/plugin list           # tesserae should appear
/mcp                   # `tesserae` MCP server should be registered
/tesserae:status       # prints the active project's graph stats

If the MCP server is missing, the tesserae_mcp binary isn't on the PATH Claude Code inherited at launch:

which tesserae_mcp

If which returns a path but the server still doesn't register, Claude Code was launched from a shell whose PATH didn't include the bin directory (pipx installs to ~/.local/bin/ which isn't on every login shell). Restart from a shell where which tesserae_mcp succeeds, or echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.zshrc.

Uninstall

/plugin uninstall tesserae

Plugin uninstall is reversible and does not touch any project's .tesserae/ directory.

See also

• Implementation plan
• Design spec
• Tesserae itself