Claude

Help make Claude Code write production-ready Elixir, every time.

Claude, not to be confused with the Claude (probably should have picked a better name 😅), is an elixir library, batteries-included integration that ensures every line of code Claude writes is properly formatted, compiles without warnings, and follows your project's conventions—automatically.

Quick Start

# Install Claude
mix igniter.install claude

# That's it! Now Claude:
# ✓ Formats every file after editing
# ✓ Checks for compilation errors
# ✓ Validates code before commits

The Problem

When Claude Code writes Elixir, you often need to:

Run mix format manually after every edit
Discover compilation errors only when you run the code
Remember to update related test files
Ensure consistent code style across your team

The Solution

Claude hooks directly into Claude Code's workflow:

# Before Claude: Unformatted code that might not compile
defmodule  MyModule  do
  def hello(  name  )  do
    "Hello, #{ nam }!"  # Oops, typo!
  end
end

# After Claude: Production-ready code, automatically
defmodule MyModule do
  def hello(name) do
    "Hello, #{name}!"
  end
end

Features

🎯 Smart Hooks

Format on save - Every .ex and .exs file is automatically formatted
Compile checks - Catch errors immediately, not in production
Pre-commit validation - Block bad commits before they happen
Related files - "You edited the schema, want to check the Phoenix Context?"

🔧 Extensible

# .claude.exs - Add your own hooks
%{
  hooks: [
    MyApp.Hooks.SecurityScanner,
    MyApp.Hooks.TestRunner
  ]
}

🤖 Sub-agents

Create specialized AI assistants for your project with built-in best practices:

%{
  subagents: [
    %{
      name: "genserver-agent",
      role: "Genserver agent",
      instructions: "You are an writing and testing genservers...",
      usage_rules: ["usage_rules:elixir", "usage_rules:otp"]  # Automatically includes best practices!
    }
  ]
}

Built-in Meta Agent: Claude includes a Meta Agent by default that helps you create new sub-agents following best practices. Just ask: "Create a sub-agent for handling GraphQL queries" and the Meta Agent will:

Generate a complete sub-agent configuration
Choose appropriate tools and permissions
Include relevant usage rules from your dependencies
Add it to your .claude.exs file

Usage Rules Integration: The real power comes from usage rules - documentation from your dependencies that gets automatically injected into sub-agents, ensuring they follow library best practices.

🔌 MCP Server Support

Integrate with Phoenix development tools via Tidewave:

%{
  mcp_servers: [tidewave: [port: 4000]]
}

📚 Best Practices

Usage rules will be added to your CLAUDE.md automatically so you can have the best chance of your agents following best practices.

Installation

Requirements

Elixir ~> 1.18
Claude Code (CLI)
Mix with Igniter support

Install via Igniter

mix igniter.install claude

This will:

Add claude to your dependencies
Generate .claude.exs configuration
Install hooks in .claude/settings.json and .claude/hooks
Create specialized sub-agents in .claud/agents

Configuration

Claude uses .claude.exs for project-specific configuration:

# .claude.exs
%{
  # Hooks to run (built-in + custom)
  hooks: [
    # Optional: Enable related files suggestions
    Claude.Hooks.PostToolUse.RelatedFiles,

    # Add your custom hooks
    MyApp.Hooks.CredoChecker
  ],

  # MCP servers (for Phoenix projects, only tidewave is supported, use claude manually to add other mcp servers)
  mcp_servers: [
    # Simple configuration
    :tidewave,

    # Or with options
    {:tidewave, [port: 5000]}
  ],

  # Specialized sub-agents
  subagents: [
    %{
      name: "test_expert",
      role: "ExUnit testing specialist",
      instructions: "You excel at writing comprehensive test suites...",
      usage_rules: ["usage_rules:elixir", "usage_rules:otp"]
    }
  ]
}

Built-in Sub-agents

Claude includes a Meta Agent by default to help you create new sub-agents.

Meta Agent

The Meta Agent is your sub-agent architect. It helps you create new, well-designed sub-agents by:

Analyzing your requirements and suggesting optimal configuration
Choosing appropriate tools and permissions
Integrating usage rules from your dependencies
Following Claude Code best practices for performance and context management

Usage: Just ask Claude to create a new sub-agent, and the Meta Agent will automatically help.

Creating Custom Hooks

Extend Claude with your own hooks:

defmodule MyApp.Hooks.CredoChecker do
  use Claude.Hooks.Hook.Behaviour,
    event: :post_tool_use,
    matcher: [:edit, :write],
    description: "Runs Credo on modified files"

  @impl true
  def run(json_input) do
    # Your hook logic here
    :ok
  end
end

How It Works

This library leverages Claude Code's hook system to intercept file operations:

Claude edits a file → PostToolUse hook triggered
Hook runs Mix tasks → mix format, mix compile --warnings-as-errors
Feedback provided → Claude sees any issues and can fix them
Process repeats → Until the code is production-ready

This happens automatically, without interrupting Claude's workflow.

Documentation

Contributing

We welcome contributions!

# Run tests
mix test

# Format code
mix format

# Run quality checks
mix compile --warnings-as-errors

Support

Roadmap

🚀 Coming Soon

Custom Slash Commands

/create-subagent - Generate a new sub-agent with guided prompts
/create-hook - Scaffold a new custom hook with boilerplate
Auto-generate commands in .claude/commands/ during installation

Scoped CLAUDE.md's

Directory-specific instructions (e.g., *_web/CLAUDE.md for Phoenix)

More MCP Servers

Database tools (PostgreSQL, MySQL, Redis)
Testing and documentation servers
Auto-configuration based on project dependencies

Dynamic Sub-agents

Generate sub-agents for each dependency with context automatically
Common workflow templates (LiveView, GraphQL, Testing)

Want to contribute? Open an issue on GitHub!

License

MIT - see LICENSE for details.

Made with ❤️ by the Elixir community

Next Page → Changelog