Getting Started with Meridian

Meridian turns Mermaid diagrams into live project dashboards. Your AI agent writes the plan, you shape it. Here’s how to get going.

---

1. Launch and pick a project

Open Meridian and select a project folder. The app looks for a .meridian/ directory inside it — that’s where your diagram files live.

If the folder doesn’t have one yet, Meridian will offer to initialize it.

---

2. Install the Claude skill

On first launch, the setup wizard can install a Claude skill to ~/.claude/skills/. This teaches Claude how to generate .meridian/ files with the correct format — Mermaid diagrams with status-encoded nodes.

You can skip this if you prefer to write diagram files by hand.

---

3. Initialize the board

Hit Cmd+I (or use the command palette) to run the init prompt. This sends your project context to Claude, which scans the codebase and generates .meridian/*.md files — one per concern.

Each file contains:

1. A title heading
2. A Mermaid diagram (flowchart TD or stateDiagram-v2) with nodes and edges
3. Four mandatory classDef lines — todo, inProgress, done, blocked
4. class assignments mapping each node to a status
5. Optional ## NodeId sections with descriptions and linked files

---

4. Navigate the canvas

Meridian renders your diagrams on an infinite, zoomable canvas.

• Pan — click and drag
• Zoom — scroll wheel

Each node shows a colored dot for its status:

Color	Status
Gray	todo
Yellow	inProgress
Green	done
Red	blocked

Multiple diagram files appear as tabs along the top. Switch between them or use the sidebar to browse.

---

5. Click a node

Clicking any node opens a panel with four actions:

1. Change status — pick from todo, inProgress, done, or blocked
2. Read description — context the agent wrote about what this node represents
3. See linked files — source files relevant to the task
4. Open in Claude — sends a contextual prompt with the node’s diagram, description, and file references so the agent can start working

Status changes write back to the .meridian/*.md file on disk immediately.

---

6. Use the terminal

Meridian has a built-in terminal drawer — toggle it with Cmd+T.

When you open a node in Claude, a terminal session spins up docked to the bottom of the app. You can run multiple sessions side by side, each tied to a specific node.

---

7. Let the loop run

The real workflow is a feedback loop:

1. Claude generates or updates .meridian/ files
2. Meridian’s file watcher picks up changes and re-renders the canvas
3. You review the graph, update statuses, and click nodes to delegate work
4. Claude reads the updated statuses and keeps going

You steer by changing what’s blocked, what’s inProgress, and what’s done. The agent adapts.

---

Keyboard shortcuts

Shortcut	Action
Cmd+K	Command palette
Cmd+I	Initialize project
Cmd+T	Toggle terminal
Cmd+O	Open directory
Cmd+E	Export diagram as PNG

---

The .meridian/ file format

Each file is plain Markdown with one Mermaid code block. All four classDef lines are mandatory. Every node needs a class assignment. Node descriptions and Files: lines are optional but help the agent understand context.

Here’s a minimal example:

# Authentication

```mermaid
flowchart TD
    JWTSetup[JWT Config]
    Login[POST /login]
    Middleware[Auth Middleware]

    JWTSetup --> Login
    Login --> Middleware

    classDef done fill:#4a9,stroke:#2d7,color:#fff
    classDef inProgress fill:#c90,stroke:#a70,color:#fff
    classDef blocked fill:#c44,stroke:#a22,color:#fff
    classDef todo fill:#5a5a65,stroke:#3e3e44,color:#fff

    class JWTSetup done
    class Login inProgress
    class Middleware todo
```

## JWTSetup — JWT Config

Configure signing keys and token expiration.

Files: src/auth/jwt.ts

## Login — POST /login

Accept credentials, return token pair.

Files: src/auth/login.ts, src/auth/validators.ts

---

That’s it. Open a project, let Claude generate the graph, and start steering.