Skip to content
AI CraftsmanSUPERPOWERS

Hosts and Capabilities

Four hosts, one engine: Claude Code, Codex, Grok, Hermes. What each host does and limitations.

Last updated: Edit on GitHub

Overview

AI Craftsman Superpowers runs on four hosts with one engine. Each host implements the same rules and gate, but observes different hook events and has different tool support.

Claude Code Codex Grok Hermes
Install /plugin install codex plugin add bin/craftsman-grok-install hermes plugins enable
Version 2.1.218+ 0.155.1+ 1.0.40+ native plugin
Write gate Write, Edit apply_patch write, search_replace opt-in
Evidence gate TaskCompleted no no pre_verify
ask decision yes no yes no
Test evidence yes no yes no
Skills 22 /craftsman:<name> 22 native 22 /<name> (plan/loop/workflow stay /craftsman:) 7 + /craftsman

GitHub Copilot has an adapter, adapters/copilot/, written against its documented hook contract; no Copilot surface is qualified yet, so it is not one of the four hosts above.

Claude Code (Native Plugin)

The primary host. Full feature parity. Latest version: check with claude --version.

What it does:

  • Write gate before disk on Write and Edit tools
  • Evidence gate on TaskCompleted event
  • ask decisions for rule violations
  • Test evidence grant and revoke
  • All 22 skills: /craftsman:<name>
  • Agent hooks, on by default: a headless Haiku review after each Write or Edit and at Stop. Turn them off with the plugin option agent_hooks: false
  • From 4.14.0 on Claude Code 2.1.269 or later: files a Bash command changed are re-read after the call, each judged as a write under its own path

What it does NOT do:

  • A file written by a shell command is not refused before it reaches disk. The re-read above happens after the Bash call, and only where the host lists the changed files (tool_response.bashEditDiff, which Claude Code documents as best effort and records in bypass and auto mode, elsewhere only with bashEditDiffEnabled in user or managed settings). CI catches the rest

Install:

/plugin marketplace add BULDEE/ai-craftsman-superpowers
/plugin install craftsman@ai-craftsman-superpowers
/craftsman:setup --quick

Verify:

/craftsman:healthcheck

See the Claude Code install section of the README for requirements and a local install.

Codex (Native Plugin)

OpenAI’s Codex CLI. Feature parity for write validation. The gate runs natively from the plugin manifest once you trust it in /hooks.

What it does:

  • Write gate before disk on apply_patch tool
  • All 22 skills loaded natively from the plugin manifest
  • Rules engine with 3-level inheritance
  • Metrics per session

What it does NOT do:

  • No evidence gate (Codex does not fire TaskCompleted)
  • No ask decision: where the gate would ask, it denies
  • No test evidence grant/revoke
  • Codex does not read user or project hooks from .codex/hooks/*.json; only from hooks.json or config.toml next to a config layer

Install:

codex plugin marketplace add BULDEE/ai-craftsman-superpowers
codex plugin add craftsman@ai-craftsman-superpowers
codex    # then /hooks: review and trust the craftsman handlers

Verify:

/craftsman:healthcheck

See the Codex quickstart for detailed setup, event list, and limits.

Grok (Native Plugin)

xAI’s Grok CLI. Full write validation. The gate is global (~/.grok/hooks/craftsman.json) and does not depend on project trust.

What it does:

  • Write gate before disk on write and search_replace tools
  • All 22 skills with alternate slash names
  • Rules engine with 3-level inheritance
  • Metrics per session
  • ask decisions for rule violations
  • Test evidence grant and revoke

What it does NOT do:

  • No evidence gate (Grok does not fire TaskCompleted)
  • No agent hooks (gate is validation only)
  • Plugin hooks are not executed on fresh process (gate is global file)
  • No shell-written files caught before disk (CI catches them)

Skill names: On Grok, most skills use the short form /<name>. Three exceptions stay /craftsman:name because Grok already owns those commands:

/design              # DDD design
/debug               # Systematic debugging
/craftsman:plan      # /plan is Grok's own command
/craftsman:loop      # /loop is Grok's own command
/craftsman:workflow  # /workflow is Grok's own command
/metrics             # Quality dashboard
/healthcheck         # Verify the install

Install:

git clone https://github.com/BULDEE/ai-craftsman-superpowers ~/src/ai-craftsman-superpowers
bash ~/src/ai-craftsman-superpowers/bin/craftsman-grok-install

Verify:

bash ~/src/ai-craftsman-superpowers/bin/craftsman-healthcheck --report

See the Grok quickstart for detailed setup, hook execution behavior, and limits.

Hermes (Native Plugin)

Nous Research’s Hermes. The gate applies at the conclusion: prevents the agent from concluding a coding turn that leaves critical violations.

What it does:

  • Evidence gate on pre_verify event (at turn conclusion)
  • Seven situation skills (/craftsman plus context)
  • Rules engine with 3-level inheritance
  • Metrics per session
  • Optional write gate (opt-in with write_gate: on in config)

What it does NOT do:

  • No pre-write gate by default (opt-in only)
  • No 22 full skills (Hermes-specific 7 situation skills)
  • No ask decisions
  • No test evidence grant/revoke

Install:

git clone https://github.com/BULDEE/ai-craftsman-superpowers ~/.hermes/plugins/craftsman
hermes plugins enable craftsman

Verify:

/craftsman:healthcheck

See the Hermes quickstart for detailed setup and skills.

Common Patterns

Writing Files from Bash

On all hosts, files written by shell commands (e.g., printf > file, sed -i, custom scripts) are NOT refused by the write gate before disk. The CI gate (ci/craftsman-ci.sh) catches them. The pre-push hook reads no file: it only warns when the session was never verified (Hermes alone refuses a push until a passing conclusion on the tree it publishes).

From 4.14.0, on Claude Code 2.1.269 or later, the post-write check also runs after a Bash call and judges each file the host lists as changed, as if it had been written by Write. That is a review after the fact, best effort on the host’s side, not a refusal.

Example: A Bash command writes a file the plugin is not aware of.

printf "bad code" > file.php   # Not refused by the write gate

Fix: Use the native write tools (Write and Edit on Claude Code, apply_patch on Codex, write and search_replace on Grok, write_file and patch on Hermes with write_gate: on) for all generated code.

Metrics Database Location

Each host and session isolation maintains its own metrics store. Resolve it at runtime:

METRICS_DB=$(bash "$(craftsman-path bin/craftsman-runtime)" metrics)
sqlite3 "$METRICS_DB"

Rules and CI

All hosts use the same rules engine. If your project has a .craft-config.yml, commit it to git so CI runs the same rules:

git add .craft-config.yml
git commit -m "config: share Craftsman rules across the team"

CI reads your project config and applies directory-level overrides, so the pipeline never diverges from your local hooks.

Which Host Should I Use?

  • Claude Code: Every gate, all 22 skills, agent hooks for semantic review. Recommended for individuals and teams.
  • Codex: OpenAI integration, native plugin support. If your team uses OpenAI’s Codex CLI.
  • Grok: xAI’s Grok CLI. If your team uses Grok and wants validation without agent overhead.
  • Hermes: Nous Research’s Hermes. If your agent runs on Hermes and you want a conclusion gate.

Troubleshooting Multi-Host Setup

Q: Can I use Craftsman on Claude Code and Codex in the same project?

Yes. Both hosts read the same .craft-config.yml and use the same rules. Metrics are isolated per host and session, so they do not interfere. Just install on both and enable the same packs.

Q: My Grok gate is not running.

The gate is global at ~/.grok/hooks/craftsman.json. Verify it exists:

ls -la ~/.grok/hooks/craftsman.json

If missing, re-run the installer:

bash ~/src/ai-craftsman-superpowers/bin/craftsman-grok-install

Q: Why did my Hermes agent conclude with violations?

The conclusion gate (pre_verify) refuses a conclusion only while a critical finding remains (layer, strict types, any, hardcoded secrets); advisory findings are surfaced once, without blocking. Hermes bounds the retries itself. To stop the two worst cases before they reach disk, turn on write_gate: on (SEC001 and LAYER001 only).