I’ve been working with Claude Code extensively and absolutely love it. However, I’ve come across the challenge of managing configuration across multiple projects. For example, some projects I want hooks, other projects I don’t. There are a few projects I want to share hooks. And I just found that reusing hooks in general was something that was messy.
Additionally, I see a lot more potential for managing Claude from the Elixir side and deeply integrating it into the Elixir ecosystem. For example, imagine being able to pull in Usage Rules, which is an awesome library by Zach Daniel and all other configuration that is necessary for Claude to work effectively. Or libraries can define their own sub-agents. Or libraries can even define their own hooks that should be hooked into Claude Code. All of this, I think, can be done with this library, though the support still needs to be added.
How It Works
You use Claude as the library name by adding it to your deps and then running mix claude.install as a mix task, and it will automatically add all of the hooks that are needed for Claude to operate effectively and within bounds. There are only a few hooks right now, but I want to add a lot more, in addition to sub-agents being able to extend hooks with your own custom hooks and more.
Vision
The goal is to create a seamless integration between Claude Code and the Elixir ecosystem, allowing:
Project-specific configuration management - Different hook configurations per project
Shared hook libraries - Reusable hooks across multiple projects
Deep ecosystem integration - Libraries can define their own Claude-specific rules and behaviors
Extensible sub-agent system - Libraries can register their own specialized agents
Automatic setup - One command to configure Claude Code optimally for your Elixir project
Current Status
This is early-stage development with basic hook management implemented. Much more functionality is planned, including better integration with existing tools like Usage Rules and expanded sub-agent capabilities.
Let me know what you think. I’d love to hear your feedback!
An extensible hook system so you can write your own hooks, in elixir!
A new meta subagent following best practices to make it easier to create claude code subagents
Automatically pull in usage docs into your CLAUDE.md file following best practices
A new mix claude.install igniter task
You can get started with mix igniter.install claude. There’s still so much more to add to scale up claude code’s capabilities and I’m excited to explore that more. See this link below for a full list of features/capabilities.
beauty, im programer fulltime with claude code, and for elixir is very weird see something like that, appreciate it! im searching for prp`s for elixir , what do you think about that?
I want to enable tidewave and in the notices, it was mentioned that I have just to uncomment that line. But then I questioned claude code and also ran claude mcp list and did not find tidewave - then googling, I found that I need to install tidewave first - i am a newcomer to this, so you might want to consider installing tidewave if it is not there already or at least the steps to install first before enabling it in the claude.exs. Or have I gotten it wrong?
Hi Bradely, Siraj from India - I am fairly new to Elixir/Phoenix and just started using Claude Code last week - So, I was quite excited to see your CC integration. I installed the package and ran it, but for some reason the hooks are not getting invoked - the user_service file is not formatted and the preferenses replacement does not give me a compiler warning. I have checked the things mentioned in troubleshooting - when I ran mix claude.install, it does not change anything. What am I missing?
Claude hooks not running?
Run claude --version to verify Claude Code CLI is installed
Check .claude/settings.json exists
Try mix claude.install to reinstall hooks
oh great! this is exactly what i was looking for, amazing work…
I wonder if there are some directories that list both elixir libs that use usage_rules, as well as a directory of sub agents specific for elixir / phoenix / liveview development as a community effort, that would be really great to have
You’ve gotten it right! I think there’s a bug in the tidewave setup where I’m not triggering mix igniter.install tidewave as I should. It’s a great suggestion and apologies for the bugginess!
I can see us moving in this direction where we have more opinionated agents and even workflows. I’ve been brain dumping ideas in the issues. They’re not too descriptive but those would be worth checking out.
thank you so much for the quick response. Let me try it out and get back to you.
But one question that is on my mind - if I am complete beginner and want to use Ash + Liveview, then what should I be configuring? I have seen tidalwave MCP, but it does not have phoenix1.8.rc4, then I saw Ash AI with its own MCP, and I have used context7 which seems to have the latest version of most phoenix libraries - I also saw that someones suggested to use Serena MCP which acts as the language server for Claude Code - I am just confused as to what should be the minimal/default configuration that I should adopt? I also want to use PhoenixTest (that is why I have looked at context7 as it has the latest version there). Any guidance on this would be really helpful for people like me.
I personally use tidewave, ash_ai and usage_rules. I also use my hexdocs_mcp project which you’re welcome to try out, though if you’re not running mac it might not work well for you.
I’m not sure how I feel about Serena MCP TBH, haven’t used it and after glancing the project, I don’t really see a need to use it for my personal use case.
I’ve been thinking it would be nice to support context7 via the project since it’s remote by default. I just think it’s important to have hooks to ensure claude is looking up dependency versions that your project uses. This is something probably worth adding to the project now that I think about it.
I agree PhoenixTest is great but yes, Claude is really bad at writing code for that library so lookups of some form are 100% required from my experience.
I recently asked Claude Code to add a stanza to CLAUDE.md “to ensure testing compliance by AI assistants”. (Of course, I was talking about it, but it pretended not to notice.) I’ll report back on whether CC actually follows its own directive.
Here’s what it added:
CRITICAL COMPLETION REQUIREMENT
BEFORE DECLARING ANY TASK FINISHED, YOU MUST:
Run the complete quality check sequence iteratively until ALL issues are resolved:
mix test && mix credo && mix dialyzer
Fix ALL issues found by each tool:
Tests - All tests must pass (0 failures, 0 errors)
Credo - All style/design issues must be resolved
Dialyzer - All type warnings must be fixed
Repeat the sequence until clean:
If ANY tool reports issues, fix them and run the full sequence again
Only declare task complete when all three tools run clean
NO EXCEPTIONS - this is mandatory for every code change
From my experience putting this kind of logic in CLAUDE.md isn’t deterministic. Claude will sometimes decide to run tests and sometimes not which is exactly why I created this project. Have you looked at hooks? I’m actively working on making it easier to create hooks within a project through this library. Stay tuned!
Bradely,
I postponed the task because I thought it would take me a lot of time. But finally when I went to the GH repo, I found that all I have to is mix claude.install - I could NOT believe it as I thought that I was reading it wrong, but I did as proposed and igniter told me that it is gonna update the settings with the mcpservers and also update CLAUDE.md to sync usage rules - Sweet.
After I did it, I checked \mcp and I saw that tidewave is listed. Thank you so much.
Then I asked claude about the hooks in my project and it listed the 3 hooks - then I did as per your getting started instructions: to create user_service.ex and it was NOT formatted and VSCode showed a popup with this error - what is going wrong? This project is a project based on the latest liveview book by Chris & co - so it has very little real code and no custom settings. It is as close to bare-bones as it could get.
there is one more thing I want to bring to your notice, assuming it might be of some value to you (if not, please let me know so that I can avoid these kind of details next time)…
The following notices were printed - some of them were overlapping and even conflicting - so, a bit confusing. please take a look - do i need to do anything more to get the mcp server working? the tidewave line is already there in claude.exs but commented out - so, why can’t the installer just do it for me or change the notice to say to uncomment rather than add. in the add you have put that single command inside a map which was confusing to me as an elixir newbie. So, please consider if you can make it easier for beginners.
Notices:
* Claude hooks have been installed to .claude/settings.json
Hook scripts generated in .claude/hooks/
Enabled hooks:
• Checks if Elixir files need formatting after Claude edits them
• Checks for compilation errors after Claude edits Elixir files
• Validates formatting, compilation, and dependencies before allowing commits
* Phoenix detected! To enable Tidewave MCP server, add the following to your .claude.exs file:
%{
mcp_servers: [:tidewave]
}
Or with a custom port:
%{
mcp_servers: [{:tidewave, [port: 5000]}]
}
Tidewave provides Phoenix-specific tools for working with your application.
* Syncing usage rules to CLAUDE.md...
This will help Claude Code understand how to use your project's dependencies.
* Generated 1 subagent(s):
• Meta Agent → .claude/agents/meta-agent.md
Subagents are now available in Claude Code.
* Tidewave MCP server has been configured in .claude/settings.json
Port: 4000
Endpoint: http://localhost:4000/tidewave/mcp
Tidewave integrates with your Phoenix application:
1. Add to your deps in mix.exs: {:tidewave, "~> 0.2.0"}
2. Run: mix deps.get
3. Configure in config/dev.exs (see Tidewave docs)
4. Start your Phoenix server: mix phx.server
5. MCP endpoint will be at: http://localhost:PORT/tidewave/mcp
* To format .claude.exs files, add ".claude.exs" to your formatter inputs:
# .formatter.exs
[
inputs: [".claude.exs", "{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
]
Then run `mix format` to apply the formatting.
I find context7 helpful in a lot of projects - so I brought it along to see whether it would be helpful for PhoenixTest (I went to context7 and asked it to fetch the latest version of PhoenixTest 0.7.0 and it did). I find playwright MCP to be very helpful as I ask Claude to visit the page after the work is done to verify it using playwright and even store the screenshots - for UI work, i check the screenshots first before even looking at the code.
I am still learning how best to use tidewave and ash_ai mcp - I followed the instruction to add ash_ai as mcp server using claude mcp add --transport sse ash_ai http://localhost:4000/ash_ai/mcp - is that wrong? for some reason, it is not connected - for me, it is not clear whether I need Ash AI if I already have tidewave - can you clarify what it provides and whether i should give some custom instructions to Claude to help it use both tools effectively?
Regarding Serena, here is the video that made me try it out - I am not really well-versed in this area, so, may I ask you to tell me whether it is worth it to install this mcp to use the language server and semantic search when looking up code or symbols rather than using grep: Wait.. Claude Code is MADE Slow on Purpose? Heres How to Fix It - YouTube
Incidentally, when I went to that channel to pick up the URL, he had a video about hooks which really helped me understand your hooks and how they work - you might just want to reference it in your Readme somewhere for people to know how they work:
In your hooks, I would like to have mix test also included - ideally, just one hook - that runs the formatting, compilation and test all in one go’ - would be great.
Thanks @siraj-samsudeen. Interesting info. I am a bit more curious about the serena MCP. You found any benefits after using it? I still did not use it - but - I felt it looks similar to GitHub - topoteretes/cognee: Memory for AI Agents in 5 lines of code Cognee. Essentially building a graph database with code - that will help the LLM in maintaining the context dynamic and relevant. I tried using Cognee - but - did not see much improvement either in the quality of code generated or the speed or reduction in number of tokens. I am curious about knowing your experience.
At a conceptual level, I understand that it uses semantic search instead of text-search which can be much faster and it also provided a language server protocol to Claude Code. 2 youtubers that I have watched claimed that it saved tokens a lot - I am not really concerned about tokens as my usage of my claude plan is very low. But I just wanted it to be faster. But it is still new for me to figure out whether it is value-add. That is why I thought of asking an experienced person like bradley who can judge whether MCP actually adds real value. Things like playwright and context7 have been very helpful to me personally.
From that error it seems like more of an elixir ls thing which is related to the language server and not this project. Does that seem correct?
These details are great ty! I really appreciate the detailed/thorough feedback. I would encourage you to submit an issue in GitHub too so we can track issues there too. That would help me and other people who find the project elsewhere to contribute to the conversation.
RE the notices, yes that is confusing and definitely a bug! Again a GitHub issue would be much appreciated!
RE doing everything for you, yes I’m working towards that! It’s a process building out the automation to do all the things, I want to get there.
So my ideal is that when you run mix claude.install the following happens:
All hooks are configured
All relevant MCP servers are setup
All subagents are setup
All usage rules are configured
All permissions are configured to allow common mix commands
All CLAUDE.md files are populated (including nested md files even but I need to implement this)
And all configuration specific to specific packages would also be set up, e.g. Ash would include ash_ai mcp server potentially and other relevant hooks that are specific to ash
RE ash ai, I would strongly encourage you to join the Ash discord server, Zach and the community are very helpful there. They can provide support. Though about your specific issue, I would recommend using the mcp proxy for that mcp server. You can see the instructions in the docs I believe.
This is a great idea. The ability to run everything in one go makes a lot of sense! I think what I want to support both out of the box and make it configurable is a mix task style hook that allows you to turn any mix task into a hook easily.
Here are my current thoughts around the types of hooks that I want:
Mix task hooks - Allow running any abitrary mix task either one or many maybe? This could be any mix task in your project.
Mix run hooks (less safe) - Allow using mix run ... to hook into your application if you want to. This enables you to run hooks that are application specific or even business logic specific.
CRITICAL COMPLETION REQUIREMENT 
Have you looked at 
