Cairn
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-alpine
python3 -m venv .venv && .venv/bin/pip install 'psycopg[binary]'
export DATABASE_URL="postgres://postgres:pw@127.0.0.1:5432/cairn"
.venv/bin/python dev.py --init
Tests run against that same database:
.venv/bin/python tests/smoke.py
.venv/bin/python tests/test_limits.py
.venv/bin/python tests/test_sp3.py
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.