Project

Contributing

Bug reports, fixes, features and docs are all welcome. One change per PR, a sign-off line on every commit, and go test ./... green.

Repository layout

Path	What is in it
`cmd/crv`	The core binary. Tool registration lives here.
`cmd/crvcli`	The one-shot CLI.
`internal/loop`	The agent loop, turn close, resume briefings, the reminder envelope.
`internal/tools`	The registry and all seventeen tools. The largest package.
`internal/api`	HTTP handlers and the SSE stream.
`internal/server`	Server wiring and the embedded panel.
`internal/guard`	The safety guard: `guard.go` for tiers, `hardrules.go` for remediation.
`internal/memory`	Typesense client, curator, recall, indexer.
`internal/window`	The context window manager.
`internal/episodic`	The append-only event log.
`internal/codeintel`	The symbol graph.
`internal/cores`	The Brain Core registry.
`internal/rfx`	Reflex manifests, packs, RFX_UI.
`internal/skills`	Markdown skill loading.
`internal/session`	Session lifecycle.
`internal/llm`	The OpenAI-compatible client.
`internal/config`	Config loading and defaults.
`panel/`	The Svelte 5 panel, embedded into the binary.
`android/`	The Pocket client. Native Java, no Gradle.
`sidecars/`	The ignite doorbell and the embedder.

Build and test

# the panel first — go:embed needs panel/build to exist
cd panel && npm install && npm run build && cd ..

go build -o ~/.local/bin/crv ./cmd/crv
go test ./...

Sign your work

Cerveau uses the Developer Certificate of Origin rather than a CLA. One line, no signup, no paperwork: signing off certifies that you wrote the change, or otherwise have the right to submit it under Apache-2.0.

git commit -s -m "fix: whatever you fixed"

That adds Signed-off-by: Your Name <you@example.com>. PRs with unsigned commits will be asked to git rebase --signoff before merge.

Ground rules

One change per PR

Small and reviewable beats big and heroic.

Match the codebase

Go stdlib-first, no framework creep. The panel is Svelte 5 runes plus the in-repo kit — use existing components before adding dependencies.

Tests pass

go test ./... must be green. Bug fixes come with a regression test.

Honest output

Tool feedback, errors and docs never claim more than what actually happened. This is a project principle, not a style preference.

Conventions worth knowing

Comments explain why, not what. The codebase is unusually well commented and the comments carry reasoning — a tuning constant records why it moved, a workaround records what broke without it. Match that.
A mechanism beats an instruction. If a behaviour can be enforced in Go rather than requested in a prompt, enforce it. See Concepts.
Degrade loudly. Every failure path has a defined, visible outcome. Silence is a bug.
Tests encode the reasoning. Several test files open with a paragraph explaining the failure the test exists to prevent. That is deliberate.

These docs

The documentation lives in the website repository under site/docs/, generated from per-page source files by a small Python script. Pages are hand-written against the source: if a page and the code disagree, the code is right and the page is a bug.

Naming and licence

Apache-2.0. "Cerveau" is a project trademark — see NOTICE. Forks are welcome and encouraged under the licence, under a different name.

Security

Do not open a public issue for a vulnerability. SECURITY.md in the repository has the disclosure process. The threat model states plainly what is and is not defended — a report that the guard can be beaten by an obfuscated command is a known limitation rather than a finding.

PreviousPocket (Android)