Elixir Agent Tools

Elixir development guidance for coding agents, with optional Mix checks and Expert language server integration.

Install the elixir-dev plugin for five skills covering language idioms, Phoenix interfaces, Ecto persistence, OTP processes, and Oban jobs. Add the tooling plugins when you want automatic checks or code navigation.

Choose your plugins

The skills are Markdown instructions and need no local Elixir installation to load. Running the project's code still requires its normal development environment. The Mix hooks support macOS and Linux, including WSL on Windows. They use Bash 3.2+, standard Unix tools, and the OS file-lock utility: lockf on macOS or flock on Linux/WSL. JSON parsing is bundled, so the Mix hooks need no jq, Python, uv, or newer Elixir version.

Installation

Claude Code

Add the marketplace and install the skills:

claude plugin marketplace add georgeguimaraes/elixir-agent-tools
claude plugin install elixir-dev@elixir-agent-tools

Install any optional tools you want:

claude plugin install mix-format@elixir-agent-tools
claude plugin install mix-compile@elixir-agent-tools
claude plugin install mix-credo@elixir-agent-tools
claude plugin install elixir-lsp@elixir-agent-tools

Both Claude Code and Codex use the marketplace ID elixir-agent-tools and the skills plugin name elixir-dev.

Codex plugin

Register the marketplace from your terminal:

codex plugin marketplace add georgeguimaraes/elixir-agent-tools

In Codex, open /plugins, select the Elixir Agent Tools marketplace, and install Elixir Development. You can also install directly from the terminal:

codex plugin add elixir-dev@elixir-agent-tools

Start a new session to use the five bundled skills. The Codex plugin contains the same skill files as the Claude Code plugin.

Install any optional Mix checks you want:

codex plugin add mix-format@elixir-agent-tools
codex plugin add mix-compile@elixir-agent-tools
codex plugin add mix-credo@elixir-agent-tools

Use /hooks in Codex to review and trust the installed hook commands. Codex requires hook trust separately from plugin installation. See the Codex hooks documentation. The Expert LSP plugin remains Claude Code only.

To try unpublished changes from a local checkout, register that directory instead of the GitHub repository:

codex plugin marketplace add /path/to/elixir-agent-tools
codex plugin add elixir-dev@elixir-agent-tools

Codex and other agents with npx skills

Use the Skills CLI to install all five skills into your current project for Codex:

npx skills add georgeguimaraes/elixir-agent-tools -a codex --skill '*'

Add -g to make them available across projects. To choose individual skills, replace --skill '*' with names such as --skill phoenix ecto. Use -a opencode for OpenCode or -a claude-code for a skills-only Claude Code installation.

To preview the available skills without installing:

npx skills add georgeguimaraes/elixir-agent-tools --list

This installs standalone skill files. Choose either this method or the native plugin to avoid duplicate skills. Install Mix hooks through the native Claude Code or Codex plugin commands above. The LSP plugin uses Claude Code's plugin installation.

Manual skills installation

Both Codex and OpenCode discover personal skills under ~/.agents/skills. Clone this repository into a persistent location and link each skill:

git clone https://github.com/georgeguimaraes/elixir-agent-tools.git "$HOME/.local/share/elixir-agent-tools"
mkdir -p "$HOME/.agents/skills"
for skill in elixir phoenix ecto otp oban; do
  ln -s "$HOME/.local/share/elixir-agent-tools/plugins/elixir-dev/skills/$skill" "$HOME/.agents/skills/$skill"
done

If a destination already exists, inspect it before replacing it. Start a new session after installation. Updating the clone updates the linked skills.

For other harnesses with Agent Skills support, install the individual folders from plugins/elixir-dev/skills/ in that harness's skill directory. Mix hooks are packaged for Claude Code and Codex. Other harnesses need an adapter for their edit events.

Elixir skills

Each skill has its own discovery description. The agent can load several skills for a task that crosses domains, such as a LiveView form backed by an Ecto changeset. There is no startup hook or mandatory routing skill.

OTP covers work and state managed by running processes. Oban covers jobs that need persistence, retry policies, or scheduling. Phoenix owns interface behavior, while Ecto owns the persistence behind it.

Upgrading to elixir-dev 3.0

Skill names now use their domain directly: elixir, phoenix, ecto, otp, and oban. Remove the -thinking suffix from explicit skill references in your prompts and agent instructions. The using-elixir-skills router and its startup hook have been removed.

The plugin is now named elixir-dev and the marketplace is elixir-agent-tools. If you installed from the old Claude Code marketplace, uninstall the plugins you used from claude-code-elixir, remove that marketplace, and add georgeguimaraes/elixir-agent-tools. Reinstall your chosen plugins with the new marketplace ID using the installation commands above. The old elixir plugin is replaced by elixir-dev.

Update any explicit plugin-qualified skill references to use the new bundle name.

If you installed skills manually, replace your old skill links or copies with the renamed folders under plugins/elixir-dev/skills/.

Sources

The skills draw on Elixir and Erlang documentation, framework guides, and talks about application design:

• José Valim - Gang of None
• Saša Jurić - The Soul of Erlang and Elixir
• Saša Jurić - Clarity
• Designing Elixir Systems with OTP
• Official Elixir Guides
• Phoenix 1.8 Scopes
• Phoenix LiveView Docs
• Stephen Bussey - Real-Time Phoenix
• Phoenix Contexts Guide
• German Velasco - DDD for Phoenix Contexts (ElixirConf 2024)
• Ecto Multi-Tenancy Guide
• Erlang OTP Design Principles
• Elixir GenServer Docs
• Elixir School - OTP Concurrency
• Saša Jurić - Elixir in Action

Optional tools

The three Mix plugins share a Bash runner and a bundled JSON.sh parser. They handle Claude Code's Edit, MultiEdit, and Write events and Codex's apply_patch events, including patches spanning multiple files or projects. Shell commands that write files do not trigger these edit hooks.

Checks run synchronously and return failures as context to the agent. The plugins serialize their Mix commands per project, but hook execution order is not guaranteed. Formatting is not guaranteed to finish before compilation or Credo starts. Hooks have bounded waits and report timeouts. Mix plugins 2.0 replace the old single-file scripts and asynchronous Credo hook.

mix-format

Runs mix format on surviving edited .ex and .exs files, using the nearest parent mix.exs to locate each project. Reports formatting failures.

mix-compile

Runs mix compile --warnings-as-errors once per affected Mix project after editing an .ex file. Deletions and both sides of a move also trigger compilation. Reports compiler warnings and errors. Edits to .exs scripts and tests don't trigger compilation.

Skips compilation when lsof detects a BEAM process running from the project directory, to avoid competing with a running server or Mix task.

mix-credo

Runs mix credo for each surviving edited .ex or .exs file using the project's Credo configuration. Reports code quality issues and skips the check if the Credo task isn't installed. Dependency and project failures remain visible.

elixir-lsp

Connects Claude Code to Expert for navigation and compiler diagnostics in .ex, .exs, .heex, and .leex files.

Install the expert binary using the Expert installation guide and make sure it's on your PATH. The bundled wrapper also requires Python 3.

The wrapper works around Claude Code's handling of server-initiated LSP requests, including client/registerCapability (upstream issue). See expert-wrapper for the implementation.

Developing the hooks

Edit the canonical runner and parser helpers under scripts/mix-hooks/, then run bash scripts/sync-mix-hooks.sh to bundle them into the three independently installable plugins. The bundled JSON.sh source and its MIT license live under vendor/ in each copy.

Run bash test/verify-plugins.sh to check package structure and bundle consistency. Run uv run --no-project python test/test-mix-hooks.py for behavioral tests with isolated plugin installations and fake Mix commands. Python is used only by development checks, not the Mix hooks.

License

Copyright (c) 2025 George Guimarães

Licensed under the Apache License, Version 2.0. See LICENSE.