# phxagents

> Elixir & Phoenix skills, agents, and commands for AI coding agents — one canonical skill set across Claude Code, Amp, Codex, Pi, OpenCode, and DeepSeek Harness.

## Getting started

- [Install](https://phxagents.dev/install/): Install phxagents for Claude Code, Amp, Codex, Pi, OpenCode, or DeepSeek Harness.
- [Runtime compatibility](https://phxagents.dev/compatibility/): Compare supported and deferred phxagents capabilities across six AI coding runtimes.
- [Iron Laws](https://phxagents.dev/iron-laws/): Non-negotiable rules that prevent the bugs Elixir tests don't catch.
- [Hooks](https://phxagents.dev/hooks/): The deterministic layer: shell scripts that always run, across every Claude Code lifecycle event — blocking destructive mix commands, verifying Iron Laws, and injecting context models cannot read themselves.

## Runtime guides

- [Install for Amp](https://phxagents.dev/install/amp/): Install and use all phxagents skills as Amp Agent Skills.
- [Install for Codex](https://phxagents.dev/install/codex/): Install phxagents as a native Codex skills plugin.
- [Install for Pi](https://phxagents.dev/install/pi/): Install phxagents through Pi’s native Git package support.
- [Install for OpenCode](https://phxagents.dev/install/opencode/): Install the generated phxagents skill tree for OpenCode.
- [Install for DeepSeek Harness](https://phxagents.dev/install/dsh/): Install the generated phxagents skill tree for DeepSeek Harness (dsh).

## Documentation

- [Catalog](https://phxagents.dev/catalog/): All skills and agents, searchable and filterable.
- [Tidewave MCP](https://phxagents.dev/tidewave-mcp/): Use Tidewave runtime introspection with phxagents in a running Phoenix application.
- [Changelog](https://phxagents.dev/changelog/): Release notes for the phxagents plugin.
- [Origin](https://phxagents.dev/origin/): Every file in this plugin started as generated output. What the sessions, the tests and the eval framework measured afterwards, including the parts that did not survive.
- [Research](https://phxagents.dev/research/): Independent measurement of the Elixir ecosystem, published with method, limits and a raw Markdown twin.
- [Hooks: Safety gates](https://phxagents.dev/hooks/safety-gates/): The three PreToolUse hooks that stop an action outright — destructive mix commands, the dependency supply-chain gate, and edit-scope freezes — plus the fail-open contract behind them.
- [Hooks: Code quality](https://phxagents.dev/hooks/code-quality/): The four PostToolUse hooks that scan what Claude just wrote: seven verified Iron Laws, blame-aware line scanning, debug-statement flagging, and why formatting only ever warns.
- [Hooks: Failure recovery](https://phxagents.dev/hooks/failure-recovery/): Two PostToolUseFailure hooks that escalate from per-command hints to a structured critic, consolidating the error history to stop Claude retrying the same failing mix command.
- [Hooks: Context injection](https://phxagents.dev/hooks/context-injection/): Intent routing on prompt submit and Iron Law injection into every spawned subagent — the two hooks built because prose rules in CLAUDE.md measurably do not fire.
- [Hooks: Session lifecycle](https://phxagents.dev/hooks/session-lifecycle/): The six SessionStart hooks: directory setup, Tidewave and Ash detection, scratchpad dead ends, plan resume, and branch freshness — all gated on mix.exs.
- [Hooks: Workflow state](https://phxagents.dev/hooks/workflow-state/): Six hooks that keep the plan workflow coherent across the things that normally destroy it — the plan STOP, compaction re-injection, and the StopFailure breadcrumb.
- [Hooks: Writing a hook](https://phxagents.dev/hooks/contributing/): Which output channel actually reaches Claude for each of the ten lifecycle events, the seven conventions every hook script follows, and how to add one.
- [Elixir SEO/AIO research](https://phxagents.dev/research/elixir-retrieval-gap/): Independent SEO/AEO/GEO audit of 85 Elixir ecosystem resources, 283 Hex packages and 287 repositories — why 69.3% of Hex download volume is invisible to markdown retrieval.

## Skills

### Phoenix workflows · phx:

- [phx:audit](https://phxagents.dev/skills/audit/): Project health audit and health check — architecture, performance, tests, dependencies, code quality. Use when assessing overall project health, before releases, or after refactors.
- [phx:boundaries](https://phxagents.dev/skills/boundaries/): Analyze Phoenix context boundaries and module coupling via mix xref. Use when checking cross-context calls, validating dependencies, before splitting modules, or reviewing architecture.
- [phx:brainstorm](https://phxagents.dev/skills/brainstorm/): Brainstorm Elixir/Phoenix features — explore ideas, compare approaches, gather requirements. Use when vague idea, not sure how to approach, or want to discuss before plan.
- [phx:brief](https://phxagents.dev/skills/brief/): Interactive briefing of a plan file — explains reasoning, schema decisions, component choices. Use when developers need to understand a plan before approving.
- [phx:challenge](https://phxagents.dev/skills/challenge/): Challenge mode reviews - rigorous questioning before approving changes. Use when you want thorough scrutiny of Ecto changes, LiveView events, OTP designs, or PR readiness.
- [phx:codex-loop](https://phxagents.dev/skills/codex-loop/): Fix Elixir/Phoenix code until Codex CLI review comes back clean — bounded review, fix, verify loop before opening a PR. Use when codex is installed and you want an external cross-model critic on your changes before pushing.
- [phx:compound](https://phxagents.dev/skills/compound/): Capture solved problems as searchable solution docs. Use after fixing bugs, when "that worked", or after successful /phx:review or /phx:investigate.
- [phx:deps-audit](https://phxagents.dev/skills/deps-audit/): Audit Hex deps for supply-chain security risk — bidi chars, compile-time exec, maintainer changes, typosquats, CVEs. Use after mix deps.update, when checking if a package upgrade is safe, or reviewing mix.lock PR diffs.
- [phx:deps-update](https://phxagents.dev/skills/deps-update/): Bump outdated Hex deps — inventory, snapshot changelogs, update, fix breaks, split reviewable PRs (patches bundled, majors solo). Use to upgrade/bump Elixir dependencies or when versions fall behind. NOT for deps.get failures (/phx:investigate).
- [phx:deps-vet](https://phxagents.dev/skills/deps-vet/): Record a vetted Hex package version in hex_vet.exs after a security review — manages the audit ledger, not the scanner. Use to approve a dep after /phx:deps-audit findings or to initialize hex_vet.exs.
- [phx:document](https://phxagents.dev/skills/document/): Generate @moduledoc/@doc for tested Elixir features; may update their README section or ADR. Not for docs lookup, documentation audits/reviews, or capturing standalone decisions.
- [phx:examples](https://phxagents.dev/skills/examples/): Provide Phoenix, LiveView, Ecto, OTP, or Oban examples. Use when asked for sample code, a walkthrough, a proper implementation, or expected workflow output. Pair with domain skills. NOT for debugging, direct changes, best-practice advice, or audits.
- [phx:freeze](https://phxagents.dev/skills/freeze/): Scope or freeze which files Claude can edit during debugging, a refactor, or review. Use when edits should stay in specific dirs, or for a read-only investigate lock. Backed by a sentinel + PreToolUse hook.
- [phx:full](https://phxagents.dev/skills/full/): Deliver a large, cross-domain Phoenix feature or complete end-to-end system through planning, implementation, verification, and review. Use when several coordinated workflows or contexts must ship together. NOT for an existing plan; use /phx:work.
- [phx:help](https://phxagents.dev/skills/help/): Choose Phoenix review, plan, debug, or test command. Use when user asks which /phx: command or plugin skill handles a task; do not route only to a domain skill. NEVER for bare /help; NOT for ambiguous requests (use intent-detection) or a plugin tour.
- [phx:init](https://phxagents.dev/skills/init/): Initialize plugin in a project — install Iron Laws, auto-activation rules, and reference auto-loading into CLAUDE.md. Use when setting up or updating the plugin.
- [phx:intro](https://phxagents.dev/skills/intro/): Walk through the Elixir/Phoenix plugin commands, workflow, and features in 6 interactive sections. Use when a new user wants to learn what the plugin offers or needs a refresher on available commands.
- [phx:investigate](https://phxagents.dev/skills/investigate/): Investigate bugs and errors in Elixir/Phoenix — root-cause analysis for crashes, exceptions, stack traces, test failures. Use --parallel for deep 4-track investigation.
- [phx:learn-from-fix](https://phxagents.dev/skills/learn-from-fix/): Capture Elixir/Ecto/LiveView lessons and Hex API rules. Use after corrections or when asked to document learning, record a lesson, prevent a fixed mistake, or remember package guidance with --library.
- [phx:mix-compression](https://phxagents.dev/skills/mix-compression/): Reduce mix output noise (5-15% token savings) by installing rtk filters that compress mix test/credo/dialyzer/compile output before it reaches Claude. Use when long mix output floods context.
- [phx:perf](https://phxagents.dev/skills/perf/): Analyze Elixir/Phoenix performance — N+1 queries, assign bloat, ecto optimization, genserver bottlenecks. Use when slowness, timeouts, or high memory reported.
- [phx:permissions](https://phxagents.dev/skills/permissions/): Recommend safe Bash permissions for Elixir mix commands in settings.json. Use when permission prompts slow workflow, "fix permissions", "reduce prompts", "auto-allow mix".
- [phx:plan](https://phxagents.dev/skills/plan/): Plan features spanning multiple domains: billing (Stripe), auth (RBAC), real-time (Presence), webhooks, jobs (Oban). Use when designing interconnected systems or converting review findings into tasks.
- [phx:pr-review](https://phxagents.dev/skills/pr-review/): Address feedback left on a GitHub pull request: fetch unresolved review threads, make agreed Elixir/Phoenix code fixes, reply, and resolve. Use for a PR URL/number or reviewer comments. NOT for pre-PR review, findings triage, or CI monitoring.
- [phx:quick](https://phxagents.dev/skills/quick/): Implement small Phoenix changes without planning — add validations, update routes, fix components, create migrations. Use for single-file edits under 50 lines.
- [phx:recall](https://phxagents.dev/skills/recall/): Recall prior work from past sessions — how a bug was fixed, what was decided, where a pattern lives. Use when asked 'have we done this before' or 'how did I fix X' in Elixir/Phoenix work. ccrider MCP when available, else git + solution docs.
- [phx:research](https://phxagents.dev/skills/research/): Research Elixir/Phoenix/Ecto topics or evaluate Hex libraries (--library). Use when learning about libraries, patterns, or comparing approaches. Searches HexDocs, ElixirForum, GitHub.
- [phx:review](https://phxagents.dev/skills/review/): Review code with parallel agents — tests, security, Ecto, LiveView, Oban. Use after implementation to catch bugs and anti-patterns before committing.
- [phx:techdebt](https://phxagents.dev/skills/techdebt/): Analyze Elixir/Phoenix technical debt — duplicates, refactoring opportunities, credo issues. Use when asked about code quality, cleanup, or what to improve.
- [phx:trace](https://phxagents.dev/skills/trace/): Trace Elixir call trees from entry points via mix xref. Use when debugging data flow, planning signature changes, or understanding how a bug reaches code.
- [phx:triage](https://phxagents.dev/skills/triage/): Triage review findings interactively — approve, skip, or prioritize each issue. Use after /phx:review to filter findings before fixing.
- [phx:verify](https://phxagents.dev/skills/verify/): Verify Elixir/Phoenix changes — compile, format, and test in one loop. Use after implementation, before PRs, or after fixing bugs.
- [phx:watch-pr](https://phxagents.dev/skills/watch-pr/): Watch an Elixir/Phoenix PR for new review comments (bot + human) and CI results via a background watcher that wakes Claude only on real events. Use after opening a PR or pushing, while waiting on CI or reviewers.
- [phx:work](https://phxagents.dev/skills/work/): Execute Elixir/Phoenix plan tasks with progress tracking. Use after /phx:plan to implement features with mix compile and mix test verification after each step, or --continue to resume interrupted work.

### LiveView · lv:

- [lv:assigns](https://phxagents.dev/skills/assigns-audit/): Inspect LiveView socket assigns for memory bloat — missing temporary_assigns, unused assigns, unbounded lists needing streams, memory estimates. Use when LiveView memory grows or you need to add temporary_assigns.

### Ecto · ecto:

- [ecto:constraint-debug](https://phxagents.dev/skills/ecto-constraint-debug/): Debug Ecto constraint violations - trace triggers, check migrations, find duplicate data. Use when seeing unique_constraint, foreign_key_constraint, or check_constraint errors.
- [ecto:n1-check](https://phxagents.dev/skills/n1-check/): Detect N+1 query anti-patterns specifically — Repo calls inside Enum/for loops, missing preloads on associations. Use when N+1 is explicitly suspected, NOT for unrelated Ecto questions or wider database performance.

### Reference skills

- [ash-framework](https://phxagents.dev/skills/ash-framework/): Ash Framework — resources, actions, policies, aggregates, calculations, AshPhoenix.Form, LiveView, migrations. Use when generating resources via mix ash.codegen, editing changes, checks, types, validations, or domain code interfaces.
- [compound-docs](https://phxagents.dev/skills/compound-docs/): Searchable Elixir/Phoenix/Ecto solution documentation system with YAML frontmatter. Builds institutional knowledge from solved problems. Use when consulting past solutions before investigating new issues.
- [deploy](https://phxagents.dev/skills/deploy/): Elixir/Phoenix deployment patterns — Dockerfile, fly.toml, runtime.exs, mix release, rel/ overlays. Use when configuring Fly.io, Docker, CI/CD, health checks, or production migrations.
- [ecto-patterns](https://phxagents.dev/skills/ecto-patterns/): Ecto patterns — schemas, changesets, queries, migrations, Multi, associations, preloads, upserts. Use when editing Repo calls, Ecto.Query, or schema fields. Skip for Ash.
- [elixir-idioms](https://phxagents.dev/skills/elixir-idioms/): OTP/BEAM patterns and Elixir idioms — GenServer, Supervisor, Task, Registry, pattern matching, with chains, pipes. Use when designing processes or debugging BEAM issues.
- [hexdocs-fetcher](https://phxagents.dev/skills/hexdocs-fetcher/): Fetch HexDocs for Elixir libraries with HTML-to-markdown conversion. Use when looking up docs on hexdocs.pm — modules, functions, guides, changelogs.
- [intent-detection](https://phxagents.dev/skills/intent-detection/): Route ambiguous or mixed Phoenix/LiveView/Ecto requests before choosing a workflow. Use when user is unsure where to start/how to approach work, asks for the right workflow, or combines intents such as fixing and refactoring. NOT for a clear task.
- [liveview-patterns](https://phxagents.dev/skills/liveview-patterns/): Build LiveView: async data (assign_async), PubSub (check connected?), phx-change events, form components/modals/uploads, streams for lists, live_patch. Use when handling interactions, debugging events, or tracking Presence.
- [narrow-bare-rescue](https://phxagents.dev/skills/narrow-bare-rescue/): Narrow bare rescue in Elixir so real errors like KeyError and typos propagate instead of being swallowed. Use to audit rescues and refactor error handling.
- [oban](https://phxagents.dev/skills/oban/): Oban job processing — workers, perform/1 (OSS) and process/1 (Pro), queues, cron, retries, unique jobs, idempotency, Oban Pro (Workflow, Batch, Chunk, Smart Engine), Testing. Use when writing Oban workers, queue config, or debugging jobs.
- [phoenix-contexts](https://phxagents.dev/skills/phoenix-contexts/): Phoenix context design — creating/splitting contexts, Scope (1.8+), Ecto.Multi, PubSub, routers, plugs, controllers. Use when editing contexts, routers, or designing boundaries.
- [security](https://phxagents.dev/skills/security/): Enforce Elixir/Phoenix security — auth, OAuth, sessions, CSRF, XSS, SQL injection, input validation, secrets. Use when editing auth files, login flows, RBAC, or API keys.
- [testing](https://phxagents.dev/skills/testing/): Write or repair Elixir tests with ExUnit, sandbox isolation, async reliability, Mox, ExMachina, and LiveViewTest. Use for test files, test setup, or failing/flaky tests. NOT for investigating an application bug outside the test suite.
- [tidewave-integration](https://phxagents.dev/skills/tidewave-integration/): Tidewave MCP runtime tools — debugging, smoke testing, live state inspection, SQL queries, hex docs. Use when evaluating code in a running Phoenix app.

## Agents

- [ash-policy-reviewer](https://phxagents.dev/agents/ash-policy-reviewer/): Ash policy security reviewer — audits policies, checks, and authorization rules for gaps, bypass patterns, and ordering hazards. Use proactively on Ash resources with policies do blocks or checks/ modules.
- [ash-query-optimizer](https://phxagents.dev/agents/ash-query-optimizer/): Ash query optimizer — detects N+1 loads, suggests aggregates over load+Enum, identifies calculation vs load tradeoffs. Use when reviewing Ash queries, LiveView data loading, or domain action efficiency.
- [ash-resource-designer](https://phxagents.dev/agents/ash-resource-designer/): Ash resource architect — designs resources the "Ash Way" with built-in changes, validations, types, and policy checks before hand-rolling. Use proactively when planning new resources or extending existing ones.
- [call-tracer](https://phxagents.dev/agents/call-tracer/): Orchestrates parallel call tree tracing using subagents for each entry point category (Controllers, LiveViews, Workers, GenServers). Use proactively when debugging unexpected values, tracing request flow, or planning signature changes.
- [codex-reviewer](https://phxagents.dev/agents/codex-reviewer/): Run OpenAI Codex CLI code review and normalize findings into review panel format. Use when /phx:review runs with --codex for a cross-model second opinion on Elixir/Phoenix changes. Requires codex CLI; degrades to SKIPPED note.
- [context-supervisor](https://phxagents.dev/agents/context-supervisor/): Compresses multi-agent output into consolidated summaries to prevent context exhaustion. Generic — works for any orchestrator. Use after sub-agents complete and before parent synthesis.
- [deep-bug-investigator](https://phxagents.dev/agents/deep-bug-investigator/): Deep bug investigation using 4 parallel subagents (reproduction, root cause, impact, fix strategy). Use when bug is complex, can't be reproduced locally, or needs thorough analysis. Spawns fresh-context subagents for each investigation track.
- [deployment-validator](https://phxagents.dev/agents/deployment-validator/): Deployment configuration validator - releases, Docker, Kubernetes, Fly.io. Use proactively before deploying to production.
- [ecto-schema-designer](https://phxagents.dev/agents/ecto-schema-designer/): Ecto schema architect - designs migrations, data models, and query patterns. Use proactively when planning database structure for new features.
- [elixir-reviewer](https://phxagents.dev/agents/elixir-reviewer/): Expert Elixir/Phoenix code reviewer - idioms, patterns, performance, conventions. Use proactively after writing Elixir code.
- [hex-deps-triager](https://phxagents.dev/agents/hex-deps-triager/): Triage Hex supply-chain audit findings in Elixir/Phoenix — review diff windows and metadata to produce structured security verdicts. Use after /phx:deps-audit.
- [hex-library-researcher](https://phxagents.dev/agents/hex-library-researcher/): Researches Elixir libraries on hex.pm. Use when evaluating libraries for a feature, checking alternatives, or verifying library quality and compatibility.
- [iron-law-judge](https://phxagents.dev/agents/iron-law-judge/): Checks code for Iron Law violations using pattern analysis. Use proactively after code changes or as part of review.
- [liveview-architect](https://phxagents.dev/agents/liveview-architect/): LiveView architecture specialist - component structure, real-time patterns, streams vs assigns, async patterns. Use proactively when planning interactive features.
- [oban-specialist](https://phxagents.dev/agents/oban-specialist/): Oban worker specialist - reviews idempotency, error handling, and production safety. Use proactively when implementing or reviewing background jobs.
- [otp-advisor](https://phxagents.dev/agents/otp-advisor/): OTP patterns specialist - GenServer, Supervisor, Agent, Task, Registry, ETS. Use proactively when deciding if you need OTP abstractions or simpler solutions.
- [parallel-reviewer](https://phxagents.dev/agents/parallel-reviewer/): Parallel code review using 4 specialist agents (elixir-reviewer, security-analyzer, testing-reviewer, verification-runner). Use for thorough review of significant changes.
- [phoenix-patterns-analyst](https://phxagents.dev/agents/phoenix-patterns-analyst/): Analyzes codebase for existing Phoenix patterns, contexts, module structure, scopes, plugs, and routing. Use proactively when planning features to understand current conventions.
- [planning-orchestrator](https://phxagents.dev/agents/planning-orchestrator/): Fans out and compresses parallel Elixir/Phoenix planning research (codebase patterns, libraries, schema/OTP/LiveView design) into one digest. Use when /phx:plan needs 3+ research agents; returns findings only, never plans or asks the user.
- [requirements-verifier](https://phxagents.dev/agents/requirements-verifier/): Cross-check implementation against task requirements (Linear issue, GitHub issue, plan, spec). Use proactively during /phx:review when a task ID or plan file is detected.
- [security-analyzer](https://phxagents.dev/agents/security-analyzer/): Security audit specialist for Elixir/Phoenix - authentication, authorization, input validation, OWASP vulnerabilities. Use proactively when implementing auth or handling user input.
- [testing-reviewer](https://phxagents.dev/agents/testing-reviewer/): Reviews test code for Elixir best practices - ExUnit patterns, Mox usage, LiveView testing, factory patterns. Use proactively after writing tests or during code review.
- [verification-runner](https://phxagents.dev/agents/verification-runner/): Run project-aware verification loop. Reads mix.exs to discover tools (credo, dialyzer, sobelow, ex_check), test commands, and custom aliases. Use proactively after code changes.
- [web-researcher](https://phxagents.dev/agents/web-researcher/): Fetches and extracts information from web sources efficiently. Optimized for ElixirForum, HexDocs, and GitHub. Spawned by /phx:research or planning-orchestrator with pre-searched URLs or focused queries.
- [workflow-orchestrator](https://phxagents.dev/agents/workflow-orchestrator/): Orchestrates the full agentic workflow cycle (plan → work → review). Internal use by /phx:full command.
- [xref-analyzer](https://phxagents.dev/agents/xref-analyzer/): Analyze module dependencies and context boundaries using mix xref. Use proactively before major refactors or when reviewing architectural changes.