---
name: integrate-harness
description: Use when adding a new agent harness (CLI-based coding agent) adapter to adapters. Covers capability audit, adapter scaffold, session parsing, auth detection, hooks/plugins wiring, tests, and docs.
---

# integrate-harness

Goal: produce a production-quality `XAdapter extends BaseAgentAdapter` with full test coverage and documentation, matching the level of the existing 11 adapters (claude, codex, cursor, gemini, opencode, openclaw, copilot, hermes, pi, omp, adapters-remote).

## Checklist

1. **Capability audit** — read the harness's CLI docs. Fill in every `AgentCapabilities` field. Unknown? Set conservatively (`false`) and note in PR.
2. **Create `packages/adapters/src/<name>-adapter.ts`** extending `BaseAgentAdapter`. Required: `agent`, `displayName`, `cliCommand`, `minVersion`, `hostEnvSignals`, `capabilities`, `models[]`, `defaultModelId`, `configSchema`, `buildSpawnArgs`, `parseEvent`, `detectAuth`, `getAuthGuidance`, `sessionDir`, `parseSessionFile`, `listSessionFiles`, `readConfig`, `writeConfig`.
3. **Session parsing** — if the harness stores JSONL sessions, delegate to `parseJsonlSessionFile`; otherwise write a custom parser and unit-test each event shape.
4. **Hooks** — if the harness supports native hooks, override `writeNativeHook` and mirror into `HookConfigManager`. If not, rely on the base class's virtual hooks.
5. **Plugins** — if it supports MCP servers under `mcpServers` in its config JSON, flip `supportsPlugins: true`, add `pluginFormats: ['mcp-server']`, and delegate to `mcp-plugins.ts` (see cursor/gemini/opencode/openclaw for the pattern).
6. **Register** — add to `packages/adapters/src/index.ts` exports and to the default registry in `packages/core/src/client.ts` (if applicable).
7. **Tests** — in `packages/adapters/tests/<name>-adapter.test.ts`:
   - capability shape
   - `buildSpawnArgs` for a few representative `RunOptions`
   - `parseEvent` for each JSONL type the harness emits
   - `detectAuth` for authenticated + unauthenticated states
   - session file parsing from a real fixture (redacted)
   - If plugins: add the adapter to `mcp-plugins-parity.test.ts`.
8. **CLI audit test** — ensure `packages/cli/tests/commands-audit.test.ts` passes (it exercises every adapter via the built CLI).
9. **File-size limit** — each source file must stay under 400 effective lines (`local/max-file-lines`). Split helpers into sibling modules if you're close.
10. **Docs** — add a row to the README capabilities matrix and a paragraph in `docs/02-agents/<name>.md`.
11. **Changeset** — `npm run changeset`, pick `minor` (new adapter), summarize.

## Verification

```bash
npm run typecheck
npm run lint
npm test
npx vitest run packages/adapters/tests/<name>-adapter.test.ts
```

All existing tests must continue to pass — no regressions in commands-audit.

## Common pitfalls

- Forgetting to add the adapter to the default registry → `commands-audit.test.ts` won't exercise it.
- JSONL parsers that assume a single event per line — some harnesses emit arrays.
- Auth detection that reads env vars synchronously at construction time instead of `detectAuth()` — breaks testability.
- `buildSpawnArgs` returning the string `"undefined"` for missing options — always gate with `if (options.X != null)`.
- Hook writers that overwrite rather than merge — use `appendJsonHook` or `appendYamlHook`.