# 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

```bash
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):

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

### 2. Claude Code plugin (recommended)

```bash
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:

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

### One-line installer

```bash
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

```bash
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`:

```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:

```bash
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.

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

## Feature flags

| Flag | Default | Effect |
|---|---|---|
| `TESSERA_ENABLE_DEBATE` | on | Enables `tessera debate` |
| `TESSERA_ENABLE_DASHBOARD` | on | Enables `tessera dashboard` |
| `TESSERA_ENABLE_COMPLIANCE` | on | Enables `tessera verify` |

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

| Metric | Target |
|---|---|
| Turn 2+ read reduction | ≥50% chars vs cold-start |
| 10-turn session reduction | ≥40% total chars |
| Cache hit rate (after turn 3) | ≥60% |
| Symbol excerpt savings | ≥70% vs full-file reads |

## 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`.

| Skill | Usage | Description |
|---|---|---|
| `/debate` | `/debate "REST vs GraphQL"` | Multi-round Claude vs GPT debate on architecture or design decisions |
| `/build` | `/build "add JWT auth"` | Full build loop: GPT plans → debate → user approval → implement → GPT review |
| `/cleanup` | `/cleanup src/` | Bidirectional slop scanner — Claude + GPT independently analyze, then reconcile |
| `/plan-review` | `/plan-review plan.md` | Send an implementation plan to GPT for structured review before coding |
| `/codex-review` | `/codex-review HEAD~2` | Independent GPT code review of staged changes, commits, or files |

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

## License

MIT