Tessera

Persistent codebase memory for Claude Code — open source, no license gating.

Tessera gives Claude Code a semantic understanding of your project that persists across turns and sessions, eliminating redundant file re-reads and providing a structured action history.

How it works

1. tessera scan . — builds a SQLite graph of your codebase (files, symbols, imports)
2. Claude calls graph_continue every turn — routes to cached, scored file recommendations
3. graph_register_edit updates the graph after edits, auto-checks plan checklists
4. Optional: run tessera debate "task" for a Claude vs GPT multi-round planning debate

Installation

Tessera is installed from GitHub. The name tessera on PyPI belongs to an unrelated project (a dashboard for Graphite), so installing it from PyPI by name gets the wrong software.

1. Install the tessera command

pipx install git+https://github.com/dr-code/tessera
# or: uv tool install git+https://github.com/dr-code/tessera

Optional extras (debate mode, dashboard):

pipx install "tessera[all] @ git+https://github.com/dr-code/tessera"

2. Claude Code plugin (recommended)

claude plugin marketplace add dr-code/tessera
claude plugin install tessera@tessera

The plugin adds the skills (/build, /debate, /cleanup, /plan-review, /codex-review), the Superpowers methodology, the Plannotator plan-review hooks, and an MCP server that runs the tessera command from step 1. Then in any project:

tessera scan .          # builds graph, writes .mcp.json and CLAUDE.md

One-line installer

curl -fsSL https://raw.githubusercontent.com/dr-code/tessera/main/install.sh | bash

Does both steps: installs the command with pipx (or uv, or pip as a last resort), then the plugin when the claude CLI is present.

Quick start

cd my-project
tessera scan .          # builds graph, writes .mcp.json and CLAUDE.md
tessera status          # show graph stats
tessera dashboard       # start dashboard at localhost:5050

MCP registration

After tessera scan ., your project will have a .mcp.json:

{
  "mcpServers": {
    "tessera": {
      "command": "tessera",
      "args": ["mcp"],
      "env": { "TESSERA_PROJECT_ROOT": "/path/to/project" }
    }
  }
}

This runs the tessera command you installed in step 1 of the installation, so it must be on your PATH. The file contains an absolute path, so keep .mcp.json out of version control. The plugin registers the same server for you without a per-project file, using the current folder as the project root.

CLI reference

tessera scan [PATH]              Build/rebuild the graph
tessera mcp                      Start MCP server (stdio)
tessera status [PATH]            Show graph stats
tessera decisions [PATH]         List locked decisions
tessera reset [PATH]             Clear action graph
tessera plans [PROJECT [SUB]]    List archived plans
tessera verify [PATH]            Compliance: plan vs git diff
tessera handoff [PATH]           Generate clipboard handoff summary
tessera debate "task" [flags]    Run Claude vs GPT debate
tessera dashboard [PATH]         Start dashboard at localhost:5050

Debate mode

Requires the debate extra (pipx install "tessera[debate] @ git+https://github.com/dr-code/tessera") and the codex CLI.

Connecting to ChatGPT (no API key needed)

If you have a ChatGPT Plus or Pro subscription you can authenticate the codex CLI with it — no separate API key or billing setup required:

npm install -g @openai/codex   # install once
codex auth login               # opens browser — sign in with your ChatGPT account

That's it. tessera debate and all Claude Code skills (/debate, /build, /cleanup, etc.) will use your subscription automatically.

Connecting via API key (optional)

Set OPENAI_API_KEY if you prefer direct API billing rather than the subscription OAuth path.

tessera debate "Add JWT authentication" \
  --project myapp \
  --subtask auth-middleware \
  --max-rounds 3

Feature flags

The dashboard binds to 127.0.0.1 by default and has no authentication. If you set TESSERA_DASHBOARD_HOST=0.0.0.0 for LAN access, every /api/* route (project graph, plans, locked decisions) becomes reachable to anyone on the network with no login required — only do this on a trusted network.

Token savings target

Claude Code in-session skills

Tessera ships five Claude Code slash commands that use the tessera graph for context and Codex CLI for GPT's perspective. The plugin marketplace install auto-installs them from the skills/ directory in this repo. For manual install, run ./install.sh or copy from skills/ to ~/.claude/skills/.

Requires: codex CLI (npm install -g @openai/codex) authenticated via codex auth login (ChatGPT subscription) or OPENAI_API_KEY.

All skills degrade gracefully when tessera MCP is not configured — they still run Claude+GPT collaboration, just without graph context.

License

MIT