{
  "markdown": "# Cairn\n\n**A local-first, open-source harness for organizing your files with an AI agent.**\n\nPoint Claude Code, Codex, Cursor — any MCP client — at a folder, and your agent\ngains a full file-organization toolset: list, read, search, grep, edit, move,\ntag, import documents, and semantically retrieve. No account, no cloud, no UI\nrequired. Your files never leave your machine.\n\n```bash\nclaude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes\n```\n\nThen ask your agent to *\"organize this folder and tag everything\"* — it will,\nusing tools that run locally over your own files.\n\n> A cairn is a stack of stones that marks a trail. This one keeps your files in\n> order and shows the way through them.\n\n---\n\n## Quickstart (2 minutes)\n\nIf you use **Claude Code**, setup is one command — the only prerequisite is\n[`uv`](https://docs.astral.sh/uv/), which provides `uvx`:\n\n```bash\n# 1. Install uv if you don't have it (provides uvx)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# 2. Add Cairn to Claude Code, pointed at a folder you want organized\nclaude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes\n```\n\nReopen Claude Code and ask:\n\n> *\"Organize this folder and tag everything.\"*\n\nCairn's tools run locally over your files — reads happen freely, and any\nmove/rename/edit asks for confirmation first. The first run auto-downloads the\npackage (~5s); no clone, no build, no account.\n\n> [!TIP]\n> Point `--workspace` at a **copy** of some notes for your first run — Cairn can\n> move, rename, and edit files.\n\n**Using Codex?** Same one-command flow (then run `/mcp` in a session to confirm):\n\n```bash\ncodex mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes\n```\n\n**Using Cursor or another MCP client?** Same package, JSON config:\n\n```json\n{ \"mcpServers\": { \"cairn\": { \"command\": \"uvx\",\n  \"args\": [\"cairn-mcp-server\", \"--workspace\", \"~/Documents/notes\"] } } }\n```\n\n`~` is expanded by Cairn, so `~/Documents/notes` works in the CLI and in config files alike.\n\n**Just want to poke at it, no agent?**\n\n```bash\nuvx cairn-cli --workspace ~/Documents/notes tree\n```\n\n## Why a harness\n\nThe agent-harness ecosystem converged on a clear pattern: the model and the\nagent loop are commodities supplied by the client (Claude Code, Codex, OpenCode).\nThe durable value is **the tools and the local data**. So Cairn ships *tools, not\nan agent* — the client provides the loop, the approval prompts (driven by our\ntool annotations), and the chat. Cairn is just the local file-organization\ntoolset that snaps into whatever harness you already use.\n\n## Architecture\n\nEverything is a thin adapter over one standard-library core, so the faces can\nnever drift.\n\n```\ncore/          cairn-core — the engine (stdlib only): the .uni document format,\n               file operations, tags, retrieval; optional document ingestion\n               (docx/pdf/pptx/xlsx/md) and embeddings-based search.\nmcp-server/    cairn-mcp-server  — MCP server: 26 tools with read-only/destructive\n               annotations, resources, and prompts.        ← the flagship\ncli/           cairn-cli  — scriptable CLI, a local HTTP API (`serve`),\n               and an `mcp` launcher.\nweb/           cairn-web  — optional zero-build local web UI\n               (browse / edit / view / tag / search).\n```\n\n## Use it\n\n**In Claude Code / Codex / Cursor (primary):**\n\n```bash\nclaude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes\n# with real-document import: uvx --with \"cairn-core[convert]\" cairn-mcp-server ...\n```\n\nThe server exposes read-only tools (list, read, search, grep, retrieve) that the\nclient runs freely, and destructive tools (move, delete, edit) that it confirms\nfirst — driven by MCP tool annotations, so you get approval prompts with no UI\nof ours.\n\n**As a CLI:**\n\n```bash\nuvx cairn-cli --workspace ~/Documents/notes tree\nuvx cairn-cli --workspace ~/Documents/notes retrieve \"budget planning\"\n```\n\n**With the optional web UI:**\n\n```bash\npip install cairn-cli cairn-web\ncairn --workspace ~/Documents/notes serve   # → http://127.0.0.1:4177/\n```\n\n## The `.uni` format\n\nA `.uni` file is a small JSON document — `{ uuid, content: \"<html>\", metadata,\ntags }` — with tags stored *in the file*. A workspace is just a directory: fully\nportable, no external database. Source documents (docx/pdf/pptx/…) import into\neditable `.uni` docs; the originals are kept by default.\n\n## Local-first & bring-your-own-key\n\n- No account, no login, no cloud sync. The filesystem is the source of truth.\n- The default retriever is lexical and needs nothing. Embeddings are opt-in and\n  bring-your-own-key (any OpenAI-compatible endpoint, including local servers\n  like Ollama or LM Studio); vectors live in a local SQLite index under\n  `<workspace>/.cairn/` and never leave your machine.\n\n## Roadmap\n\nCairn is young. Rough direction, and where help is most welcome:\n\n- **More document faces** — richer frontmatter support (nested metadata, dates),\n  and round-tripping edits back into imported source formats.\n- **Smarter digests** — summaries that use an embedding model when one is\n  configured, and saved views (`.cairn/views/*.md`).\n- **More retrieval backends** — pluggable rerankers; first-class local-model\n  presets (Ollama, LM Studio) beyond the generic OpenAI-compatible path.\n- **Editor/agent integrations** — thin recipes for wiring Cairn into common\n  MCP clients and note-taking setups.\n- **Packaging** — signed releases and a Homebrew formula.\n\nHave a use case that doesn't fit? [Open an issue](https://github.com/luckyjackluo/cairn/issues)\nor start a [discussion](https://github.com/luckyjackluo/cairn/discussions).\n\n## Contributing\n\nContributions of every size are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)\nfor the project layout, dev setup, and how to add a tool. Good first issues are\nlabeled [`good first issue`](https://github.com/luckyjackluo/cairn/labels/good%20first%20issue).\n\n## Develop\n\n```bash\nmake setup      # uv venv (3.11) + editable install of all packages + extras\nmake test       # run the suite\nmake serve WORKSPACE=~/Documents/notes   # web UI\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 6143,
  "sha": "f742bae932bb961f9c3c88c070e573f1f5d7bd02de667d566bb299e1ee951bde",
  "repo_slug": "luckyjackluo/cairn",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_luckyjackluo_cairn_0721d4b3/readme"
}