CLAUDE.md - thismoon

Monorepo for the *.this platform: local web services, CLI tools, the shared webkit package, and their ralph recipes. A macOS-first local development toolbox — every service is a web UI + CLI for the human and (where it makes sense) an MCP server for agents, all on local data. Public under the BSD-3-Clause LICENSE.

Quick reference

Layout

services/    *.this local web services (one directory per service; present also
             runs as a shared instance in Kubernetes)
tools/       CLI tools installed to the local bin
webkit/      shared Go web UI package (in-module, no separate versioning)
kit/         shared Go packages for cross-tool functionality (one subpackage
             per concern, e.g. kit/repofind for git repo discovery)
buildinfo/   shared build-metadata package (ldflags targets, /version handler)
buildinfo.mk Makefile fragment every component includes to inject it
recipes/     ralph recipes, consumed remotely via [[recipe_sources]];
             recipes/lib holds shell helpers the launchers source (no
             recipe.toml, so ralph never loads it as a recipe)
mods/        Claude Code mods (in-process plugin modules), one directory per
             mod, listed by the root .claude-plugin/marketplace.json
skills/      agent skills (Claude + Codex), one directory per skill; each is
             symlinked into ~/.claude/skills and ~/.agents/skills by its
             paired recipe (skill-only recipes for skills with no binary)
evals/harness/ harness eval runner (not a component): fixed tasks through
             claude -p with the user's hooks and MCP servers, scored on outcome
             and cost, stored to compare before and after a change
examples/    worked private-config-repo layout (overlay recipes, example
             global CLAUDE.md) — the reference for the machine-private layer
docs/adr/    architecture decision records
docs/GETTING-STARTED.md install guide: one tool via mise vs the fleet via ralph
docs/HOW-IT-FITS-TOGETHER.md fleet pitch, ralph vocabulary, rollout order
docs/MEMORY-STACK.md    memory stores (auto memory, agent-memory, worklog,
             handoff, events, moondb) and the belt hooks that surface them
docs/RELEASING.md       release process (release-please, tags, artifacts, verification)
docs/UPGRADING.md       actions a change needs on consuming machines (newest
             first), added in the same PR as the change
docs/SECURITY-UPDATES.md how a dependency advisory reaches a fix: govulncheck,
             Dependabot security updates, and the Go version bump
docs/SANDBOXING.md      srt sandboxing: a walkthrough for sandboxing a new process,
             then the srt-run launcher, access manifests and the settings
             files rendered from them, the machine-local expansion layer,
             spawn wrappers, and denial triage for sandboxed services and
             MCP servers
docs/CONTAINER-BUILDS.md package-manager build steps (npm, pip, gem) in a throwaway
             Apple container VM: the export-only pattern and the runtime setup

Conventions

• Single Go module: github.com/mad01/thismoon, go 1.27.4. No nested go.mod files.
• A component is a directory under services/ or tools/ with its own Makefile exposing build, test, and install targets. The root Makefile discovers and delegates to them.
• Releases are per-component semver with name/vX.Y.Z tags, cut by release-please manifest mode on merge to main. Artifact builds are a plain CI matrix job.
• Build metadata is shared: a component Makefile sets COMPONENT := <name>, does include ../../buildinfo.mk, and links with $(BUILDINFO_LDFLAGS). Every component then reports the same four-key object (version, commit, tag, build_time) from GET /version and <binary> version -o json, while plain <binary> version stays a bare token that status parses.
• Build targets: darwin/arm64 only — the platform is macOS-focused (see docs/adr/0007; supersedes the target list in 0004).
• Release artifacts ship with checksums.txt and cosign keyless signatures; local installs use the "mad01 Local Signing" codesign identity, which recipes/codesign creates.
• Code imported from another repo comes in clean (no git history); the import commit message records the source repo and SHA it came from.
• Recipes under recipes/ must use absolute or ~-prefixed working_dir in builds/packages — ralph resolves remote recipe paths against its sources cache, not the consuming machine's checkout.
• Recipes are the public layer only: portable build/install, t-man-guarded hooks, skills. Machine-private wiring ([[recipe_sources]] pins, MCP registration, host enables, env/secrets, config overlays) lives in the consuming repo as companion recipes. Hard depends_on on the platform foundations t-man and d-man is allowed; on anything else cross-source deps are banned. See docs/adr/0006.
• Mods under mods/ are additive, not components: no skill, hook, or service may require one, and they carry no Makefile or release line. The consuming repo registers their marketplace, never this one (docs/adr/0021).
• Every change lands through a PR: branch, push, PR, CI green, merge. For CI green, wait on the ci-ok job's conclusion, not the full check list: gh pr checks --watch can exit before the matrix jobs register. Never push to main directly; a GitHub ruleset and belt's git-push-main guard both refuse it, and merging to main is the deploy (ralph pulls main on every ralph up).
• Stores are plain JSON or JSONL files: single-writer serve, full state in memory, atomic temp-and-rename saves. An embedded database solves nothing the fleet has and costs git-diffable files you can read with cat and jq; bbolt was assessed and declined in 2026-07. Revisit only if a store outgrows memory, such as an unbounded events history. When several services need the same load and save code, share a package instead.
• Discovery surfaces stay in step with the code. Three places tell search engines and agents what the repo holds:
  • The root llms.txt indexes the docs for agents and LLM crawlers. A new, renamed, or removed component, skill, or docs/*.md guide changes its line there in the same PR. CI fails the PR when a line is missing or a link is dead. Keep each line to what the component does, in the words of its row in the README tables.
  • The README opening names what the tools cover in plain search words. Update that sentence when a component adds or drops a whole area (a new kind of scanner, a new store).
  • The GitHub description and topics are set by hand with gh repo edit and no check covers them. Revisit them when the README opening changes.
• Install the secret-scanning pre-commit hook after cloning: suspenders hook install.
• Every CLAUDE.md in the repo has a sibling AGENTS.md symlink pointing at it, so non-Claude agents (Codex and others that read AGENTS.md) discover the same instructions. New components get the symlink alongside the CLAUDE.md.

Skills

The repo ships ten agent skills under skills/, one directory per skill. Each is a SKILL.md that Claude Code and Codex load on demand. The paired recipe under recipes/<skill>/ symlinks it into ~/.claude/skills and ~/.agents/skills when the fleet applies recipes, so a provisioned machine has it in every session. Invoke one explicitly with /<skill-name>, or let the agent load it when the task matches the skill's description.

Prerequisites: golang-pro, golang-style, handoff, loom, and upgrade-note need nothing beyond the checkout. The other five need their backing MCP or service registered: that wiring is machine-private and lives in the consuming repo alongside the recipe (see docs/adr/0006), not here. Without the backing MCP the skill still loads, but its tool-backed steps are unavailable.

Release process

Full reference: docs/RELEASING.md. The short version for working here:

• release-please (manifest mode) runs on merge to main, keyed by the packages map in release-please-config.json. Conventional commits scoped by path drive per-component bumps. Merging a release PR cuts the name/vX.Y.Z tag + GitHub Release. The artifacts matrix builds darwin/arm64 tarballs with checksums.txt + cosign keyless bundle, natively on a macOS arm64 runner. csl builds with cgo for its tree-sitter grammars; everything else stays CGO_ENABLED=0.
• Release PRs merge themselves: release.yml turns on auto-merge, so one lands once its required checks pass, and merge = release. Never hand-edit .release-please-manifest.json.
• Merge with squash. A PR whose commits bump different components by different types lands with a rebase merge, so release-please reads each commit with its own files; merge commits are off.
• The workflow authenticates with a token minted from the mad01-release-please GitHub App (secrets RELEASE_APP_ID and RELEASE_APP_PRIVATE_KEY, via actions/create-github-app-token). "Error adding to tree" or a missing release PR usually means the App lost Contents or Pull requests write access on this repo. Or the private-key secret no longer matches the App.
• New component → must be added to release-please-config.json and to llms.txt; CI fails the PR otherwise.

Shipping a change to machines

Two delivery paths, independent of each other:

• Fleet (ralph): consuming machines point a [[recipe_sources]] stanza at this repo (ref = "main", update = true), so recipes merge as thismoon/<recipe> and every ralph up pulls main, rebuilds from source, and restarts services via t-man. Merging to main IS the deploy; no release tag needed. After merging recipe changes, verify with the service's /version — ralph can report ok while an old binary keeps running.
• Artifacts (releases): the per-component tags/tarballs above serve go install and manual downloads; the fleet does not consume them.
• Changes that need an action on consuming machines (a migration, a re-import, a new hook entry in the consuming repo's settings template, an ordered ralph up) ship with three things in the same PR. An entry in docs/UPGRADING.md, newest first, in the form that page describes: a dated heading, then Change, Run, Verify and Since. Run gets a "With ralph:" and a "Without ralph:" part when the steps differ. Since reads unreleased at merge, or main only when no component release carries the change. The upgrade-note skill walks through it, and go test ./kit/upgradenotes/ checks the form in CI. The same steps in the PR body. A doctor check when the missing action is detectable. The fleet pulls main without reading release notes, so a CHANGELOG line alone reaches nobody.

Machine-private wiring (which .this hosts exist, MCP registration, env/secrets, config overlays) lives in the consuming repo as companion recipes layered over these — never add it here (docs/adr/0006).

Importing a service from another repo

The migration playbook, applied to every service brought in so far. Follow it in order; each step earned its place:

1. Import clean. git archive HEAD:<svc> from the source repo, extract into services/<svc> (or tools/<name>). No git history comes along; the import commit message records the source repo and SHA.
2. Fold into the module. Delete the imported go.mod/go.sum, rewrite module paths to github.com/mad01/thismoon/..., switch webkit imports to the in-module package.
3. Drop webkit versioning. Delete webkit_version.go, remove the webkit field from /version, delete the update-webkit Makefile target — there is no pin here, the service compiles against the webkit committed beside it.
4. Rewrite docs. service-info.yaml gets spec.system: thismoon. Strip pin/bump language from the service CLAUDE.md; scan for names and hosts that must not appear in a public repo (help text and code comments too, not just docs).
5. Gates. Root go mod tidy, then per-service build/vet/test/lint, root make test, and a clean-checkout gate: git archive HEAD | tar -x into a temp dir, build and test there.
6. Register for release. Add the component to the packages map in release-please-config.json — CI fails the PR if a Makefile-bearing component is missing from it. Add its line to llms.txt and its row to the README table in the same commit; CI checks llms.txt too.
7. Recipe beside the service. recipes/<svc>/recipe.toml with a sources-cache working_dir (see Conventions). Then the scratch-config ralph up --dry-run gate: commit first, move the real sources cache aside, remove the test cache between runs, and put a config.local.toml with the right profiles beside the scratch config.
8. Two commits per service: one for the import, one for the recipe.

Cutover happens in the consuming repo (dotfiles): delete the old source dir + recipe in one PR, keep item keys identical so ralph state carries over. Then a single ralph up swaps the fleet. After it, pull the sources cache manually if the recipes are newly merged, and verify each service's /version — ralph can report ok while leaving the old binary in place.

Domain language

See CONTEXT-MAP.md for the glossaries: the root CONTEXT.md holds the repo-wide terms, and a service or skill keeps its own terms in a CONTEXT.md beside it. Check docs/adr/ before changing anything structural: the founding decisions are recorded there and are deliberate.