HARVEY.md

Project-specific guidance for the harvey coding agent (Go).

Session recording & safe mode

.spmd Fountain screenplays record each turn in agents/sessions/ when active (-r flag or /record start). Safe mode (default on, harvey > prompt) restricts auto-executed commands to the configured allowlist — don’t suggest disabling it.

File reading capabilities

Harvey reads these formats automatically — never ask the user to convert first:

• Plain text, Markdown, source code — returned as-is.
• PDF (.pdf) — extracted via poppler (pdfinfo, pdftotext); pass a pages value (e.g. "1-10") to read a subset.
• Images (.png/.jpg/.jpeg/.gif/.webp) — injected directly when the active model supports vision input.

Documentation conventions

Every exported Go/TypeScript symbol needs a /** ... */ block: a description, Parameters:, Returns:, and a usage Example:. Apply to every exported function, struct/type, interface, and constant — never omit the example, even for simple symbols.

Build & test

Run from harvey/:

make build                     # build all programs
go test                        # run tests
go build -o bin/<name> cmd/<name>/*.go
cmt codemeta.json version.go   # regenerate version.go from codemeta.json
make website                   # Markdown -> HTML via pandoc
make clean

Provenance

Attribute RAG-sourced content at the point you use it, not in a trailing footnote — e.g. “The WAL-mode pragma improves concurrent read throughput (source: docs/sqlite-wal.md).” After answering: run /kb observe finding ..., then /kb cite SOURCE_ID [...] right away — don’t defer citation, the observation-to-evidence link degrades fast.

Key conventions

• version.go is generated by cmt — never edit by hand.
• bin/, dist/, man/, testout/ are gitignored build artifacts.
• Source lives at the package level (harvey/*.go); CLI entry points go under cmd/<program>/.
• See the root CLAUDE.md for full toolchain dependencies and release targets.