Development
Read Architecture, then the target directory's README and AGENTS.md. Build from the repository root. Do not initialize new npm packages inside recovered directories or rearrange their layout. For issue ownership, main-based worktrees, PR review, and merge, follow the maintainer workflow.
Find the code for your change
| Change | Start reading | Relevant checks |
|---|---|---|
| Model requests, streaming events, tool results | responses.ts | npm run check:local, npm run test:responses-contract; live API is separate |
| Toolsets or prompts | Harness runner, Agent | npm run build -- --profile local, npm run test:runtime-build, Agent fixture in test guide |
| Host messages and run lifecycle | transcript, turn-execution | npm run build -- --profile local, Gateway smoke; no focused scheduler lane/race test is present |
| Gateway methods and events | Gateway wire, Host | npm run build -- --profile local, npm run test:runtime-build, isolated Gateway smoke |
| Mac permissions and approval | local-tool-permission, auto-review | Review contracts and Mac execution tests |
| MCP/plugin lifecycle | Local adapters | npm run check:local, then matching MCP/plugin contract |
| Electron startup, Keychain, Dock icon | desktop-src | npm run prepare:desktop -- --profile local, npm run test:desktop-keychain; live startup audit when changed |
| UI, settings presentation, CSP | renderer-src | npm run prepare:desktop -- --profile local, then relevant desktop interaction |
| Images, mounts, launch configuration | runtime | npm run test:runtime-build, Compose config with dummy values |
| Recognition or synthesis | speech | Matching npm run test:transcription / npm run test:tts, offline models, desktop audio |
| Bundle reconstruction and mappings | Source recovery | Recovery and runtime-build tests |
| Documentation and Wiki export | Publishing, exporter | docs:check, exporter tests, preview |
| Project maintenance and PR checks | Maintainer workflow, CI | npm run ci:pre-pr locally; CI runs the same selected offline gates |
Edit and rebuild
- Edit maintained source. Preserve original paths and put local behavior behind profile conditions.
- Run strict local TypeScript checks and build.
- Run tests for the affected behavior; prepare again after desktop changes.
- Update user-facing and module documentation, then inspect the diff.
npm run check:local
npm run build -- --profile local
npm run test:runtime-build
git diff --check
For desktop changes, also run npm run prepare:desktop -- --profile local, quit the old desktop, and launch again.
Restart the backend after rebuilding Host code. Environment or mount changes require npm start.
See Packaging for icon and app changes.
Choose tests
The test guide groups commands by dependency and purpose. Contracts verify protocols, boundaries, and errors. Live API/UI tests verify external services and complete flows. A deterministic model fixture can prove tool execution, but not real provider availability.
Run tests sharing a Box or display serially, or give them separate containers and profiles. Tests must clean up only their own resources. Existing evidence and coverage gaps are in Verification.
Scoped guidance coverage
For this repository, a source component is declared by a directory containing a
README and direct implementation files under src/, packages/, dune/,
reconstruction/, runtime/, or tools/. Such directories need their own
AGENTS.md; nested helper folders without a component README inherit the
nearest component's rules. npm run docs:check checks every README-declared
source component for a direct guide, so a new component README without scoped
maintenance instructions fails the check. The walk prunes installed
node_modules, .runtime, and language/tool caches before entering them.
Maintained dist/ source is still checked; the build's generated outputs live
outside the audited source roots. Update the checker's source suffix list if a
new implementation language is introduced. Vendor/release baselines and
documentation/asset-only directories are outside this source-component audit.
Documentation conventions
- English is canonical. Keep translations in separate files such as
README.zh.md, with language navigation. - The project README explains the value, shows real results, and gives a short working quickstart.
- Wiki pages separate tutorials, configuration, architecture, and maintenance. Define settings in one reference.
- Directory READMEs explain responsibilities and entry points; AGENTS.md files define maintenance constraints.
- Use generic domains and paths. Project-default loopback ports and Compose service names are useful operational examples.
- Use isolated tasks for media, disclose time compression, and follow recording notes.
Run npm run docs:check after edits. The Wiki export handles its separate repository and URL conventions;
see Publishing.
Commits and resources
Group changes by outcome. Include the documentation and tests that explain or protect an implementation in its PR; leave unrelated cleanup out.
Preserve upstream metadata, licenses, and provenance hashes. Do not reformat third-party resources.
Do not commit .env, .runtime, dist, node_modules, model keys, Gateway tokens, or user sessions.