A local-first specification editor. Markdown for prose, SQLite for entities, XML tags as the bridge, Claude as the assistant — all from a single command, no API key.
A full vertical slice for the HTTP endpoint entity — from SQLite row to the rendered card in markdown.
Module M03 exposes GET/api/endpoints, POST/api/endpoints, PATCH/api/endpoints/:slug, and DEL/api/endpoints/:slug. Each references EndpointResponse as its success payload.
Three failure modes that every architecture document hits after its first month.
get-users is the same endpoint you discussed three pages earlier.Markdown is the source of truth for content. SQLite is the source of truth for entities. XML tags are the bridge.
Pages live in pages/ as plain .md files. Git-friendly, editable in any IDE, diff-able in PRs. A file watcher refreshes the UI on external changes.
Endpoints, DTOs and database tables in a relational store. Slugs, tags, version history, linking (endpoint ↔ DTO with request / response / error relations), full-text search.
Inline <inline_mention/>, entity cards, dynamic <tagged_list/>. Rename an entity slug — every reference updates automatically. The agent sees structure, not prose.
## User registration The frontend calls <inline_mention type="endpoint" slug="create-user"/> with the payload: <single_element type="dto" slug="CreateUserRequest"/> The response matches any DTO tagged with `auth`: <tagged_list type="dto" tags="auth" filter="or"/>
Node 20+ and an authenticated claude CLI. The agent uses your Claude Max / Team subscription session — no API key required.
On first run in an empty folder, it scaffolds claude4spec.json, the SQLite database and pages/index.md. In an existing project, it auto-detects.
The server starts on http://localhost:3000 (auto-falls-back on port collision). Edit pages on the left, entities in the side panels, talk to the agent in the overlay.
# 1. verify the prerequisites $ node --version v20.11.0 $ claude --version claude-cli 1.0.4 # 2. start in any directory $ cd ~/my-spec && npx claude4spec › scaffolded pages/index.md › claude4spec.db created › listening on http://localhost:3000 # 3. opens automatically in your browser
Tables, code, blockquotes, frontmatter, slash commands /endpoint /dto /mention /tagged.
Endpoints, DTOs and database tables with version history (timeline + diff + restore), tags and find-references.
From inline mentions to dynamic tag-based lists. Slug renames propagate across the whole project automatically.
Claude runs against in-process MCP servers (endpoint-tools, dto-tools, database-tools, reference-tools, dependency-tools). It doesn't describe entities — it creates them.
Typed dependencies between sections (depends_on, implements). Change a section and dependents get flagged stale.
A SQLite file and a markdown directory — it all lives on your disk. No API key, no telemetry, no external endpoints beyond the claude CLI.
Every reference is a plain XML tag in markdown. In the editor it renders as an interactive component. For the agent, it's a structured pointer that resolves through MCP.
| Type | Example | When to use |
|---|---|---|
| inline_mention | <inline_mention type="endpoint" slug="get-users"/> | A mention inside a prose sentence. |
| single_element | <single_element type="dto" slug="UserResponse"/> | A standalone card describing one entity. |
| element_list | <element_list type="endpoint" slugs="get-users,create-user"/> | A hand-picked group of a single type. |
| tagged_list | <tagged_list type="endpoint" tags="auth" filter="or"/> | A dynamic, tag-filtered list of one type. |
| tagged_list_mixed | <tagged_list_mixed tags="auth" filter="and"/> | A multi-type list (endpoints + DTOs) grouped by type. |
| section_ref | <section_ref anchor="a7f3b2c1" relation="depends_on"/> | A link to another section with a typed relation. |
┌─────────────────────────────────────────────────────────────────────┐ │ npx claude4spec │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Sidebar │ │ Tiptap Editor │ │ Chat Overlay │ │ │ │ Pages + │ │ markdown + │ │ custom blocks │ │ │ │ Entities │ │ XML nodes │ │ + hooks only │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ │ └────────────────────┼──────────────────────┘ │ │ │ REST + SSE + WS │ │ ┌────────────▼──────────────┐ │ │ │ Express API Server │ │ │ └────────────┬──────────────┘ │ │ ┌───────────────────────┼───────────────────────┐ │ │ │ │ │ │ │ ┌─────▼─────┐ ┌──────▼──────┐ ┌───────▼────────┐ │ │ │ Filesystem│ │ SQLite │ │ agent-adapters │ │ │ │ pages/*.md│ │ (.db file) │ │ (claude-code) │ │ │ └───────────┘ └─────────────┘ └───────┬────────┘ │ │ │ spawn │ │ ┌───────▼────────┐ │ │ │ claude CLI │ │ │ │ (subscription) │ │ │ └────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘
@inharness/agent-adapters) and one chat UI kit (@inharness/agent-chat — hooks only). No direct dependency on the Anthropic SDK.Own specs for their teams. Want a single source of truth and diff-ability in PRs, not a rotting wiki page.
Design APIs and data models. Need the spec to stay in sync with the code, and to survive a slug rename.
Already run agents to implement. Want the agent to have structured access to the spec via MCP — not just raw markdown.
claude CLI, installed and signed in (Claude Max / Team subscription)No. The claude CLI uses your subscription session — the same login as Claude.ai or Claude Code.
No. Everything runs locally — Express, SQLite, filesystem. The agent spawns a local claude process.
Yes. The custom XML tags are plain HTML-like nodes; the rest is CommonMark + GFM + YAML frontmatter. Editable in any IDE.
Through git — pages and claude4spec.db both. There's no realtime collaboration (yjs) yet — it's an open question on the roadmap.
The rename propagates across every pages/*.md file via slug-rename propagation in the references layer.
npx installs nothing globally — there's nothing to uninstall. Delete claude4spec.json, claude4spec.db and pages/ to clean up a project.