cos
CLAUDE.md4 starsChanged 4 months agoMITView on GitHub
Cos — a personal "chief of staff": a writable board (board/, Next.js + a JSON store) for work+life to-dos, a knowledge vault (vault/, the LLM-Wiki pattern), a prompt-injection guard (guard/, FastAPI sidecar), semantic search (search/, sidecar), and MCP servers (mcp/) that expose it all to agents. Feature docs live in the MkDocs site under docs/ (Material theme, mkdocs.yml, published to GitHub Pages): e.g. docs/architecture/spec.md, docs/features/board.md, docs/security/guard.md, docs/reference/search.md, docs/architecture/hierarchy.md, docs/reference/migration.md. README.md (the repo landing/quickstart) stays at the root. Skills live in…
- Reads credentials
- Installs packages
In this repository17 other files it gives its agents.
- mcp/CLAUDE.mdCLAUDE.md
- add-an-addonSkill
- backup-recoverySkill
- body-mcp-setupSkill
- cos-setupSkill
- cos-upgradeSkill
- debug-cowork-mcp-issuesSkill
- fitness-mcp-setupSkill
- guard-setupSkill
- hub-handoverSkill
- mcp-bridge-setupSkill
- nutrition-mcp-setupSkill
- openwhispr-mcp-setupSkill
- setup-vaultSkill
- spoke-setupSkill
- voice-operationsSkill
- whatsapp-mcp-setupSkill
The file
We split this CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Skills live in two trees, and the split is load-bearing: Put a setup skill in the repo-root .claude/skills/ — Claude Code reads it live off …
- Very specific: line 26
Every setup/skill shell step begins with source "$(git rev-parse --show-toplevel)/config/load-config.sh", which resolves REPO_ROOT from git …
- Very specific: line 89
All project documentation lives in the MkDocs site (docs/, Material theme, config in mkdocs.yml), published to GitHub Pages by …
- Distinctive: line 92
When you add or change docs:
- Very specific: line 95
not: create new top-level *.md files at the repo root for documentation — that is the scattered-Markdown pattern we deliberately moved away …
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cos — repo guide (read this first)
Cos — a personal "chief of staff": a writable board (board/, Next.js + a JSON store) for
work+life to-dos, a knowledge vault (vault/, the LLM-Wiki pattern), a prompt-injection
guard (guard/, FastAPI sidecar), semantic search (search/, sidecar), and MCP
servers (mcp/) that expose it all to agents. Feature docs live in the MkDocs site under
docs/ (Material theme, mkdocs.yml, published to GitHub Pages): e.g. docs/architecture/spec.md,
docs/features/board.md, docs/security/guard.md, docs/reference/search.md,
docs/architecture/hierarchy.md, docs/reference/migration.md. README.md (the repo
landing/quickstart) stays at the root.
Skills live in two trees, and the split is load-bearing. Put a setup skill in the repo-root
.claude/skills/ — Claude Code reads it live off disk and Cowork never sees it (cos-setup is the
single first-run orchestrator; each add-on ships its own <name>-mcp-setup skill). Put an
operator skill — anything a scheduled sweep runs or delegates to — in board/.claude/skills/,
and rebuild its bundle with node scripts/pack-skills.mjs after every edit. Cowork installs skills
only from board/.claude/skill-bundles/*.zip, so a delegation to a root-level skill is a silent
no-op there — not an error. Rebuilding a bundle does not install it: re-upload the .zip in
Cowork (Settings → Capabilities → Skills) after every rebuild. Nothing checks this, so until you do,
that skill's half of the feature is silently dead there while the repo stays green.
The bundles are committed binaries, so git cannot merge two branches that touched the same skill:
after any merge or rebase that brings in someone else's skill edit, re-run pack-skills.mjs and
commit the rebuilt .zip — a red pack-skills --check whose output says stale or missing there
means "rebuild", not "defect" (only an automation.json sync error from the packer itself is a defect).
Every setup/skill shell step begins with source "$(git rev-parse --show-toplevel)/config/load-config.sh",
which resolves REPO_ROOT from git and exports machine config from config/cos.env (generated by
cos-setup) — paths, ports, and URLs (REPO_ROOT, BREW_PREFIX, VAULT_DIR, BOARD_URL, the bridge/
sidecar ports + URLs, etc.) so nothing is hardcoded. The config/ dir splits by concern: cos.env
(machine paths/ports), secrets.env (the Anthropic API key), settings.json (board prefs), and
auto-sync.json (router switch); the loaders, secret-validation.mjs, auto-sync.json, and the
*.example files are committed — the live cos.env/secrets.env/settings.json are gitignored.
Secrets reach the two MCP clients by different binding paths (Claude Code re-reads secrets.env
per start; Cowork gets an inlined snapshot), so rotation is a two-step — see the "Cowork holds a
COPY of every secret" gotcha in mcp/CLAUDE.md.
mcp/CLAUDE.md— read it before touchingmcp/.board/.claude/CLAUDE.md— read it before writing or editing an operator skill.board/data/CLAUDE.md—board/data/is LIVE, irreplaceable user data; read it BEFORE touching anything there — never seedboard/dataon a machine with live data.
Multi-device — one hub, thin spokes. Cos is multi-device via hub & spoke: ONE machine (the
hub) runs the board and owns all state; every other device reaches it over Tailscale. To just
VIEW/use the board from another device you need nothing on that device — the hub runs the
production board (cd board && npm run build && npm run start, or the boardapp LaunchAgent —
never next dev behind a proxy) behind tailscale serve --bg 3000, and any tailnet device opens the
portless https://<hub>.<tailnet>.ts.net in a browser (full read/write UI — the browser writes
through the same HTTP API). You add a spoke (spoke-setup — the thin local stdio MCP wrappers
pointed at the hub's BOARD_URL) ONLY when you also want agents (Claude Code/Cowork) to drive the
board from that machine, since Cowork accepts only local stdio MCP servers (not a remote HTTP MCP
over the tailnet). Move the hub role to a different machine with hub-handover (the old one stays a
browser viewer, needing no spoke). Full runbook: docs/architecture/multi-device.md.
Architecture philosophy — Cos is a state machine; agents are the intelligence
Internalise this before you build anything. Every component — the board/ and every add-on —
is a deterministic STATE MACHINE. It owns and persists its state (on cases.json, through the
single mutate() chokepoint) and exposes that state two ways: a rich, fully-typed HTTP API
(/api/*) and a stdio MCP server (mcp/<name>-server/). Those two surfaces are the whole
contract — any external agent (Claude Code, Claude Cowork, a cron routine) can read AND write
every functionality natively through them.
Components do NOT call an LLM / the Anthropic API. Any generative or "intelligent" step —
generate a training plan, draft a reply, summarize a week — happens in the external agent's
context, and the agent writes the structured result back through the API/MCP. The component only
validates, versions (SSE), attributes (human vs agent), stores, and serves it.
- Worked example: the fitness add-on does not generate a training plan. The agent
generates it (e.g. via the
fitness-coachskill, reading the health + profile data through the MCP) and persists it via thesave_training_planMCP tool /POST /api/fitness/coaching. The board validates the shape, upserts it by period intodb.coachingArtifacts, attributes it, and serves it back as a history feed. The board never calls Claude. - Why it matters: components stay key-free, offline-capable, deterministically testable, and composable. A new feature is "done" when it is a state machine with an API + MCP — not when it has a clever prompt. (Deterministic server-side compute is fine — e.g. the correlations stats, Pearson + linear regression. Only generative LLM inference is delegated to the agent.)
- THE ONE EXCEPTION — the vault MCP.
mcp/vault-serverembeds the Claude Agent SDK and legitimately runs LLM calls server-side (ingest/query) — it is itself an agent, not a state-machine component. TheANTHROPIC_API_KEYinconfig/secrets.envexists solely for the vault; no other component reads it.
Building a new component/add-on? Make it a state machine: persist state on the core store,
expose an API + an MCP server, and never import an LLM client — delegate any generative step
to the agent via an MCP write tool. Follow the add-an-addon
skill.
Documentation — write it in MkDocs, not loose Markdown
All project documentation lives in the MkDocs site (docs/, Material theme, config in
mkdocs.yml), published to GitHub Pages by .github/workflows/docs.yml — deployed MANUALLY only
(gh workflow run docs.yml or the Actions tab; never on push) after docs changes land on main.
When you add or change docs:
- Add/edit pages under
docs/and wire each new page into thenav:inmkdocs.yml. Do not create new top-level*.mdfiles at the repo root for documentation — that is the scattered-Markdown pattern we deliberately moved away from. If you're about to write aFOO.mdat the root, it belongs underdocs/<section>/foo.mdinstead. - Keep only these at the root (GitHub surfaces them; they are not site content):
README.md,LICENSE,CONTRIBUTING.md,CODE_OF_CONDUCT.md,SECURITY.md,CLAUDE.md, andCHANGELOG.md(bot-managed by release-please). ComponentREADME.mds (mcp/*/,guard/,search/,backup/,tests/) stay next to the code they document. - Cross-link with relative
.mdpaths (e.g.../security/guard.md) somkdocs build --strictvalidates them; link to repo source files with absolute GitHub blob URLs. - Generated pages (e.g.
docs/reference/labels.mdfromscripts/gen-labels-doc.mjs) — edit the generator/source and re-run it; never hand-edit the generated page. - Preview / validate locally:
uvx --with-requirements docs/requirements.txt mkdocs serveto preview,uvx --with-requirements docs/requirements.txt mkdocs build --strictto fail on any broken link — the same pinned toolchain CI installs.
Commands & CI gates
# Deps first — root workspaces AND board, on Node >= 22. Without the installs the api-* and
# MCP-stdio steps SKIP; below Node 22 the hard-gate unit tests SKIP too — in every case the
# suite still exits 0 (CI runs npm ci + npm ci --prefix board).
npm install && (cd board && npm install)
bash tests/run.sh # full test suite — sandboxed; the one live touchpoint (the guard-sidecar step) is net-zero by design
(cd board && npm run dev) # run the board — see Store schema discipline below; predev ENSURES the MCP bridges are up (launchd bootstrap + kickstart + probe; it starts services, never stops any)
(cd board && npx --no-install tsc --noEmit && npm run lint) # board typecheck + ESLint
node tests/board-lint.mjs [path] # store invariants — READ-ONLY; path defaults to the LIVE board/data/cases.json
node scripts/pack-skills.mjs # rebuild operator-skill bundles + the generated skills-README catalog; `--check` is the CI gate
node scripts/upgrade-check.mjs # AFTER a git pull on an existing install: the ordered post-pull checklist (rebuild/kickstart/re-upload/schedule) derived from the diff — the `cos-upgrade` skill runs it; never mutates
node scripts/mark-skill-uploaded.mjs <skill>|--all|--list # per-machine receipt of the bundles you uploaded to Cowork (mcp/logs/); upgrade-check lists hash drift against it- Required CI checks:
lint-test(manifest +.mcp.jsonsync-check, board tsc + ESLint, then the fulltests/run.sh) andpython(guard/+search/viauv run --extra dev pytest; reproducing it locally needsuv— run.sh self-skips the python steps without it). - A green
workflow_dispatchCI run does NOT unblock a PR — its checks attach to the commit but not the PR's status rollup, so branch protection keeps the PRBLOCKEDeven whenlint-test/pythonpass. Re-trigger with apull_requestevent (push a commit — an empty one is fine), never a re-dispatch. - A local
tests/run.shresult is never evidence about a PR — rungh pr checks <N>and report what CI said. Local and CI evaluate different check sets. Never call a local red "pre-existing" without naming the step and quoting CI's verdict for it — a suite whose reds get routinely discounted is one a real regression hides in. - A check that reads machine-local state names its source as an env key and defines the absent
case — assert where the data exists and print a distinct non-
✓line elsewhere (never fail for absence); anything touching the store takes its path fromCOS_BOARD_DATAand SKIPs when unset. Never default a data path toboard/data/cases.json— that is the live, irreplaceable store. - A tool or report states only what it verified. Print a success line only for a step whose exit
status you checked — a discarded status prints nothing and the process exits non-zero. Disambiguate
an empty result before reporting it: never ran and ran and produced nothing are different
states, and the second beside a non-zero input count is an anomaly to report with both numbers,
never a reassurance. A check that cannot observe its subject reports UNKNOWN, never clear.
Census a source tree with
git grepor anodewalk, nevergrep -r— one committed NUL byte makesgrepdrop that whole file from-r/-loutput silently, at exit 0. - Resolve a repo path against the git index (
git ls-files,git check-ignore), never the working tree — the hub holds files and directories a fresh checkout lacks, so a disk check goes green here and red in CI. - A new
mcp/*-serveris a root workspace member —npm installat the repo root and commitpackage-lock.json, or CI'snpm cifails fast. - Never
next buildinboard/while anext devis running — they share.nextand the running board 500s until restarted; verify withnpx tsc --noEmitinstead.
Contribution & release mechanics
- Branch off
main(protected — PRs only; conventions:CONTRIBUTING.md). Never hand-editCHANGELOG.mdor version fields outside the Release PR — release-please owns them; conventional PR titles are the changelog (CONTRIBUTING.md§Releasing,docs/reference/releasing.md). - Store schema discipline (
docs/reference/migration.md): NEVER run a board older than the live store'sschemaVersion— older code silently drops the newer keys on write (compare the store'sschemaVersioninboard/data/cases.jsonwithSCHEMA_VERSIONinboard/lib/types.ts). Upgrading an existing install iscos-upgrade(docs/reference/upgrading.md): a pull migrates the store on the next start but rebuilds/restarts/re-uploads NOTHING — every stale piece is a silent no-op, andscripts/upgrade-check.mjsis what turns the diff into the list.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

