# The /docgraph Skill for Claude Code

> A Claude Code plugin that connects to your vault and adds a /docgraph skill — ERDs from your real database schema, architecture and flow diagrams, and notes, all confirmed inside DocGraph.

Source: https://docs.docgraph.app/ai/claude-code/

The **DocGraph plugin for Claude Code** bundles two things: the connection to DocGraph's [MCP server](https://docs.docgraph.app/ai/mcp/), and a `/docgraph` skill that tells Claude how to use it well. With it installed you can type:

```text
/docgraph create an ERD for the database in ~/work/shop
/docgraph draw the architecture of this repo as Diagrams/shop-architecture.wb
/docgraph add a payments table linked to orders on Diagrams/shop-erd.wb
```

Claude reads the code on your machine, works out the diagram, and writes it into your open vault as a [whiteboard](https://docs.docgraph.app/whiteboards/basics/). Every write stops for your approval inside DocGraph first (unless you turn on [Auto-approve routine edits](https://docs.docgraph.app/ai/mcp/#skip-the-prompt-for-routine-edits), which still asks for deletes, renames, moves and a few other risky writes).

Plain prose such as *"use DocGraph to draw an ERD of my database"* also works once the plugin is installed — the skill just makes the intent unambiguous.

## Install

1. In DocGraph, open **Settings → Connections → Agents & MCP**, turn the **MCP server** on, and **Copy** the token. (What turning it on allows is explained on the [MCP page](https://docs.docgraph.app/ai/mcp/#getting-there).)
2. Put the token in your shell profile:

   ```bash
   export DOCGRAPH_MCP_TOKEN="<YOUR-TOKEN>"
   ```

3. Inside Claude Code:

   ```text
   /plugin marketplace add docgraph-app/docgraph
   /plugin install docgraph@docgraph
   ```

4. Restart Claude Code so it picks up the environment variable.

If you would rather not export a variable, register the server directly instead — `claude mcp add --scope user --transport http docgraph http://127.0.0.1:8765/ --header "Authorization: Bearer <YOUR-TOKEN>"` — and you get the same tools without the skill.

If the skill runs and can't find DocGraph's tools, it stops and prints these steps rather than guessing.

## What you can ask for

### An ERD of your database

Point it at a project — or say nothing and it uses the folder Claude Code is running in — and it derives the schema from source before drawing:

| Stack | What it reads |
|---|---|
| SQL | `*.sql`, `schema.sql`, `structure.sql`, `migrations/`, `db/migrate/` |
| Prisma | `schema.prisma` |
| Drizzle | `schema.ts`, `drizzle/` |
| TypeORM, MikroORM, Sequelize | `@Entity` / `@Table` classes, `models/` |
| Django | `models.py` |
| Rails | `db/schema.rb` |
| SQLAlchemy | `Base` subclasses, `alembic/versions/` |
| Laravel | `database/migrations/`, `app/Models/` |
| Go / Rust | `gorm` structs, `sqlx` / `diesel` `schema.rs`, `migrations/` |
| Supabase | `supabase/migrations/` |

Migrations are replayed in order, so a later `ALTER TABLE` wins. Each table becomes an [ERD table node](https://docs.docgraph.app/whiteboards/erd/) with its columns, types and `pk`/`fk` markers; each foreign key becomes a crow's-foot edge anchored on the exact columns. Framework bookkeeping tables (`schema_migrations`, `_prisma_migrations`, sessions, cache) are left out unless you ask for them. Larger schemas get grouped into frames by domain, and past about 40 tables the skill asks whether you want all of it or a subset.

You can also skip the code and describe the tables in the prompt — *"users, orders, order_items, with orders belonging to users"* — and it draws that directly.

### Architecture and flow diagrams

- **Architecture** — it reads the codebase (services, datastores, queues, external APIs, deploy config) and draws it with infrastructure nodes: server, database, cache, queue, load balancer, gateway, user and so on.
- **Flowcharts and processes** — steps, decisions and storage as shape nodes with labelled edges.

### Changes to an existing board

*"Add a payments table linked to orders"* or *"rename the worker to ingest-worker"* reads the board first, then edits it in place. Tables and shapes you didn't mention keep their positions; ask it to *tidy up* if you want the whole board laid out again.

### Your notes

Anything else about the vault goes through the same connection: searching and reading notes, creating or appending to them, tasks, tables and saved queries. The full tool list is on the [MCP page](https://docs.docgraph.app/ai/mcp/#the-tools-an-agent-gets).

## Where the board goes

A request can name two different paths. A **project path** ("for the database in ~/work/shop") is the code to read — it is never where the board is saved. The **board path** is inside your vault and ends in `.wb`. If you don't give one, the skill picks `Diagrams/<project>-erd.wb` (or `-architecture.wb`, `-flow.wb`) and tells you so.

When the board is written, Claude reports its path, how many tables and relationships it drew, and anything it guessed or skipped — for example a foreign key inferred only from a `_id` column name. It then offers to link the board from a note.

## Limits & troubleshooting

**Every write waits for you in DocGraph.** The approval dialog appears over the app, not in the terminal, and times out after 120 seconds, which Claude sees as a rejection. Keep DocGraph visible while it works. [Auto-approve](https://docs.docgraph.app/ai/mcp/#skip-the-prompt-for-routine-edits) removes the prompt for routine writes.

**"No vault is open".** The skill acts on whichever vault DocGraph has open. Open one and ask again.

**No schema found.** The skill says which files it looked for and asks you to point at the schema or describe it.

**Freehand ink and images can't be added.** Everything else a whiteboard supports can; add ink or an image by hand.

**What Claude reads goes to Claude's provider.** DocGraph's own privacy boundary ends at the MCP connection — see [what an external agent can do](https://docs.docgraph.app/ai/mcp/#limits--troubleshooting).