Project Little Oxford
Project Little Oxford helps you and an AI coding agent build a shared understanding of a codebase or system using diagrams. The pieces:
- Components: nodes in the system (a service, module, datastore, actor…). Each lives in its own
.oxford/components/<id>.json and is defined once.
- Views: curated picks of those components in
.oxford/views/<view-id>/view.json. Multiple views can read the same component set; each renders as its own diagram.
- Agent: writes the model by following the roadmap in
.oxford/roadmap/ (or you author it by hand).
- VS Code extension: renders any view as an interactive SVG with live updates as the model changes on disk.
- You: drag, inspect, and refine; every move pushes back into the model the agent can read.
Motivation
Coding agents already have native tools for reading, writing, and searching code. Give them a loose, generic schema to describe what they find, let them capture as much as they can, and let the renderer be specific about what it shows.
The combination of the model and the diagram is a shared understanding between agent and human of the system. Every developer's mental model of the same system looks a bit different. This project should give you the tooling to create a diagram to help you understand your system.
The ideal workflow is collaborative: the agent builds its understanding, you reshape the diagram, and that pushes back into the model which can be read and used by the agent.
Project feature: Diagram
System diagram for this project, generated in conversation with Claude Code.
A live SVG diagram rendered from the workspace shape on disk (.oxford/workspace.json + components/<id>.json + views/<view-id>/view.json). Components are first-class model entries; views select which ones to show + how they relate; ELK lays them out; the panel renders live.
- Drag-to-pin: drag any component (including nested children with parent-relative coords) to reposition; pins persist per-view in
.oxford/views/<view-id>/layout.json (so switching views doesn't carry over the previous view's pins).
- Click-to-jump-to-source via
references on each component.
- Checksum staleness dots: staleness is automatic. The extension keeps a content-hash baseline of every referenced file in
.oxford/file_snapshots.json and reconciles it on each render. Each component dot is green when its files match their snapshots and red when any referenced file has changed (or gone missing) since its snapshot: two colors, no manual step. Independent of any AI agent; works in a project that's never been touched by Claude.
- Coverage tab: a treemap + file list showing which files in your workspace are referenced by the diagram and which aren't, with the same green/red signal carried through. Backed by
.oxford/coverage.json (see Workspace shape) for what to ignore.
- Pan / zoom / view picker for workspaces with more than one view.
- Reset layout and hover tooltips.
- Help button (top-right) opens a quick-pick: email maintainer or start a GitHub discussion.
Authored by your agent following the roadmap in .oxford/ (or by hand). Schema is intentionally loose: kind is any string, no additionalProperties: false, unknown fields preserved on round-trip.
Install
From the VS Code Marketplace (recommended: auto-updates):
From a .vsix (sideload): useful for offline installs or trying a pre-release:
Grab the latest .vsix from releases (or build one yourself: see Develop), then:
- GUI:
Cmd/Ctrl+Shift+P → "Extensions: Install from VSIX..." → select the file
- Drag & drop: open the Extensions sidebar, drag the
.vsix from Finder/Explorer into the list
- CLI:
code --install-extension little-oxford.vsix
Then reload: Cmd/Ctrl+Shift+P → "Developer: Reload Window".
To uninstall: VS Code Extensions panel → Little Oxford → Uninstall.
Get started
In any workspace with code you want to diagram:
- Open the diagram panel:
little-oxford: Show Diagram. On first run the extension seeds .oxford/ with a starter workspace.json (carrying a roadmap), the step docs under .oxford/roadmap/, and a validator at .oxford/scripts/validate.mjs. With no diagram yet, the panel shows the current roadmap step and the exact thing to hand your agent.
- Point your agent at the roadmap: tell it "read and follow
.oxford/roadmap/bootstrap.md" (or whatever step the panel names). It authors .oxford/workspace.json + components/<id>.json + views/<view-id>/view.json; the diagram refreshes live and a floating pill tracks the next step. The agent runs node .oxford/scripts/validate.mjs to check its work as it goes, and confirms with you before advancing each step.
- That's it: staleness is automatic. The extension records the current hash of every referenced file in
.oxford/file_snapshots.json the first time it sees the file, and reconciles on every render. Dots stay green until a file changes underneath; then they turn red on their own. There's nothing to run.
Develop
Build from source:
git clone https://github.com/marcusraty/project-little-oxford.git
cd project-little-oxford
npm install
npm run install:local # build → npm run package → code --install-extension
Reload VS Code after install:local. Requires code on your PATH: Cmd/Ctrl+Shift+P → "Shell Command: Install 'code' command in PATH" if it isn't. To uninstall: npm run uninstall:local.
If you just want the .vsix artifact without installing it (e.g. to publish on a release), run npm run package: output lands at little-oxford.vsix in the repo root.
Test suites:
npm test # Node unit suite
npm run test:e2e # Playwright webview tests (rendered diagram in Chromium)
npm run test:vscode # VS Code integration tests (real extension host)
npm run typecheck
Debug (F5): VS Code won't open the same folder in two windows, so use a second clone as a debug workspace.
git clone https://github.com/marcusraty/project-little-oxford.git ~/code/little-oxford-debug
- Open this repo in your source window.
- Press F5. An Extension Development Host opens.
- In that host: File → Open Folder →
~/code/little-oxford-debug.
Edit source, hit Cmd/Ctrl+R in the dev host to reload. esbuild rebuilds via the preLaunchTask.
Developer diagnostics are compiled in only by the debug build (OXFORD_DEBUG=1, set by npm run build:debug / watch:debug / install:debug and by the F5 launch). The __DEBUG__ constant gates them and folds to false in a normal install:local, so esbuild strips the code: published installs ship none of it.
What the debug build enables:
Diagnostic recorder: render / drag / pin / ELK / libavoid / focus / click events stream to the little-oxford Output channel and to a JSONL log at .oxford/debug.log (gitignored). Always on in a debug build; nothing to toggle.
Two on-screen view toggles, exposed as Command Palette commands that only appear in a debug build (gated by the little-oxford.debug context key: invisible in prod):
little-oxford: Toggle Cursor Readout (debug): a small panel by the cursor showing screen + SVG coordinates, for measuring gaps/distances on the diagram.little-oxford: Toggle Edge Segment Labels (debug): labels each edge's polyline with its id and a #N marker per segment, so you can point at a specific segment when discussing routing.
These are in-memory (reset on reload) and are deliberately not VS Code settings: a contributes.configuration entry would show up in every user's Settings panel even in prod, so the toggles live behind palette commands instead.
Workspace shape
The on-disk shape lives under .oxford/:
.oxford/
workspace.json # index + project-wide defaults
coverage.json # which files are in/out of the coverage model
file_snapshots.json # tool-managed staleness baselines (per file hash)
components/
web.json # one file per node (the model)
api.json
db.json
views/
architecture/
view.json # which components + edges + per-view rules
layout.json # tool-managed pin positions
coverage.json is the single source of coverage ignore rules: there are no VS Code settings for this and .gitignore is not consulted. The extension copies a default file (templates/coverage.default.json, seeded from the canonical GitHub Node.gitignore plus .git//.oxford//.vscode/) into .oxford/coverage.json on activation if you don't already have one; it never clobbers an existing file. You then edit it directly (a JSON schema gives autocomplete + validation) or via right-click in the Coverage tab's Files view. A path is ignored when it matches an ignore glob and not an include glob:
{
"ignore": ["node_modules/", ".git/", ".oxford/", "dist", "out",
"coverage", "*.log", ".env", ".DS_Store", "..."],
"include": []
}
Glob anchoring follows git conventions: no leading slash matches at any depth (coverage ignores both coverage/ and src/coverage/: git's own behaviour), a leading slash anchors at the workspace root (/coverage/ matches only the top-level one), a trailing slash is a directory hint. include is an allow-list that overrides a broad ignore: e.g. surfacing one file inside node_modules.
workspace.json:
{
"schema_version": 1,
"name": "my-project",
"defaults": {
"component_styles": {
"service": { "symbol": "rectangle", "color": "#38bdf8" },
"storage": { "symbol": "cylinder", "color": "#2b6cb0" }
}
},
"components": ["web", "api", "db"],
"views": ["architecture"]
}
components/web.json:
{
"id": "web",
"kind": "service",
"label": "Web App",
"references": [
{ "file": "apps/web/src/main.ts" }
]
}
views/architecture/view.json:
{
"id": "architecture",
"title": "Architecture",
"components": ["web", "api", "db"],
"edges": [
{ "id": "w_to_a", "from": "web", "to": "api", "kind": "http_sync" },
{ "id": "a_to_d", "from": "api", "to": "db", "kind": "db_connection" }
]
}
Staleness is not stored on the reference. The baseline hashes that drive the dots live in the tool-managed .oxford/file_snapshots.json, keyed by file path, and are reconciled automatically on every render: the renderer compares each referenced file's current hash to its snapshot to decide dot color. (A legacy _verified_hash may still appear on a reference from an older model, but it is inert: it does not drive the dots.)
Schema is intentionally loose: kind is any string, no additionalProperties: false, unknown fields are preserved on round-trip. See the roadmap step docs (shipped in templates/roadmap/, copied into .oxford/roadmap/) for the full authoring procedure.
Known limitations
Team workflows / branch switches. Per-view layout files (.oxford/views/<view-id>/layout.json) are committed to git so the diagram looks consistent across clones, but the extension mutates them as you drag components around. Two developers touching the same view will produce git merge conflicts on its layout file. Conflicts usually auto-resolve when devs touch different components, but simultaneous edits to the same component need manual resolution. If conflicts become painful for your team, gitignore the layout files: the diagrams still render, you just lose cross-developer continuity of pinned positions.
No unified coverage report. The three test suites are run by separate tools that don't share a coverage format: c8 (npm test), Playwright in Chromium (npm run test:e2e), and @vscode/test-electron (npm run test:vscode). Files that import vscode are invisible to c8 because they can't load outside a VS Code host. The honest signal is "do all three suites pass?"
Single workspace root. The extension activates per VS Code window and only watches the first workspace root. Multi-root workspaces fall back to that root.
Roadmap
Loose ideas, no timelines:
- Multi-level diagrams (explode a component into its internals)
- Wiki-style component descriptions via sidecar markdown (
components/<id>.md)
- Test coverage overlays on the diagram itself
Contributing
Early days: not actively seeking contributors yet. If you have an idea or issue, please start a discussion or get in touch.
License
MIT.
This extension bundles elkjs (Eclipse Public License 2.0) and d3 micro-modules (ISC) at runtime. Full third-party notices in THIRD_PARTY_NOTICES.md.
