# Repository Guidelines

Contributor guide for **Harness Mix** — a local kernel that drives native coding harnesses (Codex, Pi, Claude Code, DeepSeek Harness, Antigravity) inside the official Codex Desktop UI, while sessions, model calls, tools, and permissions stay owned by each native program.

## Official Codex is a protected native route

- The default official Codex account and every thread created with it must use Codex Desktop's stock app-server directly, even after another Harness has been used in the same Desktop session. Do not put official Codex thread execution requests, responses, notifications, sessions, models, tools, permissions, or credentials through the Harness Mix Shim, Host, Protocol Core, or Codex adapter. Explicit account-management actions may call the native Codex API, but must not take ownership of official threads.
- Keep the stock Codex CLI as the Desktop app-server executable. Run Harness Mix as a separate, explicitly selected transport for other Harnesses and `Codex（协作）`; never switch the Desktop's global Codex CLI or app-server connection when the selected Harness changes.
- Any UI integration must preserve the official Codex request path and behavior. A failure or restart of Harness Mix must not prevent a new default Codex thread or an existing official Codex thread from working. Do not claim native parity from unit tests alone: verify a restarted Desktop and a sequence that uses another Harness, then creates and resumes an official Codex thread.
- The collaboration CLI (`collaboration-cli.cjs`) and its cwd discovery registry are Harness Mix's own tools and must stay quarantined from official Codex: official Codex threads are never injected with `HARNESS_MIX_*` env vars and never registered in the collaboration registry (`collab-registry/` under the platform data directory). Registry entries hold per-thread keys only; worst-case exposure is impersonating that lead thread's collaboration calls (whitelist, quotas and turn checks still enforced server-side). Never advertise, inject, or auto-run the CLI on official Codex paths.

## Project Structure & Module Organization

- `src/main/native/` — native mode: `launcher.js` (desktop activation, leftover sweep, update flow), `updater.js` + `update-state.js` (dual-channel update: git fast-forward / npm registry, lock, rollback), `host.js` (protocol entry, heartbeat, crash reports), `protocol.js` (app-server projection), `process-utils.js` (process-tree termination), `redact.js` (log redaction), `secure-store.js` (DPAPI vault wrapper), `rs/` (Rust workspace: `harness-mix-shim` protocol bridge + kill-on-close job object, `harness-mix-appx` AppX activation, `harness-mix-secret` DPAPI vault), `icons.js` (icon catalog).
- `src/main/host/` — Host Runtime: `runtime.js` (orchestration/resume/projection), `store.js`, `jsonl.js` (persistence), `usage-history.js` (usage-center aggregation), `health.js` (health-center snapshot).
- `src/main/adapters/` — one plugin per harness (`pi.js`, `omp.js`, `dsh.js`, `claude.js`, `antigravity.js`, `codex.js`, `opencode.js`, `grok.js`; Pi/OMP share `pi-family.js`, OpenCode uses native HTTP/SSE via `opencode-server.js`, Grok independently maps native stdio and `_x.ai/*` extensions), registered in `index.js`. New harnesses follow the manifest/factory/session shape documented in `README.md`.
- `src/native-ui/` — TypeScript sources of the Codex Desktop integration: `renderer-extension/` (injected UI), `desktop-control/` (CDP controller), `shared-contracts/` (shared protocol contracts).
- `src/assets/icons/` — harness and model icons, embedded at build time.
- `scripts/` — verification tooling (`check.cjs`, `build-native.cjs`, `native-*-test.cjs`, `e2e-*.cjs`) and installer packaging under `release/` (`prepare-payload.cjs`, `node-runtime.cjs`, `windows/` Inno Setup setup, `macos/` dmg setup; see `docs/installers.md`).
- `docs/images/` — Codex Desktop native UI screenshots used in the README. `output/` — build and test artifacts; do not commit.

## Build, Test, and Development Commands

- `npm install` — install devDependencies (Electron for native smoke, esbuild).
- `npm start` — launch native mode; restarts Codex Desktop with its stock CLI and a separate Harness Mix Host sidecar.
- `npm run build:native` — rebuild the Renderer extension, Desktop controller and Rust binaries (requires a Rust toolchain) into `output/native-build/`.
- `npm run dist:prepare` / `dist:windows` / `dist:macos` — assemble the installer payload and compile the per-platform double-click installers (see `docs/installers.md`).
- `npm run check` — syntax-check every `.js`/`.cjs` under `src/` and `scripts/`; must pass before submitting.
- `npm run test:core-all` — kernel test suite (contracts, projector, turn manager, adapters, replay, runtime, services).
- `npm run e2e:native` — real Shim + Host protocol check; `npm run e2e:native:pi` / `:dsh` / `:claude` send live turns.
- `npm run e2e:pi` / `npm run e2e:dsh` — end-to-end runs against the real harness through Host Runtime (requires `pi.cmd` or a DSH checkout, overridable via `HARNESS_MIX_DSH_ROOT`).

## Coding Style & Naming Conventions

Plain CommonJS JavaScript — no TypeScript, bundler, or linter is configured, so `node --check` cleanliness (via `npm run check`) is the enforced bar. Match existing style: 2-space indentation, single quotes, `require`/`module.exports`, camelCase functions, PascalCase only for classes. Adapter files are lowercase (`pi.js`); capability flags live in the adapter `manifest`, never as UI-side guesses.

## Testing Guidelines

There is no unit-test framework; verification is layered: `check` (syntax) → `test:core-all` (kernel) → `e2e:native` / `e2e:*` (real harness). Run at least `check` and `test:core-all` for any change; add an `e2e` pass when touching adapter or runtime code. Name new scripts `*.cjs` under `scripts/` and wire them into `package.json`.

## Commit & Pull Request Guidelines

This project has no committed Git history yet — adopt Conventional Commits (`feat:`, `fix:`, `refactor:`) with a scoped summary, e.g. `feat(adapter): add fork capability to pi`. PRs should describe which harness layers are affected (renderer extension / desktop control / runtime / adapter), state honestly-declared capability changes, and attach a smoke-run log or screenshot for UI changes.

## Security & Configuration Tips

Harness Mix never reads or stores credentials — accounts, keys, and permissions belong to the native harnesses. Keep it that way: do not proxy or persist tokens, and do not fabricate permission decisions in adapters; route approvals through `respond()` to the native protocol. The one sanctioned interaction with harness credentials is passive: the ZCode adapter may point the ZCode agent at its own config files and push a key-free provider declaration (`provider/updateAccountConfig` with `access: {type, entitled}` only) so the agent resolves its own shared credentials locally. Never read, log, persist, or transmit credential values, and never inline API keys into adapter pushes or config files.