Skip to content

claude-code-install.md

Latest commit

 

History

History
130 lines (98 loc) · 4.99 KB

claude-code-install.md

File metadata and controls

130 lines (98 loc) · 4.99 KB
Raw

Claude Code Install

Claude Code receives a native plugin containing the orchestrator, six namespaced specialists, MCP configuration, and the four workflow skills owned by thoth-agents. The CLI remains a required installation step for the four external skills and provider-owned thoth-mem setup, but agents do not consume either CLI during SDD phases.

Requirements

  • Node.js >=22.13 for bundled scripts
  • Claude Code with native plugin marketplace commands
  • Permission to add and trust EremesNG/thoth-agents
  • Network access during installation for the external skill repositories and thoth-mem setup package

1. Register the marketplace

Run in a terminal:

claude plugin marketplace add EremesNG/thoth-agents --scope user

The marketplace name is thoth-agents; its catalog is .claude-plugin/marketplace.json.

2. Install the plugin

claude plugin install thoth-agents@thoth-agents --scope user

Claude copies the shared plugin/ bundle into its manager-owned cache. Codex resolves to the same source through its own marketplace. thoth-agents never edits either manager cache directly.

3. Install the external skills and thoth-mem

After the two native commands succeed, preview and run the CLI layer:

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

The installer invokes npx skills add for simplify, tdd, progressive-context-router, and architectural-grilling, targeting the global Claude skill root. It then invokes npx -y thoth-mem@latest setup claude --scope global --json; dry-run adds provider --plan. A missing skill or any thoth-mem result other than consistent complete evidence makes installation incomplete. Provider manual actions and receipt remain visible for recovery.

4. Reload and initialize the project

Restart Claude Code or run /reload-plugins, then open the target repository and invoke:

/thoth-agents:thoth-init

Init preflights and synchronizes the minimum openspec/ directories, a missing constitution, and initialization metadata. Claude discovers agents, phase contracts, and SDD templates from the plugin; external execution skills come from the preceding CLI step. Project initialization is offline and idempotent, preserves existing constitutions, and leaves legacy project templates untouched.

Packaged surfaces

Surface Contents
agents/ Main orchestrator plus explorer, librarian, oracle, designer, quick, and deep generated from canonical source
skills/ Five owned workflow skills, including plan-reviewer
.mcp.json Packaged thoth-agents research MCP configuration
settings.json Activates the orchestrator as the main plugin agent

Namespaced delegation uses thoth-agents:<role>. Children never delegate. Read-only oracle owns user-selected plan review and every final verification, regardless of who implemented the change.

Verification

claude plugin marketplace list --json
claude plugin list --json

Inside Claude Code, inspect /plugin. A healthy install shows the canonical marketplace, an enabled thoth-agents@thoth-agents plugin, and all mandatory external skills reported by the CLI:

npx thoth-agents@latest status --harness=claude

Limitations

  • Claude owns marketplace snapshots, cache files, and packaged model defaults; publish a new plugin version to change them.
  • Explorer, librarian, and oracle deny Write and Edit. Fine-grained openspec/ path restrictions are instruction-level because Claude's plugin permission map is not a path-pattern sandbox.
  • Background agents cannot surface interactive permission or clarification prompts like the foreground session.
  • Organization strictKnownMarketplaces policy can block registration or updates; thoth-agents cannot bypass it.
  • Project-scope use requires workspace trust.
  • thoth-mem remains independently owned. thoth-agents invokes only its public setup; hooks, MCP, skill, lifecycle, persistence, receipts, and recovery remain provider-owned.
  • Project QA executables remain separate.

At runtime, agents follow the installed thoth-mem skill. Root owns stable session identity and lifecycle; a child receives bounded none, recall, or observe authorization without gaining workspace writes. openspec/ remains canonical.

Troubleshooting

If claude plugin is unavailable, update Claude Code and restart the terminal. For a marketplace-name conflict, inspect claude plugin marketplace list --json and resolve the conflicting native source. If policy blocks the marketplace, ask the Claude administrator to allow the repository.

Upstream references