CLAUDE.md

1# CLAUDE.md — cc-agents-md
2 
3## Overview
4CLI tool that makes Claude Code automatically load AGENTS.md files into sessions. Registers three hooks (SessionStart, UserPromptSubmit, PreCompact) so AGENTS.md content is injected without needing CLAUDE.md wrapper files or symlinks.
5 
6## Tech Stack
7- JavaScript (Node.js, ESM)
8- npm package (`cc-agents-md`)
9- Claude Code hooks API
10- Mocha/Node test runner (testing)
11- Codecov (coverage)
12 
13## Development
14```bash
15# Install dependencies
16npm install
17 
18# Run tests
19npm test
20 
21# Run benchmarks
22node bench/
23 
24# Setup (registers hooks in ~/.claude/settings.json)
25npx cc-agents-md setup
26 
27# Verify installation
28npx cc-agents-md doctor
29```
30 
31## Architecture
32- `bin/loader.sh` — Bash script invoked by the SessionStart hook. Walks upward from `$CLAUDE_PROJECT_DIR` to git root, collecting AGENTS.md files. Outputs root-first. All errors silenced to never block a session.
33- `bin/cli.js` — Node CLI entry point. Commands: setup, remove, status, doctor, preview.
34- `lib/` — Core modules
35  - `config.js` — Configuration management
36  - `detect.js` — AGENTS.md file discovery (walks up to git root)
37  - `settings.js` — Reads/writes `~/.claude/settings.json`. Merges hooks without clobbering existing ones.
38  - `patcher.js` — Hook registration in Claude Code settings
39  - `patch-native.js` — Native Claude Code hook patching
40  - `patch-bun.js` — Bun runtime compatibility
41  - `watch.js` — File change detection for re-injection
42- `test/` — Tests using `node:test`. No external test framework.
43- `docs/` — Documentation and images
44 
45## Key Design Decisions
46- **Walk upward, not downward**: At session start, you don't know what files will be edited. Walking up from CWD to git root is always correct and always bounded.
47- **Pure bash runtime**: The hook script has zero dependencies on Node.js. It runs in <50ms.
48- **Hook-based, not patch-based**: Uses Claude Code's documented `SessionStart` hook API. Survives updates.
49- **Idempotent setup**: Running `setup` twice doesn't duplicate hooks.
50- **Non-destructive remove**: Only removes our hook entry, preserves everything else in settings.json.
51 
52## Key Rules
53- Never scan downward from working directory; only walk upward to git root
54- Small AGENTS.md files are inlined; large files emit a read instruction instead
55- PreCompact hook re-injects content so instructions survive context compression
56- UserPromptSubmit hook exits silently (zero overhead) if files have not changed
57 
58## Code Style
59- Node.js `'use strict'` in all files
60- No external runtime dependencies — only Node.js built-ins
61- `c8` as the sole dev dependency (coverage)
62- Tests use `node:test` and `node:assert`
63 
64*Generated by [LynxPrompt](https://lynxprompt.com) CLI*
65