p-oliveira7/context-maps

Getting started · Features · Agent skill · Data format · API · Tests · Changelog
Context Maps is a local app to view and edit presentations as mind maps, plus an agent skill
(Claude, Codex, Cursor) that reads the context of an application — code, specs, flows, decisions — and
publishes the finished map with images, diagrams and links.
> No external backend, no CDN, no runtime dependencies. Everything runs on 127.0.0.1, and every
> presentation is a JSON file you version with Git.
From a request to a map: the skill builds it (real commands), then you explore, search and edit it.
## Contents
Why Context Maps
How it fits together
Getting started
Features — navigate · edit · diagrams · API client · export · save as
Agent skill
Data format · Server API · Security
Tests · Regenerating the screenshots
Known limitations · License · Third-party · Origin
## Why Context Maps
Explaining a system usually needs three things that live in different places: text (README, specs),
diagrams (flows, architecture) and evidence (screenshots, links). A mind map brings the three onto
one navigable surface: you start from the overview and open branches as the conversation goes.
| Versioning for free | Each presentation is a small JSON file: git diff shows exactly which idea changed. |
| No account, no cloud | The content of your architecture never leaves your machine. |
| Agent-friendly | The format is small and documented (schema.md); a CLI validates and publishes outlines. |
| Reviewable and reproducible | Edit by hand in the app, or ask the skill to regenerate or extend the map when the system changes. |
## How it fits together
mermaid
flowchart LR
ctx["Context code · specs · README"] --> agent["Agent + skill"]
agent -- outline --> cli["rm.mjs validate · create"]
cli --> srv["server.mjs 127.0.0.1"]
app["App in the browser view · edit · diagrams"] srv
srv --> files[("presentations/<id>.json + assets/")]
files --> git[["Git"]]
| Piece | What it is | Where |
| App | Map viewer and editor (HTML/CSS/ES modules) | index.html, app.js, motion.js, model.js, store.js, styles.css |
| Local server | Plain Node: serves the app and stores presentations | server.mjs |
| Presentations | One JSON per map + an images folder | presentations/ .json, presentations/ /assets/ |
| Skill | Procedure + CLI for agents to build maps | skills/context-maps/ (guide) |
| Tests | Model, browser, cards, motion, edit and skill | tests/ |
## Getting started
Requirements: Node 18+ (tested on Node 24). No npm install is needed to use the app.
bash
node server.mjs # or: npm start
Open . On first run the server creates the demo presentation in presentations/.
| Variable | Default | Purpose |
| PORT | 4173 | Server port |
| PRESENTATIONSDIR | ./presentations | Main library folder |
| CONTEXTMAPSCONFIG | ./.context-maps.json | Where the extra folders are remembered |
| COLLECTIONSDIR | ./collections | API client collections (Bruno format); secrets go to .secrets/ inside it |
> Without the server (for example python -m http.server) the app opens in view mode only, with the
> built-in demo map. Do not open index.html through file:// (it uses ES modules).
Language: the interface follows your browser's language — Portuguese (BR) or English (any other language falls back to English). Add ?lang=pt or ?lang=en to the URL to force one; the choice is remembered in the browser. Presentation content is yours and is never translated (the bundled example is in Portuguese).