aesop / bin
CLAUDE.md2 starsChanged 31 days agoMITView on GitHub
Domain: Node.js CLI entry point (bin/cli.js): scaffolds aesop orchestration template, interactive onboarding wizard, runtime subcommand dispatch (doctor/watch/dash/status/fleet/health-score/reproduce/init), and Python tools dispatch table (lint/gate/verify/wave/state/tracker/cost/bench/health/transcript). ## Universal rules (every domain) - Feature branch only, never main; every push gated by python tools/secret_scan.py --staged exit 0. - Tests never pollute cwd or global git config; temp dirs only; dummy secrets are runtime-concatenated, never literal. - In worktrees use ABSOLUTE paths under the worktree for every write. - Domain docs stay minimal-but-complete; update this…
- Installs packages
In this repository21 other files it gives its agents.
- auth/CLAUDE.mdCLAUDE.md
- chat/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- daemons/CLAUDE.mdCLAUDE.md
- dash/CLAUDE.mdCLAUDE.md
- driver/CLAUDE.mdCLAUDE.md
- hooks/CLAUDE.mdCLAUDE.md
- mcp/CLAUDE.mdCLAUDE.md
- monitor/CLAUDE.mdCLAUDE.md
- scan/CLAUDE.mdCLAUDE.md
- skills/CLAUDE.mdCLAUDE.md
- state_store/CLAUDE.mdCLAUDE.md
- stdio/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- tools/CLAUDE.mdCLAUDE.md
- ui/CLAUDE.mdCLAUDE.md
- buildsystemSkill
- dashboardSkill
- fleetSkill
- healthcheckSkill
- powerSkill
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
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 56
All args after verb pass through untouched (flags like --check, --json, --fix preserved)
- Very specific: line 75
All 113 scripts remain in tools/ with exact same names.
- Very specific: line 122
Portable paths: No machine-specific paths.
- Very specific: line 124
Non-destructive: Never overwrites existing aesop.config.json without user confirmation.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 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
bin/ — CLI scaffolder, runtime commands, and Python dispatch table
Domain: Node.js CLI entry point (bin/cli.js): scaffolds aesop orchestration template, interactive onboarding wizard, runtime subcommand dispatch (doctor/watch/dash/status/fleet/health-score/reproduce/init), and Python tools dispatch table (lint/gate/verify/wave/state/tracker/cost/bench/health/transcript).
Universal rules (every domain)
- Feature branch only, never main; every push gated by
python tools/secret_scan.py --stagedexit 0. - Tests never pollute cwd or global git config; temp dirs only; dummy secrets are runtime-concatenated, never literal.
- In worktrees use ABSOLUTE paths under the worktree for every write.
- Domain docs stay minimal-but-complete; update this file in the same PR as code it describes.
Invocation modes
Stdio pipe (aesop pipe [stdio flags], and bare aesop with stdin or stdout not a TTY): runs node stdio/cli.mjs <flags> with stdio: 'inherit', before any scaffolding. Flags such as --input-format/--output-format pass through untouched. Exit code propagates; a signal or spawn failure exits 2. Semantics are in stdio/CLAUDE.md. Without a TTY on stdin or stdout, bare aesop is the pipe and writes exactly one stderr line at entry: aesop: no TTY detected, reading stdin as a pipe; run wizard to scaffold. The decision is detectMode in stdio/tty-decision.js, re-exported by stdio/tty.mjs; bin/cli.js has no other TTY check. Chat (aesop chat, chat/CLAUDE.md): with a TTY on both, bare aesop runs the wizard unless --chat-default or AESOP_DEFAULT=chat opens chat. shouldEnterChat in chat/cli.mjs is the single chat-entry decider; bin/cli.js calls it once, from bareTtyEntry, before the scaffold steps (target dir, template copy) run.
- Auth and model verbs (
auth login|status|logout,model list|use|current) dispatch toauth/cli.mjsbefore scaffolding and never write into cwd;status,listandcurrentprint one JSON line when stdout is not a TTY; exit 0 ok, 2 usage, 3 no credential. Verbs: auth/CLAUDE.md.
Scaffolder (creates new fleet):
- Top-level gate (runs before any filesystem work; the
--controlcheck runs first on every path, namespace and auth/model passthrough included, and the other gates are skipped foraesop <namespace> ...passthrough): a--controlor--control=<x>argument exits 2 with the bare stderr lineCONTROL_CHANNEL_MESSAGEfrom stdio/pipe.mjs (bin/cli.jsdoes not test the flag itself: it sends the whole argv to the auth child viarunAuthChild, andauth/cli.mjsapplieshasControlFlagand prints the line; control records exist only on the stream-json pipe; no scaffold help is printed);--version/-vprint the package.json version and exit 0; any-argument not inDOCUMENTED_FLAGSprintsunknown optionwith no value echoed, plus help to stderr and exits 2;--globalis a documented flag (doctor --globalruns the~/.claude/skillscheck). Tests:tests/cli-version-unknown-flags.test.mjs,tests/doctor-layout-mode.test.mjs. npx @matt82198/aesop→ with a TTY on stdin and stdout, scaffolds to./aesop-fleet(default); without a TTY, bareaesopis the stdio pipe (see Invocation modes)npx @matt82198/aesop my-fleet→ scaffolds to./my-fleetnpx @matt82198/aesop my-fleet --force→ re-scaffold and replace.git/hooks/pre-pushnpx @matt82198/aesop --name "api" --domains "server,worker" --repos "/path/repo"→ headless scaffold (no interactive prompts);--reposentries must each be existing directories (missing/file/URL → bad entries printed, exit 2, before any filesystem work; URLs belong in--repo-urls); summarycp ~/.claude/CLAUDE.mdlines are printed text only, each after a backup step. Scaffolds skiphooks/**/*.test.mjs(isShippedHookTestEntryincli.js) so an adopter's coverage gate sees no orphaned hook tests. Scaffolds also skipdocs/MACHINERY-MAP.md(isAesopOnlyDocEntryincli.js, exact filename, docs/ copy only): the map cites aesop-only targets (ci.yml, verify-receipt.yml, bin/cli.js, STATE.md) a scaffold never ships, socheck_machinery_map_symbolswould fail in every adopter tree. Test:tests/scaffold-no-machinery-map.test.mjs. Scaffolds also skip ignored artifact directories at any depth (IGNORED_ARTIFACT_NAMESandisIgnoredArtifactEntryincli.js: node_modules, aesop-fleet, .git, build, coverage, Python test and type caches;distexcluded because trackedui/web/distis served). Tests:tests/cli-config.test.mjs,tests/scaffold-ignores-artifacts.test.mjs.
Wizard (guided setup, ~60 sec):
npx @matt82198/aesop wizard→ prompts: project name (default: "my-fleet"), repos (auto-discover from~), port (default: 8770, validates 1–65535), brain root (default:~/.claude) -npx @matt82198/aesop wizard --yes→ uses all defaults, no prompts (CI-safe); non-TTY input auto-skips prompts
Bare-TTY chat error path (bin/cli.js onOk boundary, ~lines 245-249): a synchronous throw from shouldEnterChat or startScaffold is caught, printed as one Error: stderr line with no stack trace, and exits 2.
Runtime commands (after scaffolding; dispatch pattern in cli.js). doctor, watch, dash, status, fleet, health, health-score, reproduce, init and runner (install|remove) are dispatched from cli.js. Every one of them except health prints a per-subcommand usage block on --help|-h (SUBCOMMAND_HELP in cli.js) and exits 0 before any side effect (no scaffolding, no readiness run, no dashboard launch). health is a Python namespace (pythonNamespaces), so health --help|-h prints the namespace usage and verb list instead (exit 0, before dispatch). Tests: tests/cli-subcommand-help.test.mjs (init, doctor), tests/cli-runtime-help.test.mjs (the rest).
const runtimeCommands = ['doctor', 'watch', 'dash', 'status', 'fleet', 'health', 'health-score', 'reproduce', 'init', 'runner'];
// 'init' dispatches to Python: spawnSync('python3', ['tools/init_project.py', '--dir', '.', ...])
// All others load+run a Node module:
const commandMap = {
'doctor': '../tools/doctor.js', // Preflight check (Node, Python, git, config, dirs, hooks, port)
'watch': '../tools/watch.js', // Launch daemon; spawns daemons/run-watchdog.sh
'dash': '../tools/dash.js', // Launch web dashboard; spawns python3 ui/serve.py (default localhost:8770)
'status': '../tools/status.js', // One-shot snapshot (heartbeats, port, git branch)
'fleet': '../tools/fleet.js', // One-shot JSON snapshot (agents, heartbeats, tracker, orchestrator; Node STDLIB only, graceful degrade)
'health': '../tools/health.js' // Fleet health aggregator (heartbeats, alerts, orchestrator, tracker; Python wrapper)
};
require(commandMap[args[0]]); // Load + run; returns immediately afterInit command (npx @matt82198/aesop init):
- Scaffolds aesop orchestration into the CURRENT directory (not a new fleet dir)
- Creates: CLAUDE.md, domain CLAUDE.md for first code dir, aesop.config.json, state/.gitkeep, .github/workflows/ci.yml, pre-push hook
- Flags:
--name <name>(project name, auto-detected from git remote),--force(overwrite existing files),--ci-mode hosted|self-hosted-runner|local-receipt-gate+--self-hosted-labels L1,L2(CI workflow template from templates/ci/ and theciblock of aesop.config.json; see docs/CI-MODES.md) - Delegates to
tools/init_project.pyvia spawnSync (python3 with python fallback) - Non-destructive by default: an existing
CLAUDE.mdoraesop.config.jsonis kept and a- Kept existing ...line is printed;--forceoverwrites them. Tests:tests/test_init_project.py.
CI-modes surface (docs/CI-MODES.md): doctor [--json] appends a REPORT-ONLY "CI capability" table (mode -> runnable here, from tools/ci_capability.py; never fails the doctor) and validates the config ci block via tools/ci_config.js (Node mirror of tools/common.py validate_ci_config); runner install|remove [...] dispatches to tools/runner_install.py through the fail-closed propagator (preflight refuses on Smart App Control / UMCI boxes and on public repos without all_external_contributors fork approval; --dry-run plans only). Tests: tests/ci-modes.test.mjs.
Python dispatch table (aesop <namespace> <verb> [args...]):
- Routes to 113
tools/*.pyscripts via namespace+verb lookup table (Phase 2: additive, no script moves or renames) - Interpreter resolution: tries
python3thenpython; verifies interpreter is executable; exits 2 if not found - Exit codes propagated unchanged: 0 (success), 1 (findings/failure), 2 (usage/could-not-evaluate)
- Fail-closed propagator: all spawnSync dispatches (namespaces +
initand its python fallback) route throughexitCodeFromSpawnResult(result)— numericstatusverbatim, butresult.erroror a non-numericstatus(null = signal-killed, undefined = unknown) exits 2. Neverresult.status || 0: null collapses to 0, so a SIGTERM/SIGKILL/CI-cancelledaesop gate secret-scanreported a passing gate. Requiringbin/cli.jsas a module (require.main !== module) exports the helper instead of running the CLI. - All args after verb pass through untouched (flags like
--check,--json,--fixpreserved) aesop <namespace> --helplists that namespace's verbs and their underlying script paths
Namespaces and verbs (via pythonNamespaces table in cli.js):
aesop lint encoding|claudemd|commit|deadcode|docstring|filesize|imports|todos|bash
aesop gate secret-scan|dispatch|spec-contract|portability|stateapi|subprocess|watcher|metrics
aesop verify dashboard|activity-filter|cost-panel|dispatch-panel|failure-drilldown|prboard|scorecards|submit-encoding|wave-telemetry|test-coverage|counts
aesop wave preflight|manifest-lint|template|scorecard|resume
aesop state query|rebuild|verify|ensure
aesop tracker autoclose|guard|reconcile
aesop cost ceiling|projection|forecast|econ
aesop bench run|results
aesop health check|score|incidents|stall
aesop transcript timeline|replay|digestHook/CI integration (unchanged):
hooks/pre-push-policy.shand.github/workflows/*.ymlinvoke scripts by absolute path; CLI is parallel, optional front door only- All 113 scripts remain in
tools/with exact same names; no moves, renames, or relocations - Direct script invocation works exactly as before; CLI dispatch is additive
Scaffold files (filesToCopy array in cli.js lines 243–260)
Directories copied (recursive):
daemons/, dash/, monitor/, tools/, ui/, docs/, state_store/, skills/, mcp/, scan/, hooks/, driver/
Files copied:
aesop.config.example.json, README.md, LICENSE, CHANGELOG.md, CLAUDE-TEMPLATE.md, requirements.txt, requirements-dev.txt
NOT copied:
aesop.config.json (user must cp aesop.config.example.json and edit), state/ (runtime durable state, git-ignored), .git/, node_modules/, build artifacts, Python bytecode (__pycache__/ dirs and *.pyc files). copyRecursive filters these by name before statSync, so a .pyc written or deleted by a concurrent process mid-copy cannot raise ENOENT. Test: tests/cli-doctor-defects.test.mjs "DEFECT 6b".
npm package.json files array (lines 9–36): If adding new dirs/files to filesToCopy, add to files array so npm publish includes them.
Skill + dependency installation
Scaffolding installs skills itself; it does not print instructions and hope.
Claude Code only discovers skills under ~/.claude/skills/ (or a project's
.claude/skills/), so a skill left in the scaffolded ./skills/ is
undiscoverable and the orchestrator cannot be invoked.
installSkills(targetDir, {force, skip})— copies eachskills/*/into the skills home. Idempotent: a skill whoseSKILL.mdmatches byte-for-byte is reported as already-installed; one that DIFFERS is preserved and warned about (stderr), never silently overwritten.--forceoverwrites;--no-skillsskips. Refuses to follow a symlinked skills home (same guard as the pre-push install).AESOP_SKILLS_HOME— redirects the install target. Tests MUST set it; writing to the real~/.claudeviolates the no-global-state test rule.installDependencies(targetDir, {enabled})—--install-depsonly, so scaffolding stays offline-safe. Runsnpm installwhen the target has apackage.jsonandpip install -r requirements.txtwhen it has one; both degrade to a warning on failure rather than aborting the scaffold.
Worktree support (git worktree .git files)
- Worktree .git handling: In git worktrees,
.gitis a FILE (not directory) containinggitdir: <path>. - Real git dir resolution:
resolveRealGitDir()detects worktree.gitfiles and usesgit rev-parse --git-common-dirto find the actual git directory. Fallback: parse gitdir pointer manually from.gitfile. - Hook installation paths:
installPrePushHook()andinstallPreCommitWaveguard()use resolved git dir to install hooks in the common git directory (not worktree), preventing ENOTDIR crashes.installPreCommitWaveguard()'s wrapper also chainshooks/pre-commit-dispatch-lint.shafter the waveguard step (fail-closed dispatch gate; skipped only if the hook file is absent). - Security: symlink checks on
.gitand hooks directories preserved throughout resolution.
Invariants
- Idempotent on empty targets: Fails if
targetDirexists and is non-empty (except.git, aesop scaffolded dirs). Safe to retry. - Skill install never clobbers: a divergent installed skill survives scaffold unless
--force. - Push-gate artifacts are generated, not shipped: after git init, the scaffold runs the repo's own regenerate commands (
PUSH_GATE_ARTIFACTSin cli.js) fortools/INDEX.mdand.pyflakes-baseline.json,.subprocess-guard-baseline.json,.portability-baseline.json,.stateapi-baseline.json, one line each. They are left for the adopter's first commit; a failure prints a WARN with the regenerate command, and the hook anddoctorfail closed until it is fixed. The generators run concurrently;AESOP_SKIP_PUSH_GATE_ARTIFACTS=1skips them (used only by tests that never push). Timing is printed to stdout so a CI deadline red carries durations:[push-gate] starting <n> generators, then one[push-gate] <script> ok|FAILED in <ms> msper generator as it finishes, then[push-gate] all <n> generators done in <ms> ms(CI-A1; test:tests/push-gate-generator-timing.test.mjs). - Symlink guard: Rejects symlinks in target dir (lstat check, not stat); prevents escaping targetDir during copy.
- Portable paths: No machine-specific paths;
path.join()+__dirnamehandle cross-platform resolution. Config uses~form (~/.claude,~/scripts) expanded at load time. - Async wizard: Main execution is async IIFE to support readline prompts.
- Non-destructive: Never overwrites existing
aesop.config.jsonwithout user confirmation. - Worktree-safe: Scaffolding works correctly when cwd is a git worktree (absolute paths + resolved git dirs).
Test commands
Node.js tests (npm run test:node):
npm run test:node→node --test --test-timeout=60000 tests/*.test.mjs- Fleet CLI tests:
tests/fleet-cli.test.mjs— spawns CLI in temp fixture, verifies JSON shape (heartbeats, agents, tracker, orchestrator), graceful degrade, exit 0, no cwd pollution - CLI config tests:
tests/cli-config.test.mjs— scaffold flags (--name, --domains, --repos, --repo-urls), fleet_root auto-set to os.homedir(), config validation, repo URL generation - CLI dispatch tests:
tests/cli-dispatch.test.mjs— Python namespace dispatch routing, verb help, exit code fidelity (0/1/2), fail-closed propagator (signal-kill / null status / spawn error → 2, cross-checked against a real self-SIGTERM child on POSIX), interpreter resolution, unknown namespace/verb errors, arg passthrough - Skill install tests:
tests/cli-skills-install.test.mjs— skills land in the skills home,--no-skillsopts out, re-scaffold is idempotent, a modified skill survives without--forceand is replaced with it, dependency manifests ship, real~/.claudeuntouched (all viaAESOP_SKILLS_HOME)
First-hour test suite (inline in test files above):
- Empty state directory graceful degrade (no state files)
- Present heartbeat files parsed correctly
- Invalid/malformed JSON degrades gracefully
- Process timeouts handled (10s max per invocation)
- Python dispatch: verifies script paths exist, interpreter found, exit codes propagate, --help works per namespace
Shell integration (npm run test:sh): Pre-push hook tests + watchdog tests (separate domains, see hooks/ and daemons/)
Dropped (reason)
- Post-scaffold user guidance steps (belongs in README/CLAUDE-TEMPLATE.md output, not scaffolder contract)
- Repo discovery implementation details (discoverRepos function is simple, documented inline in code)
- Port validation logic (validatePort function documented inline; accepts 1–65535)
Map of all domains: /CLAUDE.md
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.

