Also see Troubleshooting sections for further debugging tips

Supported platforms:

• macOS
• linux
• windows (experimental)

Core features should work on windows as long as running a bash terminal. Some MCP servers may not work as is and may need manual setup instead. Please raise any issue encountered and we will try to help.

Supported terminals:

• bash
• zsh

Run bash to open a bash terminal if running in an unsupported termnial (e.g. shell, powershell)

Required dependencies:

• Python 3.10+
• pip
• git
• jq
• claude

Required if using MCP servers (refer to .mcp.json for details):

• npx
• uvx
• uv
• pipx
• pnpx
• docker

Ensure the requirements above are met

# Clone repository
cd ~/ && git clone https://github.com/blueraai/clauder.git

# Install (must be run from the `clauder` dir)
cd clauder && bash ./clauder_install.sh

[ Important ]

Activating Clauder may override any existing .claude configuration. Backups will automatically be created to save/restore your existing configurations. These can be found at ./.claude-backup/, ./.claude-mcp-backup/ for MCP configurations.

Notably, .claude/settings.json will be overriden for consistency and security purposes, upon every activation (including auto-updates). Custom settings must be defined in .claude/settings.local.json to remain persisted throughout clauder activation.

Run in your project directory:

clauder_activate

# or you may activate it from anywhere else by providing a path to the project
# clauder_activate ./project_path

# or skip this step, start clauder, and choose 'activate' when prompted

This will copy the .claude configuration to your project.

Clauder's configuration will automatically:

• Create checkpoint commits before each session
• Protect sensitive files and directories (see .claude/.ignore and .claude/.immutable)
• Log all actions for live monitoring, or auditing purposes (see .claude/logs); enabled in .claude/preferences.md
• Enforce history and specifications tracking as you interact with Claude Code (see HISTORY.md, SPECIFICATIONS.md)
• Provides general guidelines/rules to Claude (see .claude/rules.md; Never guaranteed, but does help steering it; Do not solely rely on instructions for policing or workflows)
• Provide audio feedback on completion (optional, supports mac, linux experimental; enabled in .claude/preferences.md)
• Define custom commands for advanced workflows (e.g. /consult to consult a third party model for specific tasks, /spawn to create task specific agents, /recruit to recruit relevant agents for your project and needs, /review for a general review)
  • Required MCP servers detailed below.
• Define custom agents to help the main instance achieve specific tasks

Domain specific expansion packs available (including agents, commands, hooks and configurations - see below)

[ Important ]

Opening Claude without interacting is sufficient to index and learn all secrets in the directory. Never keep secrets such as .env in the project directory.

If secrets have been indexed or read by an AI such as Claude, you should consider removing them from the project, invalidating them and renewing them. Production secrets should be stored in a secure vault, unreadable by AI. Keeping secrets out of the working directory prevents auto-indexing, but does not prevent Claude from finding ways to access them through running commands or calling tools.

Disclaimer:

Clauder will try to prevent leaking secrets, and potentially destructive, or unrecoverable actions, by detecting unsafe operations and requesting a Human in the loop, but none of it is bulletproof.

Please make sure to supervise your AI's actions as you grant it access to sensitive or critical systems. It cannot be trusted and will inadvertently make unrecoverable mistakes, which may critically impair the company and its production services. Backup your systems, and sandbox as much as possible through restrictive AI-level access control. You are responsible for your AI's actions, as you are when using any other tool, or when managing a team.

Prefer closer, slower supervision when working on root/core nodes in your project. Equally, allow faster, lower supervision for faster iterations when working on leaf nodes, or when prototyping.

# Navigate to project root directory (must be a git repository)
cd replace-with-project-root-path # && git init (if not already a repository)

In your project's .gitignore, exclude the following paths for cleaner commits:

.claude 
.claude-backup
.claude-mcp-backup
.mcp.json

Start a new clauder session:

clauder

☕ clauder includes security features, auto-updates, and configuration backups. All Claude Code arguments supported (e.g. --continue to recall the last session)

In Claude, type:

/rules

This will define the mandatory guidelines for Claude Code.

[ Tip ]

• If your project includes a HISTORY.md file at root level, clauder will enforce keeping a history of requests and actions taken, and use it to reason about the next action to take. Comprehensive history tracking may take time.
• If your project includes a SPECIFICATIONS.md file at root level, clauder will enforce keeping an updated list of specifications as it takes actions, and use it to reason about the next action to take. When writing code manually, you may ask clauder to read the git diffs and backfill the specifications file. Comprehensive specifications tracking may take time.
• Define your secret files and folders in .claude/.ignore so clauder can guard them from being read/written.
• Define your read-only files and folders in .claude/.immutable so clauder can guard them from being overwritten.
• Exclude safe configuration files and folders in .claude/.exclude_security_checks so clauder can ommit them from safety checks (e.g. secret detection).
• Check .claude/requirements.md for prerequisites, and recommended MCP tools. clauder will automatically take advantage of those tools should you have added them to Claude Code.
• Check Claude Code's best practices for better results.
• Define your custom settings in .claude/settings.local.json instead of .claude/settings.json, so they remain persisted when clauder auto-updates.
• Declare custom rules in CLAUDE.md at root level for persisted intructions when clauder auto-updates.

Declare custom rules in CLAUDE.md at root level for persisted intructions when clauder auto-updates.

Those will be read by Claude Code on start.

Make sure these instructions do not conflict with clauder's rules (see .claude/rules.md).

Do not modify the clauder rules themselves as those will be reset when clauder auto-updates.

You may ask for a general purpose code review using:

/review

or about something specific:

/review Assess the responsiveness of this application

Create custom commands or sub-agents for project specic-reviews.

While Claude's models are performant for general coding, for particular tasks, such as ones requiring extensive context, or specialized training, requiring help from a different model may lead to better results.

If the consult7 MCP tool is added to Claude Code, with a valid OpenRouter key, clauder will allow you to consult any supported model via the following command (default: openai/gpt-5, 400k token context; for larger context you may alternatively use google/gemini-2.5-pro, 1M token context; larger context windows generally lower performance):

/consult <user query>

e.g.

/consult Review the security of this application

Note:

• Files and directories listed in .claude/.ignore will not be passed as context.
• Third party models consulted in the cloud do not have access to Claude Code's tools.

Claude may create dedicated agents for specific tasks. They are called Sub-Agents and report to the main Claude instance. These agents have their own system prompts, tools subsets (inherit all tools by default), and context window (unaware of other chats). They are helpful in creating and recalling task-specific personas and context.

clauder includes a agent-builder agent, which helps you define and craft performant agents for your specific needs. Should the context7 and consult7 MCP tools be set in Claude Code, it will automatically use them to help enhance the new agent's workflows, best practices, and toolsets. For better results, please be specific and detailed when creating specialized agents.

You may create a new agent simply by asking for it:

Create a new agent to help review my code, it should.. 

or using the /spawn command explicitly.

/spawn Create a new agent to help review my code, it should.. 

The resulting agent instructions will be define in .claude/agents/<agent-name>.md. You may review, and edit this file to further refine your new sub-agent. You may dismiss a sub-agent at any time, by deleting .claude/agents/<agent-name>.md.

New agents become available/unavailable on start of a new Claude Code session. Creating or deleting an agent will not apply to current sessions. Start a new clauder session to use your newly created agent.

[ Tip ]

Best practices:

• Tailor agents to your specific project and needs, as you would when recruiting people.
• Limit the number of agents, prefer smaller teams with clear separation of ownership/expertise. Lesser communication and orchestration loss.
• Leave all core coding to the main Claude instance, and consult other specialized agents for review or unrelated/leaf tasks. Agents have their own context and do not know about the general history and reasoning for how and why things were done a certain way, or what other agents have said. Relying on communication greatly degrades the signal and often leads to breakage or unintended side effects. These personas are not better at coding than the main instance, they run the same model and backend orchestration. They are good at prioritizing / directing attention to specific areas - which is particularly useful for review, consultation, and leaf-type activities (as opposed to core parts). Prefer one chef, with a few very good advisors, than too many chefs or too many advisors.

clauder includes a command to recommend sub-agents for your project.

You may ask for general project-specific recommendations using:

/recruit

or about something specific:

/recruit I want to make this web app..

Ensure the requirements above are met.

About MCP: https://modelcontextprotocol.io/docs/getting-started/intro

To easily add project specific MCP servers run in your project root:

clauder_activate

⚡ 66+ pre-integrated, hot-swappable, MCP servers for instant use.

• Configuration automatically backed up locally prior each activation.
• MCP servers become active upon running clauder.

You may remove them, or update their environment variables at any time in .mcp.json at root level.

Do not hardcode any secret keys in your project. Set and reference environment variables instead. Do not leave an empty or malformed .mcp.json file as it may interfere with clauder when adding servers to your existing configuration.

If you'd like to manually add MCP servers globally or at project level, beyond the list of pre-integrated servers, you may of course as you usually do. Clauder will honor them.

The following servers come pre-integrated for easy installation.

clauder also provides ready-made agents for various development projects, optionally installable as expansion packs.

clauder_activate --expansions <expansion_name> <expansion_name>

# e.g.
# clauder_activate --expansions general-software-dev frontend-dev

Expansions remain installed and auto-updated until .claude is removed.

All agents are automatically called by the main Claude instance when relevant, for advisory purposes.

If you'd like to query a sub-agent directly (advisory only by design):

/task <agent_name> "<query>"

# e.g.
#  /task system-architecture-consultant "Analyze the current system architecture..."
#  /task ux-research-specialist "Research user experience patterns for..."
#  /task qa-strategy-specialist "Develop testing strategy for..."

Refer to the expansion details for dedicated hooks and commands.

# Important: backup your configuration before resetting it
rm -rf ./.claude && clauder_activate

If you'd like a more surgical approach, you may delete the corresponding .claude/.expansion_packs entry and remove the corresponding agents, commands, hooks and settings for that expansion.

Frontend Development (frontend-dev)

• Agents
  • react-specialist - Expert consultant for React ecosystem development, providing code review, architecture guidance, and best practices recommendations
  • vue-specialist - Specialized consultant for Vue.js development, offering architectural guidance and Vue ecosystem best practices
  • angular-specialist - Expert consultant for Angular development, providing framework-specific guidance and architectural recommendations
  • svelte-specialist - Specialized consultant for Svelte development, offering modern reactive framework guidance and optimization strategies
  • typescript-specialist - Expert consultant for TypeScript implementation, providing type safety guidance and advanced type system recommendations
  • css-architect - Specialized consultant for CSS architecture, offering design system guidance and styling best practices
  • frontend-performance-optimizer - Expert consultant for frontend performance optimization, providing bundle analysis and rendering optimization strategies
  • accessibility-specialist - Specialized consultant for web accessibility (a11y), offering WCAG compliance guidance and inclusive design recommendations
  • security-reviewer - Expert consultant for frontend security, providing vulnerability assessment and security best practices
  • build-engineer - Specialized consultant for frontend build systems, offering bundler optimization and deployment pipeline guidance
• Commands / Hooks / Configuration
  • N/A

Backend Development (backend-dev)

• Agents
  • api-architect - Expert consultant for REST/GraphQL API design, microservices architecture, and API governance
  • database-architect - Specialized consultant for database design, offering schema optimization and data modeling strategies
  • auth-specialist - Expert consultant for authentication and authorization systems, providing security pattern guidance
  • caching-specialist - Specialized consultant for caching strategies, offering performance optimization and cache management guidance
  • messaging-specialist - Expert consultant for message queues and event-driven architectures, providing distributed system guidance
  • observability-engineer - Specialized consultant for monitoring and observability, offering logging, metrics, and tracing strategies
  • backend-security-specialist - Expert consultant for backend security, providing vulnerability assessment and security hardening guidance
  • backend-testing-specialist - Specialized consultant for backend testing strategies, offering test architecture and quality assurance guidance
  • serverless-specialist - Expert consultant for serverless architectures, providing cloud-native development and function optimization guidance
• Commands / Hooks / Configuration
  • N/A

Data Science (data-science)

• Agents
  • data-scientist - Expert consultant for data analysis and statistical modeling, providing insights and analytical strategy guidance
  • data-engineer - Specialized consultant for data pipeline architecture, offering ETL optimization and data infrastructure guidance
  • ml-engineer - Expert consultant for machine learning implementation, providing model deployment and ML pipeline guidance
  • data-visualization-specialist - Specialized consultant for data visualization, offering chart design and interactive dashboard guidance
  • analytics-engineer - Expert consultant for analytics implementation, providing tracking strategy and data analysis guidance
  • data-quality-engineer - Specialized consultant for data quality assurance, offering validation strategies and data governance guidance
  • statistical-consultant - Expert consultant for statistical analysis, providing experimental design and hypothesis testing guidance
  • ml-ethics-advisor - Specialized consultant for AI ethics and responsible ML, offering bias detection and fairness assessment guidance
• Commands / Hooks / Configuration
  • N/A

AI Development (ai-dev)

• Agents
  • openai-api-specialist - Expert consultant for OpenAI API integration, providing model selection and prompt engineering guidance
  • openrouter-specialist - Specialized consultant for OpenRouter integration, offering multi-model API strategy and cost optimization guidance
  • langchain-specialist - Expert consultant for LangChain framework, providing chain design and agent development guidance
  • langgraph-specialist - Specialized consultant for LangGraph orchestration, offering workflow design and state management guidance
  • transformers-specialist - Expert consultant for Hugging Face Transformers, providing model fine-tuning and deployment guidance
  • vllm-specialist - Specialized consultant for vLLM inference optimization, offering high-performance model serving guidance
  • unsloth-specialist - Expert consultant for Unsloth fine-tuning, providing efficient model training and optimization guidance
  • rag-specialist - Specialized consultant for Retrieval-Augmented Generation, offering knowledge base design and retrieval optimization guidance
  • conversational-ai-specialist - Expert consultant for conversational AI systems, providing chatbot design and dialogue management guidance
  • agentic-orchestration-specialist - Specialized consultant for multi-agent systems, offering agent coordination and workflow orchestration guidance
  • agent-observability-specialist - Expert consultant for AI agent monitoring, providing performance tracking and debugging guidance
  • agent-cost-specialist - Specialized consultant for AI cost optimization, offering token usage analysis and cost management strategies
  • mcp-specialist - Expert consultant for Model Context Protocol, providing tool integration and MCP server development guidance
  • llm-security-specialist - Specialized consultant for LLM security, offering prompt injection protection and AI safety guidance
• Commands / Hooks / Configuration
  • N/A

Infrastructure (infrastructure)

• Agents
  • cloud-infrastructure-architect - Expert consultant for cloud infrastructure design, providing multi-cloud strategy and resource optimization guidance
  • container-orchestration-specialist - Specialized consultant for Kubernetes and Docker, offering containerization strategy and orchestration guidance
  • devops-pipeline-engineer - Expert consultant for CI/CD pipeline design, providing automation strategy and deployment optimization guidance
  • site-reliability-engineer - Specialized consultant for SRE practices, offering reliability engineering and incident response guidance
  • infrastructure-security-specialist - Expert consultant for infrastructure security, providing security hardening and compliance guidance
  • infrastructure-cost-optimizer - Specialized consultant for cloud cost optimization, offering resource management and cost analysis guidance
  • database-infrastructure-specialist - Expert consultant for database infrastructure, providing scaling strategies and performance optimization guidance
  • network-architecture-specialist - Specialized consultant for network design, offering connectivity strategy and security architecture guidance
• Commands / Hooks / Configuration
  • N/A

Game Development (game-dev)

• Agents
  • game-mechanics-designer - Expert consultant for game mechanics design, providing gameplay balance and system design guidance
  • game-state-manager - Specialized consultant for game state management, offering save systems and progression tracking guidance
  • game-performance-specialist - Expert consultant for game performance optimization, providing rendering optimization and frame rate guidance
  • game-input-specialist - Specialized consultant for game input systems, offering control scheme design and input handling guidance
  • game-audio-designer - Expert consultant for game audio design, providing sound implementation and audio engine guidance
  • level-design-architect - Specialized consultant for level design, offering world building and spatial design guidance
  • game-visual-designer - Expert consultant for game visual design, providing art direction and visual asset optimization guidance
• Commands / Hooks / Configuration
  • N/A

Desktop Development (desktop-dev)

• Agents
  • electron-specialist - Expert consultant for Electron applications, providing cross-platform desktop app development guidance
  • tauri-specialist - Specialized consultant for Tauri framework, offering Rust-based desktop app development guidance
  • flutter-desktop-specialist - Expert consultant for Flutter desktop development, providing cross-platform UI framework guidance
  • pwa-specialist - Specialized consultant for Progressive Web Apps, offering web-to-desktop conversion and offline capability guidance
  • neutralino-specialist - Expert consultant for Neutralino framework, providing lightweight desktop app development guidance
  • lynx-specialist - Specialized consultant for Lynx framework, offering Tauri alternative desktop development guidance
  • desktop-security-specialist - Expert consultant for desktop application security, providing security hardening and vulnerability assessment guidance
• Commands / Hooks / Configuration
  • N/A

General Software Development (general-software-dev)

• Agents
  • system-architecture-consultant - Expert consultant for system architecture design, providing scalable architecture and design pattern guidance
  • ux-research-specialist - Specialized consultant for user experience research, offering usability testing and user-centered design guidance
  • qa-strategy-specialist - Expert consultant for quality assurance strategy, providing testing methodology and quality management guidance
• Commands / Hooks / Configuration
  • N/A

Clone .claude-expansion-packs/example to get started. The folder name is the name of your expansion. Define your custom agents, commands, hooks (set up in settings.json), and configurations.

Disclaimer: Remember to be specific, to prevent conflicts with the base clauder setup.

Disabled by default, requires logging enabled in .claude/preferences.md

Every event and automated clauder intervention is locally logged in a SQLite database for auditing and live monitoring Claude.

That database is available at .claude/logs/trace.sqlite, once the first event has been logged.

Additionally, all bash commands ran and MCP tool calls are duplicated as text logs for easy inspection at .claude/logs/bash-logs.txt and .claude/logs/mcp-logs.txt.

Disabled by default, requires traces enabled in .claude/preferences.md

You may use or build any monitoring app you'd like to inspect that SQLite database. For convenience, a lightweight tracer app is also shipped with clauder.

You may run the tracer app in a parallel termimal at any time, new events will be live streamed to it:

# install (using conda, in project directory)
conda create -n clauder_trace python=3.11 -y && conda activate clauder_trace && pip install -r ./.claude/tracer/requirements.txt

# install (without conda, in project directory)
pip install -r ./.claude/tracer/requirements.txt

# run (using conda, in project directory)
conda activate clauder_trace && clauder_trace

# run (without conda, in project directory)
clauder_trace

Access the tracer app at http://localhost:4441 in your browser.

[ Tip ]

You may set any of the supported themes: green, blue, gray, dark

Run in browser console: localStorage.setItem('clauder.tracer.theme', 'dark'); location.reload();

Defines hooks and permissions. Will be overriden upon auto-updating to ensure a safe and working setup.

For custom settings use .claude/settings.local.json instead, so they remain persisted when clauder auto-updates.

Files and directories to ignore (forbidden read & write).

[ Note ]

As of July 2025, there is no possible way to prevent Claude from automatically & silently learning every change made to the codebase, including secrets. These are only meant as a best effort to prevent retrieving them.

Files and directories that cannot be modified (read-only).

[ Note ]

The immutable file list is strictly enforced and cannot be overridden, even with explicit user permission.

Files and directories to skip in security scans.

Behavioral guidelines.

[ Note ]

Rules can never be enforced, they are used to steer the AI in a desired direction.

User preferences and customization settings.

Clauder dependencies and recommended MCP servers.

• Never store in project: Keep secrets outside the working directory
• Secure vaults: Use dedicated secret management systems (e.g. doppler, hashicorp vault, unix pass)
• AI isolation: Ensure AI cannot access production secrets
• Regular rotation: Rotate secrets if accidentally exposed

• Human oversight: Always supervise AI operations
• Backup systems: Maintain regular backups of critical systems
• Sandboxing: Use isolated environments for AI testing
• Access limits: Restrict AI access to sensitive systems

When working with monorepos, where packages may share git versionning with a parent folder, or where Clauder may need to navigate to different packages to operate, you'll need Clauder to be activated in each package. To do so, you'll need to:

1. Run clauder_activate at root level and at package level
2. (If sharing a parent git repository) disable git_requirement_checks in the .claude/preferences.json at package level
3. Ensure your clauder configuration files (e.g. .ignore, .immutable, .exclude_security_checks) are accurate both at root level and at package level, depending what Clauder's current directory is.

Clauder crashes my terminal

# Clauder will exit for safety purposes when detecting potential secrets, so they do not get indexed by Claude.
# For details about problematic files, run:

clauder_security_check & echo done

New agent not found

# New agents become available/unavailable on start of a new Claude Code session.
# Creating or deleting an agent will not apply to current sessions. 
# Start a new session to use your newly created agent.

clauder # (or) clauder --continue

Missing required tools

# Install required tools
brew install git jq  # macOS
sudo apt install git jq  # Ubuntu/Debian

Git repository not initialized

# Initialize git repository
git init

Permission denied errors

# Make hooks executable
chmod +x .claude/hooks/*.py
chmod +x .claude/hooks/*.sh

Audio not working

# Check audio preferences
cat .claude/preferences.json
# Ensure "audio_summary.enabled" is true

Safe commands blocked

# You may choose to disable unsafe command detection in `.claude/preferences.json` at your own risk

.claude/*: [Errno 2] No such file or directory

# You may have an early legacy version of Clauder installed, which is no longer supported. 
# Please pull the latest clauder and rerun 'bash ./clauder_install.sh'.
# Newer versions of Clauder now auto-updates, so you never have to do it again.

Aliases not working

# Re-run alias setup (Important: Run from the `clauder` directory)
bash ./clauder_install.sh
# Or restart your shell

Security checks failing

# Check exclusion patterns (Important: Do not exclude actual secrets)
cat .claude/.exclude_security_checks

# Alternatively, you may choose to disable secret pattern detection in `.claude/preferences.json`

claude: command not found

# clauder runs claude in a standard 'bash' shell, irrespective of where it was started (e.g. ZSH).
# You may only have Claude Code installed in a ZSH terminal.

# Please make sure the 'claude' command is also installed in bash terminals (run 'bash' and install Claude Code using these instructions: https://docs.anthropic.com/en/docs/claude-code/troubleshooting).

# Once installed, confirm installation using:
bash
# Then, in bash terminal
which claude # macOS, Linux
where claude # windows

# If claude's path is displayed, you may now run in any terminal (e.g. ZSH, bash):
clauder
# Else, please refer to troubleshooting link above to fix your Claude Code installation.

Clauder does not auto-update, or 'clauder' fails unexpectedly after updating to the latest version

# You may have an early legacy version of Clauder installed, which is no longer supported. 
# Please pull the latest clauder and rerun 'bash ./clauder_install.sh'.
# Newer versions of Clauder now auto-updates, so you never have to do it again.

If you're not sure where to start, have an issue, or a question, just let us know what's on your mind, we're here to help.

You may provide feedback by:

• Opening an issue at the top of this page
• Chatting with us on Discord
• Emailing us security concerns

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Hooks documentation: https://docs.anthropic.com/en/docs/claude-code/hooks

Tip: Hooks are dedupped and run in parallel. They rely on strict interpretation from the console output for decision making. Make sure never to print anything other than the expected specifications for Claude Code to parse it correctly, any offset will cause Claude Code to omit the decision entirely. Beware of infinite loop, particularly when blocking a 'Stop' event to inject an extra step, as the 'Stop' event will retrigger once that step completes. By default, Claude Code will continue unless set to 'False'. A 'block' decision only blocks a given interaction with a 'reason', at which point Claude Code may decide to take a different action or find a way to bypass it. Use claude --debug to enable debug logs when working on hooks, as they are hidden by default. When developing, never test clauder changes on a real project as bugs may have irreparable consequences - use a test project instead.