Daemux Dev Toolkit

A unified toolkit of development agents that ships to two CLI hosts from one source of truth:

• Claude Code — installs as a marketplace plugin (@daemux/claude-plugin).
• OpenAI Codex CLI — installs as a Codex marketplace plugin plus sidecar subagents/hooks.

The same eight agents (architect, developer, reviewer, simplifier, tester, devops, designer, product-manager) run on both hosts. The installer translates a portable definition in agents-source/ into the right shape for each target at publish time.

Install / Update

The installer is invoked the same way for both targets. Use --target to pick the host. --target claude is the default for backward compatibility.

Claude Code

Project-specific (default): Run from your project directory:

npx --yes @daemux/claude-plugin

Global (all projects): Install once for all projects:

npx --yes @daemux/claude-plugin --global

OpenAI Codex CLI

Codex installs are global by convention (Codex resolves agents from ~/.codex/agents/ and <project>/.codex/agents/). Both scopes are supported.

Global (recommended):

npx --yes @daemux/claude-plugin --target codex --global

Project-specific:

npx --yes @daemux/claude-plugin --target codex

Both targets

Install Claude Code AND Codex CLI in one shot. Useful on a fresh dev machine.

npx --yes @daemux/claude-plugin --target both --global

If the Claude install fails (e.g., claude binary not on PATH), the Codex install is skipped — fix Claude first, then re-run.

Same command works for fresh install and updates

The installer is idempotent. Run it any time to upgrade. Auto-update hooks also check the npm registry once per day on each session start and update silently in the background when a newer version is available. The semver-aware comparison (since 1.31.0) ensures auto-update only fires on real upgrades — never downgrades.

Uninstall

Each target uninstalls independently. Use the same --target flag.

Claude Code (project):

npx --yes @daemux/claude-plugin --uninstall

Claude Code (global):

npx --yes @daemux/claude-plugin --global --uninstall

Codex CLI (global):

npx --yes @daemux/claude-plugin --target codex --global --uninstall

Codex CLI (project):

npx --yes @daemux/claude-plugin --target codex --uninstall

Both at once:

npx --yes @daemux/claude-plugin --target both --global --uninstall

Uninstall preserves user-authored content: CLAUDE.md / AGENTS.md are spliced (sentinels removed); user-set [features] codex_hooks = false is left alone; environment keys shared with sibling Daemux plugins (e.g., store-automator) are intentionally not removed.

CLI Options

npx --yes @daemux/claude-plugin [options]

Options:
  -g, --global         Install/uninstall globally (~/.claude or ~/.codex) instead of project scope
  -u, --uninstall      Uninstall the plugin
  --target <target>    Install target: claude (default), codex, or both
  --only <agents>      Install only specified agents (comma-separated)  [Claude only]
  --exclude <agents>   Exclude specified agents (comma-separated)        [Claude only]
  --list               List available agents and their tiers
  -v, --version        Show version number
  -h, --help           Show help message

Selective Installation (Claude Code)

--only and --exclude filter which agents are installed for the Claude target. The Codex target installs the full agent set; selective Codex installation is a future enhancement.

npx --yes @daemux/claude-plugin --list
npx --yes @daemux/claude-plugin --only=developer,reviewer
npx --yes @daemux/claude-plugin --exclude=designer,devops
npx --yes @daemux/claude-plugin -g --only=developer,reviewer,tester

Agent Tiers

| Tier | Agents | Description | |----------|----------------------------------------|------------------------------| | Core | developer, reviewer | Minimum viable pipeline | | Enhanced | + architect, simplifier, tester | Full quality pipeline | | Full | + product-manager, designer, devops | Complete workflow |

What Gets Installed

Claude Code target

• Plugin payload registered in ~/.claude/plugins/marketplaces/daemux-claude-plugins/
• Plugin enabled via claude plugin install daemux-dev-toolkit@daemux-claude-plugins
• CLAUDE.md workflow rules injected between <!-- BEGIN daemux-dev-toolkit --> / <!-- END --> sentinels (project: <cwd>/CLAUDE.md; global: ~/.claude/CLAUDE.md)
• .claude/settings.json env vars (CLAUDE_CODE_ENABLE_TASKS=true, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) and a status line; previously-existing user values are preserved.
• Two SessionStart hooks: silent auto-update (24h cache) and CLAUDE.md re-sync.

Codex CLI target

• Codex plugin payload installed at ~/.codex/.daemux-marketplace/plugins/daemux-dev-toolkit-codex/
• Local marketplace registered via codex plugin marketplace add <local-marketplace-root> (idempotent)
• Subagent TOMLs copied to ~/.codex/agents/ (Codex auto-discovers from this directory)
• AGENTS.md workflow rules injected between sentinels at ~/.codex/AGENTS.md (mirrors the Claude template; carries a <!-- daemux-dev-toolkit@VERSION --> marker for the sync-agents-md hook)
• Two SessionStart hooks merged into ~/.codex/hooks.json: silent auto-update + AGENTS.md re-sync. Each hook entry is tagged with a _daemux marker so uninstall removes only ours.
• ~/.codex/config.toml gets [features] codex_hooks = true (required to enable hooks). If you've already set it to false we leave it alone and emit a warning on stderr.

Configuration

Both targets work out of the box. For the Claude target, ~/.claude/settings.json (or project .claude/settings.json) is automatically updated:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TASKS": "true",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Add additional environment variables as needed for your project — they'll survive plugin updates.

For the Codex target, ~/.codex/config.toml gets [features] codex_hooks = true. Other entries (model preferences, MCP servers) are left alone.

Pin a Specific Version

npx --yes @daemux/[email protected]
npx --yes @daemux/[email protected] --target codex --global

Troubleshooting

Claude Code

| Symptom | Cause / Fix | |--------------------------------------------------|-------------| | claude: command not found | Install the Claude Code CLI first: https://claude.com/code | | Plugin doesn't appear in claude /plugins | Re-run the installer; it re-registers the marketplace and re-runs claude plugin install. | | CLAUDE.md lost user content after an update | Plugin only writes between its sentinels. Backups go to ~/.claude/backups/dev-toolkit/. Restore from there. | | Auto-update keeps re-running | Ensure your installed version matches the registry. cat ~/.cache/daemux-claude-plugin/.update-check shows last check + last seen latest. |

Codex CLI

| Symptom | Cause / Fix | |--------------------------------------------------|-------------| | codex: command not found | Install Codex CLI first: https://developers.openai.com/codex. The installer falls back gracefully but won't register the marketplace. | | Subagents don't appear in codex /agents | Restart Codex; it scans ~/.codex/agents/ (and project .codex/agents/) at session start. | | AGENTS.md rules not applied | Verify ~/.codex/AGENTS.md exists and contains the daemux sentinel block. The sentinel marker line <!-- daemux-dev-toolkit@VERSION --> is what sync-agents-md.sh checks for idempotency — if missing, re-run the installer. | | Hooks don't fire | Check ~/.codex/config.toml has [features] codex_hooks = true. The installer warns on stderr if it found codex_hooks = false and refused to flip it. | | Marketplace add prompts for confirmation | Codex's codex plugin marketplace add is interactive on first registration. Subsequent runs are no-ops. |

Migration

Existing Claude-only users do not need to do anything. The Claude install path is byte-identical to prior releases (verified by test/m2-claude-byte-identity.test.mjs). Codex support is opt-in via --target codex or --target both.

Cross-Platform Notes

• macOS, Linux: fully supported.
• Windows native: not supported. The auto-update hooks rely on bash + curl + sort -V. Use WSL2 (Ubuntu, Debian, etc.) and install from inside the WSL distribution.
• sort -V divergence: macOS BSD sort and GNU coreutils sort disagree on pre-release ordering (BSD: 1.0.0 < 1.0.0-rc.1; GNU: 1.0.0 > 1.0.0-rc.1). Both are accepted — the installer uses whichever ordering the host produces. Plain release versions (1.30.20 < 1.30.21) are unambiguous.

Architecture

agents-source/<name>.md      → portable Markdown source-of-truth
   ├── compile-agents.mjs    → emit-claude.mjs → plugins/daemux-dev-toolkit/agents/<name>.md
   └──                       → emit-codex.mjs  → codex-sidecar/agents/<name>.toml + plugin payload
   ↓
   bin/cli.mjs --target {claude | codex | both}
   ├── install-claude.mjs (settings, marketplace, hooks, CLAUDE.md sentinel)
   └── install-codex.mjs  (TOML agents, marketplace, hooks, AGENTS.md sentinel, config.toml)

Both compiler outputs are committed to git, so installs work from a plain npm install without a build step. CI gates verify agents-source/ matches the compiled outputs (scripts/check-agents-source-vs-compiled.mjs) and the Codex schema we depend on stays tolerant (scripts/check-codex-schema.mjs).

Included Plugins

daemux-dev-toolkit (Claude Code)

daemux-dev-toolkit-codex (Codex CLI)

Both ship the same eight agents:

• architect - Designs architecture before development
• designer - UI/UX design specs before frontend development
• developer - Code implementation (backend/frontend)
• devops - DevOps operations (deploy, database, server management)
• product-manager - Pre/post-dev validation
• reviewer - Code review after changes
• simplifier - Code simplification
• tester - Testing (backend/frontend/integration)