agentleFS
philipyazphilipyaz/cos/CLAUDE.md

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

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
  1. Very specific:

    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 …

    line 12
  2. Very specific:

    Every setup/skill shell step begins with source "$(git rev-parse --show-toplevel)/config/load-config.sh", which resolves REPO_ROOT from git …

    line 26
  3. Very specific:

    All project documentation lives in the MkDocs site (docs/, Material theme, config in mkdocs.yml), published to GitHub Pages by …

    line 89
  4. Distinctive:

    When you add or change docs:

    line 92
  5. Very specific:

    not: create new top-level *.md files at the repo root for documentation — that is the scattered-Markdown pattern we deliberately moved away …

    line 95

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 touching mcp/.
  • 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 seed board/data on 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-coach skill, reading the health + profile data through the MCP) and persists it via the save_training_plan MCP tool / POST /api/fitness/coaching. The board validates the shape, upserts it by period into db.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-server embeds the Claude Agent SDK and legitimately runs LLM calls server-side (ingest/query) — it is itself an agent, not a state-machine component. The ANTHROPIC_API_KEY in config/secrets.env exists 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 the nav: in mkdocs.yml. Do not create new top-level *.md files at the repo root for documentation — that is the scattered-Markdown pattern we deliberately moved away from. If you're about to write a FOO.md at the root, it belongs under docs/<section>/foo.md instead.
  • 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, and CHANGELOG.md (bot-managed by release-please). Component README.mds (mcp/*/, guard/, search/, backup/, tests/) stay next to the code they document.
  • Cross-link with relative .md paths (e.g. ../security/guard.md) so mkdocs build --strict validates them; link to repo source files with absolute GitHub blob URLs.
  • Generated pages (e.g. docs/reference/labels.md from scripts/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 serve to preview, uvx --with-requirements docs/requirements.txt mkdocs build --strict to 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.json sync-check, board tsc + ESLint, then the full tests/run.sh) and python (guard/ + search/ via uv run --extra dev pytest; reproducing it locally needs uv — run.sh self-skips the python steps without it).
  • A green workflow_dispatch CI run does NOT unblock a PR — its checks attach to the commit but not the PR's status rollup, so branch protection keeps the PR BLOCKED even when lint-test/python pass. Re-trigger with a pull_request event (push a commit — an empty one is fine), never a re-dispatch.
  • A local tests/run.sh result is never evidence about a PR — run gh 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 from COS_BOARD_DATA and SKIPs when unset. Never default a data path to board/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 grep or a node walk, never grep -r — one committed NUL byte makes grep drop that whole file from -r/-l output 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/*-server is a root workspace member — npm install at the repo root and commit package-lock.json, or CI's npm ci fails fast.
  • Never next build in board/ while a next dev is running — they share .next and the running board 500s until restarted; verify with npx tsc --noEmit instead.

Contribution & release mechanics

  • Branch off main (protected — PRs only; conventions: CONTRIBUTING.md). Never hand-edit CHANGELOG.md or 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's schemaVersion — older code silently drops the newer keys on write (compare the store's schemaVersion in board/data/cases.json with SCHEMA_VERSION in board/lib/types.ts). Upgrading an existing install is cos-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, and scripts/upgrade-check.mjs is what turns the diff into the list.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.