Cartograph

Visual codebase mapping plugin for OpenCode — auto-generates architecture diagrams as you code

Cartograph runs silently in the background while you use OpenCode. No commands to run. No tools to invoke. Just install and open the web UI at http://localhost:3333.

---

Quick Install

bunx @cloudshipai/cartograph install

That's it! The installer automatically adds Cartograph to your OpenCode config.

---

Features

• Zero Configuration — Plugin auto-starts a visualization server
• Live Updates — Diagrams update in real-time as you (or AI) make changes
• Mermaid Diagrams — Architecture, dataflow, sequence, class, state, ER, dependency
• Interactive UI — Expand/collapse diagrams, view source, dark theme
• Multi-Language — TypeScript, JavaScript, Python, Go

---

What You'll See

Open http://localhost:3333 after installing:

| Feature | Description | |---------|-------------| | Architecture Diagrams | High-level system component visualization | | Dataflow Diagrams | How data moves through your system | | Sequence Diagrams | Interaction flows between components | | Live Updates | Diagrams refresh via WebSocket as code changes |

---

Installation Options

Option 1: One-liner (Recommended)

bunx @cloudshipai/cartograph install

Option 2: Manual Config

Add to ~/.config/opencode/opencode.json:

{
  "plugin": ["cartograph"]
}

Option 3: Development Install

git clone https://github.com/cloudshipai/cartograph.git
cd cartograph
bun install
bun run build
bunx @cloudshipai/cartograph install

---

Usage

Once installed, Cartograph automatically:

1. Starts when you run opencode
2. Opens a web UI at http://localhost:3333
3. Listens for diagram generation requests

Example Prompts

Ask the AI to generate diagrams:

"Generate an architecture diagram of this codebase"
"Create a sequence diagram for the auth flow"
"Update the dataflow diagram"
"Show me a class diagram of the models"

---

For LLM Agents

If you're an AI assistant helping a user, Cartograph provides these tools:

| Tool | Description | |------|-------------| | diagram_types | List available diagram types | | diagram_generate | Generate a diagram from description | | diagram_update | Update a diagram with new Mermaid code | | diagram_prompt | Get prompt for generating specific diagram type |

Step-by-step Installation

# 1. Install Cartograph
bunx @cloudshipai/cartograph install

# 2. Verify config was updated
cat ~/.config/opencode/opencode.json

# 3. Start OpenCode
opencode

# 4. Verify web UI is running
curl -s http://localhost:3333/api/health

---

Uninstall

bunx @cloudshipai/cartograph uninstall

---

Configuration

Cartograph works with zero configuration. The plugin uses:

| Setting | Value | |---------|-------| | Port | 3333 | | WebSocket | ws://localhost:3333 | | UI | Material Design dark theme |

---

Supported Diagram Types

| Type | Description | |------|-------------| | architecture | High-level system components | | dataflow | Data movement between systems | | sequence | Interaction sequences | | class | Class relationships | | state | State machine diagrams | | er | Entity-relationship diagrams | | dependency | Module dependency graphs |

---

How It Works

┌─────────────────────────────────────────────────────────────┐
│                         OpenCode                             │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Cartograph Plugin                        │   │
│  │                                                       │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │   │
│  │  │   Hooks     │  │   Tools     │  │   Server    │  │   │
│  │  │             │  │             │  │             │  │   │
│  │  │ • ready     │  │ • generate  │  │ • HTTP :3333│  │   │
│  │  │ • shutdown  │  │ • update    │  │ • WebSocket │  │   │
│  │  │ • message   │  │ • types     │  │ • REST API  │  │   │
│  │  └─────────────┘  └─────────────┘  └──────┬──────┘  │   │
│  └───────────────────────────────────────────┼──────────┘   │
└──────────────────────────────────────────────┼──────────────┘
                                               │
                    ┌──────────────────────────┘
                    │
                    ▼
         ┌──────────────────┐
         │    Web UI        │
         │  localhost:3333  │
         │                  │
         │  ┌────────────┐  │
         │  │  Mermaid   │  │
         │  │  Diagrams  │  │
         │  └────────────┘  │
         └──────────────────┘

1. Plugin loads → starts web server on port 3333
2. Registers tools → AI can generate/update diagrams
3. WebSocket connection → real-time diagram updates
4. Mermaid rendering → diagrams display in browser

---

Development

git clone https://github.com/cloudshipai/cartograph.git
cd cartograph
bun install

# Build everything
bun run build

# Development mode
bun run dev        # Watch plugin
bun run dev:web    # Watch web UI

# Run tests
bun test           # All 65 tests
bun test:unit      # Unit tests
bun test:integration  # Integration tests

See DEVELOPMENT.md for detailed development guide.

---

Contributing

Contributions welcome! Please read DEVELOPMENT.md first.

---

License

MIT © CloudShip AI