Cairn

Cairn

[PyPI] [MCP Registry] [License: MIT]

A work tracker that remembers what you did. It captures your coding sessions, the files you touch, tasks moving from pending to done, and project notes, then keeps them in one place with daily and weekly rollups. The name is the pile of stones that marks a trail.

Cairn runs as a multi-tenant web app on Vercel with a Neon Postgres database. Each account signs up, logs in, and only ever sees its own data.

How it's built

The whole server is the Python standard library plus one dependency (psycopg). No framework.

• api/index.py — the Vercel serverless entrypoint. Vercel's Python runtime treats it as a catch-all, so every request lands here.
• lib/handler.py — routing. The same BaseHTTPRequestHandler runs three ways: the Vercel function, the local dev server, and the tests.
• lib/data.py — every SQL statement, each one scoped by user_id.
• lib/db.py — Neon connection (pooled endpoint) plus small query helpers.
• lib/auth.py — PBKDF2 password hashing, sessions, and token resolution.
• lib/limits.py — signup/login rate limiting and per-account quota caps, both backed by Postgres.
• lib/assets.py — the single-page app and favicon, embedded as base64 so they ship inside the function bundle. Generated by build_assets.py; re-run it after editing static/.

Local development

You need a Postgres to point at. A throwaway one in Docker works:

docker run -d --name cairn_pg -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=cairn -p 5432:5432 postgres:16-alpinepython3 -m venv .venv && .venv/bin/pip install 'psycopg[binary]'export DATABASE_URL="postgres://postgres:[email protected]:5432/cairn".venv/bin/python dev.py --init    # create the schema, then serve on :8765

Tests run against that same database:

.venv/bin/python tests/smoke.py        # core CRUD + isolation.venv/bin/python tests/test_limits.py  # rate limiting + quotas.venv/bin/python tests/test_sp3.py     # file activity + filtered lists

Deployment

Pushing to main deploys to production through the Vercel GitHub integration. DATABASE_URL and the other Neon variables come from the Vercel ↔ Neon integration; the app reads the pooled connection string. Schema changes go on with initdb.py against the direct (unpooled) URL.

The agent side

The agent/ folder is the MCP server and two Claude Code hooks that run on your machine. They talk to this API over HTTPS using your account's token, so anything Claude Code does flows into your Cairn account. The server gives Claude a set of cairn tools; the hooks log sessions and file edits on their own.

On Claude Code the quickest install is the plugin — this repo doubles as a plugin marketplace (.claude-plugin/marketplace.json):

/plugin marketplace add https://github.com/cybort360/cairn/plugin install cairn@cairn

That wires up the MCP server and both hooks; you just save your token to ~/.cairn_token (it needs uv on your PATH). The manual route — clone, venv, claude mcp add — is in agent/README.md. The web app deploy ignores agent/; it's client-side only.

Design notes

Each sub-project that built Cairn has a spec under docs/superpowers/specs/: the cloud core, the auth hardening, and the local agent cutover. Read those if you want the reasoning behind a decision rather than just the code.