claude-sonar: Instructions file for Claude Code

CLAUDE.md — Instructions for AI agents working on claude-sonar

This file tells Claude Code (and any AI coding agent) how to work on this project effectively. If you are a blind or low-vision developer using Claude Code to contribute to claude-sonar, this file is written with you in mind.

What This Project Is

claude-sonar is a screen reader accessibility plugin for Claude Code. It intercepts tool output via hooks and reformats it into concise, spoken-friendly summaries. The people who use this project may not be able to see your code changes — they will hear them through a screen reader or TTS engine. Keep that in mind with every line you write.

Project Status

This project was released as a seed for the community. The scaffolding, architecture, and test suite are solid (545 tests, 42 test files), but there may be bugs in edge cases, especially around screen reader output quality. If you are fixing a bug, add a test for it. If you are improving spoken output, test it with a screen reader if you can.

Build and Test

npm run build        # Build with tsup (dual ESM/CJS)
npm test             # Run all tests (vitest)
npm run test:coverage # Tests with V8 coverage
npm run lint         # ESLint
npm run typecheck    # tsc --noEmit

Always run npm test after changes. All 545+ tests should pass. Do not skip this.

Architecture — The Short Version

The core is a pure pipeline with no I/O:

stdin JSON -> parseHookEvent() -> formatToolUse() -> classifySignificance() -> applySignificance() -> buildHookOutput() -> stdout JSON

The CLI layer (src/cli/) is a thin wrapper that handles stdin, stdout, TTS, and earcons. The pipeline (src/core/pipeline.ts) is a pure function: string in, structured result out. This separation is what makes the project testable.

Key Source Locations

Directory	What It Contains
src/core/pipeline.ts	Main entry point. Routes hook events to handlers. Start here.
src/core/types.ts	All hook event type definitions
src/core/significance.ts	Classifies events as noise, routine, notable, or important
src/core/apply-significance.ts	Adjusts output based on significance level
src/core/digest.ts	Accumulates events for end-of-turn summary
src/core/progress.ts	Tracks tool elapsed time
src/core/history.ts	JSONL event log per session
src/core/code-summarizer.ts	Extracts function, class, and interface declarations from code
src/formatters/	One file per tool (bash.ts, edit.ts, read.ts, etc.)
src/formatters/index.ts	Formatter registry with conflict detection
src/formatters/types.ts	FormattedOutput (contextText + ttsText), Formatter interface
src/config/types.ts	All config interfaces (SonarConfig and sub-interfaces)
src/config/defaults.ts	Default config values
src/earcon/sounds.ts	Earcon IDs and OS sound mappings
src/settings/index.ts	Claude Code settings.json hook management
src/cli/index.ts	CLI entry point (all commands registered here)
src/output/index.ts	Builds the final HookJsonOutput JSON for stdout