Why thoth-agents

Describe what you want to build or fix. Thoth keeps the conversation together, handles straightforward work directly, and brings in specialists when research, design, implementation, or an independent review would help.

Small changes stay small. Larger changes get a specification, a plan, and verification you can follow—without manually coordinating every agent.

• A team, not seven conversations. One adaptive Orchestrator coordinates six specialists and brings their results back to you.
• The right amount of process. Choose a quick Direct path or a structured specification-driven development (SDD) workflow for more involved work.
• Specialists where they add value. Repository discovery, current documentation, UI/UX, focused edits, complex implementation, and independent review have distinct roles.
• Models you can tune. Configure models per role to suit your workflow and the providers available in your harness.
• Continuity between sessions. Published installs include setup of thoth-mem, the independent memory companion for reusable decisions and project knowledge. thoth-mem owns its own memory lifecycle, persistence, and storage; thoth-agents only invokes its setup.

[!NOTE] OpenCode is the default and most integrated path. All four harnesses share the workflow and role design, but their permissions, delegation, and runtime capabilities are not identical. Your harness's trust and approval rules still apply.

Install

You need Node.js >=22.19, a supported harness already installed, and network access for setup. Authenticate your model providers in that harness separately. The commands below install at global/user scope.

| Harness | What you get | Install command | | --- | --- | --- | | OpenCode | Native plugin, agent team, workflow skills, and memory setup. Recommended starting point. | npx thoth-agents@latest install --agent=opencode | | Codex | Native plugin plus the required global agent and instruction setup. Close Codex first. | npx thoth-agents@latest install --agent=codex | | Claude Code | Marketplace agents and skills, completed by the CLI's external skills and memory setup. Run the prerequisites below first. | npx thoth-agents@latest install --agent=claude | | Pi | Native package, six specialists, delegation and research extensions, workflow skills, and memory setup. | npx thoth-agents@latest install --agent=pi |

Claude Code prerequisites

Run these two commands before the Claude CLI install command in the table:

claude plugin marketplace add https://github.com/EremesNG/thoth-plugins.git --scope user
claude plugin install thoth-agents@thoth-plugins --scope user

[!TIP] Add --dry-run to any npx thoth-agents ... install command to preview setup without writing changes. After installation, restart your harness; Claude Code also supports /reload-plugins.

Pi setup currently supports the default ~/.pi/agent root. See the Pi installation guide for runtime requirements, existing-package conflicts, and recovery. Pi extensions run with your user's system permissions; agent tool allowlists are not an OS sandbox.

For scopes, troubleshooting, or local checkout installation, see the installation guide. Local Pi checkout installs keep thoth-mem setup separate.

Get started

1. Check your installation

After setup completes, inspect the installed state:

npx thoth-agents@latest status

If setup reports a missing dependency or a manual action, resolve it before continuing. Package installation alone does not prove provider authentication or a successful live model request.

2. Initialize your project

Open your repository in the harness and invoke the installed thoth-init skill:

| Harness | In your agent conversation | | --- | --- | | OpenCode | /thoth-init | | Codex | $thoth-init | | Claude Code | /thoth-agents:thoth-init | | Pi | Ask: Use the thoth-init skill to initialize this repository. |

This prepares the repository's openspec/ governance for structured workflows. It does not install plugins or dependencies, and it preserves existing constitutions.

3. Give Thoth a task

Start with a goal, not a list of agents to manage. For example:

Fix the broken documentation link using the Direct route.

Add CSV export to the reports page using Accelerated SDD.
Keep the existing filters and include tests for empty results.

Use Full SDD to plan a migration from our current authentication system.
Explore the risks before proposing changes.

You can name a route explicitly or let Thoth recommend one. Describe your constraints and expected outcome; the Orchestrator decides whether to handle work directly or bring in a specialist.

Meet the team

One coordinator

Research and review

| Explorer | Librarian | Oracle | | :---: | :---: | :---: | | | | | | Finds the relevant code. Maps unfamiliar repository behavior before changes begin. | Checks current sources. Looks up authoritative documentation and external evidence. | Challenges the result. Independently reviews plans and verifies changes when the workflow or risk requires it. |

Design and implementation

| Designer | Quick | Deep | | :---: | :---: | :---: | | | | | | Makes interfaces work well. Owns UI/UX, accessibility, implementation, and visual quality. | Makes focused changes. Handles clear, narrow, low-risk implementation tasks. | Handles complex changes. Works through coupled behavior, edge cases, and correctness-critical implementation. |

Research and review specialists are read-only. Implementation work has one writer per area; independent areas can proceed in parallel when the harness supports it. You do not need to summon every role for every task.

Choose your workflow

SDD means specification-driven development: agree on the intended result, plan the work, implement it, and check it against that intent.

| Route | Best for | What to expect | | --- | --- | --- | | Direct | Clear, bounded, low-risk fixes and documentation changes. | Implement → verify. No planning artifacts required. | | Accelerated | Features spanning several areas, moderate risk, or a request to use SDD. | Specify → plan → tasks → implement → verify → archive. Planning runs in one pass unless a material decision needs you. | | Full | Uncertain requirements, architectural changes, or high-cost failures. | Explore first, then follow the structured workflow with separate planning checkpoints. |

For Accelerated and Full, the specification, plan, tasks, and verification reports live under openspec/, so you can inspect what was agreed and what was checked. You can choose an optional Oracle plan review before implementation; final verification is required either way. These routes and materially risky Direct work use an independent Oracle for final verification.

[!TIP] You stay in control of the route. Say “Use Direct,” “Use Accelerated SDD,” or “Use Full SDD” when you already know how much structure you want.

The installed skills cover project initialization, SDD, project principles, plan review, and archiving. External skills add test-driven development, behavior-preserving simplification, focused repository context, and architectural questioning when needed. See Skills and MCPs and the SDD workflow guide for details.

Configure and update

Tune the team

Use the interactive CLI to inspect setup and configure role models:

npx thoth-agents@latest

Choose models your harness and provider account can access. OpenCode ships the OpenAI preset; per-role overrides let you customize it. Other harnesses use their own model configuration and capability rules.

See Provider Configuration and Codex Model Customization.

Keep the complete installation current

Preview an update, then apply it explicitly:

npx thoth-agents@latest update --harness=opencode
npx thoth-agents@latest update --harness=opencode --apply

Replace opencode with codex, claude, or pi for your harness. Close Codex before applying its update, and restart the selected harness afterward.

An applied update refreshes the complete CLI-managed setup, including required skills and provider setup—not just the plugin. Native marketplace updates alone do not prove those other pieces are current. Use status to inspect the last complete CLI-managed installation and follow any reported recovery actions.

Documentation

User guides

| Guide | Use it to… | | --- | --- | | Installation | Check prerequisites, preview setup, troubleshoot, and repair an installation. | | Quick Reference | Find commands, roles, skills, and workflow reminders. | | SDD Pipeline | Understand planning, review, verification, and archiving. | | Skills and MCPs | See the included workflows, research tools, and memory boundaries. | | Provider Configuration | Configure models and providers. | | Codex Install | Follow Codex-specific setup, activation, and trust requirements. | | Codex Model Customization | Adjust Codex specialist models. | | Claude Code Install | Follow marketplace setup and activation. | | Pi Setup | Check Pi dependencies, permissions, and recovery steps. | | Tmux Integration | Configure OpenCode's optional terminal-pane integration. |

Technical guides

Working on thoth-agents itself? Start here rather than in the user setup above.

| Guide | What it covers | | --- | --- | | Development | Local build, verification, and harness development setup. | | Architecture | Repository structure and component responsibilities. | | Codex Plugin Packaging | Plugin contents, the global layer, and local synchronization. | | Claude Code Plugin Packaging | Native discovery, packaging, and ownership boundaries. | | Codex Surface Validation | Harness-specific validation evidence and limitations. | | Agent Context Index | Task-specific engineering and testing guidance. |