DEV Community: Anjan

BodhiKit: A Research-Backed AI Coding Tutor That Teaches You Instead of Writing Code For You

Anjan — Sat, 14 Mar 2026 15:05:51 +0000

The Problem With AI and Learning

AI tools are incredible at writing code. But writing code for you and teaching you to write code are two fundamentally different things.

When an AI writes your code, you get a working solution. When an AI teaches you to write code, you get a working brain.

Most AI coding tools optimize for the first. BodhiKit optimizes for the second.

What is BodhiKit?

BodhiKit is a free, open source plugin for Claude Code that turns Claude into a deeply personalized, interactive coding tutor. The name comes from Pali, the language of early Buddhist texts. Bodhi means "awakening." Because learning, at its best, is exactly that.

It does not write code for you. It asks questions. It gives hints. It creates exercises. It tests your understanding. And it remembers where you left off, so every session builds on the last.

17 skills. 3 AI agents. 15 knowledge bases. Works with any programming topic: React, Rust, Python, Zig, system design, web development, databases, anything.

The Philosophy

BodhiKit speaks with the voice of a wise, patient teacher. Think Master Oogway from Kung Fu Panda, Yoda, Gautama Buddha, and Dr. B.R. Ambedkar. Patient, honest, respectful, never condescending.

Three core principles:

The learner writes code. BodhiKit asks questions. If you ask it to write code for you, it will gently redirect: "The learning happens when your hands are on the keyboard."
Struggle is sacred. When you are stuck, BodhiKit gives the smallest hint that keeps you thinking. Not the answer. Productive struggle is where real learning happens.
The goal is to become unnecessary. A good teacher does not create dependency. A good teacher creates independence.

The Science Behind It

BodhiKit is not built on vibes. It is built on decades of research in learning science:

Spaced Repetition (Ebbinghaus, Leitner): Your brain forgets 67% of new information within 24 hours. BodhiKit tracks every concept you learn and resurfaces it at optimal intervals. Get it right, and the interval grows. Get it wrong, and it comes back tomorrow. This is not flashcards. It is spaced problem-solving, code review, and concept re-explanation.

Bloom's Taxonomy (Bloom, Anderson): Not all knowledge is equal. "I can recall the syntax" is Level 1. "I can design a system from scratch" is Level 6. BodhiKit tracks your level per concept, not globally. You might be Level 5 on arrays and Level 2 on recursion. That granularity matters.

Zone of Proximal Development (Vygotsky): If a task is too easy, you learn nothing. If it is too hard, you shut down. The sweet spot is just beyond what you can do alone. BodhiKit calibrates every exercise to sit in that zone.

Feynman Technique: After explaining a concept, BodhiKit asks you to explain it back in your own words. No jargon. If you cannot explain it simply, you do not understand it yet. This is the single most powerful check for real understanding.

Deliberate Practice (Ericsson): Coding for 10 hours is not practice. Coding for 1 hour with targeted focus on your specific weakness, with immediate feedback, is practice. BodhiKit designs exercises that isolate one skill at a time and provide clear feedback.

Growth Mindset (Dweck): "You have not mastered this yet." The word "yet" changes everything. BodhiKit never says "that is wrong." It says "let us look at this differently."

Desirable Difficulties (Bjork): BodhiKit mixes problem types, varies contexts, and uses retrieval practice instead of re-reading. These feel harder in the moment but produce dramatically stronger long-term retention.

Metacognition (Flavell): BodhiKit does not just teach you WHAT to learn. It teaches you HOW you learn. End-of-session reflections build your awareness of your own learning process, which research shows improves retention by 20-30%.

Mentoring Theory (Kram, Whitmore): BodhiKit uses the GROW model (Goal, Reality, Options, Will) for career guidance and Kram's mentoring theory to balance coaching with encouragement. It is honest about what an AI cannot do (sponsorship, networking) and transparent about its limitations.

Pair Programming (Beck, Williams & Kessler, Falco): Three modes of collaborative coding. Strong-style pairing forces explicit communication of thinking. Ping-pong pairing with TDD teaches both specification and implementation. Research shows pairing improves learning outcomes, satisfaction, and retention.

Scientific Debugging (Zeller, O'Dell): Developers spend 35-50% of their time debugging, yet it is rarely taught. BodhiKit teaches Zeller's TRAFFIC method (reproduce, hypothesize, probe, isolate, fix) and frames bugs as puzzles, not failures. It never fixes bugs for you.

Constructivism (Piaget, Bruner, Papert): Learning by building. BodhiKit uses Bruner's spiral curriculum to revisit concepts at increasing depth, progressing from guided follow-along to fully independent projects.

How to Install

You need Claude Code (Anthropic's CLI tool).

/plugin marketplace add https://codeberg.org/AnjanJ/bodhikit.git
/plugin install bodhikit@bodhikit

Restart Claude Code after installing. That is it.

Or test locally without installing:

claude --plugin-dir ~/code/bodhikit

One Command, Complete Learning Session

This is what makes BodhiKit different from just "chatting with an AI about code." Run /bodhikit:continue and the entire session is orchestrated for you:

/continue
  ├── /status       → quick 3-line check-in (project, streak, concepts due)
  ├── spaced review → quiz on concepts due for review today
  ├── /teach        → guided teaching of the next concept
  │     ├── explain with analogies and code examples
  │     ├── work through a problem together (guided practice)
  │     ├── independent exercise (you write the code)
  │     └── quick retention check
  └── /reflect      → end-of-session metacognitive reflection

One command. No need to remember which skills to invoke. BodhiKit handles the flow, you focus on learning.

How Teaching Works

When BodhiKit teaches, it follows the Gradual Release of Responsibility model:

I Do (Modeling): BodhiKit explains the concept. Not with a wall of text, but with analogies from everyday life, concrete code examples, and a clear connection to what you already know. It shows WHY the concept matters, not just what it does.

We Do (Guided Practice): You and BodhiKit work through a problem together. It asks guiding questions: "How would you start? What data structure fits here?" You make the decisions. It keeps you on track.

You Do (Independent Practice): BodhiKit gives you an exercise calibrated to your level. Beginners get starter files with TODO comments. Advanced learners get a problem statement and nothing else. You solve it yourself.

Verify: Quick retention check. 2-3 questions to confirm the concept stuck. New concepts are added to spaced repetition tracking.

The key rule: BodhiKit never lectures for more than 5 minutes without interaction. It is a conversation, not a presentation.

End-of-Session Reflection

When you say goodbye, BodhiKit asks four questions:

What felt hardest today? Identifies concepts that need more time.
Was anything easier than expected? Calibrates your self-assessment.
Confidence rating (1-10)? Low-confidence concepts get reviewed sooner.
What would you do differently? Builds strategic thinking about learning itself.

This takes 3-5 minutes and multiplies the value of the entire session. Your confidence rating feeds directly into the spaced repetition system. A concept you rate at 3/10 comes back tomorrow. A concept you rate at 9/10 can wait a week.

How to Use BodhiKit: Real Scenarios

Scenario 1: "I want to learn Rust from scratch"

/bodhikit:learn rust

BodhiKit will:

Ask why you want to learn Rust, what your programming background is, and your timeline
Assess your current knowledge through adaptive questions (starting at Level 3, adjusting up or down based on your answers)
Build a personalized learning plan with phases, modules, and exercises
Create a project folder (learningWithBodhi/rust-basics/) with tracking files
Give you your first exercise immediately. Not "go read the Rust Book." An actual exercise you can do in 5-10 minutes.

The next day, run:

/bodhikit:continue

It shows your status, reviews due concepts, teaches the next topic, gives you an exercise, and runs a reflection when you are done. All automatic.

Scenario 2: "I am reading a book and want a teaching assistant"

Say you are working through "The Rust Programming Language" (the Rust Book):

/bodhikit:resources add "The Rust Programming Language"

BodhiKit analyzes the book's structure and maps chapters to your learning plan. Then it can:

Quiz you on what you just read
Give you extra practice exercises on the same concepts
Explain concepts differently when the book's explanation does not click
Review your code from the book's exercises

It works as a TA, not a replacement. The book is the primary material. BodhiKit fills the gaps.

Scenario 3: "I want to check where I stand with React"

/bodhikit:assess react

No learning project needed. It runs a standalone assessment: 8-12 adaptive questions, classifies your Bloom's level per sub-topic (JSX, components, hooks, state management, routing, etc.), and shows you where you stand.

If you want to go deeper after the assessment:

/bodhikit:learn react

Your assessment becomes the starting point for the learning plan.

Scenario 4: "I wrote some code and want feedback"

/bodhikit:review ./my-project/src/app.tsx

This is not a production code review. It is an educational review. BodhiKit analyzes what your code reveals about your understanding:

What concepts you demonstrate mastery of
What misconceptions are visible
What patterns you are ready to learn next

And instead of telling you what to fix, it asks Socratic questions: "I notice you used a for loop here. What do you know about array methods like map and filter?"

It also works with GitHub, GitLab, and Codeberg URLs:

/bodhikit:review https://github.com/username/repo

Scenario 5: "I do not understand closures"

/bodhikit:explain closures

BodhiKit explains the concept simply, with analogies, no jargon. Then it asks you to explain it back. Then it identifies the gaps in your explanation and helps you fill them. This is the Feynman Technique in action.

Scenario 6: "Give me something to practice"

/bodhikit:practice

It creates an exercise calibrated to your current level:

Beginners get starter files with TODO comments and tests to run
Intermediate learners get requirements and test cases, no starter code
Advanced learners get a problem statement and nothing else

After you complete it, BodhiKit reviews your code educationally and suggests what to try next.

Scenario 7: "How far have I come?"

/bodhikit:evaluate

This is the big picture. It reads your entire learning history, runs a fresh assessment, and compares where you started to where you are now. Growth map, strengths, gaps, recommendations, and a suggested project to solidify what you have learned.

Scenario 8: "Quick check — where am I?"

/bodhikit:status

Three lines. Five seconds:

📍 react-fundamentals | State and Hooks | 45% complete
🔥 Streak: 3 days | 2 concepts due for review today
📅 Last session: yesterday

Scenario 9: "My code has a bug and I am stuck"

/bodhikit:debug-together ./exercises/05-todo-list/TodoList.jsx

BodhiKit does not look at the code first. It starts with you:

"What did you expect to happen?"
"The todo should be removed when I click delete."
"And what actually happened?"
"Nothing happens. No error either."
"Good. No error but wrong behavior. What is your theory?"
"Maybe the filter is not working?"
"That is a testable theory. Before changing anything, let us verify. Add a console.log before the filter that prints the array and the ID you are trying to remove. What do you expect to see?"

You add the probe. The array prints correctly, but the ID being passed is undefined.

"Interesting. Your theory about the filter was reasonable, but the real cause is upstream. The ID is not reaching the function. What could cause that?"

You trace it back to the onClick handler and discover you forgot to pass the todo's ID. You fix it yourself. BodhiKit closes:

"You systematically tested a hypothesis, found it was not the cause, followed the data upstream, and found the real issue. That is exactly how experienced developers debug."

This also auto-invokes during /practice or /teach when your code has bugs.

Scenario 10: "I want to build something together"

/bodhikit:pair strong-style

BodhiKit explains the rule: "For an idea to go from my head into the computer, it must go through your hands. I will describe what to build. You type it."

"Create a function called calculateTotal. It takes an array of items, each with a price and quantity property."

You start typing. You write function calculateTotal(items).

"Good. Now, inside the function, what do you think is the first step?"
"Loop through the items?"
"Yes. Which loop would you use here, and why?"
"A for loop?"
"That would work. Have you seen reduce? It is designed exactly for this kind of accumulation. Try it if you would like, or stick with the for loop. Your call."

You try reduce. You get it slightly wrong. BodhiKit guides without correcting:

"Walk me through what your reduce callback does with each item."

You talk through it, spot the issue yourself, fix it.

"Good. Now walk me through what you just wrote, line by line."

After 15 minutes, BodhiKit offers: "Now let us switch. You tell me what to build next. You navigate, I follow."

Mode auto-selects based on your Bloom's level, or you can choose: strong-style for beginners, ping-pong for intermediate (BodhiKit writes a test, you make it pass), navigate for advanced.

Also auto-invoked by /teach during Phase 3 (guided practice).

Scenario 11: "I finished React. What should I learn next?"

/bodhikit:mentor

BodhiKit reads your learner profile and all your learning projects:

"Let us step back and look at the bigger picture. You started learning React two months ago. You are now at Bloom's Level 4 on components, props, state, and hooks. Level 3 on effects and routing. That is real growth."

"What draws you to programming? Is it a career change, a specific project, or something else?"
"I want to become a full-stack developer."
"Good. For a full-stack developer, here is what I see:

Strong foundation: React, HTML/CSS, JavaScript
Growing: React patterns (Level 3, almost there)
New territory: Backend (Node.js, databases, APIs, deployment)

This is not a deficit list. It is a map. And you are further along than most who set this goal."

"Here are three paths I see:

Node.js + Express — builds on your JavaScript. You stay in one language.

Ruby on Rails — different language, but Rails teaches excellent patterns fast.

Go deeper in React first — state management, testing, performance. Solidify before adding backend.

Each is valid. Which resonates?"

You choose Node.js. BodhiKit offers to start a new project:

"Would you like me to start a learning project with /learn nodejs? Based on your pace, this would take about 6-8 weeks. After that, the next step would be databases."

It is honest about its limits: "I can help you build the skills. For visibility and advocacy in your career, seek human mentors and sponsors in your workplace or community."

Also auto-invoked by /evaluate when you complete a major milestone or finish a learning project.

Scenario 12: "Quiz me on what I just learned"

/bodhikit:quiz

BodhiKit checks your current module and spaced review schedule, then generates 5-7 adaptive questions:

"Let us see what has taken root. This is not a test. It is a conversation with your memory."

"What does useState return in React?" (Level 2 — you should get this)
"An array with the state value and a setter function."
"Correct. Now, what happens if you call the setter function with the same value the state already has?" (Level 4 — stretch)
"Hmm... it re-renders?"
"Let us approach this differently. Think about what React is optimizing for. If nothing changed, would it need to update the DOM?"

After each wrong answer, BodhiKit does not give the answer. It asks a simpler version or gives a hint. At the end, concepts you got right move up a Leitner box (reviewed less often). Concepts you missed drop to Box 1 (reviewed tomorrow).

Scenario 13: "I want to adjust my learning plan"

/bodhikit:plan adjust

"What would you like to change about your learning plan?"
"I want to skip the CSS module. I already know CSS well."
"Let me verify. Can you explain the difference between grid and flexbox and when you would choose each?"

If you answer well, it skips the module. If your answer has gaps: "Your intuition is close, but there are a few pieces worth solidifying. Would you like to do a quick review instead of the full module?"

You can also reorder modules, add new topics, change pace, or integrate a book you started reading.

Scenario 14: "How is my end-of-session reflection?"

When you say goodbye during any session, BodhiKit auto-invokes /reflect:

"Before we close, let us look back at today's path. You worked on useEffect and dependency arrays."

"What felt hardest today?"
"The dependency array. I kept getting infinite loops."
"That is one of the most common struggles with useEffect. The fact that you can name it means you are developing awareness of your own learning."

"How confident would you feel explaining useEffect to a colleague right now, 1 to 10?"
"About 4."
"A 4 is honest. I have noted useEffect for review in your next session. We will approach it from a different angle."

Your confidence rating feeds directly into spaced repetition. A 4/10 concept comes back tomorrow. A 9/10 can wait a week.

How Agents Work Behind the Scenes

BodhiKit uses three specialized AI agents that handle complex tasks automatically. You never invoke them directly. Skills launch them when needed.

Skill Assessor Agent (used by /learn, /assess, /evaluate): Runs adaptive Bloom's taxonomy assessments. Asks 8-12 questions, starting at Level 3, escalating or de-escalating based on your answers. Returns per-topic classifications with confidence ratings. This shapes your entire learning plan.

Code Reviewer Agent (used by /review, /practice, /teach): Performs educational code review. Not "is this good code" but "what does this code reveal about your understanding?" Returns Socratic questions and graduated hints, not fixes.

Resource Finder Agent (used by /resources): Searches the web for verified, community-recommended free resources. Prioritizes official docs, interactive platforms (Exercism, freeCodeCamp), and structured courses. Verifies every link is live. Returns ranked results with difficulty level and estimated time.

The Daily Workflow

A typical 30-minute learning session:

/bodhikit:continue

That is it. One command. BodhiKit handles the rest:

Status check — where you are, what is due (auto)
Spaced review — quiz on due concepts, 5 minutes (auto)
Teaching — guided lesson on the next concept, 15 minutes (auto)
Practice — hands-on exercise within the lesson (auto)
Reflection — what was hard, what clicked, confidence rating (auto, when you say goodbye)

Consistency beats intensity. 30 minutes daily is better than 5 hours on a weekend.

What Makes This Different From ChatGPT / Copilot / Other AI Tools

Feature	Typical AI Tool	BodhiKit
Writes code for you	Yes	No. Guides you to write it yourself
Proactive teaching	No	Yes. Walks you through concepts step by step
Tracks your progress	No	Yes, per concept, across sessions
Spaced repetition	No	Yes, Leitner box system
Adapts to your level	Sometimes	Always, using Bloom's Taxonomy
Gives direct answers	Yes	No. Questions and hints only
Remembers where you left off	No	Yes, via `.bodhi/` tracking files
End-of-session reflection	No	Yes, metacognitive awareness building
Works with your books/courses	No	Yes, as a teaching assistant
One-command sessions	No	Yes, `/continue` orchestrates everything
Research-backed pedagogy	No	13+ methodologies integrated
Pair programming	No	Yes, 3 modes (strong-style, ping-pong, navigator)
Scientific debugging	No	Yes, Zeller's TRAFFIC method
Career mentoring	No	Yes, GROW model with honest AI limitations

All 17 Skills

Skill	What It Does
`/learn`	Start a new learning project with assessment and personalized plan
`/continue`	Resume where you left off, auto-invokes teach, reflect, status
`/teach`	Proactive guided teaching: explain, demonstrate, practice, verify
`/assess`	Standalone skill assessment on any topic
`/review`	Educational code review (local files, GitHub, GitLab, Codeberg)
`/quiz`	Active recall check with spaced repetition tracking
`/plan`	View, adjust, or regenerate your learning plan
`/progress`	Full learning progress dashboard
`/resources`	Find, verify, and manage learning resources
`/explain`	Deep-dive explanation using the Feynman technique
`/practice`	Hands-on exercise calibrated to your level
`/evaluate`	Comprehensive evaluation of your learning journey
`/reflect`	End-of-session metacognitive reflection
`/status`	Quick 3-line check-in
`/mentor`	Career and learning path guidance using the GROW model
`/pair`	Pair programming: strong-style, ping-pong, or navigator mode
`/debug-together`	Scientific debugging: reproduce, hypothesize, probe, isolate, fix

Tips for Getting the Most Out of BodhiKit

Be honest about what you do not know. "I do not know" is the most useful answer you can give. It tells BodhiKit exactly where to focus.
Do not skip spaced reviews. They feel like a detour, but they are the reason you will remember this in 3 months instead of forgetting it in 3 days.
Type the code yourself. Do not copy from examples. Do not ask BodhiKit to write it. Your fingers on the keyboard is where the learning happens.
Explain things out loud. When BodhiKit asks you to explain a concept back, actually do it. The Feynman Technique works because it forces you to confront what you do not understand.
Take breaks. Your brain does important work during rest (diffuse mode thinking). After a focused session, walk away. The "aha moment" often comes in the shower, not at the keyboard.
Trust the struggle. If it feels hard, you are learning. If it feels easy, you are reviewing. Both have value, but growth lives in the struggle.
Do the reflection. When BodhiKit asks "what was hardest today?" at the end of a session, answer honestly. That 3-minute reflection multiplies the value of everything you just did.

Open Source

BodhiKit is free and open source (MIT license).

Repository: https://codeberg.org/AnjanJ/bodhikit

Contributions, feedback, and bug reports are welcome.

I also built ShipKit, a developer productivity plugin for Claude Code with 15 skills, 2 agents, and 6 path-scoped rules.

Made with ❤️ by Anjan

Buy me a coffee ☕

More Rules, Worse Results: The Case for a Minimal CLAUDE.md

Anjan — Sun, 08 Mar 2026 15:22:21 +0000

There are at least five Claude Code starter kits already published. They range from 27 commands with 4 npm packages to 47 commands with 4 MCP servers. Every single one of them is over-engineered.

This isn't speculation. Arize AI's research on coding agent rules shows that optimized rulesets contain 20–50 rules and improve SWE-bench accuracy by 10–15% — without changing the model, architecture, or tools. HumanLayer's analysis is more pointed: as instruction count increases, instruction-following quality decreases uniformly. The model doesn't ignore your new instructions — it starts ignoring all of them. Claude Code's system prompt already uses ~50 of your ~150–200 instruction budget before your CLAUDE.md even loads.

The kit that works best says the least.

After building 42 skills across 13 repositories — Rails, React, Elixir, vanilla JS — I distilled everything down to 8 workflow rules, 8 skills, 2 agents, and 1 knowledge base. The base CLAUDE.md is 99 lines. With a stack appended, it's ~160. Here's what survived.

Principles Over Rules

Every other kit I've seen includes rules like "functions under 20 lines" or "always use TypeScript interfaces." These are rules. They tell you what. They don't tell you when or why.

The 8 workflow rules encode principles instead:

### 1. Plan Mode Default
Enter plan mode for any task requiring 3+ steps.
For simple fixes (typo, one-line change), skip planning and just do it.

### 2. Subagent Strategy
Use subagents only for atomic, well-defined tasks.
Keep all reasoning and decision-making in the main session.

### 3. Self-Improvement Loop
When the user corrects you, update CLAUDE.md with the lesson.
Don't repeat the same mistake twice.

### 4. Verification Before Done
Never say "done" without proving it works:
- Code change → run tests
- Bug fix → reproduce before/after
- Refactor → full test suite passes

### 5. Demand Elegance (Balanced)
For non-trivial changes: pause, ask "is there a simpler way?"
For obvious fixes: just do it, don't overthink.

### 6. Autonomous Bug Fixing
Read the error, read the source, fix the root cause.
Don't ask — investigate and fix. Only ask if genuinely stuck.

### 7. Task Management
Plan → verify plan → track progress → explain decisions → document.

### 8. Core Principles
- Simplicity first — minimum complexity needed
- No laziness — never skip tests, never leave TODOs
- Minimal impact — change only what's necessary

Notice what's missing: no line limits, no naming conventions, no style preferences. Those belong in your linter config. These 8 rules shape behavior — how Claude thinks, plans, and self-corrects. The underlying principles (Clean Code, SRP, YAGNI, KISS) are taught through a code review knowledge base that explains when to apply each one and when to relax it.

DRY enforcement uses the Rule of Three: don't extract until you've seen three repetitions. YAGNI is enforced at four levels simultaneously — as a review lens, a new-feature gate, a test quality standard, and an anti-pattern catalog. One principle, four enforcement points, zero hardcoded opinions.

Rules tell you what. Principles tell you when and why.

Smell-Driven, Not Pattern-Driven

Most starter kits either ignore design patterns entirely or prescribe them upfront: "use the Repository pattern for data access," "all services should follow the Command pattern." Both approaches are wrong.

The /review-my-code skill uses an 8-lens review system. After applying all lenses, it checks whether any detected smells have a well-known pattern fix — but only when the smell is real:

Smell You Found	Pattern to Suggest	When It's Worth It
Long `case`/`if` switching on type	Strategy	3+ branches that will grow
Object creation scattered across conditionals	Factory	2+ creation paths, likely to add more
Multiple objects reacting to state changes	Observer/Pub-Sub	3+ listeners, or listeners will grow
Complex object with many optional params	Builder	4+ optional params, or complex validation
Adding behavior without modifying class	Decorator	Composable features (logging, caching, auth)
Step-by-step process with varying steps	Template Method	Shared skeleton, varying details

The rules that govern this table:

Only suggest when the code already smells — never preemptively
Prefer the framework's built-in pattern (Rails concerns, Phoenix behaviours) over rolling your own
If the simple version works and won't grow, skip the pattern — three if branches is fine

That third rule is the key. Every pattern adds indirection. Indirection is only justified when the smell is real and the code is likely to grow. A three-branch if statement that handles all known cases doesn't need a Strategy pattern. It needs to be left alone.

No existing starter kit encodes this smell-driven approach. Most either force patterns or ignore them entirely. Smells are the signal; patterns are the response.

Safety as a First-Class Citizen

Of the five major starter kits I've reviewed, none include destructive operation guards. Zero. This is wild. An AI agent with rm -rf access and no guardrails is a P0 incident waiting to happen.

The kit's safety section is short and non-negotiable:

### Destructive Operations — ALWAYS Ask First
These actions require explicit user confirmation every time:
- **Database:** dropping tables, removing columns, changing column types
- **Schema:** present a rollback strategy before executing
- **Files:** deleting files, rm -rf, overwriting uncommitted changes
- **Secrets:** never stage or commit .env, credentials, or API tokens
- **Git:** force push, reset --hard, amending published commits
- **Dependencies:** never upgrade a major version without asking
- **External APIs:** warn before calls that could cost money or hit rate limits

The migration rollback strategy requirement deserves attention. Before executing any schema change that could destroy data, Claude must present a rollback plan: add the new column → migrate data → remove the old column. Not the other way around. This single rule prevents the most common category of production data loss in Rails applications.

The philosophy is simple arithmetic: the cost of asking is 5 seconds. The cost of not asking is a production incident. There is no scenario where skipping confirmation is worth the risk.

Verification Loops

AI-generated documentation has a specific failure mode: confident statements that are subtly wrong. The model doesn't say "I think payments might use Sidekiq." It says "Payments are processed asynchronously via Sidekiq" — and if that's wrong, you won't catch it unless you check.

The /explain-system skill solves this with a claims table. Every factual claim from the analysis is extracted and verified against source code:

#	Claim	Source File(s)	Confidence	Status
1	Uses PostgreSQL as primary DB	`Gemfile:8`, `database.yml:3`	VERIFIED	Confirmed
2	Payments processed async via Sidekiq	`app/jobs/payment_job.rb:1`	VERIFIED	Confirmed
3	Failed jobs retry 3 times	(Sidekiq default)	INFERRED	Needs confirmation
4	Chose Rails for rapid prototyping	(no code evidence)	UNCERTAIN	Ask user

Three confidence levels:

VERIFIED — directly observed in source code with file:line reference
INFERRED — reasonable conclusion from evidence, not directly stated
UNCERTAIN — cannot confirm from code alone

The gate: zero UNCERTAIN claims in the final document. This gate is not optional — even if the user asks to skip it. Unresolvable items get an explicit callout: "[Not confirmed from code]". INFERRED claims are allowed but tagged.

The /walkthrough skill takes a different approach to the same problem. Instead of a verification loop, it requires a mandatory file:line reference on every single step:

### Step 3: Controller — Validates input and delegates to service

**File:** `app/controllers/orders_controller.rb:42`

The controller validates strong params, then delegates to OrderService.
If validation fails, it returns a 422 with error details.

**Data in:** Raw params from request
**Data out:** Validated order attributes

No file:line, no step. This is the trace-based equivalent of verification — every claim is anchored to a specific location in the codebase. You can verify any step by opening the file.

Verification is cheaper than correction. A 30-claim table takes 10 minutes to verify. Finding a subtle error in published documentation takes hours — if it's found at all.

The Kit

The complete configuration:

8 workflow rules that shape behavior, not style
8 base skills — QA, code review, testing, rule updates, context audit, onboarding, system explanation, walkthroughs
2 agents — test analyzer and codebase explorer (both read-only)
1 knowledge base — code review standards with 8 lenses, smell-to-pattern mapping, and severity definitions
4 stack configs — Rails, React, Elixir, static sites

Base CLAUDE.md: 99 lines. With a stack appended: ~160 lines.

Setup:

bash <(curl -s https://codeberg.org/gatleon/claude-starter-kit/raw/branch/main/setup.sh)

The setup script auto-detects your stack (Gemfile → Rails, mix.exs → Elixir, package.json + react → React), finds your test framework, and fills in the template. No manual configuration. No npm packages. No MCP servers.

The best CLAUDE.md is the one you actually read. 160 lines gets read. 2,000 lines gets ignored — and the research confirms it.

Source code on Codeberg · Made with ❤️ by Anjan · Built with Claude Code

My One-Command macOS Dev Setup: Ruby, Elixir, Zig, and Everything in Between

Anjan — Sun, 08 Mar 2026 04:47:54 +0000

Every developer knows the pain. You get a new machine — or worse, you nuke your old one — and spend the next two days installing Homebrew, cloning repos, configuring editors, setting up language versions, and wondering why your terminal looks wrong. By the time you're actually writing code again, it's Wednesday.

I got tired of that. So I built a dotfiles repo that turns a fresh macOS install into a fully configured development environment with three commands. One window manager. Two editors. Two terminal multiplexers. Seven languages. 288 packages. All wired together with a unified color theme.

This is how it works, and more importantly, why it's built this way.

Why I Built This

I've been a Rails developer for 9+ years. Over that time, my setup grew organically — a Vim plugin here, a shell alias there, a theme that only worked in one app. When I saw DHH's Omakase approach applied to developer tooling (everything opinionated, everything in one place), something clicked. That philosophy already shaped how I write Rails apps. Why not my entire dev environment?

I started over with five principles:

One command to install everything. No "Step 7: now manually configure X."
One theme everywhere. If my editor, terminal, prompt, and multiplexer all look different, my brain wastes cycles adjusting. Tokyo Night everywhere.
Keyboard-first. If I have to reach for the mouse, something is wrong.
Modular by concern. Shell config split by domain (Rails, Elixir, terminal tools), not dumped into one 2,000-line .zshrc.
Idempotent and safe. Run the installer twice and nothing breaks. Existing configs get backed up with timestamps.

I think of myself as an integrator — I prefer to find the best dev tools rather than build new tools from scratch, I find the best ones and wire them together. This repo is that philosophy made concrete.

The Stack at a Glance

Tool	What	Why
Aerospace	Tiling window manager	i3-like on macOS, pure keyboard control
Ghostty	GPU-accelerated terminal	Fast, minimal, built-in Tokyo Night theme
Neovim	Terminal editor	AstroNvim + 17 plugin configs, deep Rails/Elixir support
Zed	GUI editor	When you need a full IDE — 24 tasks, 68 snippets, 7 LSPs
tmux	Terminal multiplexer	50K line scrollback, Ctrl+A prefix, TPM plugins
Zellij	Alt multiplexer	Rust-based, WebAssembly plugins, session persistence
Starship	Shell prompt	16x faster than Spaceship, shows Ruby/Elixir/Node/Zig versions
mise	Version manager	One tool for Ruby, Elixir, Node, Python, Go, Rust (replaces rbenv/nvm/pyenv)

Repo: github.com/AnjanJ/dotfiles

One-Command Install

git clone https://github.com/AnjanJ/dotfiles.git ~/dotfiles
cd ~/dotfiles
bash install.sh

That's it. The script walks through 11 steps:

Installs Homebrew (if missing)
Runs brew bundle install — 72 CLI packages, 106 cask apps, 110 VS Code extensions
Creates ~/.config/ directories
Backs up your existing configs to ~/.dotfiles_backup_YYYYMMDD_HHMMSS/
Sets up mise and installs 7 language runtimes
Symlinks every config file into place
Installs TPM (tmux plugin manager)
Bootstraps Neovim (lazy.nvim auto-installs plugins on first launch)
Copies Zed settings, tasks, and snippets
Sets zsh as default shell
Runs health check (optional)

The key design choice: symlinks, not copies. Every config file lives in the git repo. Edit your Zed settings in ~/dotfiles/.config/zed/settings.json, and the change is immediately tracked by git. No manual syncing.

# What the symlink setup looks like
ln -sf ~/dotfiles/.zshrc ~/.zshrc
ln -sf ~/dotfiles/.config/starship.toml ~/.config/starship.toml
ln -sf ~/dotfiles/.config/aerospace/aerospace.toml ~/.config/aerospace/aerospace.toml
# ... and 15+ more

Already have configs? They're safe. The installer backs up everything to a timestamped directory before touching anything. And since the script is idempotent, you can re-run it after pulling new changes — it'll update symlinks without clobbering your data.

Modular Shell: Why 4 Files Instead of 1

Most dotfiles repos dump everything into a single .zshrc. Mine splits it into four files by concern:

File	Lines	What's in it
`.zshrc`	171	Core: Starship, mise, PATH, project aliases
`.zshrc-dhh-additions`	644	Rails: `r`, `rs`, `rc`, RSpec, Bundle, Git, database helpers
`.zshrc-elixir-additions`	340	Phoenix: Mix, IEx, LiveView, Ecto shortcuts
`.zshrc-terminal-enhancements`	201	CLI: fzf, zoxide, bat, eza, ripgrep integration
Total	1,356

The magic is in how .zshrc loads them:

# DHH-inspired Rails developer setup
if [ -f ~/.zshrc-dhh-additions ]; then
  source ~/.zshrc-dhh-additions
fi

# Modern terminal enhancements
if [ -f ~/.zshrc-terminal-enhancements ]; then
  source ~/.zshrc-terminal-enhancements
fi

# Elixir & Phoenix developer setup
if [ -f ~/.zshrc-elixir-additions ]; then
  source ~/.zshrc-elixir-additions
fi

Don't use Elixir? Comment out one line. Want to add Rust-specific aliases? Create .zshrc-rust-additions and source it. The pattern is self-documenting.

The DHH additions file alone has 16 organized sections — Rails aliases, Bundle shortcuts, Git workflow, Docker Compose, Heroku, database helpers, credential management, and even an alias discovery system:

# Core Rails commands — type less, ship more
alias r='bin/rails'
alias rs='bin/rails server'
alias rc='bin/rails console'
alias rgen='bin/rails generate'

Zed Editor: My Secret Weapon

I use Neovim for quick terminal edits and Zed for longer sessions. Zed is absurdly fast (it's written in Rust), has native terminal integration, and lets me configure everything in JSON without plugins.

7 LSPs configured out of the box: ruby-lsp (with RuboCop), TypeScript, ESLint, elixir-ls, tailwindcss, zls (Zig), and Prettier. Each language has its own formatter, tab size, and linting rules.

24 tasks accessible from Cmd+Shift+P:

{
  "label": "RSpec: Run current file",
  "command": "bundle exec rspec $ZED_FILE",
  "use_new_terminal": false,
  "tags": ["ruby-test"]
},
{
  "label": "RSpec: Run current line",
  "command": "bundle exec rspec $ZED_FILE:$ZED_ROW",
  "use_new_terminal": false,
  "tags": ["ruby-test"]
}

I have tasks for RSpec (4), Rails (5), RuboCop (2), Elixir/Mix (5), npm (2), and Zig (6). I never leave the editor to run tests.

68 snippets across three languages — Ruby (31), Zig (24), and ERB (13). These are the patterns I type every day: frozen_string_literal headers, RSpec describe/context/it blocks, Rails controller actions, Zig error handling, ERB form helpers.

The Zed config uses symlinks too. Edit snippets or tasks in ~/dotfiles/.config/zed/, commit, push. Any machine I clone this repo to gets the same editor experience.

Window Management: Keyboard-First with Aerospace

Aerospace is an i3-like tiling window manager for macOS. Windows automatically tile. No dragging, no resizing with a mouse.

I use Ctrl+Shift as the primary modifier (instead of Cmd) because it works reliably across international keyboards:

# Focus windows with vim keys
ctrl-shift-h = 'focus left'
ctrl-shift-j = 'focus down'
ctrl-shift-k = 'focus up'
ctrl-shift-l = 'focus right'

# Move windows
ctrl-alt-h = 'move left'
ctrl-alt-j = 'move down'
ctrl-alt-k = 'move up'
ctrl-alt-l = 'move right'

9 workspaces organized by purpose. Each major app gets a dedicated hotkey:

Hotkey	App	Workspace
`Ctrl+Shift+C`	Chrome	1 (Work)
`Ctrl+Shift+Z`	Zed	2 (Code)
`Ctrl+Shift+W`	Warp	3 (Terminal)
`Ctrl+Shift+F`	Firefox	5 (Personal)
`Ctrl+Shift+G`	Ghostty	7 (Personal Terminal)
`Ctrl+Shift+O`	Obsidian	8 (PKM)
`Ctrl+Shift+P`	1Password	9 (Utils)

System apps (Calculator, System Settings, Finder, Zoom) automatically float instead of tiling. The config handles all of this declaratively — no scripts, no daemon, just TOML.

Keeping It Alive: Update and Health Check

Dotfiles that rot are worse than no dotfiles. I built two scripts to keep everything current.

bash update.sh pulls the latest changes, updates Homebrew, refreshes symlinks, upgrades mise runtimes, updates tmux plugins, and reloads configs — all in one command.

bash scripts/health-check.sh validates that everything still works. It checks 11 categories:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Core Tools
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Homebrew: installed (Homebrew 4.x.x)
✓ git: installed (git version 2.x.x)
✓ mise: installed (2025.x.x)
✓ starship: installed (starship 1.x.x)

It checks core tools, terminals, window management, editors, shell config symlinks, all 7 language runtimes, CLI utilities, databases, framework tools, and custom scripts. Color-coded output with pass/fail/warning counts at the end.

After a macOS update breaks something (and it will), health-check.sh tells you exactly what needs fixing.

Tokyo Night Everywhere

Cognitive load matters. When your editor uses one color scheme, your terminal uses another, and your prompt uses a third, your eyes constantly readjust. It's a small thing, but it adds up over a full day.

Every tool in this setup uses Tokyo Night:

Neovim — tokyo-night-theme.lua plugin
Ghostty — theme = tokyonight_night (built-in)
Starship — custom [palettes.tokyonight] section with all 16 colors
Zellij — hand-mapped themes/tokyo-night.kdl with RGB values
tmux — tokyo-night plugin via TPM

Five config files, one visual language. The Starship config alone defines 20 color values to match:

[palettes.tokyonight]
background = "#1a1b26"
foreground = "#c0caf5"
red = "#f7768e"
green = "#9ece6a"
blue = "#7aa2f7"
purple = "#bb9af7"
cyan = "#7dcfff"
orange = "#ff9e64"

How to Adapt This for Yourself

This repo is opinionated — it reflects how I work. But the modular design makes it easy to make it yours.

Don't use Elixir? Delete .zshrc-elixir-additions and remove the source line from .zshrc. Done.

Want different languages? Edit .config/mise/config.toml:

[tools]
ruby = "3.4.5"
elixir = "latest"
node = "latest"
python = "3"
go = "latest"
rust = "latest"
# Add or remove languages here

Want a different theme? Change it in 5 places:

starship.toml — the [palettes] section
ghostty/config — the theme line
nvim/lua/plugins/ — swap the theme plugin
zellij/themes/ — edit the KDL file
.tmux.conf — change the theme plugin

Want your own Zed snippets? Add JSON files to .config/zed/snippets/. The installer symlinks the entire directory.

Fork it. Remove what you don't need. Add what you do. The install script handles everything — your fork is one bash install.sh away from working on any Mac.

git clone https://github.com/YOUR_USERNAME/dotfiles.git ~/dotfiles
cd ~/dotfiles
bash install.sh

What's Next

I keep iterating on this. Recent additions include Zig language support (6 Zed tasks, 24 snippets, ZLS configured), browser window cycling across workspaces, and AI model configuration in Zed (Claude, GPT-4o, Gemini — all ready to use).

If you want the full details — every keybinding, every alias, every snippet — the README is comprehensive.

Star it if it's useful. Fork it if you want to make it yours. And if you have a setup trick I'm missing, I'd love to hear about it.

github.com/AnjanJ/dotfiles

I'm a Rails engineer with 9+ years of experience, currently open to remote opportunities. You can find me on GitHub and LinkedIn.

Self-Hosted Error Tracking for Rails 8.1 + SolidQueue: A Complete Setup Guide

Anjan — Sat, 07 Mar 2026 13:32:49 +0000

How to set up rails_error_dashboard with SolidQueue — capturing errors from controllers AND background jobs, with optional database isolation.

Rails 8.1 ships with SolidQueue as the default background job backend. No more Redis. No more Sidekiq licensing questions. Just your database.

But here's a question nobody talks about: what happens when your background jobs fail?

Sure, SolidQueue tracks failed executions. But do you get a dashboard? Severity classification? Trend charts? Notifications? Priority scoring?

Not out of the box.

I built rails_error_dashboard to solve exactly this — a self-hosted, open-source error tracking gem that works entirely inside your Rails process. No external services, no monthly fees, no data leaving your servers.

In this post, I'll walk you through setting it up with a Rails 8.1 app using SolidQueue, including the optional separate database configuration for production-grade isolation.

What We're Building

By the end of this guide, you'll have:

Automatic error capture from both controllers and SolidQueue jobs
A full error dashboard at /error_dashboard with analytics, severity scoring, and workflow management
Optional: errors stored in a separate database from your app data
Verified that SolidQueue's retry mechanism still works (errors are captured, not swallowed)

Prerequisites

Ruby 3.2+ (tested with Ruby 4.0.1)
Rails 7.0+ (this guide uses Rails 8.1.2)
SolidQueue (ships with Rails 8.1 by default)

Part 1: Basic Setup (Same Database)

Step 1: Add the Gem

# Gemfile
gem "rails_error_dashboard"

bundle install

Step 2: Run the Installer

rails generate rails_error_dashboard:install
rails db:migrate

That's it. Seriously. The installer:

Creates the initializer at config/initializers/rails_error_dashboard.rb
Copies 19 migrations for error logs, occurrences, baselines, comments, and more
Mounts the engine at /error_dashboard in your routes

Step 3: Configure SolidQueue for Development

Rails 8.1 only configures SolidQueue as the queue adapter in production by default. For development testing, add it explicitly:

# config/environments/development.rb
config.active_job.queue_adapter = :solid_queue
config.solid_queue.connects_to = { database: { writing: :queue } }

You also need the multi-database setup for the queue database in development:

# config/database.yml
development:
  primary:
    <<: *default
    database: storage/development.sqlite3
  queue:
    <<: *default
    database: storage/development_queue.sqlite3
    migrations_paths: db/queue_migrate

Then load the queue schema:

rails db:schema:load:queue

Step 4: Start the Server with SolidQueue

The simplest way to run both Puma and SolidQueue together is the Puma plugin:

SOLID_QUEUE_IN_PUMA=1 rails server

This runs the SolidQueue supervisor (dispatcher + worker) inside the Puma process — perfect for development and single-server deployments.

Alternatively, run them separately:

# Terminal 1
rails server

# Terminal 2
bin/jobs

Step 5: Verify It Works

Visit http://localhost:3000/error_dashboard and log in with the default credentials (gandalf / youshallnotpass). Change these in your initializer before deploying to production.

To test error capture, create a simple failing job:

# app/jobs/test_error_job.rb
class TestErrorJob < ApplicationJob
  queue_as :default

  def perform
    raise RuntimeError, "Test error from SolidQueue"
  end
end

Enqueue it:

rails runner "TestErrorJob.perform_later"

Within seconds, the error should appear in your dashboard with:

Error type and message
Full backtrace
Severity classification (auto-detected)
Occurrence count
Priority score

How Error Capture Works

The gem uses a dual-layer approach to ensure no error goes uncaptured:

Layer 1: Rails Error Subscriber

Rails 7+ introduced Rails.error.subscribe — a built-in error reporting API. The gem subscribes to this, which means it automatically captures errors from:

Controllers (via rescue_from and error handling)
ActiveJob (SolidQueue, Sidekiq, etc.)
Anywhere you use Rails.error.handle or Rails.error.record

# This happens automatically — you don't need to do anything
Rails.error.subscribe(RailsErrorDashboard::ErrorReporter.new)

Layer 2: Rack Middleware

A lightweight Rack middleware sits at the top of the middleware stack as a final safety net. If an exception escapes all the way up, it captures it and then re-raises it so Rails can still render the appropriate error page.

# Simplified version of what the middleware does
def call(env)
  @app.call(env)
rescue => error
  Rails.error.report(error, handled: false, source: "middleware")
  raise  # Always re-raise!
end

The Critical Rule: Always Re-raise

This is the most important design decision in the entire gem. When we capture an error from a background job, we never swallow the exception. We report it and re-raise it.

Why? Because of Sentry issue #1173. Sentry's Sidekiq middleware once swallowed exceptions, which meant Sidekiq thought failed jobs had succeeded — retries never happened. Data was silently lost.

We verified this explicitly: after our gem captures a SolidQueue job error, the error still appears in solid_queue_failed_executions. SolidQueue's retry mechanism is fully intact.

Part 2: Separate Database Setup (Production-Grade)

For production apps, you might want error data in a separate database. Benefits:

Performance isolation — high-frequency error writes don't contend with your app's queries
Independent scaling — put your error DB on a different server
Different retention — aggressive cleanup of old errors without touching app data
Security — separate access controls and backup schedules

Step 1: Add the Database Configuration

# config/database.yml
development:
  primary:
    <<: *default
    database: storage/development.sqlite3
  queue:
    <<: *default
    database: storage/development_queue.sqlite3
    migrations_paths: db/queue_migrate
  error_dashboard:
    <<: *default
    database: storage/development_error_dashboard.sqlite3
    migrations_paths: db/error_dashboard_migrate

production:
  primary:
    <<: *default
    database: storage/production.sqlite3
  queue:
    <<: *default
    database: storage/production_queue.sqlite3
    migrations_paths: db/queue_migrate
  error_dashboard:
    <<: *default
    database: storage/production_error_dashboard.sqlite3
    migrations_paths: db/error_dashboard_migrate

For PostgreSQL in production (recommended):

production:
  primary:
    adapter: postgresql
    database: myapp_production
    # ... your existing config

  queue:
    adapter: postgresql
    database: myapp_queue_production
    # ...

  error_dashboard:
    adapter: postgresql
    database: myapp_errors_production
    pool: <%= ENV.fetch("RAILS_MAX_THREADS", 5) %>
    username: <%= ENV['ERROR_DB_USER'] %>
    password: <%= ENV['ERROR_DB_PASSWORD'] %>
    host: <%= ENV['ERROR_DB_HOST'] %>
    migrations_paths: db/error_dashboard_migrate

Step 2: Install with Separate Database Flag

rails generate rails_error_dashboard:install \
  --separate-database \
  --database error_dashboard

Or if you've already installed, update the initializer:

# config/initializers/rails_error_dashboard.rb
RailsErrorDashboard.configure do |config|
  config.use_separate_database = true
  config.database = :error_dashboard  # Must match your database.yml key
  # ...
end

Step 3: Move Migrations

The installer places migrations in db/migrate/ by default. For a separate database, move them to match your migrations_paths:

mkdir -p db/error_dashboard_migrate
mv db/migrate/*rails_error_dashboard* db/error_dashboard_migrate/

Step 4: Create and Migrate

rails db:create    # Creates all databases
rails db:migrate   # Runs migrations against the correct databases

Step 5: Verify Isolation

You can verify the databases are truly isolated:

# Check error_dashboard DB has the gem's tables
sqlite3 storage/development_error_dashboard.sqlite3 ".tables"
# => rails_error_dashboard_error_logs, rails_error_dashboard_applications, ...

# Check primary DB has NO error tables
sqlite3 storage/development.sqlite3 ".tables"
# => ar_internal_metadata, schema_migrations (clean!)

# Check queue DB has only SolidQueue tables
sqlite3 storage/development_queue.sqlite3 ".tables"
# => solid_queue_jobs, solid_queue_failed_executions, ...

Three databases, three concerns, zero cross-contamination.

What You Get Out of the Box

Once installed, the dashboard at /error_dashboard gives you:

Error list with search, filtering by type/severity/status/timeframe, and batch operations
Error details with full backtrace, occurrence timeline, and context
Analytics with 7-day trend charts, severity breakdown, and spike detection
Workflow — assign errors, set priority, add comments, snooze, resolve
Multi-channel notifications — Slack, Email, Discord, PagerDuty, webhooks (all optional)
Platform detection — automatically tags errors as iOS/Android/Web/API
Dark mode — because we're not savages

Production Checklist

Before deploying:

Change the default credentials in your initializer
Set retention_days to prevent unbounded growth (e.g., config.retention_days = 90)
Consider async logging for high-throughput apps:

   config.async_logging = true
   config.async_adapter = :solid_queue  # Use your existing SolidQueue!

Configure notifications — at minimum, set up Slack or email for critical errors
Consider error sampling if you're generating thousands of errors per day:

   config.sampling_rate = 0.1  # Log 10% of non-critical errors

Common Gotchas

SolidQueue Queue Database Not Set Up

Rails 8.1 only configures the queue database in production. If you see Could not find table 'solid_queue_processes' in development, you need to:

Add the queue database to your development config in database.yml
Add config.solid_queue.connects_to = { database: { writing: :queue } } to your development environment
Run rails db:schema:load:queue

Migrations Running Against the Wrong Database

When using separate databases, the gem's migrations must be in the directory matching your migrations_paths. If you see error tables in your primary database, move the migration files:

mv db/migrate/*rails_error_dashboard* db/error_dashboard_migrate/

CSRF Errors When Testing with curl

If you're testing the enqueue endpoint with curl and getting 422 errors, that's Rails' CSRF protection working correctly. Use rails runner or the Rails console instead:

rails runner "TestErrorJob.perform_later"

Try It Out

The gem is open source and free forever:

GitHub: AnjanJ/rails_error_dashboard
RubyGems: gem install rails_error_dashboard
Live Demo: rails-error-dashboard.anjan.dev (gandalf / youshallnotpass)

If you're running Rails 8.1 with SolidQueue, this is the easiest way to get production-grade error tracking without paying for a SaaS product. Five minutes of setup, zero monthly fees, and your data never leaves your servers.

Have questions or feedback? Open an issue on GitHub

Why I Built Rails Error Dashboard (And Why You Might Want to Self-Host Too)

Anjan — Sat, 07 Mar 2026 12:40:19 +0000

I needed error tracking for my side project but wanted complete control over my data and monitoring stack. So I built Rails Error Dashboard — a self-hosted, open-source alternative to commercial services. It’s in beta (v0.1.20), production-ready with 850+ tests, and completely free. Try the live demo →

The Real Problem: It’s Not About the Money
Let me be honest upfront: Most error tracking services have generous free tiers.

Sentry: Free up to 5,000 errors/month
Rollbar: Free up to 5,000 events/month
Bugsnag: Free tier available
Honeybadger: Free for solo developers

For a small side project, these free tiers work fine. I could have used any of them for $0.

So why did I build my own?
What Actually Bothered Me
I run Audio Intelli — an AI platform that transforms audio into searchable intelligence — on a Raspberry Pi 5 for testing. My entire server costs $80 one-time.

When I looked at error tracking options, the free tiers seemed great at first. But then I noticed:

1. Free Tiers Have Real Limitations

Sentry’s free tier: Only 7 days of data retention
One bad deploy could burn through 5,000 errors.
Limited to basic features (no custom dashboards, advanced workflows)
You’ll eventually outgrow it as your app grows

2. Your Error Data Lives on Their Servers
Every error contains sensitive information:

User IDs and session data
Request parameters (potentially PII)
Stack traces showing your business logic
Accidentally logged secrets

With Audio Intelli handling voice conversations and transcriptions, I wanted complete control over every piece of data.

3. You’re Dependent on SaaS Pricing
Free tiers can change or disappear:

Remember Heroku’s free tier? Gone.
Remember MongoDB Atlas’s free tier changes? Painful.
What happens when they decide free isn’t sustainable?

Once you’re locked in with 6 months of historical error data on their platform, moving is painful.

4. I Wanted to Learn
I’m a Rails developer. Error tracking is fundamentally storing exceptions in a database with some analytics. How hard could it be?

Turns out: not that hard. But incredibly educational.

What I Built
Rails Error Dashboard is a Rails Engine that mounts into your existing Rails app. No external services, no APIs to configure, no data leaving your server.

Core Features (What It Does Today)

Error Tracking:

Automatic capture from controllers, background jobs, and Rack middleware
Platform detection (iOS, Android, Web, API) from user agents
Manual error reporting API for frontend/mobile apps
Smart deduplication (groups similar errors automatically)
Full stack traces with context (user, params, URL, IP)

Dashboard:

Clean interface with dark/light mode
Real-time updates via Turbo Streams (no polling needed)
Search and filtering with PostgreSQL full-text search
Error detail views with occurrence history
Works in both full Rails and API-only apps

Analytics:

7-day error trend charts
Severity breakdowns (critical, high, medium, low)
Platform health monitoring
Automatic spike detection
Affected users tracking

Workflow Management:

Assign errors to team members
Set priority levels
Add comment threads
Mark as resolved with references
Batch operations (resolve/delete multiple errors)

Optional Features (Opt-in During Install):

Notifications: Slack, Discord, Email, PagerDuty, Custom Webhooks
Advanced Analytics: Fuzzy error matching, cascade detection, co-occurring errors, pattern recognition
Performance: Async logging, error sampling, separate database support
Plugins: Jira integration, custom extensions via event hooks

What It Doesn’t Do (Being Honest)
This isn’t a Sentry replacement for everyone:

❌ No distributed tracing — If you’re debugging microservices across 20 services, Sentry is better
❌ No session replay — I don’t capture user sessions (yet)
❌ No advanced source maps — JavaScript error mapping is basic (planned)
❌ Limited integrations — 5 built-in vs Sentry’s 50+
❌ Self-hosted only — You manage your own infrastructure

Who this is NOT for:

Large teams (50+ developers)
Complex distributed architectures
Teams that want fully managed infrastructure
Companies needing enterprise support contracts

Who this IS for:

Solo developers running side projects
Indie hackers bootstrapping SaaS
Small teams (2–5 people) who value independence
Privacy-conscious applications (GDPR, healthcare, finance)
Developers who enjoy self-hosting
Anyone learning how error tracking works

The Technical Reality (No Exaggeration)
I built this with clean architecture because I hate messy code:

CQRS Pattern:

Commands for write operations: LogError, ResolveError, BatchOperations
Queries for read operations: ErrorsList, DashboardStats, AnalyticsStats
Services for business logic: PlatformDetector, SimilarityCalculator, BaselineCalculator
Value Objects for immutable data: ErrorContext

Testing:

137 RSpec files
2,615 individual test cases
Tests across Ruby 3.2–4.0 and Rails 7.0–8.1
All passing consistently in CI

Current Version: v0.3.1

Pre-1.0 means the API might change before v1.0
Pre-1.0 doesn't mean unstable — I use it in production
I'm gathering feedback before locking the public API

Supports:

Ruby 3.2, 3.3, 3.4, 4.0
Rails 7.0, 7.1, 7.2, 8.0, 8.1
PostgreSQL (recommended), MySQL, SQLite

Installation: Actually 5 Minutes

# Gemfile
gem ‘rails_error_dashboard’

bundle install
rails generate rails_error_dashboard:install
rails db:migrate

The interactive installer asks which optional features you want:

? Enable Slack notifications? (y/N)
? Enable advanced analytics? (y/N)
? Enable async logging for performance? (y/N)

Choose what you need. Everything works out of the box without configuration.

Then visit http://localhost:3000/error_dashboard and log in:

Username: gandalf
Password: youshallnotpass

(Yes, LOTR-themed defaults. Change them in config/initializers/rails_error_dashboard.rb before production!)

— -

Try Before You Install: Live Demo
I’m running a live demo with 250+ sample errors from fictional scenarios:

Demo URL: https://rails-error-dashboard.anjan.dev
Username: gandalf
Password: youshallnotpass

Click around. Test search. Try filters. Check out the analytics. See if it fits your needs.

No signup, no credit card, no tracking.

Honest Comparison: When to Use What
Use Sentry/Rollbar Free Tier If:

✅ You’re just starting out (5K errors/month is plenty)
✅ You’re okay with 7–30 day data retention
✅ You don’t mind data on their servers
✅ You want zero ops work (managed infrastructure)
✅ You need their extensive integrations (Sentry has 50+)
✅ You might scale to a large team eventually

For most solo devs starting their first side project, Sentry’s free tier is completely fine.

Use Rails Error Dashboard If:

✅ You want unlimited errors with no ceiling
✅ You need long-term data retention (years, not days)
✅ You’re privacy-conscious (GDPR, HIPAA, data sovereignty)
✅ You want to own your monitoring stack completely
✅ You enjoy self-hosting and learning
✅ You’re worried about SaaS pricing changes long-term
✅ You want full customization (access to source code)
✅ You’re running on constrained infrastructure (Raspberry Pi, home server)

The honest truth: If you value independence, privacy, unlimited usage, and learning, Rails Error Dashboard is better. If you just want to ship fast and don’t care about the above, use Sentry’s free tier.

What About Rails 8 and Solid Errors?
You might be thinking:
”Doesn’t Solid Errors suffice, which also does error tracking now?”

Solid Errors exists but is intentionally minimalist:

Solid Errors is for:

Absolute simplicity (bare-bones logging)
No frills, no complexity
Just store errors in your database

Rails Error Dashboard is for:

Professional monitoring features
Analytics, trends, spike detection
Team workflows (assign, prioritize, comment)
Multi-channel notifications
Advanced features (fuzzy matching, cascade detection)

Both are self-hosted and free. Choose based on your needs:

Solid Errors: You want the simplest possible solution
Rails Error Dashboard: You want feature-complete monitoring

The Cost Comparison (Being Realistic)
Sentry Free Tier:

Cost: $0
Limits: 5,000 errors/month, 7-day retention
When you outgrow it: $26–80/month

Rails Error Dashboard:

Cost: $0 (forever)
Limits: None (unlimited errors, unlimited retention)
Infrastructure: Runs on your existing Rails server
Maintenance: ~1 hour/month (responding to updates, issues)

The real savings isn’t about avoiding $26/month.

The real value is:

No artificial limits — Deploy a bug that generates 50K errors? No problem.
Keep data forever — Historical trends over years, not days
Independence — Never worry about pricing changes
Privacy — Complete data sovereignty
Learning — Understand how error tracking actually works

The Audio Intelli Connection
Rails Error Dashboard started as an internal tool for Audio Intelli.

When you’re managing errors across:

iOS app (Swift)
Android app (Kotlin)
Web dashboard (Rails + Turbo)
Background AI processing (Queues + OpenAI/Whisper)

When you need unified error tracking. I could have used Sentry’s free tier, but I wanted:

Complete privacy for voice data
Unlimited errors without worrying about quotas
Full control over the monitoring stack
Long-term data retention

I built it for myself. Then I realized other indie Rails developers might value the same things.

So I:

Cleaned up the code
Wrote comprehensive tests
Added extensive documentation (25+ guides)
Made it fully configurable
Open-sourced it under MIT license

If you’re working with audio: Audio Intelli transforms podcasts, meetings, and voice recordings into searchable, actionable intelligence. We’re in private beta. Join the waitlist →

Same philosophy: build tools you own, not tools that own you.

Why I Open-Sourced It

Reason 1: I’m Not Building a SaaS

I don’t want to run error monitoring as a business. I built this to solve my own problem. Open-sourcing it means:

Others can maintain it if I get busy
The Rails community can make it better
Nobody gets vendor locked-in to me
It stays free forever (MIT license)

Reason 2: Rails Deserves Better Self-Hosted Options

The Rails ecosystem is moving toward eliminating unnecessary SaaS dependencies:

Kamal → replaces Heroku
Solid Queue → replaces Sidekiq Enterprise
Solid Cache → replaces Redis Cloud
Rails Error Dashboard → alternative to Sentry/Rollbar

This is the indie hacker way: own your tools, control your costs, stay independent.

Reason 3: I Believe in Data Sovereignty

Your error data contains your business logic, user behavior patterns, and potentially sensitive information.

You should own it. Not rent access to it.

The Long-Term Plan
I’m committed to maintaining this project long-term because:

I use it myself — Dogfooding ensures I care about quality
The Rails community needs this — Real demand for self-hosted error tracking
It’s not a business — No pressure to monetize or pivot.

Final Thoughts
This isn’t about saving money. Sentry’s free tier is generous, and if you’re just starting out, use it!

This is about:

Ownership — Your data, your server, your rules
Independence — Not at the mercy of pricing changes
Privacy — Complete data sovereignty
Learning — Understanding how error tracking works
Unlimited — No caps, no quotas, no artificial limits

If those values resonate with you, give Rails Error Dashboard a try.

It’s not perfect. It’s not as feature-rich as Sentry. But it’s free, it’s open-source, you own your data, and it works.

That’s good enough for me and might be for other indie Rails developers who value independence.

Links

Live Demo: rails-error-dashboard.anjan.dev (gandalf / youshallnotpass)
GitHub: github.com/AnjanJ/rails_error_dashboard
Audio Intelli: audiointelli.com

zs: One Command to Rule Your Zed Setup

Anjan — Sun, 27 Jul 2025 13:04:17 +0000

zs: One Command to Rule Your Zed Setup

TL;DR: Tired of manually configuring Zed for every project? Just run zs. It auto-detects your project type, installs debug dependencies, creates tasks, and sets up git hooks. Zero configuration required.

curl -sSL https://raw.githubusercontent.com/AnjanJ/zs/main/install.sh | bash
cd any-project
zs
✅ Rails project ready (15 tasks, debugging enabled)

The Problem

Every time I switched projects in Zed, I found myself:

🔧 Manually creating .zed/tasks.json for that specific framework
🐛 Setting up debug configurations (that never quite worked)
📦 Installing language-specific debug adapters
🔒 Configuring different git hooks for work vs personal projects
😤 Googling the same configurations over and over

Multiply this by switching between Rails, React, Python, and Elixir projects daily... you get the idea.

The Solution: zs

After one too many manual setups, I decided to automate everything. The goal? Zero cognitive load.

cd ~/work/canvas-lti-app
zs
✅ Rails project ready (21 tasks, debugging enabled)
  → Work project: commits need 'Refs: JIRA-XXXX'

That's it. No flags. No options. No decisions.

How It Works

zs is built on a simple philosophy: The best interface is no interface.

When you run zs, it:

Detects your project type automatically
- Rails? ✓ (Gemfile + config/application.rb)
- React? ✓ (package.json with react dependency)
- Python? ✓ (requirements.txt)
- Elixir? ✓ (mix.exs)
Installs only what Zed needs
- Ruby: debug gem (provides rdbg)
- Python: debugpy
- Elixir: elixir-ls
- Nothing else - no bundle install or npm install
Creates proper configurations
- .zed/tasks.json with framework-specific tasks
- .zed/debug.json with working debug configs (using Zed's format, not VS Code's!)
Configures smart git hooks
- Work projects: Reminds about JIRA tickets
- Personal projects: Standard format
- Never blocks, just reminds
Reports success in one line
- ✅ Project ready (15 tasks)

⚠️ Note on Debugging Support

Debugging in Zed is still evolving, and we're actively testing configurations:

Ruby: Experimental support via debug gem
Python: Full support with debugpy
JavaScript/TypeScript: Full support
Elixir: Not yet supported in Zed

We're updating configurations as Zed's debugging capabilities mature. Your mileage may vary!

Real-World Examples

Rails Project

// Auto-generated .zed/tasks.json includes:
{
  "label": "💎 Rails Server",
  "command": "bundle",
  "args": ["exec", "rails", "server"]
},
{
  "label": "🧪 Run Current Test File",
  "command": "bundle", 
  "args": ["exec", "rspec", "$ZED_FILE"]
},
// ... 13 more tasks

Work vs Personal Context

# Personal project
cd ~/code/my-app
zs
✅ Rails project ready (15 tasks, debugging enabled)

# Work project (auto-detected from path)
cd ~/work/enterprise-app
zs
✅ Rails project ready (21 tasks, debugging enabled)
  → Work project: commits need 'Refs: JIRA-XXXX'

Smart Caching

# First run
zs
✅ React project ready (16 tasks, debugging enabled)

# Run again
zs
✅ Already configured (react project)

The Hidden Power

While the interface is minimal, zs packs some smart features:

30-day refresh: Automatically updates stale configs
Docker awareness: Adjusts commands for containerized environments
.nohooks file: Disable git hooks when needed
Force refresh: zs force (hidden feature for power users)

Performance

Setup time: < 100ms ⚡

That's faster than opening the tasks menu in most editors.

Installation

# One-time install
curl -sSL https://raw.githubusercontent.com/AnjanJ/zs/main/install.sh | bash
source ~/.zshrc

# Then forever
cd any-project
zs

The Philosophy

After building increasingly complex configurations, I realized the best solution was radical simplification:

❌ 10+ commands → ✅ 1 command
❌ Multiple flags → ✅ 0 flags
❌ Verbose output → ✅ 1 line
❌ Manual validation → ✅ Automatic
❌ Decision fatigue → ✅ Zero decisions

As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."

Open Source

zs is MIT licensed and open for contributions. The entire brain is just 231 lines of shell script.

🌟 GitHub: AnjanJ/zs

Special features for contributors:

Plugin system for custom project types
Team configurations via .zsrc
CI/CD ready with GitHub Actions

What's Next?

Currently, zs supports:

Rails / Ruby
React / Node.js
Python
Elixir
LTI projects
Docker environments

Want support for your stack? PRs welcome!

Try It Now

If you use Zed and switch between projects, give zs a try:

curl -sSL https://raw.githubusercontent.com/AnjanJ/zs/main/install.sh | bash

Then just run zs in any project. That's it.

One command. Zero configuration. Pure productivity.

If zs saves you time, give it a star on GitHub. If you have ideas for improvement, I'd love to hear them!

What repetitive tasks do you automate in your development workflow? Let me know in the comments!

Anjan Jagirdar is a developer who believes the best tools get out of your way. When not automating workflows, he's probably debugging why his automation isn't working.

Setting Up Your macOS Development Environment and Automating Backups.

Anjan — Sat, 27 Jan 2024 07:44:59 +0000

Setting Up Your macOS Development Environment and Automating Backups.

My Repo : My-Mac-Settings

I recently got a new M3 Max 14" for myself and wanted to port over all my setup from earlier 14" M1 pro. Hence I came up with below scripts to make things easy for me.

Please leave your suggestions & thoughts.

In this comprehensive guide, I'll walk you through the process of setting up a robust development environment on your macOS system. I'll cover everything from installing essential tools and applications to automating the backup of critical configuration files.

My Brewfile contains all the apps installed via Homebrew, Macapp Store and also all of my VSCode extensions.

Then we will use the script auto_update_Brewfile.sh to update & upgrade brew formulae and apps installed using Homebrew. It also backups .zshrc file if it has been changed in past week.

Below are the paid apps I am using.

You can go through the entire list of apps in my Brewfile and remove or add apps as per your need.

AlDente Pro

AlDente Pro is a premium application designed to manage your MacBook's battery and charging effectively. It optimizes your battery's lifespan and keeps you informed about its health. Learn more about it here.

iStat Menus

iStat Menus offers real-time monitoring of your Mac's performance, including CPU usage, memory utilization, and network statistics. It's a powerful tool for keeping an eye on your system's health. Explore it further here.

Raycast

Raycast is a productivity powerhouse that replaces Spotlight and provides quick access to a wide range of functions. It enhances your workflow and simplifies everyday tasks. Discover more about it here.

Warp Terminal.

Warp is free for now and my goto terminal app which replaced iTerm for me. Its beautiful and very easy to use, I have paired it up with a free app called Fig.io

The Heart of the Setup: `setup_dev_env.sh` Script

The setup_dev_env.sh script is a powerful automation tool for macOS. It's designed to perform the following tasks:

Check for and install Homebrew.
Download a Brewfile from a specified URL.
Use Homebrew to install all the software listed in the Brewfile.

Initial Steps: Downloading and Running the Script

Downloading the Script: You can either clone the script from a my repository or copy-paste it directly from the here.

Hosting the Brewfile: Your Brewfile, which lists all the desired software and packages, should be hosted online and accessible via a direct URL. This URL is used by the script to download the Brewfile.

Modifying and Executing the Script: After downloading, modify the script to include the URL of your Brewfile. Then, run the script in the terminal after giving it execute permissions using chmod +x setup_dev_env.sh.

Automating Brewfile Backups with Crontab

An essential part of managing a development environment is keeping your software list up to date. This is where the auto_update_Brewfile.sh script comes in, coupled with cron jobs for automation.

Setting Up Cron Jobs: Use crontab -e to edit your cron jobs. Add a line to schedule the backup script to run at specific times, like every Friday and Sunday at 7 PM.

You can check if there are any present cron tasks or your changes have been made correctly or not by using crontab -l command.
It will show output as below.

Script Execution and Permissions: Make sure the backup script is executable by using chmod +x auto_update_Brewfile.sh.

Backup and Update: The script updates brew formulae, upgrades installed apps, backs up the old Brewfile, generates a new one, back ups .zshrc file if it has been changed in past week and pushes the updates to a specified GitHub repository.

Troubleshooting and Tips

Regularly check your cron jobs and script logs to ensure they're running as expected.
Test the scripts manually before relying on the automated schedule.

Conclusion

With the setup and automation described in this guide, you can easily maintain a robust development environment on your macOS system. Plus, you'll have peace of mind knowing that your essential configuration files are automatically backed up on GitHub.

Start by forking My-Mac-Settings and following the steps outlined here or in the readme. Enjoy your optimized macOS experience!