Mini-CoderBrain - Frequently Asked Questions

Version: 2.1.0 Last Updated: October 2025

📋 Table of Contents

General

What’s new in v2.1?

Three major features:

Behavior Profiles - 4 customizable AI modes (default, focus, research, implementation)
Patterns Library - 4,700 lines of behavioral training (zero token cost)
Smart Metrics - Automatic effectiveness tracking with /metrics command

Plus: Comprehensive documentation, migration guide, user guides

See also: V2.1 Release Notes

Is v2.1 backward compatible?

YES! 100% backward compatible.

No breaking changes
Default profile = v2.0 behavior
All v2.0 features work unchanged
Optional feature activation

You can upgrade risk-free and ignore new features if you want.

See also: Migration Guide

Should I upgrade from v2.0?

Yes, if you want:

✅ Customizable AI behavior (profiles)
✅ Data-driven insights (metrics)
✅ Modular behavioral system (patterns)
✅ Longer conversations (focus profile)
✅ Deeper learning (research profile)

Stay on v2.0 if:

❌ Happy with current behavior
❌ Don’t need customization
❌ Want to wait for v2.1 stability

Migration time: 5 minutes Risk: None (fully backward compatible)

What’s the token impact?

v2.1 Token Cost: +200 tokens avg per session (~0.1% increase)

Breakdown:

Patterns Library: +0 tokens (read on-demand)
Behavior Profiles: +150-300 tokens (once per session)
Metrics System: +0 tokens (background collection)

Comparison:

v2.0: 79.9% token reduction
v2.1: 79.8% token reduction

Result: Virtually unchanged efficiency, massive feature addition!

Behavior Profiles

What are behavior profiles?

Profiles control how Claude behaves during sessions.

Think of it like:

Text editor modes (Vi: insert, command)
Driving modes (Sport, Comfort, Eco)
IDE perspectives (Debug, Development)

4 core profiles:

default: Balanced (like v2.0)
focus: Minimal output, deep concentration
research: Verbose, detailed learning
implementation: Rapid feature building

See also: Profiles User Guide

Which profile should I use?

Quick Guide:

General work → default
Bug fixing → focus
Learning codebase → research
Building features → implementation
Not sure → default

Detailed Decision Matrix:

Your Task	Recommended Profile	Why
Full-stack development	default	Balanced for varied work
Complex bug fix	focus	Minimal distractions
New project onboarding	research	Detailed explanations
Sprint feature work	implementation	Fast execution
Production hotfix	focus	Time-sensitive
Architecture review	research	Deep understanding
Rapid prototyping	implementation	Quick iteration

See also: Profile Comparison

Can I switch profiles mid-session?

Not yet (coming in v2.2).

Current behavior:

Edit CLAUDE.md to change behavior_profile:
Restart Claude Code
New profile active

v2.2 will add: Environment variable override for single-session changes

Workaround: Use /metrics --profile to validate profile choice for next session

How do I create a custom profile?

Step-by-step:

# 1. Copy template
cp .claude/profiles/custom-template.md .claude/profiles/my-workflow.md

# 2. Edit settings
nano .claude/profiles/my-workflow.md

## Core Settings
output_style: terse              # terse, balanced, verbose
proactivity: low                 # low, medium, high
explanation_depth: minimal       # minimal, standard, detailed

# 3. Activate in CLAUDE.md
behavior_profile: "my-workflow"

# 4. Restart Claude Code

See also: Custom Profile Template

Do profiles affect code quality?

No! Profiles only change communication style, not coding standards.

What profiles change:

✅ Response verbosity (words per response)
✅ Suggestion frequency (how often to suggest)
✅ Explanation depth (how much to explain)
✅ Communication tone (friendly vs efficient)

What profiles DON’T change:

❌ Code quality (same standards always)
❌ Testing requirements (still writes tests)
❌ Security practices (always validates)
❌ Context awareness (always checks context)
❌ Tool selection (follows same patterns)

All profiles follow: systemPatterns.md coding standards

Patterns Library

What are behavioral patterns?

Patterns are reference documents that define behavioral rules.

5 core patterns:

pre-response-protocol - Mandatory checklist before responding
context-utilization - How to use memory bank effectively
proactive-behavior - When to make suggestions
anti-patterns - What NOT to do (1200 lines)
tool-selection-rules - Which tool for each task

Total: 4,700 lines of behavioral guidance

See also: Patterns User Guide

Do I need to read patterns?

No! Claude reads them automatically when needed.

You only read patterns for:

Understanding why Claude behaves certain way
Creating custom profiles (informed customization)
Contributing improvements
Learning Mini-CoderBrain methodology

Claude reads patterns when:

Stuck on decision → Reads relevant pattern
Unsure which tool → Reads tool-selection-rules
About to suggest → Reads proactive-behavior

User action required: None (automatic)

Why zero token cost?

Traditional approach (wasteful):

Every prompt: Inject all 4,700 lines
Result: Massive token waste

Mini-CoderBrain approach (efficient):

Prompt 1: No patterns (not needed)
Prompt 5: Need guidance → Read specific pattern once
Prompt 10: Pattern already in history (no re-read)
Result: Read only when needed

Math:

Without on-demand: 4,700 lines × 100 prompts = 470,000 lines waste
With on-demand: 4,700 lines × 1 read = 4,700 lines (99% savings)

That’s how we maintain 79.8% token efficiency!

Can I modify patterns?

Yes! Patterns are markdown files, fully customizable.

How to modify:

# Edit any pattern
nano .claude/patterns/proactive-behavior.md

# Restart Claude Code to apply changes

What to modify:

Adjust suggestion frequency
Change banned questions list
Add project-specific anti-patterns
Customize tool preferences

Caution: Test changes! Patterns guide behavior, so edits affect Claude’s actions.

See also: Advanced Pattern Usage

Metrics System

What metrics are tracked?

Tool Usage:

Which tools used (Read, Edit, Bash, etc.)
How often each tool used
Tool usage patterns

Session Metrics:

Duration (minutes)
Operation count
Profile used
Tasks completed (future)
Errors (future)

Profile Performance:

Token usage (actual vs estimated)
Response characteristics
Effectiveness per profile

See also: Metrics User Guide

Is my code being tracked?

NO! Absolutely not.

What we DON’T track: ❌ Code content ❌ File names ❌ File paths ❌ Commit messages ❌ Conversation content ❌ Personal information

What we DO track: ✅ Tool usage counts (e.g., “Read used 15 times”) ✅ Session duration ✅ Profile used ✅ Operation counts

Privacy-first design: Only behavioral metadata, no sensitive data ever.

See also: Privacy & Data Storage

Can I disable metrics?

Yes, but why? Zero overhead and privacy-first!

To disable:

# Option 1: Remove metrics collector calls
# Edit .claude/hooks/session-end.sh
# Comment out metrics collection section

# Option 2: Delete metrics folder
rm -rf .claude/metrics/

# Option 3: Don't run /metrics command
# Metrics collected but not viewed

Recommended: Keep enabled. Metrics help optimize workflow with zero cost.

How do I use metrics to improve?

Weekly Review Process:

# 1. Check weekly summary
/metrics --weekly

# 2. Identify patterns
# - Which tools most used?
# - Which profiles most effective?
# - How long are sessions?

# 3. Compare profiles
/metrics --profile

# 4. Make adjustments
# - Switch to better-performing profile
# - Review tool selection patterns
# - Adjust workflow based on data

# 5. Repeat next week
# - Measure improvements
# - Iterate based on data

Example Optimization: Scenario-Based Optimization

Troubleshooting

Getting “Prompt too long” errors frequently

Symptom: Context conversations hitting token limits quickly, frequent compactions

Cause: Memory bloat from accumulated session updates in activeContext.md

Solution (v2.2+):

# 1. Run memory cleanup
/memory-cleanup

# This will:
# ✅ Archive old session updates (keeps last 5)
# ✅ Reduce token usage by 40-60%
# ✅ Prevent "Prompt too long" errors
# ✅ ALL data preserved in .claude/archive/

# 2. Check memory health
# Session-start will show warnings:
# 💡 Memory cleanup recommended (9+ updates)
# ⚠️  Memory bloat detected (13+ updates)

# 3. Preventive maintenance
# Run /memory-cleanup weekly during active development
# Hook will remind you when needed

How v2.2 Helps:

Session-start now excludes session history (48% token reduction)
Automatic memory health checks at session start
Proactive warnings before bloat becomes critical

Related: Memory Health Check Pattern

Profile not showing in session status

Symptom: No 🎭 Profile: ... line in session start

Solution:

# 1. Check CLAUDE.md has profile setting (line ~41)
grep "behavior_profile" CLAUDE.md

# 2. Verify profile file exists
ls .claude/profiles/default.md

# 3. Restart Claude Code completely
# Close all windows, reopen

# 4. Check session status
# Should show: 🎭 Profile: default

If still missing: Profile detection failed, defaults to “default” (works fine)

Metrics command shows no data

Symptom: /metrics shows “No session data available”

Solution:

# 1. Check if jq installed
which jq

# If missing, install:
# Ubuntu/Debian:
sudo apt-get install jq

# macOS:
brew install jq

# 2. Check metrics folder exists
ls .claude/metrics/sessions/

# 3. Work for a bit to generate data
# Metrics collected at session end

# 4. Try again
/metrics

Note: New sessions need time to accumulate data

Behavior seems same as v2.0

Possible Causes:

Using default profile (same as v2.0 by design)
- Solution: Try focus or research profile to see difference
Didn’t restart after changing profile
- Solution: Save CLAUDE.md, restart Claude Code
Profile name typo (falls back to default)
- Solution: Check exact spelling: “focus” not “Focus”
Cache from previous session
- Solution: Close all Claude windows, reopen

Verify profile is active: Check 🎭 Profile: [name] in session status

How do I rollback to v2.0?

Three options:

Option 1: Git Tag

git checkout v2.0-stable

Option 2: Restore Backup

# If you backed up before upgrade:
cp -r .claude-backup .claude

Option 3: Reinstall v2.0

git clone -b main https://github.com/kunwar-shah/mini-coder-brain.git
# Follow v2.0 installation

See also: Rollback Instructions

🔄 Still Have Questions?

Before Asking:

✅ Check relevant user guide:
✅ Search existing issues:
- GitHub Issues
✅ Try troubleshooting steps above

Still Stuck?

Open a GitHub issue: New Issue

Include:

Mini-CoderBrain version (v2.1)
Profile being used
Output of /metrics (if relevant)
Steps to reproduce
Expected vs actual behavior

📚 Documentation Index

Getting Started

README - Project overview
Migration Guide - Upgrade from v2.0
Release Notes - What’s new

User Guides

Behavior Profiles - Complete profiles guide
Patterns Library - Behavioral patterns reference
Smart Metrics - Metrics system guide
FAQ - This document

Reference

Can’t find answer? We’re here to help! 🤝

Open an issue • View docs