# waycairn

> **Status: early-stage, active development.** Issues and PRs are welcome.

A local-first MCP server for documenting a codebase as you work in it —
architecture diagrams and notes stored inside the repo itself
(`.waycairn/`), versioned in git, no cloud backend, no auth. An AI agent
(Claude Code, Codex CLI, opencode) reads and writes documentation as part
of its normal workflow, nudged to keep it current.

## Install

    npm install -g waycairn

Inside a repo you want to document:

    waycairn init

This computes the repo's identity from its git `origin` remote, registers
it in a global `~/.waycairn/registry.json`, ensures `.waycairn/index.sqlite`
is gitignored, and installs the MCP server + (where supported) a
documentation Skill and a session-end nudge for every AI agent detected on
the machine (Claude Code, Codex CLI, opencode).

If you usually open your agent at a *parent* folder holding several
sibling repos (rather than one repo at a time), use
`waycairn init --workspace` there instead — it installs the same MCP/skill/
hook config without requiring a git remote and without registering the
folder itself (it isn't a documentable repo). The MCP tools already
support this via `repoPath` (see below); this just gets the config
installed at that level.

## How it stores documentation

Every artifact is a JSON file under `.waycairn/<kind>/<id>.json` — the
versioned source of truth, small enough that two people documenting
different things on different branches rarely conflict. A derived,
gitignored SQLite index (`.waycairn/index.sqlite`) gives the MCP server
fast reads; it's rebuilt lazily from the `.json` files whenever it's stale
(a `git pull`, a branch switch, a manual edit), never the thing you're
supposed to merge.

The only kind implemented today is `"diagram"` — a C4/UML-ish node/edge
graph — but the storage layer is kind-agnostic: adding a new kind (session
notes, ADRs, ...) is a new validator plus one registry entry, not a
rewrite.

## Tools exposed (all local, no auth, no scopes)

| Tool | Notes |
|---|---|
| `list_artifacts` | lists every artifact of a `kind` in a repo |
| `get_artifact` | fetch one artifact by `kind` + `id` |
| `upsert_artifact` | the only write path — validates before writing; scoped to the repo the agent is actually in, never a different one |
| `validate_artifact` | dry-run validation, no write |
| `list_repos` | discovers repos: "local" (siblings under the session's working directory) and "registered" (anywhere on the machine, via `waycairn init`) |

`list_artifacts`/`get_artifact` take either `repoPath` (relative to the
session's working directory — the common case, and the only option when
the session is a parent folder of several sibling repos) or `repoId` (a
registered repo's global id, reaching it independent of where the current
session happens to be open). `upsert_artifact` only takes `repoPath` — an
agent documents the repo it's in, not some other repo it doesn't have
open.

A diagram node can reference another repo's artifact via
`externalRef: { repo: "<repoId>", artifactId: "<id>" }` — validated for
shape when written (same as `childDiagram`'s existing behavior: a typo in
`artifactId` creates a dangling reference instead of failing fast, since
resolving it means reaching into a different repo's store), resolved later
by whoever reads it, via `get_artifact`'s `repoId` parameter. The waycairn
UI's diagram canvas follows `externalRef` nodes with a real click-through
into the other repo's diagram.

A diagram with id `"deployment"` is treated as a system-level root: writing
one is rejected if (a) any node — in this diagram or another — would make
"deployment" a child (`childDiagram`/`externalRef.artifactId` pointing at
it), or (b) another repo already owns a "deployment" diagram within the
same cross-repo dependency graph (repos connected transitively via
`externalRef`). Only one "deployment" diagram is allowed per connected set
of repos, and it's always a drill-down entry point, never a destination.

## CLI

    waycairn init              # register this repo, install agent integrations
    waycairn init --workspace  # install agent integrations for a parent folder of sibling repos, without registering it
    waycairn mcp               # start the stdio MCP server (what an agent's config actually launches)
    waycairn ui                # start a local, read-only web UI for browsing diagrams
    waycairn -h                # show the full command reference

## UI

`waycairn ui` starts a local Express server (binds to `127.0.0.1` only —
no auth, so it never listens on the network) at
`http://localhost:4317` (override with `WAYCAIRN_UI_PORT`). It serves a
picker over every repo registered via `waycairn init`, a searchable list
of each repo's root diagrams, and the diagram canvas itself with
drill-down through `childDiagram` links (same repo) and `externalRef`
links (jumps to another registered repo's diagram tree). Read-only in this
first version — diagrams are still written by an agent via the MCP tools,
not from the UI.

## Testing

    npm test

## Known limitations

- Codex's session-end hook only fires once the user has marked the project
  trusted in Codex itself; `waycairn init` can't detect or control that.
- A registry entry whose `path` has moved or been deleted isn't cleaned up
  automatically — re-run `waycairn init` from the new location.
- `externalRef`/`childDiagram` aren't validated against what they point at
  when written — a typo is only visible when something tries to resolve
  the reference later.
- `waycairn ui` is read-only and only browses repos registered via
  `waycairn init` — a `local` (unregistered) repo isn't browsable from it
  yet, and `externalRef` click-through only works if the target repo is
  registered too.