Cairn

Cairn

A local-first, open-source harness for organizing your files with an AI agent.

Point Claude Code, Codex, Cursor — any MCP client — at a folder, and your agent gains a full file-organization toolset: list, read, search, grep, edit, move, tag, import documents, and semantically retrieve. No account, no cloud, no UI required. Your files never leave your machine.

claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

Then ask your agent to *"organize this folder and tag everything"* — it will, using tools that run locally over your own files.

A cairn is a stack of stones that marks a trail. This one keeps your files in

order and shows the way through them.

Quickstart (2 minutes)

If you use Claude Code, setup is one command — the only prerequisite is uv, which provides uvx:

# 1. Install uv if you don't have it (provides uvx)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Add Cairn to Claude Code, pointed at a folder you want organized

claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

Reopen Claude Code and ask:

*"Organize this folder and tag everything."*

Cairn's tools run locally over your files — reads happen freely, and any move/rename/edit asks for confirmation first. The first run auto-downloads the package (~5s); no clone, no build, no account.

[!TIP]

Point --workspace at a copy of some notes for your first run — Cairn can

move, rename, and edit files.

Using Codex? Same one-command flow (then run /mcp in a session to confirm):

codex mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

Using Cursor or another MCP client? Same package, JSON config:

{ "mcpServers": { "cairn": { "command": "uvx",

"args": ["cairn-mcp-server", "--workspace", "~/Documents/notes"] } } }

~ is expanded by Cairn, so ~/Documents/notes works in the CLI and in config files alike.

Just want to poke at it, no agent?

uvx cairn-cli --workspace ~/Documents/notes tree

Why a harness

The agent-harness ecosystem converged on a clear pattern: the model and the agent loop are commodities supplied by the client (Claude Code, Codex, OpenCode). The durable value is the tools and the local data. So Cairn ships *tools, not an agent* — the client provides the loop, the approval prompts (driven by our tool annotations), and the chat. Cairn is just the local file-organization toolset that snaps into whatever harness you already use.

Architecture

Everything is a thin adapter over one standard-library core, so the faces can never drift.

core/          cairn-core — the engine (stdlib only): the .uni document format,

file operations, tags, retrieval; optional document ingestion (docx/pdf/pptx/xlsx/md) and embeddings-based search. mcp-server/ cairn-mcp-server — MCP server: 26 tools with read-only/destructive annotations, resources, and prompts. ← the flagship cli/ cairn-cli — scriptable CLI, a local HTTP API (serve), and an mcp launcher. web/ cairn-web — optional zero-build local web UI (browse / edit / view / tag / search).

Use it

In Claude Code / Codex / Cursor (primary):

claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes

with real-document import: uvx --with "cairn-core[convert]" cairn-mcp-server ...

The server exposes read-only tools (list, read, search, grep, retrieve) that the client runs freely, and destructive tools (move, delete, edit) that it confirms first — driven by MCP tool annotations, so you get approval prompts with no UI of ours.

As a CLI:

uvx cairn-cli --workspace ~/Documents/notes tree

uvx cairn-cli --workspace ~/Documents/notes retrieve "budget planning"

With the optional web UI:

pip install cairn-cli cairn-web

cairn --workspace ~/Documents/notes serve # → http://127.0.0.1:4177/

The .uni format

A .uni file is a small JSON document — { uuid, content: " ", metadata, tags } — with tags stored *in the file*. A workspace is just a directory: fully portable, no external database. Source documents (docx/pdf/pptx/…) import into editable .uni docs; the originals are kept by default.

Local-first & bring-your-own-key

• No account, no login, no cloud sync. The filesystem is the source of truth.
• The default retriever is lexical and needs nothing. Embeddings are opt-in and bring-your-own-key (any OpenAI-compatible endpoint, including local servers like Ollama or LM Studio); vectors live in a local SQLite index under /.cairn/ and never leave your machine.

Roadmap

Cairn is young. Rough direction, and where help is most welcome:

• More document faces — richer frontmatter support (nested metadata, dates), and round-tripping edits back into imported source formats.
• Smarter digests — summaries that use an embedding model when one is configured, and saved views (.cairn/views/*.md).
• More retrieval backends — pluggable rerankers; first-class local-model presets (Ollama, LM Studio) beyond the generic OpenAI-compatible path.
• Editor/agent integrations — thin recipes for wiring Cairn into common MCP clients and note-taking setups.
• Packaging — signed releases and a Homebrew formula.

Have a use case that doesn't fit? Open an issue or start a discussion.

Contributing

Contributions of every size are welcome — see CONTRIBUTING.md for the project layout, dev setup, and how to add a tool. Good first issues are labeled good first issue.

Develop

make setup      # uv venv (3.11) + editable install of all packages + extras

make test # run the suite make serve WORKSPACE=~/Documents/notes # web UI

License

MIT — see LICENSE.