claude-elixir-phoenix

Elixir Phoenix Plugin for Claude Code

Docs: phxagents.dev -- install guides per runtime, the runtime compatibility matrix, all 26 Iron Laws, and a browsable skill and agent catalog.

Claude Code is great. But it doesn't know that assign_new silently skips on reconnect, that :float will corrupt your money fields, or that your Oban job isn't idempotent.

This plugin does. It coordinates 26 specialist agents that plan, implement, review, and verify your Elixir/Phoenix code in parallel -- each with domain expertise, fresh context, and enforced Iron Laws that catch the bugs your tests won't.

Using Amp? Install the generated edition for the same 51 Elixir, Phoenix, LiveView, Ecto, Oban, testing, and security skills, plus 40 deterministic workflow wrappers, five read-only specialist agents, parallel review/investigation, and native edit/verification guards, and the native PR watch lifecycle plugin. See Use with Amp for the important differences from the full Claude Code plugin, or the Amp install guide on phxagents.dev.

Using Codex? Install the native generated skills plugin for all 51 skills, including $elixir-phoenix:phx-investigate and $elixir-phoenix:phx-review workflows. See Use with Codex or the Codex install guide; a trust-gated destructive-command safeguard is included, while custom agents are intentionally not included and Tidewave MCP registration remains external.

Using Pi? Install the native generated skills package for all 51 skills, including Pi-compatible /skill:phx-investigate and /skill:phx-review workflows. See Use with Pi or the Pi install guide; extensions, prompt templates, MCP, and custom agents are intentionally not included yet. Tidewave can be used when the Pi host exposes it independently.

Using OpenCode? Install the generated skills-only target for all 51 skills, including phx-investigate and phx-review. In the tested OpenCode 1.17.2 setup, they are also available as /phx-investigate and /phx-review; the skill tool is the portable explicit interface. See Use with OpenCode, the OpenCode guide, or the OpenCode install guide.

Using DeepSeek Harness (dsh)? Install the generated skills-only target for all 51 skills. A /phx-investigate or /phx-review token anywhere in your message loads the skill deterministically, and dsh reads your CLAUDE.md natively. See Use with DeepSeek Harness, the dsh guide, or the dsh install guide; hooks and custom agents are intentionally not included, and Tidewave MCP registration is external.

Compare native invocation, installation, and deliberately deferred capabilities in the canonical runtime support matrix. Generated skills support does not imply full Claude Code feature parity.

# You describe the feature. The plugin figures out the rest.
/phx:plan Add real-time comment notifications

# 4 research agents analyze your codebase in parallel.
# A structured plan lands in .claude/plans/comment-notifications/plan.md
# Then:

/phx:work .claude/plans/comment-notifications/plan.md
# Implements task by task. Compiles after each change.
# Stops cold if code violates an Iron Law.

/phx:review
# 4 specialist agents audit in parallel:
# idioms, security, tests, compilation.
# Deduplicates findings. Flags pre-existing issues separately.

No prompt engineering. No "please check for N+1 queries." The plugin auto-loads the right domain knowledge based on what files you're editing and enforces rules that prevent the mistakes Elixir developers actually make in production.

┌─────────────────────────────────────────────────────────────────────┐
│  ⚗  Elixir/Phoenix Plugin for Claude Code                           │
│                                                                     │
│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐           │
│  │    26    │    51    │   140    │    30    │    26    │           │
│  │  Agents  │  Skills  │   Refs   │Hook Regs │Iron Laws │           │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘           │
│                                                                     │
│  AGENTS                          COMMANDS                           │
│  ─────────────────────           ──────────────────────────         │
│  Orchestrators (opus)            Workflow                           │
│    workflow-orchestrator           /phx:plan    /phx:work           │
│    planning-orchestrator           /phx:review  /phx:full           │
│    parallel-reviewer               /phx:compound /phx:quick         │
│    context-supervisor              /phx:brief   /phx:triage         │
│                                                                     │
│  Reviewers (sonnet)              Investigation & Debug              │
│    elixir-reviewer                 /phx:investigate /phx:trace      │
│    testing-reviewer                /ecto:n1-check   /phx:perf       │
│    security-analyzer (opus)        /ecto:constraint-debug           │
│    iron-law-judge                  /lv:assigns                      │
│                                                                     │
│  Architecture (sonnet)           Analysis & Review                  │
│    liveview-architect              /phx:audit    /phx:verify        │
│    ecto-schema-designer            /phx:techdebt /phx:boundaries    │
│    phoenix-patterns-analyst        /phx:pr-review /phx:challenge    │
│    otp-advisor                     /phx:research  /phx:document     │
│                                                                     │
│  Investigation (sonnet/haiku)    Knowledge (auto-loaded)            │
│    deep-bug-investigator           liveview-patterns  ecto-patterns │
│    call-tracer                     elixir-idioms      security      │
│    xref-analyzer                   phoenix-contexts   oban          │
│    verification-runner             testing   deploy   tidewave      │
│                                                                     │
│  Domain (sonnet)                 Hooks                              │
│    oban-specialist                 auto-format · auto-compile       │
│    deployment-validator            iron-law-verify · security-scan  │
│    hex-library-researcher          debug-stmt-detect · error-critic │
│    web-researcher (haiku)          progress-tracking · block-danger │
│                                                                     │
│  ───────────────────────────────────────────────────────────        │
│  26 Iron Laws · Tidewave-aware · plan→work→verify→review→compound   │
│  github.com/oliver-kriska/claude-elixir-phoenix                     │
└─────────────────────────────────────────────────────────────────────┘

v3.0.0 -- all 51 canonical skill trees have generated distributions for Amp, Codex, Pi, OpenCode, and DeepSeek Harness. Nine core workflows are fully adapted: the six flagship lifecycle workflows plus phx-trace, phx-audit, and phx-research. The remaining projections preserve domain knowledge but may require the runtime to translate Claude-specific orchestration. Claude Code remains the full canonical plugin; hooks, agents, MCP, instructions, and workflow portability intentionally vary by runtime. See the support matrix before assuming feature parity. Issues welcome.

Installation

Claude Code

From GitHub (recommended)

# In Claude Code, add the marketplace
/plugin marketplace add oliver-kriska/claude-elixir-phoenix

# Install the plugin
/plugin install elixir-phoenix

Requires Claude Code 2.1.110 or newer. The install name stays elixir-phoenix, while its public workflow commands remain /phx:* — Claude Code namespaces commands by the plugin's manifest name, not its install name. A fresh install also pulls in two small compatibility namespaces for /ecto:* and /lv:* automatically; you do not need to install them separately. After an update, run /reload-plugins before trying the commands in an already-open session.

Updating from v2.x

[!WARNING] Do not run claude plugin update on its own. v3 introduced two compatibility plugins (ecto, lv) that v2 never declared, and claude plugin update does not install dependencies a new version newly declares. The updated plugin then fails to load entirely — you lose all 36 /phx:* commands, not just /ecto:* and /lv:*. Install the two compatibility plugins first, using the exact order below.

claude plugin marketplace update oliver-kriska
claude plugin install ecto@oliver-kriska
claude plugin install lv@oliver-kriska
claude plugin update elixir-phoenix@oliver-kriska

Restart Claude Code afterward. In an already-open session, /reload-plugins reloads the updated skills, agents, and hooks. Confirm that /phx:help, /ecto:n1-check, and /lv:assigns appear before continuing work.

Already updated in the wrong order?

If claude plugin list reports ✘ failed to load with Dependency "ecto@oliver-kriska" is not installed, install the two compatibility plugins to recover — nothing is lost, and no reinstall is needed:

claude plugin install ecto@oliver-kriska
claude plugin install lv@oliver-kriska

Note that claude plugin install elixir-phoenix@oliver-kriska also repairs the state, but resolves only one missing dependency per run, so it needs two invocations here.

Commands are /phx:*, not /elixir-phoenix:*

Plugin versions before v3.0.0 shipped a manifest named elixir-phoenix, so their commands resolved as /elixir-phoenix:work even though /phx:init wrote /phx:* into CLAUDE.md. v3.0.0 renamed the manifest to phx, which is what makes /phx:* correct. If Claude Code reports /phx: commands as unknown, you are on a pre-v3 version — follow the upgrade steps above, then re-run /phx:init --update.

Claude Code subagent compatibility

No configuration is required. Claude Code 2.1.219+ defaults to a maximum subagent spawn depth of 3, so /phx:full, deep /phx:plan, parallel /phx:investigate, and /phx:trace can use their nested orchestrators. Claude Code 2.1.217–2.1.218 defaulted to depth 1; on those versions, or when you explicitly configure depth 1–2, the workflows keep orchestration in the main conversation and spawn leaf specialists directly. They preserve the same decisions, artifacts, verification, and review gates; only the agent topology changes.

To explicitly enable the full nested topology, start Claude Code with depth 3:

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3 claude

Depth 2 is sufficient for /phx:trace's call-tracer alone. This must be set in the environment that starts Claude Code; a plugin hook cannot change its parent process environment.

Multi-stack tip — project-scope enable. This plugin is opinionated for Elixir/Phoenix. If you work across multiple language stacks, prefer enabling it per-project rather than globally — drop this into <project>/.claude/settings.json:

{ "enabledPlugins": { "elixir-phoenix@oliver-kriska": true } }