cartograph

cartograph-plugin

Agent plugin for Cartograph, the widget library manager for AI coding agents.

Ships the Cartograph MCP server plus a set of skills. Designed to work across hosts. Currently packaged for Claude Code, Codex, and Gemini CLI, with one shared body of skill content and per-host manifests in their respective conventions.

What ships

MCP server

The Cartograph MCP server exposes registry search, installed-widget management, widget status, widget creation, validation, checkin, rules management, and config. It is published to PyPI as cartograph-mcp and runs through the cartograph-mcp console command (or python -m cartograph_mcp.server when invoked as a Python module).

Each host registers the server its own way:

• Claude Code — mcpServers block in .claude-plugin/plugin.json
• Codex — .mcp.json referenced from providers/codex/.codex-plugin/plugin.json
• Gemini CLI — mcpServers block in gemini-extension.json

Skills

• cg-plan drives widget-first decomposition for a feature.
• cg-config interprets the current Cartograph setup and recommends named profiles when the user wants to change defaults.
• cg-cloud explains the cloud layer: publishing, governance, adopt, sync, and what the available choices mean.
• cg-proposals walks the pending proposals queue on widgets the user owns, one proposal at a time.

How each host surfaces skills depends on the host. See the per-host sections below.

Repo layout

• skills/ — base skill content shared across hosts.
• .claude-plugin/ — Claude Code plugin manifest + Claude marketplace manifest.
• gemini-extension.json — Gemini CLI extension manifest at repo root.
• .agents/plugins/marketplace.json + providers/codex/ — Codex marketplace manifest and provider package. Codex skills may diverge from the base skills when Codex needs provider-specific instructions.
• scripts/ — bootstrap helpers (cross-platform Python).

Prerequisites

Python 3.10 or newer with pip on the PATH. The Cartograph MCP server is a Python package, and python must resolve to a Python 3 interpreter on your PATH (true on Windows out of the box, and on modern macOS/Linux).

The cleanest setup on any host:

pip install cartograph-mcp

Claude Code can also do this for you on first session via a bootstrap hook (see "Install for Claude Code" below). Codex and Gemini CLI do not have an equivalent hook, so install once yourself.

Install for Claude Code

Claude Code treats this repo as a plugin via the manifest at .claude-plugin/plugin.json. The plugin auto-registers the MCP server and (optionally) installs cartograph-mcp on first session.

From the Claude Code marketplace

/plugin marketplace add benteigland11/cartograph-plugin
/plugin install cartograph@cartograph-marketplace

Skills appear as /cartograph:cg-plan, /cartograph:cg-config, /cartograph:cg-cloud, and /cartograph:cg-proposals, and also auto-trigger based on natural language matching their descriptions.

Local development install

git clone https://github.com/benteigland11/cartograph-plugin
claude --plugin-dir ./cartograph-plugin

After editing any SKILL.md, plugin.json, or the hook script, run /reload-plugins to pick up the change without restarting Claude Code.

How the Claude Code bootstrap hook works

The plugin ships a SessionStart hook at scripts/init-mcp.py (cross-platform Python — works on Linux, macOS, and Windows). On the first run it checks whether cartograph_mcp is importable. If the import fails it runs pip install --target $CLAUDE_PLUGIN_DATA/lib cartograph-mcp, which also pulls in cartograph-cli as a dependency. On every later session the check passes instantly and the hook exits as a no-op.

Claude Code launches the MCP server as python -m cartograph_mcp.server with PYTHONPATH set to the plugin data lib, so the auto-installed package is always found.

If the auto-install fails (no network, restricted environment, a pip configuration that blocks --target), the hook prints a clear fallback instruction asking you to run pip install cartograph-mcp manually and restart Claude Code. You can also pre-install at any time and the hook becomes a no-op.

This bootstrap is a Claude-Code-specific convenience because Claude Code has session-start hooks. The other hosts don't, so on those you install cartograph-mcp once yourself.

Install for Codex

Codex consumes the marketplace manifest at .agents/plugins/marketplace.json and the plugin manifest at providers/codex/.codex-plugin/plugin.json.

Install cartograph-mcp first:

pip install cartograph-mcp

Then add this plugin marketplace to Codex:

codex plugin marketplace add https://github.com/benteigland11/cartograph-plugin