5.2 KB · updated 2026-07-31 · md

claude-code-plugin.md

docs/integrations/claude-code-plugin.md

Claude Code plugin

<!-- translations:start -->

한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end -->

Tesserae ships a Claude Code plugin so you can drive the full Tesserae workflow from inside a TUI session — slash commands, an auto-registered MCP server, a skill that orients the agent, and four hooks that close the agent↔project-memory loop. The plugin lives in-repo at plugin/.

Install

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

Pre-req: tesserae already installed (pip install tesserae or pipx install tesserae). If installing via pipx, make sure ~/.local/bin is on the PATH Claude Code inherits at launch.

What's shipped

  • 9 slash commands — seven 1:1 wrappers around the CLI (/tesserae:compile, /tesserae:ask, /tesserae:sessions-import, /tesserae:build-site, /tesserae:serve, /tesserae:obsidian-sync, /tesserae:setup) plus two workflow macros (/tesserae:refresh chains import + compile + obsidian-sync; /tesserae:status shows graph counts and last compile).
  • Auto-MCP-registration for the tesserae server — the agent gets the full tool surface as mcp__plugin_tesserae_tesserae__<tool> without manual config edits: graph queries (search_nodes, node_context, graph_ppr, search_facts), the on-demand compile_context / list_communities / fresh_insights compiler, session memory (ask, list_sessions, find_session_findings, find_code_symbol_mentions), and guided tesserae_setup_plan / tesserae_setup_apply. See mcp.md for the complete list.
  • using-tesserae skill — auto-loads when you ask about the typed graph, past-session recall, wiki/vault content, or any tesserae workflow. Teaches the agent which MCP tool to use vs which slash command to suggest.
  • 5 hooks — SessionStart prints a graph summary; SessionEnd backgrounds an import+compile so this conversation's insights become graph nodes for the next session; two PostToolUse hooks fire on Edit/Write/MultiEdit — one does an opt-in incremental recompile on docs/ edits, the other debounces (~30s) a code-graph sync; PreToolUse (on Bash) gates large-graph compiles via a confirmation dialog.

The session-close compile is opportunistic, not guaranteed. The hook detaches its background job with setsid where that exists, and falls back to nohup otherwise. macOS ships no setsid, and nohup only ignores SIGHUP — it leaves the job in the session's process group — so a harness that reaps the group on session close can still kill the compile mid-flight. What that 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 the SQLite store is written after graph.json, so a kill inside that window leaves them missing or one compile behind. It is never silent, though — .tesserae/manifest.json marks a document graphed only once the artifacts land, so the next compile --changed-only refuses its no-op, says graph.json is not known to cover every tracked document, and re-extracts the whole corpus, which rebuilds the projections too. Don't build a workflow that assumes a long compile survives the session that started it — run it in the foreground, or via tesserae engine.

Full details, the complete command/hook tables, and per-project opt-out instructions are in the plugin's own MD0.

Why a plugin AND an MCP server?

Different surfaces, different roles:

  • MCP tools = read-only graph queries the agent calls during a conversation. Always-on, low-friction.
  • Slash commands = workflow actions you explicitly invoke (compile, refresh, obsidian-sync). High-leverage but should be your decision.

You can use the MCP server alone (manual claude_desktop_config.json edit via tesserae projects mcp-config) — the plugin just packages it together with the slash commands, the skill, and the hooks so installation is one step.

Verify install

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

Uninstall

/plugin uninstall tesserae

Reversible. Does not touch any project's .tesserae/ directory.

See also