elixir-phoenix-guide

Elixir Phoenix Guide for Claude Code and Codex

· Changelog

A Claude Code plugin (with Codex support for the skills) that keeps Claude's Elixir and Phoenix code idiomatic and current. It ships 24 skills checked against Phoenix 1.8's generators, plugin-native hooks that catch dangerous commands and risky code as Claude writes it, and on-demand analysis scripts.

v2.6.0 — five new skills, each verified against the library source and a generated Phoenix 1.8 app: Phoenix 1.8 scopes and generators, Tailwind v4 + daisyUI, zero-downtime Ecto migrations, Ecto query performance, and HTTP clients with Req. Codex installs the plugin directly with codex plugin add. See CHANGELOG.md.

What's Included

Skills (24)

Each skill opens with a RULES section and a "Verified against" line naming the library versions it was checked against. Skills load on demand when Claude's task matches their description.

• elixir-essentials - Pattern matching, with, error contracts, modern Elixir (1.18+): type checker, JSON, dbg; Phoenix project layout reference
• phoenix-liveview-essentials - Lifecycle, forms (to_form, phx-change), streams, assign_async/start_async, JS commands, colocated hooks; LiveView checklist and JS interop references
• ecto-essentials - Scoped context functions, schemas, queries, migrations, upserts, Repo.transact; Ecto reference
• phoenix-uploads - allow_upload, content-type allowlists, magic-byte checks, external uploads, authorized downloads
• testing-essentials - DataCase/ConnCase, generated fixtures and scopes, LiveView helpers, Mox, Req.Test; testing reference
• otp-essentials - GenServer, Supervisor, Task, Registry, ETS, PartitionSupervisor, timeouts
• oban-essentials - Workers, uniqueness, transactional enqueue, Oban 2.24 plugin config, Lifeline, Oban.Testing
• code-quality - Compiler and Credo first, then on-demand duplication and branch-complexity scans
• phoenix-liveview-auth - The generated UserAuth: on_mount, live_session, mount_current_scope, sudo mode, logout disconnects
• ecto-changeset-patterns - Separate changesets per operation, password/email rules, never casting privileged fields
• phoenix-auth-customization - Adding fields to the phx.gen.auth user, registration changeset, fixtures
• phoenix-pubsub-patterns - Scoped topics, broadcasting from contexts, streams in handle_info, Presence in LiveView
• phoenix-authorization-patterns - %Scope{}-first contexts, ownership checks, policies, mass-assignment safety
• ecto-nested-associations - cast_assoc/cast_embed, inputs_for sort/drop params, on_replace, cascades, Multi
• security-essentials - Injection, XSS, SSRF, open redirects (external:), CSP, safe deserialization, Sobelow
• deployment-gotchas - mix phx.gen.release --docker, runtime.exs, release migrations, SSL, rolling deploys, health checks
• phoenix-channels-essentials - Socket auth and tokens, join authorization, intercept/handle_out, Presence
• telemetry-essentials - Logger metadata, telemetry handlers, metric tag cardinality, OpenTelemetry, LiveDashboard
• phoenix-json-api - phx.gen.json-style JSON views, FallbackController, keyset pagination, hashed API tokens, rate limits

New in 2.6.0:

• phoenix-scopes-and-generators - Phoenix 1.8 scopes: the generated %Scope{} and config :scopes keys, phx.gen.* with --scope/--no-scope, adding an org scope (config entry, plug + on_mount, test helpers), adopting scopes in pre-1.8 apps
• phoenix-tailwind-daisyui - Tailwind v4 in app.css (@source, @plugin, no tailwind.config.js), dynamic class names, daisyUI themes and dark mode, extending core_components (<.input>, <.button>, <.icon>, <.table>), Layouts.app/flash, accessibility
• ecto-migrations-safety - Zero-downtime PostgreSQL migrations: concurrent indexes, migration locks, lock_timeout, NOT NULL/foreign keys via NOT VALID, batched backfills, expand-and-contract renames
• ecto-queries-performance - N+1 and preload strategy, dynamic/subquery/exists composition, counting, Repo.stream, locking and optimistic locking, insert_all bulk upserts, EXPLAIN, query-driven indexes, prepare_query tenancy guards
• http-clients-req - Calling external APIs with Req 0.7: client modules, retries/Retry-After, timeouts, idempotency keys, JSON bodies, SSRF-safe redirects, Finch pools, Req.Test/Mox, telemetry and circuit breaking

Longer reference material lives next to the skill that uses it (skills/<skill>/*.md) and Claude reads it only when needed.

Hooks (ship inside the plugin)

Hooks live in hooks/hooks.json and activate when the plugin is installed. They need jq.

Event	Check	Result
SessionStart	Project summary for Claude: Phoenix/LiveView versions (locked and required), scopes, Ecto adapter, Oban, umbrella apps; warns when jq is missing	context
PreToolUse (Bash)	mix ecto.reset / mix ecto.drop unless MIX_ENV=test	block
PreToolUse (Bash)	git push --force, -f, -uf, +refspec (--force-with-lease and --force-if-includes allowed)	block
PostToolUse (Write/Edit)	Interpolated SQL in Repo.query/SQL.query or fragment(); redirect(external: params…); removed/deprecated APIs (form_for, live_redirect, live_patch, push_redirect)	block
PostToolUse (Write/Edit)	String.to_atom/1, raw/1, Logger interpolating secrets, IO.inspect/dbg, timing-unsafe == on secrets, missing @impl true, migration FK without index or on_delete, @current_user in a scopes app	review

• block — exit 2 with the reason on stderr; Claude must deal with it (for Bash, the command doesn't run).
• review — an advisory note (additionalContext); Claude decides, nothing is blocked.
• File checks report only the lines that tool call changed, ignore comments and @doc text, and skip tests, deps/, _build/ and node_modules/.
• The Bash guard runs only in Elixir projects. To run a blocked command deliberately, prefix it with EPG_ALLOW=force_push (or ecto_reset, ecto_drop) or set that variable in Claude Code's environment.

See INSTALL-HOOKS.md for details and known limits.

Analysis Scripts

Shipped with the plugin under scripts/ and run on demand (the code-quality skill tells Claude how):

• code_quality.exs - Duplicate function bodies across the whole tree (names and variables ignored) and branch complexity. For unused code, use mix compile --warnings-as-errors and mix xref.
• run_analysis.sh - Runs the scans over lib/ (or apps/*/lib in an umbrella)
• detect_project.sh - Project stack detection used by the SessionStart hook

Project Template

• CLAUDE.md.template - Project-specific instructions template

Installation

Note: Official marketplace publication is in progress. Once available, installation will be even simpler through the official Claude Code marketplace.

Installing for the First Time

In a Claude Code session:

# Step 1: Add the marketplace (first time only)
/plugin marketplace add j-morgan6/elixir-phoenix-guide

# Step 2: Install the plugin
/plugin install elixir-phoenix-guide@elixir-phoenix-guide

Skills and hooks activate automatically — nothing else to configure. Optional extras (the CLAUDE.md project template, cleanup of legacy pre-2.4.0 installs) are available via ./install.sh from a checkout:

git clone https://github.com/j-morgan6/elixir-phoenix-guide.git
cd elixir-phoenix-guide
./install.sh

Codex

The skills also work in OpenAI Codex (hooks are Claude Code only). Install them as a Codex plugin:

codex plugin marketplace add j-morgan6/elixir-phoenix-guide
codex plugin add elixir-phoenix-guide@elixir-phoenix-guide

Codex reads the same marketplace as Claude Code and the manifest in .codex-plugin/plugin.json, and loads every skill with its reference files. To update, upgrade the marketplace (codex plugin marketplace upgrade elixir-phoenix-guide) and re-add the plugin.

Without the plugin system, ./install-codex.sh from a checkout copies the skill directories into ${CODEX_HOME:-~/.codex}/skills instead (keep the checkout: the code-quality skill runs its scripts from there).

Updating to Latest Version

If you already have the plugin installed:

# Open the interactive plugin manager
/plugin

# Select "Marketplaces" → "elixir-phoenix-guide" → "Update"
# Then update the plugin from the menu

See CHANGELOG.md for full release notes and version history.

Usage

Once installed, Claude Code will automatically:

1. Load skills when the task matches a skill's description
2. Run hooks on Bash commands and file writes - blocking dangerous commands and flagging risky code
3. Read a skill's reference files when a task needs the detail
4. Follow CLAUDE.md (if present) - respecting project-specific conventions

Example Interactions

Before (without optimization):

def process(user) do
  if user.status == :active do
    if user.role == :admin do
      :allowed
    else
      :denied
    end
  else
    :inactive
  end
end

After (with skills guiding idiomatic Elixir):

• Skill suggests pattern matching over nested conditionals
• Claude generates:

def process(%{status: :active, role: :admin}), do: :allowed
def process(%{status: :active}), do: :denied
def process(_), do: :inactive

Testing the Setup

1. Open a Phoenix/Elixir project in Claude Code
2. Ask Claude to create a LiveView
3. Observe:
   • Skills guide idiomatic implementation
   • Hooks flag anti-patterns in the lines Claude wrote (missing @impl, security issues, Phoenix deprecations)
   • The LiveView checklist is used before finishing

What This Optimizes

Code Quality

• Blocks destructive Bash commands (mix ecto.reset/ecto.drop outside test, force pushes)
• Blocks near-certain bugs in written code: SQL built by interpolation, redirect(external:) from params, removed Phoenix APIs
• Flags for review: String.to_atom/1, raw/1, secrets in Logger interpolation, timing-unsafe comparisons, debug calls, missing @impl true, migration FK indexes and on_delete, @current_user in scope-based apps
• Scans on demand for duplicated function bodies and branch complexity

Developer Experience

• Proactive guidance on Elixir idioms
• Real-time feedback on code quality
• Detailed checklists for complex features
• Consistent conventions across projects
• Reduced iterations and corrections

Learning

• Clear explanations of "why" not just "what"
• Links to relevant patterns and best practices
• Progressive disclosure of complexity
• Examples of idiomatic vs non-idiomatic code

Why This Exists

This plugin was created to ensure Claude Code consistently produces idiomatic Elixir and Phoenix code by making best practices impossible to ignore, not just available. It combines enforced patterns, real-time validation, and comprehensive guidance for all Elixir development work.

Project-Specific Setup

For project-specific instructions, you can create a CLAUDE.md file in your project root with:

• Your app name and description
• Project-specific contexts
• Custom commands and workflows
• Team conventions

This file will be automatically loaded by Claude Code when working in your project.

File Structure