thoth-agents

[!WARNING] Thoth-Agents is under active development. Core concepts, workflows, and specifications are still evolving, and significant breaking changes may occur before a stable release.

Why thoth-agents

Describe what you want to build or fix. Thoth keeps the conversation together, directs specialists to discover and implement by default, and retains your goals, constraints, decisions, acceptance, and final synthesis in one root thread.

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

• A team, not six conversations. One adaptive Orchestrator coordinates five specialists and brings their results back to you.
• Proportional process. Small, clear, low-risk work stays artifact-free; substantial work uses one ID-named record and proportionate verification.
• Specialists execute by default. Repository discovery, current documentation, UI/UX, bounded 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] Pi is the default harness and our recommendation for the best Thoth-Agents experience. 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.

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.

Inside Pi, use /subagents-model to edit model and effort profiles for global and project subagent definitions. See subagent profile configuration. Use /subagents-tools to edit each specialist's explicit tool list, including registered active and inactive extension and MCP tools. Globs (including *) are manual advanced selections over all registered root tools; the panel preserves them read-only. Edit disallowed_tools manually for injected tools and trimming globs; only Oracle denies ask_orchestrator by default. See tool selection controls.

Pi setup currently supports the default ~/.pi/agent root. See the Pi installation guide for runtime requirements, existing-package conflicts, and recovery. Thoth manages its separate Pi delegation runtime as package @thoth-agents/pi-subagents (0.1.0) through npm:@thoth-agents/pi-subagents@>=0.1.0. Existing pi-subagents and pi-subagents-j0k3r installs need manual recovery through Pi's package manager before setup. Local checkout development uses pnpm run setup:pi:local, which points Pi at the fork under pi-packages/pi-subagents; publishing the fork is not required for that path. 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:

This creates only missing minimum .thoth/ governance, including .thoth/constitution.md, .thoth/specs/, and the change archive. It does not install plugins or dependencies and preserves existing project-owned governance and historical records.

3. Give Thoth a task

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

Fix the broken documentation link with the smallest sufficient workflow.

Add CSV export to the reports page. Understand the existing filters, specify how empty results behave, and clarify any material decision before a test-first implementation. Keep the work proportional.

Plan a migration from our current authentication system. Explore the risks, specify acceptance, and clarify material decisions before implementation. If classification is substantial, keep the plan and acceptance in one `.thoth/changes/<id>/<id>.md` record.

Describe the desired outcome, constraints, and acceptance. The Orchestrator first builds proportional understanding, then classifies by coordination, uncertainty, and risk and selects the fitting specialist.

Meet the team

One coordinator

Research and review

Design and 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.

Proportional SDD

Every change completes explore, specify, and clarify in order, proportionally to its uncertainty and impact. These steps do not force a document, specialist, or interview. The Orchestrator resolves repository facts through evidence and asks only when a material human-owned decision cannot safely be inferred; unresolved material uncertainty blocks classification.

Only after understanding does it classify by meaningful coordination and contract impact, uncertainty, and risk. File count alone does not increase scope: a clear, low-risk localized mechanical change may touch several files and remain small. Small work uses test-first implementation and focused verification with no record. Substantial or materially risky work plans in one .thoth/changes/<id>/<id>.md record after classification; risk may warrant planning even for a patch-sized change. No alias, duplicate record, report, evidence directory, or process tooling is created.

For substantial work, optional fresh Oracle plan review runs only when selected. After a selected [OKAY], root separately asks Implement (Recommended) or Stop; review alone never authorizes implementation or replaces final verification. Substantial and materially risky work receives a fresh read-only Oracle verification. Declared durable changes sync transactionally to .thoth/specs/ after PASS. Active governance lives at .thoth/constitution.md; historical records remain preserved, and provider memory stays separate. Native harness execution and liveness remain authoritative. See the SDD guide and Skills and MCPs for limits.

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.

For Pi, the first-party thoth-agents package remains exact and receipt-verified. The five mandatory external extensions use stable minimum-only >= ranges, so Pi's native package manager can update them independently without waiting for a Thoth release. Status validates each installed manifest's package name and SemVer floor; newer stable versions are healthy, while prerelease, malformed, missing, or older versions are not. Re-running Install or applying Update migrates legacy exact external sources through Pi while preserving package resource filters and unrelated settings.

Documentation

User guides

Technical guides

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