# CLAUDE.md — cc-agents-md

## Overview
CLI 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.

## Tech Stack
- JavaScript (Node.js, ESM)
- npm package (`cc-agents-md`)
- Claude Code hooks API
- Mocha/Node test runner (testing)
- Codecov (coverage)

## Development
```bash
# Install dependencies
npm install

# Run tests
npm test

# Run benchmarks
node bench/

# Setup (registers hooks in ~/.claude/settings.json)
npx cc-agents-md setup

# Verify installation
npx cc-agents-md doctor
```

## Architecture
- `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.
- `bin/cli.js` — Node CLI entry point. Commands: setup, remove, status, doctor, preview.
- `lib/` — Core modules
  - `config.js` — Configuration management
  - `detect.js` — AGENTS.md file discovery (walks up to git root)
  - `settings.js` — Reads/writes `~/.claude/settings.json`. Merges hooks without clobbering existing ones.
  - `patcher.js` — Hook registration in Claude Code settings
  - `patch-native.js` — Native Claude Code hook patching
  - `patch-bun.js` — Bun runtime compatibility
  - `watch.js` — File change detection for re-injection
- `test/` — Tests using `node:test`. No external test framework.
- `docs/` — Documentation and images

## Key Design Decisions
- **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.
- **Pure bash runtime**: The hook script has zero dependencies on Node.js. It runs in <50ms.
- **Hook-based, not patch-based**: Uses Claude Code's documented `SessionStart` hook API. Survives updates.
- **Idempotent setup**: Running `setup` twice doesn't duplicate hooks.
- **Non-destructive remove**: Only removes our hook entry, preserves everything else in settings.json.

## Key Rules
- Never scan downward from working directory; only walk upward to git root
- Small AGENTS.md files are inlined; large files emit a read instruction instead
- PreCompact hook re-injects content so instructions survive context compression
- UserPromptSubmit hook exits silently (zero overhead) if files have not changed

## Code Style
- Node.js `'use strict'` in all files
- No external runtime dependencies — only Node.js built-ins
- `c8` as the sole dev dependency (coverage)
- Tests use `node:test` and `node:assert`

*Generated by [LynxPrompt](https://lynxprompt.com) CLI*