Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions content/docs/guide/concepts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ Use **OpenCoven** when talking about the broader project family.

Coven is the local runtime substrate. It owns project-scoped harness sessions, PTYs, logs, local daemon state, and the socket API.

Coven is **not a harness**. Harnesses — Codex, Claude Code, and future adapters — are external coding-agent CLIs that operate *within* Coven's substrate. Coven provides the shared layer they all run on: enforced project boundaries, supervised PTY lifecycle, append-only session records, and a stable local API that any client can talk to regardless of which harness is running.

Use **Coven** for the CLI, daemon, Rust crate, npm wrapper, and local session runtime.

## CovenCLI
Expand Down
13 changes: 11 additions & 2 deletions content/docs/guide/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,20 @@ This guide takes a new user from a fresh checkout or npm install to a visible pr

## What Coven Is

Coven is a local-first runtime for coding-agent harnesses. It runs supported CLIs such as Codex and Claude Code inside explicit project boundaries, records session metadata and events, and exposes the work through a CLI, TUI, and local socket API.
Coven is not a harness. It is the **substrate** that harnesses operate within.

A harness — Codex, Claude Code, or any future adapter — brings its own provider credentials, model selection, and tool runtime. Coven provides the shared layer underneath: enforced project boundaries, supervised PTY processes, an append-only session record, and a stable local API. When work passes through Coven, every run gains consistent lifecycle management, replay, and auditability regardless of which harness ran it.

This matters in practice:

- **Provider independence** — switch between Codex and Claude Code without rewiring your workflow; the substrate stays the same.
- **Enforced boundaries** — harnesses can only operate inside the project root you declared; no harness can silently widen scope.
- **Auditable history** — every session is recorded and replayable; completed work survives process restarts.
- **Unified client surface** — any client (CLI, TUI, CastCodes, OpenClaw, or a script) talks to any harness through one local API.

The short promise:

> One project. Any harness. Visible work.
> One substrate. Any harness. Reproducible, auditable work.

## Install Paths

Expand Down
3 changes: 3 additions & 0 deletions content/docs/harnesses/what-is-a-harness.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,14 @@ summary: "A harness is a PTY-driven adapter for one external coding-agent CLI."
description: "Definition of a Coven harness and the boundary between harnesses, familiars, clients, and the daemon."
read_when:
- You are new to Coven terminology
- You need to explain why a harness is not the same thing as Coven itself
- You need to explain why a harness is not the same thing as a familiar
---

A harness is a coding-agent CLI that Coven can run as a supervised process. The harness is not the daemon, not a familiar, and not the user interface. It is the external agent runtime that receives a prompt and works inside a PTY.

**Coven is not a harness.** Coven is the substrate that harnesses run within. It provides enforced project boundaries, supervised PTY lifecycle, session records, event logs, and a unified local API — so that any harness can operate in a well-defined, auditable, reproducible way without each one needing to reinvent lifecycle management, boundary enforcement, or client access.

## Boundary map

| Term | Role |
Expand Down
6 changes: 5 additions & 1 deletion lib/coven-proxy-dial.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,11 @@ export function envelope(
details: Record<string, unknown>,
status: number,
): Response {
return Response.json({ error: { code, message, details } }, { status });
const body = JSON.stringify({ error: { code, message, details } }, null, 2) + '\n';
return new Response(body, {
status,
headers: { 'content-type': 'application/json; charset=utf-8' },
});
}

export function daemonUnreachable(
Expand Down
Loading