thoth-agents is a delegate-first agent system for coding harnesses. It started as an OpenCode plugin and now provides a shared seven-agent workflow for OpenCode and Codex, with each harness getting the integration surface that fits it best.

OpenCode remains the stable default path: native plugin install, native task delegation, optional tmux monitoring, and generated config. Codex is supported through an explicit agent-pack and Personal plugin setup path, with documented trust review and instruction-level governance caveats where Codex does not provide the same hard runtime controls.

What It Is

• A canonical seven-agent roster: orchestrator, explorer, librarian, oracle, designer, quick, and deep.
• A delegate-first operating model that keeps the root coordinator focused on decisions while specialists gather evidence, implement, review, and verify.
• A bundled requirements interview and SDD pipeline for moving from ambiguous requests to planned, verified implementation.
• A thoth-mem integration for durable project memory, SDD artifacts, and cross-session recovery.
• A multi-harness package that preserves OpenCode defaults while adding a Codex setup path.

What It Is Not

• It is not a claim that every harness has identical runtime behavior.
• It is not a replacement for each harness's security, trust, sandbox, or approval model.
• It does not rename the seven roles or require new visual assets.
• It does not make Codex tmux-aware; tmux integration is scoped to OpenCode child task sessions.

Harness Support

| Harness | Status | Setup path | Notes | | --- | --- | --- | --- | | OpenCode | Stable default | npx thoth-agents@latest install or npx thoth-agents@latest install --agent=opencode | Native plugin config, native task delegation, optional tmux panes, OpenCode provider auth. | | Codex | Supported explicit path | npx thoth-agents@latest install --agent=codex | Installs ambient/root guidance, six role subagents, and a Personal plugin source. Requires /plugins and /hooks trust review. Some governance remains instruction-level. |

OpenCode can load the plugin with:

{
  "plugin": ["thoth-agents@latest"]
}

That plugin entry is not a shell command. To run the installer or TUI, use the npm binary through a global install, npx thoth-agents@latest, or pnpm dlx thoth-agents@latest.

Quick Start

Run the binary with no arguments in an interactive terminal to open the multi-harness TUI:

npx thoth-agents@latest

The same no-argument binary invocation falls back to the OpenCode install path in CI, redirected, or TERM=dumb terminals. Use explicit commands when you need deterministic automation.

OpenCode

npx thoth-agents@latest install
npx thoth-agents@latest install --agent=opencode
opencode auth login
opencode

Then ask OpenCode to verify the roster:

ping all agents

For non-interactive setup:

npx thoth-agents@latest install --no-tui --tmux=no --skills=yes

Interactive status, list, update, sync, and model previews are available from the no-argument TUI. Command help also documents the explicit command names for terminal workflows.

Codex

Review the plan first, then install explicitly:

npx thoth-agents@latest install --agent=codex --dry-run
npx thoth-agents@latest install --agent=codex

Restart Codex and review plugin/hook trust:

/plugins
/hooks

Codex install does not create a selectable orchestrator TOML, does not bypass trust review, and does not make role permissions or memory governance hard runtime guarantees unless Codex exposes those controls.

Reset Generated Config

npx thoth-agents@latest install --reset

Seven-Agent Roster

The delegate-first philosophy is simple: the orchestrator coordinates while specialists execute. Shared concepts are the same across harnesses, but the dispatch mechanism is harness-bound. In OpenCode, specialists are launched with the native task tool. In Codex, the installed role agents and plugin-bundled skills provide the closest supported workflow, with some behavior enforced by instructions rather than hard runtime APIs.

Primary Agent

Specialist Subagents

SDD And Memory

The bundled requirements interview is the front door for open-ended work. It clarifies intent, assesses scope, asks for user approval when needed, and routes work into direct implementation, accelerated SDD, or full SDD.

propose -> [spec || design] -> tasks -> apply -> verify -> archive

For moderate work, the accelerated path usually runs propose -> tasks. For high-risk or high-complexity work, the full path adds specification and design artifacts before task execution.

Artifacts can be persisted in four modes:

| Mode | Writes to | Cost | Use when | | --- | --- | --- | --- | | thoth-mem | Memory only | Low | Fast iteration without repo planning files | | openspec | openspec/ files only | Medium | Reviewable planning artifacts in the repo | | hybrid | Both | High | Maximum durability; default | | none | Neither | Lowest | Ephemeral iterations, no persistence |

Thoth-mem is the local memory MCP used for durable observations, architectural decisions, SDD artifacts, and session summaries. The core retrieval pattern is:

1. mem_search for compact candidate records
2. mem_timeline for chronological context
3. mem_get_observation for the full selected record

Skills And MCPs

thoth-agents ships bundled skills for requirements discovery, plan review, SDD planning/execution, verification, and archiving. It also registers MCP servers for docs research, public code search, and local memory where the harness supports that delivery surface.

| Surface | Shared concept | OpenCode binding | Codex binding | | --- | --- | --- | --- | | Skills | Requirements, SDD, review, execution workflows | Copied into the OpenCode skills directory when --skills=yes | Packaged as plugin-bundled skills for the Personal plugin source | | MCPs | exa, context7, grep_app, thoth_mem | Registered by generated OpenCode plugin config | Packaged/configured only on validated Codex surfaces | | Delegation | Seven-role specialist workflow | Native task tool | Custom agents plus prompt/plugin guidance | | Blocking choices | Use a structured question surface | OpenCode question tool | request_user_input when enabled and available |

See docs/skills-and-mcps.md for the detailed matrix.

Documentation

• Installation: OpenCode default setup, explicit Codex setup, non-interactive installs, reset behavior, and troubleshooting.
• Codex Install: Codex targets, backups, dry-run behavior, trust review, and limitations.
• Quick Reference: Agent roster, SDD flow, memory, delegation, tmux, and key config fields.
• Skills and MCPs: Bundled skills, MCP servers, and harness delivery surfaces.
• Provider Configurations: OpenCode provider presets, fallback chains, and Codex customization cross-links.
• Tmux Integration: OpenCode-scoped live pane monitoring for delegated task sessions.
• SDD Pipeline: Planning and execution workflow details.
• Codex Plugin Packaging: Codex plugin package layout and packaging boundaries.
• Codex Surface Validation: Validated, unknown, and unsupported Codex generation surfaces.
• Codex Model Customization: Codex role model defaults and customization limits.

Development

The OpenCode integration targets @opencode-ai/plugin and @opencode-ai/sdk v1.4.7. The repository also contains Codex adapter and packaging code for the multi-harness install path.

Use Node.js >=22.13 with Corepack-managed [email protected]:

corepack enable
corepack prepare [email protected] --activate
pnpm install

| Command | Purpose | | --- | --- | | pnpm run build | Build TypeScript into dist/ and generate declarations/schema | | pnpm run typecheck | Run TypeScript type checking without emit | | pnpm test | Run the Vitest suite | | pnpm run lint | Run Biome linter | | pnpm run format | Run Biome formatter | | pnpm run check | Run Biome check with auto-fix | | pnpm run check:ci | Run Biome check without writes | | pnpm run dev | Build and launch the OpenCode plugin in local dev mode |

License

MIT