Skip to content
Open
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
27 changes: 25 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ uv run mypy src # type-check
uv run pytest -q # tests
```

A handful of smoke tests exercise real ACP agents and are skipped automatically when the corresponding binaries (`claude-agent-acp`, `codex-acp`) are not installed.
A handful of smoke tests exercise real ACP agents and are skipped automatically when the corresponding binaries (`claude-agent-acp`, `codex-acp`, or `opencode`) are not installed. Live provider checks can spend tokens and must stay explicitly opt-in; hermetic tests plus disposable host configuration checks are the default evidence floor.

## Pull requests

Expand All @@ -32,7 +32,30 @@ A handful of smoke tests exercise real ACP agents and are skipped automatically

## Adding a provider

Zenith's agent providers (Claude Code, Codex, Hermes, …) are declared in [`zenith/src/zenith_harness/providers.py`](zenith/src/zenith_harness/providers.py), with per-provider assets under [`zenith/src/zenith_harness/bundled/providers/`](zenith/src/zenith_harness/bundled/providers/). New provider PRs should include an orchestrator prompt path, ACP adapter command, and tests in `tests/`.
Zenith's agent providers (Claude Code, Codex, Hermes, OpenCode, ...) are declared in [`zenith/src/zenith_harness/providers.py`](zenith/src/zenith_harness/providers.py), with per-provider assets under [`zenith/src/zenith_harness/bundled/providers/`](zenith/src/zenith_harness/bundled/providers/). New provider PRs should include an orchestrator prompt path, ACP adapter command, and tests in `tests/`.

### OpenCode PR-A boundaries

OpenCode support in this branch is project-scoped and experimental. Keep docs,
tests, and implementation aligned with `zenith init --agent opencode` generating
`.opencode/opencode.json`, `.opencode/orchestrator_prompt.md`, `.opencode/agents/`,
`.opencode/skills/`, and `.agents/skills/`. The managed OpenCode config should
contain only Zenith's `mcp.zenith` local MCP entry and safe Zenith routing
values; it must not persist provider API keys, OpenCode credentials, a default
model/provider, permission policy, plugin configuration, global OpenCode config,
or arbitrary provider secret environment variables.

Do not claim PR A proves live OpenCode worker or validator execution, OpenCode
model/effort ACP session options, isolated OpenCode terminal review, user-scoped
OpenCode setup, or provider-neutral billing grants. Those belong to later PR B/C
work. If you add future live OpenCode smoke tests, keep them opt-in and document
that normal worker and validator sessions use the credentials available to the
`opencode` process and therefore share the operator's billing trust boundary.

Keep the audience-specific OpenCode docs in sync with code changes:
[`docs/opencode-support/user.md`](docs/opencode-support/user.md),
[`docs/opencode-support/admin.md`](docs/opencode-support/admin.md), and
[`docs/opencode-support/developer.md`](docs/opencode-support/developer.md).

## License

Expand Down
69 changes: 63 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
<a href="technical_report/Technical_Report.pdf"><img src="https://img.shields.io/badge/technical%20report-PDF-b31b1b.svg" alt="Technical Report"></a>
</p>

Zenith is an agent harness for work that may run for days or weeks, where the dominant failure mode is *premature completion* rather than inability to make progress. It runs a coding agent (Claude Code, Codex, or Hermes) as a multi-agent orchestrator over MCP/ACP: one orchestrator session reads task state each turn and decides whether to spawn workers and testers, register reusable skills, replan, or stop.
Zenith is an agent harness for work that may run for days or weeks, where the dominant failure mode is *premature completion* rather than inability to make progress. It runs a coding agent (Claude Code, Codex, Hermes, or experimental OpenCode support) as a multi-agent orchestrator over MCP/ACP: one orchestrator session reads task state each turn and decides whether to spawn workers and testers, register reusable skills, replan, or stop.

This repository contains the Zenith harness ([`zenith/`](zenith/)) and the Intelligent Internet technical report (2026) behind it.

Expand All @@ -29,10 +29,10 @@ Our Zenith method keeps the useful parts of repeated review while making the loo

### Option 1 — Let your agent install it

Copy this prompt into Claude Code or Codex:
Copy this prompt into Claude Code, Codex, or OpenCode:

```text
/goal Read the readme at https://github.com/Intelligent-Internet/zenith, detect if using Claude Code, Codex, or both, install requirements, install and run Zenith (i.e. uv run zenith, as in the readme), and create a new skill called /zenith — when used (along with an additional prompt) it will call the skill: the minimum skill content should be: """First read .claude/orchestrator_prompt.md and treat it as your primary role, then use Zenith to run this mission.""" Afterwards, you can add information about the Zenith harness, based on the readme and the technical report (inside the repo), and info on how to start Zenith if it's not already running. Change the skill to use .codex when using it in Codex. If both harnesses are available, make sure to add the skill to both of them correctly. In fact, there might be more harness options (Hermes, for example). See what is supported in zenith/src/zenith_harness/providers.py, and for those that you detect are present, add their skills correctly. When finished, confirm to me that Zenith is installed, running, and ready, explain a bit about Zenith, and why and when to use it.
/goal Read the readme at https://github.com/Intelligent-Internet/zenith, detect if using Claude Code, Codex, OpenCode, or multiple supported agents, install requirements, install and run Zenith (i.e. uv run zenith, as in the readme), and create a new skill called /zenith — when used (along with an additional prompt) it will call the skill: the minimum skill content should be: """First read .claude/orchestrator_prompt.md and treat it as your primary role, then use Zenith to run this mission.""" Afterwards, you can add information about the Zenith harness, based on the readme and the technical report (inside the repo), and info on how to start Zenith if it's not already running. Change the skill to use .codex when using it in Codex and .opencode when using it in OpenCode. If multiple harnesses are available, make sure to add the skill to both of them correctly. In fact, there might be more harness options (Hermes, for example). See what is supported in zenith/src/zenith_harness/providers.py, and for those that you detect are present, add their skills correctly. When finished, confirm to me that Zenith is installed, running, and ready, explain a bit about Zenith, and why and when to use it.
```

This will:
Expand All @@ -41,7 +41,7 @@ This will:
- start Zenith using `uv`
- create a `/zenith` skill for each agent harness it detects

Then, in Claude Code or Codex, type:
Then, in Claude Code, Codex, or OpenCode, type:

```text
/zenith <your instruction or query>
Expand All @@ -54,7 +54,7 @@ Then, in Claude Code or Codex, type:
- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/)
- Node.js 22+ and `npm`
- Claude Code, Codex, or Hermes (see [`providers.py`](zenith/src/zenith_harness/providers.py) for the supported set)
- Claude Code, Codex, Hermes, or OpenCode (see [`providers.py`](zenith/src/zenith_harness/providers.py) for the supported set)

**Install**

Expand All @@ -76,6 +76,21 @@ npm install -g @agentclientprotocol/codex-acp
command -v codex-acp
```

OpenCode has a native ACP server, so no third-party ACP adapter is required.
Install OpenCode using the current OpenCode installation instructions for your
platform, then confirm the `opencode` binary is on `PATH`:

```bash
# Common OpenCode 1.x install path; see https://opencode.ai/docs/ for alternatives.
curl -fsSL https://opencode.ai/install | bash
command -v opencode
opencode --version
```

This PR-A OpenCode support was implemented against OpenCode `1.18.30` and uses
the `opencode acp` command, project `.opencode` configuration, OpenCode agents,
and OpenCode skills.

**Initialize a workspace**

Initialize the project workspace Zenith should operate on. This is your target app/repo, not the Zenith source checkout:
Expand All @@ -86,6 +101,9 @@ uv run zenith init --workspace-dir /path/to/your-app --agent claude

# Or Codex, from this Zenith checkout
uv run zenith init --workspace-dir /path/to/your-app --agent codex

# Or OpenCode, from this Zenith checkout
uv run zenith init --workspace-dir /path/to/your-app --agent opencode
```

**Run a mission**
Expand All @@ -98,16 +116,55 @@ cd /path/to/your-app
claude
# or
codex
# or
opencode
```

Then ask the agent to read the generated orchestrator prompt (use `.codex/orchestrator_prompt.md` for Codex):
Then ask the agent to read the generated orchestrator prompt (use `.codex/orchestrator_prompt.md` for Codex and `.opencode/orchestrator_prompt.md` for OpenCode):

```text
First read .claude/orchestrator_prompt.md and treat it as your primary role, then use Zenith to run this mission.

<your instruction or query>
```

### OpenCode project setup

`zenith init --agent opencode` performs project-scoped setup only. It writes or
updates `.opencode/opencode.json` with Zenith's managed `mcp.zenith` local MCP
entry, using OpenCode's `command`, `environment`, `enabled`, and millisecond
`timeout` fields. It also creates `.opencode/orchestrator_prompt.md`, installs
OpenCode subagents under `.opencode/agents/`, and installs bundled skills under
both `.opencode/skills/` and `.agents/skills/`.

Zenith preserves unrelated strict JSON OpenCode settings and unrelated MCP
servers. It does not rewrite JSONC; if `.opencode/opencode.jsonc` or a project
`opencode.jsonc` defines `mcp.zenith` in a way that would shadow Zenith's
managed entry, initialization fails with remediation instead of normalizing the
commented file.

OpenCode PR-A support is intentionally experimental. It registers OpenCode as a
host and execution provider, selects the native `opencode acp` command for
worker, validator, and terminal-reviewer roles, and selects OpenCode `build`
mode for normal ACP sessions. It does not yet claim verified live OpenCode
worker or validator execution, per-role OpenCode model/effort session options,
isolated OpenCode terminal review, user-scoped OpenCode setup, or
provider-neutral billing grants. Those are future PR B/C boundaries.

Zenith does not choose or persist an OpenCode default model, provider credential,
permission policy, plugin configuration, global OpenCode config, or provider API
key. Normal OpenCode worker and validator sessions run with the credentials
available to the `opencode` process, so provider access and billing remain under
the operator's OpenCode trust boundary. PR-A checks are hermetic by default and
use disposable local OpenCode configuration checks such as `opencode debug
config`; any live-provider smoke that can spend tokens must stay explicit and
opt-in.

For audience-specific OpenCode guidance, see the
[user](docs/opencode-support/user.md),
[admin](docs/opencode-support/admin.md), and
[developer](docs/opencode-support/developer.md) guides.

## How Zenith Works

<p align="center">
Expand Down
Loading