Interface

Everything in Cairn — a file, an issue, a transcript, a terminal, a skill, an external tool — has an address, and every action is one of three verbs applied to addresses: read, write, and run. Agents and users share this surface: you can read the same resources an agent reads, with the same gestures.

Addresses

Address	What it names
`file:src/lib.rs`	A file in the working tree (`file:` alone is the root)
`cairn://p/CAIRN`	A project
`cairn://p/CAIRN/issues`	Its issue list
`cairn://p/CAIRN/123`	One issue
`cairn://p/CAIRN/123/1/builder`	An agent run on that issue — its transcript (`/chat`), changed files (`/changed`), tasks, and artifacts sit a segment further down
`cairn:~/`	An agent's shorthand for its own node — `cairn:~/todos` is its own task list
`cairn://skills/testing`	A skill, readable inline
`cairn://mcp/playwright`	An external MCP server and its tools
`https://…`, `*.pdf`	Web pages and PDFs, returned as markdown

Reading a cairn:// resource returns its content and an affordance block — the actions the resource accepts and how to call them — so the surface is discoverable by reading it. An agent needs none of it in advance: it starts from the issue it is on and follows the addresses outward, learning each part of the system by reading it.

read

read fetches and searches. One call can carry several addresses and return them in order. Filters ride in the address as a query string:

Filter	Effect
`?grep=REGEX`	Search a file, a directory tree, or any resource's rendered text
`?glob=*/.rs`	Match filenames under a directory
`?search=...`	Full-text search across a project
`?offset=N&limit=M`	Window a large target in its own units — lines for a file, entries for a list

read file:src?grep=parse_uri&glob=**/*.rs
read cairn://p/CAIRN/123/1/builder/chat
read cairn://p/CAIRN?search=uri parser&limit=5

write

write mutates: file edits, issue comments, spawned sub-agents, questions to the user, output artifacts. A single write is one logical move rather than one edit — it can touch several files and resources together, and its file changes land as a single commit with the message the write carries.

Some writes hand control over: a question written to cairn:~/questions pauses the agent until you answer; a task written to cairn:~/tasks pauses it until the sub-agent returns.

run

run executes shell commands, skill scripts, and external MCP tools — one call can carry many, in parallel or in sequence. Read cairn://mcp/<server> to see a server's tools, then run one by its address.

The commit rule

A write or run that changes tracked files carries a commit message and lands as one commit, so the working tree always equals the latest commit. History is captured continuously as coherent, self-described moves — the branch that becomes a pull request is that sequence of moves.