From f3bfa1fff8f870518dc42f5e8048bd6efe344e20 Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Tue, 21 Jul 2026 18:57:28 -0500 Subject: [PATCH] docs: add connect-a-harness guide (guides checkpoint 3) Second catalog entry: choose, install, authenticate, and verify a harness (Codex, Claude Code, Coven Code, Copilot), then run it through Coven. Install hints and unavailable-harness behavior verified against coven-cli harness.rs built-ins and selected_available_harness. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- content/docs/guides/connect-a-harness.mdx | 106 ++++++++++++++++++++++ content/docs/guides/index.mdx | 2 +- content/docs/guides/meta.json | 2 +- scripts/check-guides-docs.mjs | 10 +- 4 files changed, 117 insertions(+), 3 deletions(-) create mode 100644 content/docs/guides/connect-a-harness.mdx diff --git a/content/docs/guides/connect-a-harness.mdx b/content/docs/guides/connect-a-harness.mdx new file mode 100644 index 0000000..d44f936 --- /dev/null +++ b/content/docs/guides/connect-a-harness.mdx @@ -0,0 +1,106 @@ +--- +title: "Connect a Harness" +summary: "Install, authenticate, and verify a coding-agent CLI — Codex, Claude Code, Coven Code, or Copilot — so Coven can supervise it." +description: "Step-by-step guide to connecting a harness to Coven: choose one, install its CLI, authenticate with the provider, verify with doctor, and run it." +read_when: + - coven doctor reports a harness as missing + - You want to add a second harness or switch providers +--- + +Coven launches and supervises external coding-agent CLIs called [harnesses](/docs/harnesses). This guide connects one: install its CLI, authenticate it with its provider, and verify Coven can launch it. + +## Prerequisites + +- The Coven CLI installed and passing its store checks — see [Install and first run](/docs/guides/install-and-first-run). +- An account with the provider of the harness you choose (OpenAI, Anthropic, or GitHub). Coven Code needs no separate CLI account setup beyond its engine auth. +- npm (or Homebrew on macOS) to install the harness CLI. + +## Step 1 — Choose a harness + +The four built-in harness ids: + +| Harness | Harness id | Provider account | +| --- | --- | --- | +| Codex | `codex` | OpenAI | +| Claude Code | `claude` | Anthropic | +| Coven Code | `coven-code` | Connected engine providers | +| Copilot CLI | `copilot` | GitHub | + +External adapters (like `grok` or `hermes`) can register more via `coven adapter install` — see [Custom adapters](/docs/harnesses/custom-adapters). The rest of this guide uses Codex; every step maps one-to-one to the other harnesses. + +## Step 2 — Install the harness CLI + +```bash +npm install -g @openai/codex +``` + +The equivalents for the other harnesses: + +```bash +npm install -g @anthropic-ai/claude-code # Claude Code +npm install -g @github/copilot # Copilot CLI +coven engine install # Coven Code +``` + +On macOS, Codex and Copilot are also on Homebrew: `brew install --cask codex` and `brew install --cask copilot-cli`. Details per harness live in [Installing harness CLIs](/docs/harnesses/installing). + +**Expected output:** the package installs without errors and the executable is on `PATH` — `which codex` prints a path. + +## Step 3 — Authenticate with the provider + +Each harness owns its provider credentials; Coven never reads them ([Provider auth](/docs/harnesses/provider-auth)): + +```bash +codex login +``` + +The equivalents: + +```bash +claude doctor # Claude Code: finishes local auth/setup +copilot login # Copilot CLI +``` + +**Expected output:** the harness CLI confirms you are logged in. Run the harness once on its own (for example plain `codex`) if you want to confirm it works before Coven supervises it. + +## Step 4 — Verify with doctor + +```bash +coven doctor +``` + +**Expected output:** the harness line flips from missing to ready: + +```text +Harnesses: + [OK] Codex `codex` is ready (built-in) +``` + +If it still shows `[!!] … missing`, open a new terminal so `PATH` changes apply, then rerun `coven doctor`. Doctor's install hint under the failing line tells you the exact missing step. + +## Step 5 — Run it through Coven + +From a project directory: + +```bash +coven run codex "explain this repo in 5 bullets" +``` + +**Expected output:** the `Coven session created` banner with `harness: codex`, then the live harness session. Selecting an unavailable harness fails fast instead: Coven reports that the harness is not available and repeats the same install hint doctor shows. + +Repeat this guide any time you add another harness — sessions from every harness land in the same recorded list under `coven sessions`. + +## Troubleshooting + +- **Doctor still reports the harness missing** — `PATH` is stale or the executable landed outside your shell profile's `PATH`; see [Harness missing](/docs/reference/troubleshooting#harness-missing). +- **The harness launches but immediately exits with an auth error** — rerun the provider login step (`codex login`, `copilot login`) or `claude doctor`; see [Provider auth](/docs/harnesses/provider-auth). +- **`coven run` fails with `pty_spawn_failed`** — the executable disappeared between doctor and run; see the [error code lookup](/docs/reference/troubleshooting#error-code-lookup). +- **You want a harness that is not built in** — follow [Custom adapters](/docs/harnesses/custom-adapters). +- **Anything else** — [Harness troubleshooting](/docs/harnesses/troubleshooting). + +## Related + +- [What is a harness?](/docs/harnesses/what-is-a-harness) +- [Installing harness CLIs](/docs/harnesses/installing) +- [Run reference](/docs/cli/run) +- [Install and first run](/docs/guides/install-and-first-run) diff --git a/content/docs/guides/index.mdx b/content/docs/guides/index.mdx index 0c87e7c..60e2e84 100644 --- a/content/docs/guides/index.mdx +++ b/content/docs/guides/index.mdx @@ -33,7 +33,7 @@ The catalog is being built out one guide at a time, prioritized by the questions | Guide | Question it answers | | --- | --- | | [Install and first run](/docs/guides/install-and-first-run) | How do I go from nothing to my first supervised session? | -| Connect a harness | How do I run Codex, Claude Code, or Copilot through Coven? | +| [Connect a harness](/docs/guides/connect-a-harness) | How do I run Codex, Claude Code, or Copilot through Coven? | | Set up the daemon | How do I start the daemon and confirm it is healthy? | | Set up memory | How do I enable memory and inspect what is stored? | | Fix a failed install | My install broke — how do I diagnose and repair it? | diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json index 6f19b43..90cc93a 100644 --- a/content/docs/guides/meta.json +++ b/content/docs/guides/meta.json @@ -3,5 +3,5 @@ "description": "Step-by-Step How-Tos", "root": true, "icon": "LuCompass", - "pages": ["index", "install-and-first-run"] + "pages": ["index", "install-and-first-run", "connect-a-harness"] } diff --git a/scripts/check-guides-docs.mjs b/scripts/check-guides-docs.mjs index c3ed82b..3baeba2 100644 --- a/scripts/check-guides-docs.mjs +++ b/scripts/check-guides-docs.mjs @@ -5,7 +5,7 @@ const root = process.cwd(); const docsRoot = join(root, 'content', 'docs'); const guidesRoot = join(docsRoot, 'guides'); -const requiredPages = ['index', 'install-and-first-run']; +const requiredPages = ['index', 'install-and-first-run', 'connect-a-harness']; const requiredMentions = [ 'step-by-step', @@ -23,6 +23,10 @@ const requiredMentions = [ 'coven run codex', 'coven sessions --plain', 'Coven session created', + 'coven engine install', + 'coven adapter install', + '@github/copilot', + 'copilot login', ]; function fail(message) { @@ -98,4 +102,8 @@ if (!readFileSync(join(guidesRoot, 'install-and-first-run.mdx'), 'utf8').include fail('install-and-first-run guide must link to the install debugging reference.'); } +if (!readFileSync(join(guidesRoot, 'connect-a-harness.mdx'), 'utf8').includes('/docs/harnesses/provider-auth')) { + fail('connect-a-harness guide must link to the provider auth boundary.'); +} + console.log('Guides docs check passed.');