how to contribute patterns and conventions

Patterns and conventions

The repo-wide rules live in AGENTS.md at the repository root; read it before contributing. This page summarizes the patterns that shape code across packages, plus the rules that are easy to trip over.

Code style

• TypeScript ESM throughout ("type": "module"), strict typing, no any unless absolutely necessary.
• Never use inline imports: no await import("./foo.js"), no import("pkg").Type in type positions, no dynamic imports for types. Always standard top-level imports.
• Biome (biome.json) formats and lints; npm run check runs biome check --write --error-on-warnings ., then tsgo --noEmit (the TypeScript native-preview compiler), then installer, browser-smoke, rendering, and web checks. It does not run tests.
• Comments are for serious ambiguity only; don't pad code with commentary.
• Do not hardcode keybinding checks (matchesKey(keyData, "ctrl+x")); all keybindings must be configurable, with defaults added to DEFAULT_EDITOR_KEYBINDINGS or DEFAULT_APP_KEYBINDINGS.
• Never modify packages/ai/src/models.generated.ts directly; update packages/ai/scripts/generate-models.ts and regenerate.
• Never remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead. Dependency updates are subject to a 7-day minimum release age (.npmrc min-release-age=7); override only for urgent security patches with npm install --min-release-age=0 <pkg>.
• Never run npm run dev, npm run build, or npm test at the repo root as a validation step; use npm run check and run specific tests from the package root via npx tsx ../../node_modules/vitest/dist/cli.js --run test/<file>.test.ts.

Repository layout rules

• Root is the npm workspace (packages/*); web/ is a separate pnpm workspace. Never npm install inside web/, and never pnpm install at the repo root.
• web/server links @earendil-works/* with pnpm link: (not file:) so nested agent deps resolve through the root npm tree. Do not add packages/{ai,agent,tui,coding-agent} to web/pnpm-workspace.yaml.
• Browser code (web/app/src, web/design) talks HTTP only: NDJSON + SSE. Never import @earendil-works/* from there. web/server is the only web package that imports the agent packages.
• When a change in packages/coding-agent touches the public surface the adapter consumes (createAgentSession, AgentSessionEvent, ExtensionUIContext, IpythonKernelProvisioner, SessionManager), update web/server in the same change. Do not add web-specific exports to coding-agent.
• The web contract lives in web/protocol/src/chat-protocol.ts; schemas are zod in chat-protocol.zod.ts.

The connection seam

CONTEXT.md defines the agent language: clients interact through AgentConnection (with its extensions sub-interface), SessionView, afterReplace/ReplacedClientContext, and seedMessages. Avoid SessionManager (implementation), Session, Host, and the retired InteractiveModeLocalSessionHost. Process-local members (extension callbacks, getAbortSignal, getReadonlySessionManager, getSystemPromptSync, setup, withSession) must not be invented on the wire; daemon adapters throw AgentConnectionUnsupportedError.

Daemon protocol changes

Classify every daemon command, event, and response-shape change as backward-compatible, capability-gated, or incompatible:

• Optional features go behind a negotiated server capability; clients must check the capability before sending the command or depending on the event.
• Bump DAEMON_PROTOCOL_VERSION (packages/coding-agent/src/modes/daemon/daemon-protocol.ts) for incompatible changes or when startup begins requiring behavior an older daemon cannot provide.
• Update DAEMON_SCHEMA_REVISION, the command/event compatibility maps, and both new-client/old-daemon and old-client/new-daemon tests for every wire change.
• Optional daemon metadata and UI features must degrade locally; they must not prevent the agent, session attachment, or interactive startup from working.
• Never make a new daemon command part of startup without a protocol or capability gate.

Testing

• Vitest per package; run tests from the package root, not the repo root.
• For packages/coding-agent/test/suite/, use test/suite/harness.ts plus the faux provider. Do not use real provider APIs, real API keys, or paid tokens.
• Put issue-specific regressions under packages/coding-agent/test/suite/regressions/ named <issue-number>-<short-slug>.test.ts.
• If you create or modify a test file, you must run that file and iterate until it passes.
• Web tests run under web/ with vitest (pnpm --dir web test) and Playwright for e2e (test:e2e in web/app).

Changelogs and releases

• Each package has its own CHANGELOG.md; new entries always go under ## [Unreleased] as flat past-tense bullets, one line each. Never modify released version sections.
• Internal fixes cite the issue (Fixed foo bar ([#123](https://github.com/PrimeIntellect-ai/prime-agent/issues/123))); external contributions cite PR and author.
• Lockstep versioning: all packages share the same version. npm run release:patch for fixes and additions, npm run release:minor for API breaking changes. No major releases.

Git rules for parallel agents

Multiple agents may work in the same worktree. Only commit files you changed in this session; always git add <specific-file-paths>, never git add -A or git add .. Forbidden: git reset --hard, git checkout ., git clean -fd, git stash, git commit --no-verify. Push with git pull --rebase && git push; resolve conflicts only in your own files, and never force push. Include fixes #<number> or closes #<number> in commit messages when a related issue exists.

Related pages

• Development workflow, the branch-to-merge cycle
• Testing, frameworks and how to run them
• Daemon protocol, the wire contract in detail
• Design decisions, rationale behind the seam and the fork