{"id":50362173,"url":"https://github.com/benteigland11/cartograph-plugin","last_synced_at":"2026-05-30T02:05:30.481Z","repository":{"id":353507198,"uuid":"1219717007","full_name":"benteigland11/cartograph-plugin","owner":"benteigland11","description":"Agentic plugin for Cartograph: A local first CLI for turning code into permanent engineering assets paried with it's MCP.","archived":false,"fork":false,"pushed_at":"2026-05-04T04:01:21.000Z","size":70,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T06:09:41.973Z","etag":null,"topics":["claude-plugin","codex-plugin","gemini-cli-extension"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/benteigland11.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-24T06:41:04.000Z","updated_at":"2026-05-04T04:01:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/benteigland11/cartograph-plugin","commit_stats":null,"previous_names":["benteigland11/cartograph-plugin"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/benteigland11/cartograph-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benteigland11%2Fcartograph-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benteigland11%2Fcartograph-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benteigland11%2Fcartograph-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benteigland11%2Fcartograph-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/benteigland11","download_url":"https://codeload.github.com/benteigland11/cartograph-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/benteigland11%2Fcartograph-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33677261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-plugin","codex-plugin","gemini-cli-extension"],"created_at":"2026-05-30T02:05:30.373Z","updated_at":"2026-05-30T02:05:30.474Z","avatar_url":"https://github.com/benteigland11.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cartograph-plugin\n\nAgent plugin for [Cartograph](https://github.com/benteigland11/Cartograph),\nthe widget library manager for AI coding agents.\n\nShips the Cartograph MCP server plus a set of skills. Designed to work\nacross hosts. Currently packaged for **Claude Code**, **Codex**, and\n**Gemini CLI**, with one shared body of skill content and per-host\nmanifests in their respective conventions.\n\n## What ships\n\n**MCP server**\n\nThe Cartograph MCP server exposes registry search, installed-widget\nmanagement, widget status, widget creation, validation, checkin, rules\nmanagement, and config. It is published to PyPI as `cartograph-mcp`\nand runs through the `cartograph-mcp` console command (or\n`python -m cartograph_mcp.server` when invoked as a Python module).\n\nEach host registers the server its own way:\n- **Claude Code** — `mcpServers` block in `.claude-plugin/plugin.json`\n- **Codex** — `.mcp.json` referenced from `providers/codex/.codex-plugin/plugin.json`\n- **Gemini CLI** — `mcpServers` block in `gemini-extension.json`\n\n**Skills**\n\n- `cg-plan` drives widget-first decomposition for a feature.\n- `cg-config` interprets the current Cartograph setup and recommends\n  named profiles when the user wants to change defaults.\n- `cg-cloud` explains the cloud layer: publishing, governance,\n  adopt, sync, and what the available choices mean.\n- `cg-proposals` walks the pending proposals queue on widgets the\n  user owns, one proposal at a time.\n\nHow each host surfaces skills depends on the host. See the per-host\nsections below.\n\n## Repo layout\n\n- `skills/` — base skill content shared across hosts.\n- `.claude-plugin/` — Claude Code plugin manifest + Claude marketplace manifest.\n- `gemini-extension.json` — Gemini CLI extension manifest at repo root.\n- `.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.\n- `scripts/` — bootstrap helpers (cross-platform Python).\n\n## Prerequisites\n\nPython 3.10 or newer with `pip` on the PATH. The Cartograph MCP server\nis a Python package, and `python` must resolve to a Python 3 interpreter\non your PATH (true on Windows out of the box, and on modern macOS/Linux).\n\nThe cleanest setup on any host:\n\n    pip install cartograph-mcp\n\nClaude Code can also do this for you on first session via a bootstrap\nhook (see \"Install for Claude Code\" below). Codex and Gemini CLI do\nnot have an equivalent hook, so install once yourself.\n\n## Install for Claude Code\n\nClaude Code treats this repo as a plugin via the manifest at\n`.claude-plugin/plugin.json`. The plugin auto-registers the MCP server\nand (optionally) installs `cartograph-mcp` on first session.\n\n### From the Claude Code marketplace\n\n    /plugin marketplace add benteigland11/cartograph-plugin\n    /plugin install cartograph@cartograph-marketplace\n\nSkills appear as `/cartograph:cg-plan`, `/cartograph:cg-config`,\n`/cartograph:cg-cloud`, and `/cartograph:cg-proposals`, and also\nauto-trigger based on natural language matching their descriptions.\n\n### Local development install\n\n    git clone https://github.com/benteigland11/cartograph-plugin\n    claude --plugin-dir ./cartograph-plugin\n\nAfter editing any SKILL.md, plugin.json, or the hook script, run\n`/reload-plugins` to pick up the change without restarting Claude\nCode.\n\n### How the Claude Code bootstrap hook works\n\nThe plugin ships a `SessionStart` hook at `scripts/init-mcp.py`\n(cross-platform Python — works on Linux, macOS, and Windows). On the\nfirst run it checks whether `cartograph_mcp` is importable. If the\nimport fails it runs `pip install --target $CLAUDE_PLUGIN_DATA/lib\ncartograph-mcp`, which also pulls in `cartograph-cli` as a dependency.\nOn every later session the check passes instantly and the hook exits\nas a no-op.\n\nClaude Code launches the MCP server as `python -m cartograph_mcp.server`\nwith `PYTHONPATH` set to the plugin data lib, so the auto-installed\npackage is always found.\n\nIf the auto-install fails (no network, restricted environment, a pip\nconfiguration that blocks `--target`), the hook prints a clear fallback\ninstruction asking you to run `pip install cartograph-mcp` manually and\nrestart Claude Code. You can also pre-install at any time and the hook\nbecomes a no-op.\n\nThis bootstrap is a Claude-Code-specific convenience because Claude\nCode has session-start hooks. The other hosts don't, so on those you\ninstall `cartograph-mcp` once yourself.\n\n## Install for Codex\n\nCodex consumes the marketplace manifest at\n`.agents/plugins/marketplace.json` and the plugin manifest at\n`providers/codex/.codex-plugin/plugin.json`.\n\nInstall `cartograph-mcp` first:\n\n    pip install cartograph-mcp\n\nThen add this plugin marketplace to Codex:\n\n    codex plugin marketplace add https://github.com/benteigland11/cartograph-plugin\n\nOpen Codex's slash plugin picker, select `cartograph`, and press Enter\nto install/enable it for the current Codex setup. Adding the marketplace\nonly makes the plugin available; this picker step is what installs it.\n\nIf you already added the marketplace before an update, refresh it with:\n\n    codex plugin marketplace upgrade cartograph-marketplace\n\nThen register the MCP server with Codex:\n\n    codex mcp add cartograph -- cartograph-mcp\n\nConfirm Codex can see it:\n\n    codex mcp list\n\nYou should see `cartograph` with command `cartograph-mcp` and status\n`enabled`.\n\nThe published marketplace entry points Codex at `providers/codex/`.\nThat provider package contains the Codex manifest, skills, assets, and\n`.mcp.json`. The explicit `codex mcp add` step is still needed for\nCodex versions that do not auto-register MCP servers from a marketplace\nplugin.\n\n`.mcp.json` launches the server with:\n\n    cartograph-mcp\n\n## Install for Gemini CLI\n\nGemini CLI uses the `gemini-extension.json` manifest at the repo root.\n\nInstall `cartograph-mcp` first:\n\n    pip install cartograph-mcp\n\nThen link the plugin locally:\n\n    gemini extensions install https://github.com/benteigland11/cartograph-plugin\n\nThis:\n1. Registers the Cartograph MCP server.\n2. Enables the `cg-plan`, `cg-config`, `cg-cloud`, and `cg-proposals` skills.\n3. Loads the `GEMINI.md` context file.\n\nFor gallery discoverability, the upstream `cartograph-plugin` repo is\ntagged with the `gemini-cli-extension` GitHub topic so the Gemini CLI\ncrawler can find it.\n\n## Install for OpenClaw\n\nOpenClaw can load this repo as a compatible plugin bundle. The root\npackage includes the ClawHub-required `openclaw.plugin.json` plus a\nClaude-compatible bundle with shared skills and `.mcp.json`;\n`providers/codex/` is also a Codex-compatible bundle with the same MCP\nserver config and Codex-specific skill copies. Current OpenClaw\nversions still detect the root package as a bundle and expose the MCP\nserver from `.mcp.json`.\n\nInstall `cartograph-mcp` first:\n\n    pip install cartograph-mcp\n\nFor local testing with current OpenClaw versions:\n\n    openclaw plugins install ./cartograph-plugin\n    openclaw plugins list\n    openclaw plugins inspect cartograph\n    openclaw gateway restart\n\nBundles should show as `Format: bundle`. OpenClaw maps the skill roots\nand the stdio MCP server declared in `.mcp.json`; the MCP tools are\nexposed with OpenClaw's bundle-safe tool naming.\n\nTo publish/register on ClawHub, use the package workflow from a current\n`clawhub` CLI:\n\n    npm i -g clawhub\n    clawhub login\n    clawhub package publish benteigland11/cartograph-plugin --dry-run\n    clawhub package publish benteigland11/cartograph-plugin\n\n`clawhub package publish` is newer than the legacy skill-only\n`clawhub publish` command. If your local CLI only shows\n`clawhub publish`, update `clawhub` before attempting plugin\nregistration.\n\n## Validate\n\nAfter editing Codex packaging or shared skill metadata, run:\n\n    scripts/validate-codex-plugin.sh\n\nThat checks Codex JSON, required skill frontmatter, the\n`cartograph-mcp` entrypoint, shared identity metadata drift between\nthe Claude and Codex manifests, and reports any intentional Codex skill\nvariants that differ from the base skills. Provider versions are\nindependent, so a Codex-only skill change only needs a Codex version\nbump.\n\nAfter editing OpenClaw-facing bundle metadata, run:\n\n    scripts/validate-openclaw-bundle.sh\n\nThat checks the ClawHub package manifest, root bundle marker, Codex\nbundle marker, MCP stdio config, skill metadata, root/Codex skill\nparity, and whether the local OpenClaw and ClawHub CLIs are new enough\nto run the documented live inspection and package publish commands.\n\n## Quick start\n\nOnce the plugin is loaded on any host, prompts like these will invoke\nthe relevant skill:\n\n\u003e \"I want to build a retry wrapper for HTTP calls. What parts should\n\u003e be widgets?\"\n\nThe agent runs `cg-plan` and walks the feature through widget\nidentification.\n\n\u003e \"How should Cartograph be set up if I want to keep widgets private?\"\n\nThe agent runs `cg-config` and recommends a named profile.\n\n\u003e \"Someone proposed a change to one of my widgets. Help me review it.\"\n\nThe agent runs `cg-proposals` and walks the queue, showing the\ninline diff summary for each proposal.\n\n## What Cartograph is\n\nWidgets are reusable code modules with tests, examples, and metadata.\nInstalled widgets live under `cg/\u003cwidget_id\u003e/` in the project root.\nCartograph searches, installs, validates, and publishes them across\nlanguages and domains.\n\nWidget identity follows the pattern `\u003cdomain\u003e-\u003cname\u003e-\u003clanguage\u003e`, for\nexample `backend-retry-backoff-python`.\n\nSee the main repo for the full CLI surface and the list of language\nengines Cartograph supports.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenteigland11%2Fcartograph-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbenteigland11%2Fcartograph-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbenteigland11%2Fcartograph-plugin/lists"}