---
slug: "claude-code-onboarding"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/kumaran-is/claude-code-onboarding@main/README.md"
repo: "https://github.com/kumaran-is/claude-code-onboarding"
source_file: "README.md"
branch: "main"
---
# Claude Code — Team Onboarding Kit
[](https://deepwiki.com/kumaran-is/claude-code-onboarding)
[](https://docs.anthropic.com/en/docs/claude-code)
[](https://medium.com/@kumaran.isk/my-claude-code-setup-heres-what-i-learned-d0403b1b1fec)
[](https://medium.com/@kumaran.isk/the-practices-that-fixed-my-claude-code-workflow-f72ada6a52a5)
[](https://medium.com/@kumaran.isk/claude-code-beyond-sub-agents-orchestrating-peer-to-peer-ai-with-agent-teams-3406d2169bfd)
[](https://medium.com/@kumaran.isk/claude-code-agent-teams-a-7-agent-full-stack-app-playbook-f584a7fa1a69)
[](https://medium.com/@kumaran.isk/how-i-added-voice-mode-to-claude-code-hands-free-coding-in-5-minutes-101a5086968f)
[](https://medium.com/@kumaran.isk/2c7333c10988)
[](https://medium.com/@kumaran.isk/3-ways-to-run-claude-code-cli-desktop-and-web-a-developers-workflow-guide-fe6f2581b2a8)
[](https://medium.com/@kumaran.isk/scheduled-tasks-in-claude-desktop-your-machine-is-now-a-24-7-autonomous-agent-1ba126bc94e8)
**Get your team from zero to productive with Claude Code in under 30 minutes.**
This repository is a pre-configured starter kit packed with agents, skills, slash commands, and MCP integrations — ready to go for the following tech stack:
| Layer | Technologies |
|---|---|
| **Backend** | Java 21, Spring Boot WebFlux v3.5.x, Node.js v24.14, NestJS v11.17.x, Python v3.14 |
| **Agentic AI** | Python 3.14, LangChain v1.2.8, LangGraph v1.0.7, Google ADK, FastAPI 0.135.2 |
| **Frontend** | Angular 21.2.x, TypeScript 5.9.x, A2UI v0.8 (Agent-to-User Interface renderer), Three.js r160+ (3D/WebGL) |
| **Mobile** | Flutter 3.41.x, Dart 3.10.9, three_dart (3D in Flutter) |
| **Data & Infra** | PostgreSQL, pgvector (vector search), Weaviate Serverless, Firebase |
| **AI Tooling** | Claude Code, MCP servers |
Clone it, install Claude Code, and start building.
## Table of Contents
- [Claude Code — Team Onboarding Kit](#claude-code--team-onboarding-kit)
- [Table of Contents](#table-of-contents)
- [What is Claude Code?](#what-is-claude-code)
- [1. Prerequisites](#1-prerequisites)
- [2. Clone This Repo](#2-clone-this-repo)
- [3. Set Up Your Editor (Install VS Code)](#3-set-up-your-editor-install-vs-code)
- [4. Install Claude Code](#4-install-claude-code)
- [Native Binary (Recommended)](#native-binary-recommended)
- [5. First-time Using Claude Code](#5-first-time-using-claude-code)
- [6. Install Claude-Mem (Persistent Memory) *(Optional)*](#6-install-claude-mem-persistent-memory-optional)
- [What Claude-Mem Does](#what-claude-mem-does)
- [6a. Set Up Team Memory Sharing *(Optional)*](#6a-set-up-team-memory-sharing-optional)
- [7. Enable Voice Mode *(Optional)*](#7-enable-voice-mode-optional)
- [One-Prompt Setup](#one-prompt-setup)
- [Manual Setup](#manual-setup)
- [Prerequisites](#prerequisites)
- [Quick Install](#quick-install)
- [What Each Step Does](#what-each-step-does)
- [OpenAI API Configuration](#openai-api-configuration)
- [Usage](#usage)
- [How It Works](#how-it-works)
- [Auto-Approve Voice Tools](#auto-approve-voice-tools)
- [Platform-Specific Dependencies](#platform-specific-dependencies)
- [Troubleshooting](#troubleshooting)
- [8. Try It Out — Your First 5 Minutes](#8-try-it-out--your-first-5-minutes)
- [Ask about the project](#ask-about-the-project)
- [Scaffold something](#scaffold-something)
- [Use a sub-agent](#use-a-sub-agent)
- [Pull live docs with MCP](#pull-live-docs-with-mcp)
- [Check what's loaded](#check-whats-loaded)
- [A note on permissions](#a-note-on-permissions)
- [9. Understanding Claude Code Components](#9-understanding-claude-code-components)
- [How They Fit Together](#how-they-fit-together)
- [Decision Matrix - When to Use What](#decision-matrix---when-to-use-what)
- [CLAUDE.md (Project Context)](#claudemd-project-context)
- [Slash Commands — Reusable Prompt Shortcuts](#slash-commands--reusable-prompt-shortcuts)
- [Agents (Subagents) — Specialist AI Personas](#agents-subagents--specialist-ai-personas)
- [Subagent-Driven Development (SDD) — Plan-to-PR Pipeline](#subagent-driven-development-sdd--plan-to-pr-pipeline)
- [Skills — Auto-Activated Knowledge](#skills--auto-activated-knowledge)
- [MCP Servers — External Tool Integrations](#mcp-servers--external-tool-integrations)
- [settings.json Configuration](#settingsjson-configuration)
- [Hooks — Automated Guardrails](#hooks--automated-guardrails)
- [Lessons Log — Self-Improvement Loop](#lessons-log--self-improvement-loop)
- [Model Selection \& Cost Awareness](#model-selection--cost-awareness)
- [10. Cheaper Alternative: MiniMax M2.5](#10-cheaper-alternative-minimax-m25)
- [Why Choose MiniMax M2.5?](#why-choose-minimax-m25)
- [Overview of MiniMax M2.5 for Coding](#overview-of-minimax-m25-for-coding)
- [Step-by-Step Configuration](#step-by-step-configuration)
- [11. Multiple Sub Agents](#11-multiple-sub-agents)
- [12. Agent Teams — Coordinated Multi-Agent Collaboration](#12-agent-teams--coordinated-multi-agent-collaboration)
- [How to Enable](#how-to-enable)
- [13. Claude Code Desktop — GUI with Live Preview](#13-claude-code-desktop--gui-with-live-preview)
- [What It Can Do](#what-it-can-do)
- [Testing Frontend SPAs (Angular, React)](#testing-frontend-spas-angular-react)
- [Testing Backend REST APIs (Spring Boot, NestJS)](#testing-backend-rest-apis-spring-boot-nestjs)
- [Testing Flutter Apps (Canvas Limitation)](#testing-flutter-apps-canvas-limitation)
- [CI/CD \& PR Workflow](#cicd--pr-workflow)
- [Remote SSH Debugging](#remote-ssh-debugging)
- [Desktop vs CLI — When to Use What](#desktop-vs-cli--when-to-use-what)
- [Quick Start](#quick-start)
- [14. What Gets Sent to the LLM?](#14-what-gets-sent-to-the-llm)
- [Context Window Anatomy](#context-window-anatomy)
- [What Each Layer Contains](#what-each-layer-contains)
- [Key Takeaways](#key-takeaways)
- [15. What's in This Repo](#15-whats-in-this-repo)
- [MCP Servers (`.mcp.json`)](#mcp-servers-mcpjson)
- [Browser Automation](#browser-automation)
- [Sample Prompts](#sample-prompts)
- [16. iOS App Store Release Pipeline](#16-ios-app-store-release-pipeline)
- [17. Android Google Play Release Pipeline](#17-android-google-play-release-pipeline)
- [16. Hands-On Exercises](#16-hands-on-exercises)
- [Exercise 1: Scaffold a Flutter Fitness App](#exercise-1-scaffold-a-flutter-fitness-app)
- [Exercise 2: Build a Weather REST API (Java)](#exercise-2-build-a-weather-rest-api-java)
- [Exercise 3: Build a Todo API (NestJS)](#exercise-3-build-a-todo-api-nestjs)
- [Exercise 4: Build an Analytics API (Python)](#exercise-4-build-an-analytics-api-python)
- [Exercise 5: Design a Full-Stack E-Commerce System](#exercise-5-design-a-full-stack-e-commerce-system)
- [Exercise 6: Pull Live Docs with Context7 (MCP)](#exercise-6-pull-live-docs-with-context7-mcp)
- [Exercise 7: Design \& Review Architecture](#exercise-7-design--review-architecture)
- [Exercise 8: Build an AI Agent Service (Agentic AI)](#exercise-8-build-an-ai-agent-service-agentic-ai)
- [Exercise 9: Domain-Driven Design with DDD Architect](#exercise-9-domain-driven-design-with-ddd-architect)
- [Exercise 10: Add a Feature End-to-End](#exercise-10-add-a-feature-end-to-end)
- [Exercise 11: Build an A2UI Renderer (Agent-to-User Interface)](#exercise-11-build-an-a2ui-renderer-agent-to-user-interface)
- [Exercise 12: Build a Google ADK Agent Service](#exercise-12-build-a-google-adk-agent-service)
- [Exercise 13: Build a Three.js 3D Scene (Angular/Web)](#exercise-13-build-a-threejs-3d-scene-angularweb)
- [Exercise 14: Build a three\_dart 3D Scene (Flutter)](#exercise-14-build-a-three_dart-3d-scene-flutter)
- [What's Next?](#whats-next)
- [17. Development Workflow — Putting It All Together](#17-development-workflow--putting-it-all-together)
- [How Components Interact](#how-components-interact)
- [Phase 1: Design \& Architecture](#phase-1-design--architecture)
- [Phase 2: Scaffold \& Bootstrap](#phase-2-scaffold--bootstrap)
- [Phase 3: Feature Development](#phase-3-feature-development)
- [Phase 4: Review \& Enforce Quality](#phase-4-review--enforce-quality)
- [Phase 5: Evolve Your Setup](#phase-5-evolve-your-setup)
- [17a. AI-DLC — Full Development Lifecycle Workflow *(Optional)*](#17a-ai-dlc--full-development-lifecycle-workflow-optional)
- [How It Works](#how-it-works)
- [How It Fits With This Kit](#how-it-fits-with-this-kit)
- [18. Security Considerations](#18-security-considerations)
- [What Goes to Anthropic's API](#what-goes-to-anthropics-api)
- [MCP Server Credentials](#mcp-server-credentials)
- [The `--dangerously-skip-permissions` Flag](#the---dangerously-skip-permissions-flag)
- [Pre-configured Guardrails in This Kit](#pre-configured-guardrails-in-this-kit)
- [Checklist Before Using Claude Code on a Real Project](#checklist-before-using-claude-code-on-a-real-project)
- [19. Customizing the Kit](#19-customizing-the-kit)
- [Adding a New Agent](#adding-a-new-agent)
- [Adding a New Slash Command](#adding-a-new-slash-command)
- [Adding a New Skill](#adding-a-new-skill)
- [Adding a New Hook](#adding-a-new-hook)
- [Removing Components You Don't Need](#removing-components-you-dont-need)
- [Version Update Guide](#version-update-guide)
- [20. Claude Code Power Features](#20-claude-code-power-features)
- [Keyboard Shortcuts (Inside Claude Code)](#keyboard-shortcuts-inside-claude-code)
- [Essential CLI Flags](#essential-cli-flags)
- [Core Tools](#core-tools)
- [Permission Model](#permission-model)
- [21. Tips \& Best Practices](#21-tips--best-practices)
- [Prompting Best Practices](#prompting-best-practices)
- [Common Pitfalls — Avoid These](#common-pitfalls--avoid-these)
- [@ File References](#-file-references)
- [Context Window Management](#context-window-management)
- [Parallel Workflows](#parallel-workflows)
- [Team Collaboration Patterns](#team-collaboration-patterns)
- [Plugins Ecosystem](#plugins-ecosystem)
- [Skills — Best Practices](#skills--best-practices)
- [Writing a Good CLAUDE.md](#writing-a-good-claudemd)
- [The Basics: WHAT → WHY → HOW](#the-basics-what--why--how)
- [Key Principles](#key-principles)
- [Progressive Disclosure Example](#progressive-disclosure-example)
- [Quick Rules of Thumb](#quick-rules-of-thumb)
- [When Claude Ignores Its Rules](#when-claude-ignores-its-rules)
- [Start-of-Task Prompt](#start-of-task-prompt)
- [When Claude Guesses Instead of Verifying](#when-claude-guesses-instead-of-verifying)
- [When Claude Flip-Flops](#when-claude-flip-flops)
- [When Challenging Claude's Analysis](#when-challenging-claudes-analysis)
- [22. Troubleshooting](#22-troubleshooting)
- [`command not found: claude`](#command-not-found-claude)
- ["Context too large" error](#context-too-large-error)
- [Edit tool fails with "string not found"](#edit-tool-fails-with-string-not-found)
- [MCP server not connecting](#mcp-server-not-connecting)
- [Claude isn't using skills or agents](#claude-isnt-using-skills-or-agents)
- [Background task not responding](#background-task-not-responding)
- [Permission errors](#permission-errors)
- [Windows-Specific Setup](#windows-specific-setup)
- [Run diagnostics](#run-diagnostics)
- [23. Quick Reference Card](#23-quick-reference-card)
- [Commands You'll Use Every Day](#commands-youll-use-every-day)
- [Scaffolding](#scaffolding)
- [Design \& Review](#design--review)
- [Agents (use @name)](#agents-use-name)
- [Keyboard Shortcuts](#keyboard-shortcuts)
- [MCP Tips](#mcp-tips)
- [24. Resources](#24-resources)
---
## What is Claude Code?
**[Claude Code](https://code.claude.com/docs/en/overview)** is an **agentic AI coding assistant that lives in your terminal**. It understands your codebase, edits files, runs commands, and writes code — all through natural language.
Think of it as a senior developer pair-programming with you who knows your entire project, follows your team's conventions, and never gets tired.
## 1. Prerequisites
Before you begin, make sure you have:
- **A Claude subscription** — Claude Pro or Max at [claude.ai](https://claude.ai), or an Anthropic API key from the [Console](https://console.anthropic.com)
**Optional for Quick Start (required for MCP servers):**
- [Node.js v24+](https://nodejs.org/en/download)
- [Python v3.14+](https://www.python.org/downloads/)
## 2. Clone This Repo
This repo is your playground — use it to learn and practice Claude Code (Agentic AI coding assistant) and get familiar with its components (agents, skills, slash commands, hooks, MCP servers, memory) so you can automate your development workflow.
**Option A: Learn & Explore (recommended for first-timers)**
Clone the full repo and work through the exercises:
```bash
git clone https://github.com/kumaran-is/claude-code-onboarding.git
cd claude-code-onboarding
```
**Option B: Adopt into an Existing Project**
Already have a project? Copy just the Claude Code configuration into it:
```bash
# From the cloned repo, copy the config into your project
cp -r claude-code-onboarding/.claude/ your-project/.claude/
cp claude-code-onboarding/CLAUDE.md your-project/
cp claude-code-onboarding/.mcp.json your-project/
# Then customize for your project
cd your-project
```
After copying, you'll want to:
1. Edit `CLAUDE.md` — replace the tech stack and conventions with your project's
2. Edit `.claude/settings.json` — adjust `permissions.allow` for your build tools (e.g., remove `flutter` if you don't use it)
3. Edit `.mcp.json` — remove MCP servers you don't need, add project-specific ones
4. Remove agents/skills/commands for stacks you don't use
5. Run `chmod +x .claude/hooks/*.sh` to make hooks executable
6. Install the git pre-commit secrets hook (blocks commits containing API keys, tokens, and credentials):
```bash
cp git-hooks/pre-commit-secrets.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```
> **Customize for your tech stack and team.**
> This kit ships with skills, agents, rules, and commands covering Java, NestJS, Python, Angular, Flutter, iOS, Android, and more — but you don't need all of them. Keep only what matches your stack and workflow:
>
> | Component | Where | What to trim |
> |-----------|-------|--------------|
> | **Skills** | `.claude/skills/` | Delete skill folders for stacks you don't use (e.g. remove `java-spring-api/` if you're Python-only) |
> | **Agents** | `.claude/agents/` | Remove agent `.md` files for domains outside your stack — each one adds ~150 tokens to every session |
> | **Rules** | `.claude/rules/` | Keep `core-behaviors.md`, `lessons.md`, and `code-standards.md` as a minimum. Add team-specific rules as new files in this folder — they are always loaded |
> | **Commands** | `.claude/commands/` | Keep slash commands your team will actually use; delete the rest |
> | **Hooks** | `.claude/hooks/` + `settings.json` | Disable hooks you don't need by removing their entry from `settings.json` under `hooks:` |
> | **MCP servers** | `.mcp.json` | Remove servers for tools you don't use — each connected server adds to session startup time |
>
> The goal is a lean, focused setup: fewer agents means less context overhead per session, fewer rules means clearer signal, and fewer commands means less noise in `/` autocomplete. Start minimal and add back what you find yourself needing.
## 3. Set Up Your Editor (Install VS Code)
We recommend open source **[Visual Studio Code](https://code.visualstudio.com/)** as your IDE, though Claude Code works from any terminal — no specific editor is required. Download and install **[Visual Studio Code](https://code.visualstudio.com/)** from the official site:
After installing, open the cloned project `claude-code-onboarding` with **[Visual Studio Code](https://code.visualstudio.com/)** and use the **integrated terminal** for the remaining steps.
## 4. Install Claude Code
Open the **[Visual Studio Code](https://code.visualstudio.com/)** integrated terminal and run the following:
### Native Binary (Recommended)
1. For macOS / Linux
```bash
curl -fsSL https://claude.ai/install.sh | bash
```
2. Reload your shell
```bash
source ~/.bashrc # or: source ~/.zshrc
```
3. After installation, **restart VS Code(Close and reopen VS Code)** so the terminal picks up the new PATH, then verify installation
```bash
claude --version
```
> For Windows, see the [official installation docs](https://code.claude.com/docs/en/quickstart).
## 5. First-time Using Claude Code
> **Note:** First-time users will be prompted to authenticate with a Claude Pro/Max subscription or an Anthropic API key.
From the VS Code terminal, launch the CLI:
```bash
claude
```
Follow the on-screen prompts to log in. Once authenticated with your **Claude Pro/Max subscription** or **Anthropic Console API key**. Claude Code automatically detects and loads the project configuration:
That's it! Claude Code will automatically detect and load:
| File / Directory | Purpose |
|---|---|
| `CLAUDE.md` | Project context and conventions |
| `.mcp.json` | MCP server configurations |
| `.claude/agents/` | Specialized AI agents |
| `.claude/skills/` | Domain knowledge and templates |
| `.claude/commands/` | Slash commands |
Try these right away:
```
> /project-status
> What agents and skills are available in this project?
> Explain the tech stack from CLAUDE.md
```
🔗 **Official Docs:** [https://code.claude.com/docs/en/quickstart](https://code.claude.com/docs/en/quickstart)
## 6. Install Claude-Mem (Persistent Memory) *(Optional)*
Claude Code forgets everything between sessions. **[Claude-Mem](https://github.com/thedotmack/claude-me)** gives Claude persistent memory across sessions.
Inside a Claude Code CLI session, run:
```
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
```
Then **restart Claude Code** (`/exit`) or restart (close and reopen) the vscode.
### What Claude-Mem Does
- **Automatically captures** what Claude Code does (file edits, decisions, tool usage)
- **Compresses** sessions into searchable memory using AI
- **Injects relevant context** at the start of new sessions
- **Web viewer** at `http://localhost:37777` to browse memory
Verify with: Inside a Claude Code CLI session, run:
```
> Do you have any memory from previous sessions?
```
### 6a. Set Up Team Memory Sharing *(Optional)*
Once each developer has claude-mem installed individually, **[claude-mem-sync](https://github.com/lopadova/claude-mem-sync)** lets the team share selected observations (decisions, bug fixes, discoveries) across a shared GitHub repo — so your team's collective knowledge grows over time.
Run the one-shot setup command inside a Claude Code session:
```
> /setup-team-memory
```
This command:
- Installs and configures `claude-mem-sync`
- Creates `.claude/memories/` folder structure in the repo
- Adds a GitHub Actions workflow that auto-merges contributions on push
- Updates `.gitignore` to keep raw contributions local
- Schedules weekly exports (Fridays 4pm) and imports (Saturdays 9am)
- Prints a full pass/fail verification table at the end
Safe to re-run — skips any step already completed. Each developer runs it once on their machine; the shared infrastructure files (workflow, memories folder) are committed once and shared via the repo.
## 7. Enable Voice Mode *(Optional)*
Claude Code does not support voice mode by default. VoiceMode is a community MCP server that adds this capability, letting you **talk to Claude Code** instead of typing, using OpenAI Whisper for STT (speech-to-text) and OpenAI TTS for speech output.
**Note:** VoiceMode supports any OpenAI-compatible STT/TTS service, not just OpenAI's Whisper/TTS.
### One-Prompt Setup
Open a Claude Code session and paste this prompt — it handles the full installation *(macOS, Linux, and Windows WSL2)*:
```text
Set up VoiceMode for Claude Code using OpenAI Whisper (STT) and OpenAI TTS (speech output). Do the following steps in order:
1. Check if UV is installed (uv --version). If not, install it: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Run: uvx voice-mode-install
3. Run: claude mcp add --scope user voicemode -- uvx --refresh voice-mode
4. Create or update ~/.voicemode/voicemode.env with these two lines:
VOICEMODE_TTS_BASE_URLS=https://api.openai.com/v1
VOICEMODE_STT_BASE_URLS=https://api.openai.com/v1
5. Check if OPENAI_API_KEY is set in the environment. If not, remind me to add it to ~/.zshrc and re-source it.
Tell me when each step completes and flag any errors before moving to the next step.
```
> After setup, restart Claude Code so the MCP server loads.
### Manual Setup
#### Prerequisites
- Python 3.14+
- A microphone and speakers (or headphones)
- An OpenAI API key (for Whisper STT and OpenAI TTS)
#### Quick Install
```bash
# 1. Install UV package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Install VoiceMode
uvx voice-mode-install
# 3. Register VoiceMode MCP server with Claude Code
claude mcp add --scope user voicemode -- uvx --refresh voice-mode
```
#### What Each Step Does
| Step | Command | What It Does |
|------|---------|-------------|
| **1** | `curl ... \| sh` | Installs UV, a fast Python package manager |
| **2** | `uvx voice-mode-install` | Installs the VoiceMode Python package and adds the `voicemode` CLI to your system. Also checks system dependencies (PortAudio, FFmpeg) |
| **3** | `claude mcp add ...` | Registers VoiceMode as an MCP server so Claude Code knows it exists. Without this, Claude Code has no idea the voice tools are installed — like installing PostgreSQL but never adding the connection string to your app |
#### OpenAI API Configuration
VoiceMode uses OpenAI Whisper for speech-to-text (STT) and OpenAI TTS for speech output — two separate services under the same API key:
```bash
# 1. Set your OpenAI key (add to ~/.zshrc to persist)
export OPENAI_API_KEY=your-openai-key
# 2. Configure voicemode to use OpenAI for both STT and TTS
# Add to ~/.voicemode/voicemode.env:
VOICEMODE_TTS_BASE_URLS=https://api.openai.com/v1
VOICEMODE_STT_BASE_URLS=https://api.openai.com/v1
# 3. Restart Claude Code so the MCP server picks up the new key
claude converse
```
> **Important:** The MCP server reads `OPENAI_API_KEY` from the environment at startup. If you set the key after Claude Code is already running, you must restart it for the change to take effect.
#### Usage
```bash
# Start Claude Code with voice mode
claude converse
# Or combine with auto-approved permissions (learning/playground only ⚠️)
claude --dangerously-skip-permissions converse
```
Once running, just **speak into your mic** — Claude will listen, process, and respond through your speakers. Say "stop" or press `Ctrl+C` to exit.
#### How It Works
```
OpenAI Cloud API (same key, separate models)
┌─────────────────────────────────────────────────────┐
│ Whisper (whisper-1) /v1/audio/transcriptions │
│ You speak ──────────────────────────► Claude Code │
│ │ │
│ OpenAI TTS (tts-1) /v1/audio/speech │ │
│ You hear ◄─────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
```
#### Auto-Approve Voice Tools
To avoid permission prompts every time voice mode activates, the kit's `.claude/settings.json` includes:
```json
{
"permissions": {
"allow": [
"mcp__voicemode__converse",
"mcp__voicemode__service",
"Bash(voicemode *)"
]
}
}
```
#### Platform-Specific Dependencies
macOS
Usually works out of the box. If you get audio errors:
```bash
brew install portaudio ffmpeg
```
Ubuntu / Debian
```bash
sudo apt update
sudo apt install -y ffmpeg libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev python3-dev
```
Fedora
```bash
sudo dnf install alsa-lib-devel ffmpeg portaudio portaudio-devel python3-dev
```
Windows (WSL2)
```bash
sudo apt install -y ffmpeg libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev
```
> WSL2 requires pulseaudio packages for microphone access.
#### Troubleshooting
| Problem | Fix |
|---------|-----|
| "No audio input device" | Check microphone permissions in System Settings → Privacy → Microphone |
| `[BLANK_AUDIO]` returned | Speak during the recording window; check mic is selected as default input |
| Audio choppy/laggy | Close other audio apps; try wired headset over Bluetooth |
| MCP not connecting | Run `/mcp` in Claude Code; restart after install |
| API key not picked up | Restart Claude Code — MCP server reads `OPENAI_API_KEY` at startup only |
## 8. Try It Out — Your First 5 Minutes
You're set up. Before diving into components and theory, take Claude Code for a spin. Run these inside your Claude Code session:
### Ask about the project
```
> What is this project? Summarize the tech stack and structure
```
```
> /project-status
```
### Scaffold something
```
> /scaffold-spring-api hello-world
```
Watch how Claude creates the full project structure, files, and boilerplate — all from a single command.
Or, if you're not sure which scaffold command to use, describe what you want to build and let `/new-project` figure it out:
```
> /new-project flutter fitness tracker with Firebase
> /new-project python REST API for invoices
> /new-project angular dashboard for analytics
```
`/new-project` reads your description, maps it to the right tech stack, and routes to the correct scaffold command — including running the Mobile Design checkpoint and plan gate for Flutter projects. Supported stacks: Spring Boot, NestJS, Python/FastAPI, Agentic AI, Angular, Flutter, PostgreSQL schema, vector database.
### Use a sub-agent
```
> @architect What improvements would you suggest for this project's structure?
```
Notice how the agent runs in its own context without cluttering your main conversation.
### Pull live docs with MCP
```
> Explain how to set up Spring Security with JWT. use context7
```
The `context7` MCP server fetches current, version-specific documentation instead of relying on training data.
### Check what's loaded
```
> What agents, skills, and slash commands are available in this project?
```
```
> /mcp
```
```
> /agents
```
That's the core workflow: **slash commands** to scaffold, **agents** for expertise, **MCP servers** for external tools, and **skills** that activate automatically in the background. The next section breaks down each component in detail.
### A note on permissions
Claude Code will ask for permission before accessing files or running commands. You'll see prompts like:
```
Do you want to proceed?
1. Yes
❯ 2. Yes, allow reading from claude-code-onboarding/ from this project
3. No
```
This can feel repetitive at first. The kit ships with pre-configured `allow` rules in `.claude/settings.json` that auto-approve common operations (build tools, git, Docker) — so most prompts you'll see are for operations that genuinely deserve a second look.
> ⚠️ **For this learning playground only**, you can skip all permission prompts:
> ```bash
> claude --dangerously-skip-permissions
> ```
> **Do not use this in real projects.** It disables all guardrails including the hooks and deny rules this kit ships with. For real projects, add frequently-used commands to the `allow` list in `settings.json` instead — see the [Settings Configuration](#settingsjson-configuration) section for the full reference.
## 9. Understanding Claude Code Components
Knowing *when to use what* is the key to being productive with Claude Code. Here's a quick reference:
| Component | What It Does | Location | How It's Invoked |
|---|---|---|---|
| **CLAUDE.md** | Project context Claude reads at startup — tech stack, coding standards, architecture, workflows | `./CLAUDE.md`, `~/.claude/CLAUDE.md`, `.claude/rules/` | Auto-loaded at startup |
| **settings.json** | JSON configuration for permissions, hooks, and environment — allow/deny/ask permission rules, hooks config, env vars for Claude Code | `.claude/settings.json` (project), `~/.claude/settings.json` (user) | Auto-loaded at startup |
| **Skills** | Modular expertise Claude applies automatically based on context — lazy-loaded when needed, not user-invoked. Best for complex, recurring workflows (code review, API design patterns) | `.claude/skills//SKILL.md` | Auto (Claude decides) |
| **Slash Commands** | `/command` shortcuts for repeatable prompts — quick actions you trigger manually | `.claude/commands/.md` | You type `/command` |
| **Sub-agents** | Specialized AI with isolated context for complex tasks — parallel processing, focused expertise | `.claude/agents/.md` | You type `@agent` or Auto (Claude decides|
| **Hooks** | Scripts that run at lifecycle events — auto-formatting, validation, notifications. Types: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact`, `Notification` | Defined in `settings.json` → `hooks` | Automatic on events |
| **MCP Servers** | Tool connections to external services — GitHub, Slack, databases, docs, APIs | `.mcp.json` (project root) | Claude uses as needed |
### How They Fit Together
```
┌──────────────────────────────────────────────────────────────┐
│ CLAUDE.md → What Claude knows about your project │
│ settings.json → What Claude can / can't do │
│ Skills → How Claude handles recurring tasks │
│ Commands → Quick actions you trigger manually │
│ Sub-agents → Specialists for complex work │
│ Hooks → Automatic formatting / validation │
│ MCP Servers → External tool connections │
└──────────────────────────────────────────────────────────────┘
```
### Decision Matrix - When to Use What
| Use | You Need To… | Example |
|---|---|---|
| **CLAUDE.md** | Set project conventions and context | Project Overview, Project Context, Tech Stack, Coding Standards, Rules |
| **settings.json** | Control what Claude can do | Allow `git` commands, deny `sudo` |
| **Skill** | Auto-apply patterns for a domain | Always use Riverpod State Management when building Flutter |
| **Slash Command** | Run a repeatable prompt yourself(manual) | `/scaffold-spring-api weather-service` |
| **Sub-agent** | Get deep domain expertise in isolation, can be manual or auto | `@database-designer Design schema for…` |
| **Hook** | Enforce hard rules every time | Block commits without passing tests |
| **MCP Server** | Connect to external services | GitHub PRs, Context7 live docs, Firebase |
| **Claude-Mem plugin** | Remember things across sessions | Persistent memory of past decisions |
### CLAUDE.md (Project Context)
**What:** A Markdown file at the project root that gives Claude Code, context about your project — tech stack, conventions, common commands, architecture, and rules.
**When to use:** Every project should have one. It's the first thing Claude reads at startup.
**Where:** `./CLAUDE.md` (project root) or `~/.claude/CLAUDE.md` (global, all projects)
You can auto-generate one by running `/init` inside a Claude Code session. This repo already includes one, so you can skip this step.
```bash
# Auto-generate one from your codebase
claude
> /init
```
**Tips:**
- Keep it under 40KB — too much context overloads the LLM's 200K token window
- Put the most important rules at the top
- Use imports for large docs: `@docs/api-reference.md`
**File Locations & Priority**
| Type | Location | Scope | Git |
|------|----------|-------|-----|
| Enterprise | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) | All users in org | N/A |
| User Global | `~/.claude/CLAUDE.md` | All your projects | No |
| Project | `./CLAUDE.md` | Team-shared | Yes |
| Project Local | `./CLAUDE.local.md` | Personal (your machine) | No (auto-ignored) |
| Directory-specific | `./src/api/CLAUDE.md` | Subdirectory scope | Yes |
| Rules Directory | `.claude/rules/*.md` | Conditional rules | Yes |
### Slash Commands — Reusable Prompt Shortcuts
**What:** Prompts you trigger with `/command-name`. Think of them as reusable prompt shortcuts.
**When to use:** When you have a repeatable workflow you run often — scaffolding, reviewing, deploying.
**Where:** `.claude/commands/my-command.md` (project) or `~/.claude/commands/` (global)
**Examples: Try running below commands inside Claude Code Session**
```
> /scaffold-spring-api weather-service
> /scaffold-flutter-app fitness-tracker
> /design-database fitness tracking with users, workouts, and goals
```
Use `$ARGUMENTS` in the command file (`.claude/commands/scaffold-spring-api.md`) to accept parameters.
### Agents (Subagents) — Specialist AI Personas
**What:** Specialized AI with isolated context for complex tasks with their own system prompt and tool restrictions. They run in a **separate context window**, so they don't pollute your main conversation.
**When to use:** When you need deep expertise in a specific domain — a dedicated backend developer, database architect, or codereviewer.
**Where:** `.claude/agents/my-agent.md` (project) or `~/.claude/agents/` (global)
**Examples: Try running below commands inside Claude Code Session**
```
> @java-spring-api Create a CRUD API for a Product entity with name, price, and category
> @flutter-mobile Build a login screen with Firebase Auth
> @database-designer Design the schema for an e-commerce platform
> @architect Design the system architecture for a real-time chat feature
```
### Subagent-Driven Development (SDD) — Plan-to-PR Pipeline
**What:** A 3-role autonomous pipeline that turns an approved plan file into reviewed, committed code — without you shepherding each step.
**Pipeline:** Research (optional) → Implementer → Spec Reviewer → Quality Reviewer → PR
| Role | What it does |
|------|-------------|
| **Research** *(optional)* | Explores unfamiliar APIs or domains, produces `docs/research/.md` |
| **Implementer** | Writes code + tests for each task in the plan |
| **Spec Reviewer** | Checks implementation against the plan's acceptance criteria |
| **Quality Reviewer** | Tech-stack-specific review (Spring, NestJS, Flutter, etc.) |
**When to use:** A plan file exists at `docs/plans/YYYY-MM-DD-.md` (created via `/plan-review`) and the work spans 3+ tasks.
**Research phase — when it helps:** When the feature touches an external API or service your team hasn't integrated before (e.g., Stripe Connect, a new compliance standard, an unfamiliar third-party SDK). The research agent produces a committed `docs/research/.md` artifact that the spec reviewer uses to validate API usage in Step 2. Skip it when the stack is familiar.
**Two dispatch modes:**
- **Subagent mode** — `Agent` tool, general-purpose agents, sequential. Best for ≤5 tasks.
- **Team mode** — `TeamCreate` with tech-specific agents running concurrently. Best for 6+ tasks.
**How to trigger:**
```
> Run the SDD pipeline for docs/plans/2026-03-01-payments.md
> Use subagent-driven-development to implement the auth feature plan
```
Or Claude auto-activates the `subagent-driven-development` skill when it detects a plan file and 3+ tasks.
**Skill:** `.claude/skills/subagent-driven-development/`
---
### Skills — Auto-Activated Knowledge
**What:** Markdown files with domain knowledge, templates, and code patterns. Unlike commands, Skills are *lazy-loaded* and only brought into context when needed. **Claude decides when to use them** based on the task context — you don't invoke them explicitly.
**When to use:** When you want Claude to **automatically** apply certain patterns whenever a matching task comes up (e.g., always use your team's DTO pattern when creating Spring entities).
**Where:** `.claude/skills/my-skill/SKILL.md`
The skills in this repo auto-activate based on context:
| When You Ask About… | Skill That Activates |
|---|---|
| Spring Boot | `java-spring-api` |
| Angular components | `angular-spa` |
| Flutter screens | `flutter-mobile` |
| Database schemas | `database-design` |
| System architecture | `architecture-design` |
| Three.js scene / 3D web | `threejs-fundamentals`, `threejs-geometry`, `threejs-materials` etc. |
| Three.js animation | `threejs-animation` |
| GLTF / GLB model loading (web) | `threejs-loaders` |
| Custom GLSL shaders | `threejs-shaders` |
| Post-processing / bloom / DOF | `threejs-postprocessing` |
| three_dart / 3D Flutter | `three-dart-fundamentals`, `three-dart-geometry` etc. |
| Flutter GLTF / model loading | `three-dart-loaders` |
### MCP Servers — External Tool Integrations
**What:** The Model Context Protocol connects Claude Code to external services (GitHub, databases, documentation servers, gmail, slack, APIs) so Claude can use them as tools.
**When to use:** When Claude needs to interact with services beyond the local filesystem — creating GitHub PRs, querying live databases, fetching up-to-date documentation, invoking APIs.
**Where:** `.mcp.json` (project root)
This repo comes pre-configured with:
| Server | What It Does |
|---|---|
| **Context7** | Live, version-specific documentation for any library — add `use context7` to prompts |
| **GitHub** | Create issues, PRs, browse repos, review code via GitHub Copilot MCP |
| **Angular CLI** | Angular schematics, builds, and project scaffolding directly from Claude |
| **Chrome DevTools** | Browser debugging and inspection |
| **Firebase** | Firestore and Auth operations |
| **Sequential Thinking** | Step-by-step reasoning for complex multi-step problems |
| **Dart** | Dart language server integration |
| **XcodeBuildMCP** | Build, run, debug, and test Xcode projects from Claude — covers iOS simulator, device, and macOS targets |
| **Maestro** | Cross-platform mobile E2E testing — run test flows on iOS simulator and Android emulator using natural language |
| **Filesystem** | Secure file search and manipulation with configurable directory permissions |
| **LangChain Docs** | Live LangChain documentation lookup |
| **Weaviate Docs** | Live Weaviate documentation lookup |
## Weaviate Docs MCP Server
Gives Claude Code instant access to Weaviate documentation inside your editor.
### Configuration
Add the following to your `.mcp.json`:
```json
{
"mcpServers": {
"weaviate-docs": {
"type": "stdio",
"command": "npx",
"args": [
"mcp-remote",
"https://weaviate-docs.mcp.kapa.ai"
],
"timeout": 60000,
"env": {}
}
}
}
```
### Authentication
The server requires a one-time OAuth login. Run the following command and follow the browser prompt to sign in with Google or GitHub:
```bash
npx mcp-remote https://weaviate-docs.mcp.kapa.ai
```
Your session will be cached at `~/.mcp-remote/` — you won't need to re-authenticate on subsequent uses.
Verify the server is connected:
```bash
claude mcp get weaviate-docs
```
You should see `Status: ✓ Connected`.
### settings.json Configuration
**Purpose**: Permissions, environment variables, hooks, and tool behavior.
**File Locations & Priority**
| Type | Location | Scope |
|------|----------|-------|
| User | `~/.claude/settings.json` | All projects |
| Project (shared) | `.claude/settings.json` | Team-shared |
| Project (local) | `.claude/settings.local.json` | Personal |
| Enterprise | OS-specific managed location | Organization |
**Permission Rule Syntax**
| Pattern | Example | Description |
|---------|---------|-------------|
| Exact match | `Bash(npm run test)` | Only this exact command |
| Wildcard suffix | `Bash(npm run:*)` | npm run followed by anything |
| Glob patterns | `Read(./src/**/*.ts)` | All .ts files recursively |
| Tool types | `Read`, `Write`, `Edit`, `Bash`, `WebFetch`, `WebSearch` | Tool categories |
**Key design decisions:**
This kit ships with a pre-configured `settings.json` that balances safety with productivity.
| Category | What's Configured | Why |
|----------|-------------------|-----|
| **Allow** | Build tools (`npm`, `mvn`, `flutter`, `ng`), git read/write, Docker, Python tooling | These run frequently — prompting every time kills productivity |
| **Ask** | Destructive file ops (`rm`, `mv`, `cp`), `curl`/`wget`, git reset | One-time confirmation prevents accidents without blocking workflow |
| **Deny** | Force-push, `sudo`, `eval`, reading `.env`/secrets/keys | Never allowed — these are hard guardrails |
| **Env** | `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Keeps Claude in the project root instead of drifting to `/home/user` |
> **Note:** This uses the **array-style permission syntax** (e.g., `"Bash(npm *)"`) which is the current format. If you see older examples with object-style syntax (`"Bash": ["npm *"]`), those are outdated.
To add your own project-specific permissions, modify `.claude/settings.json` or create a personal `.claude/settings.local.json` for overrides that aren't committed to git.
### Hooks — Automated Guardrails
**What:** Shell scripts that run automatically at specific lifecycle events (before/after tool use, on session start/end). Think of them as **middleware for Claude Code** — deterministic, always execute the same way.
**When to use:** When you need hard rules enforced every time, like **run linter before commit** or **block commits without passing tests** or **block destructive commands** or **auto-format after every edit**.
| Hook Event | Fires When | Mental Model | Real-World Examples |
|---|---|---|---|
| **PreToolUse** | Before a tool executes | 🛑 *Stop something dangerous from happening* | Block `git push` to main/master, prevent `rm -rf /` or `DROP DATABASE`, protect `.env` files from edits |
| **PostToolUse** | After a tool completes | 🔧 *Fix/check what just happened to a single file* | Auto-format with Prettier/ruff after edits, run ESLint on the changed file, type-check with `tsc --noEmit` |
| **Stop** | When Claude finishes responding | ✅ *Validate the whole result before calling it done* | Run unit tests once at the end (not per-file), audit all changed files, scan for leaked secrets |
| **PermissionRequest** | When Claude shows a permission dialog | 🔐 *Auto-decide on permission prompts* | Auto-approve `git status`, deny `sudo` commands |
| **UserPromptSubmit** | When you send a message | 📥 *Intercept and enrich your input* | Auto-prepend "use context7" to all prompts, inject current git branch name, Inject project-specific context, validate prompt format|
| **SubagentStop** | When a sub-agent finishes | 🔍 *Quality-check delegated work* | Check generated code compiles, verify output format |
| **PreCompact** | Before context compaction | 💾 *Save state before memory shrinks* | Export TODO list, save working notes to a file |
| **SessionStart** | When a session starts or resumes | 🚀 *Set up the environment* | Source `.env` files, verify toolchain is installed |
| **SessionEnd** | When a session ends | 🧹 *Clean up after yourself* | Log session summary, clean up temp files |
| **Notification** | On permission prompts or idle | 📢 *Route alerts externally* | Send Slack alert on long-running tasks, desktop notifications |
**Where:** `.claude/settings.json` → `hooks` section, scripts in `.claude/hooks/`
> **Note:** `SessionStart`, `SessionEnd`, `SubagentStop`, `PreCompact`, and `PermissionRequest` hooks were added in recent Claude Code releases. If a hook event doesn't fire, verify your Claude Code version with `claude --version` and update if needed. The core events (`PreToolUse`, `PostToolUse`, `Stop`) are available in all versions.
This repo includes 4 hooks out of the box:
| Hook | Script | Event | What It Does |
|------|--------|-------|-------------|
| **Bash Guard** | `pre-bash-guard.sh` | `PreToolUse` → Bash | Blocks `rm -rf /`, `rm -rf .`, force-push to main, `DROP DATABASE` |
| **Protect Sensitive Files** | `pre-edit-protect-sensitive.sh` | `PreToolUse` → Write/Edit | Blocks edits to `.env`, credentials, private keys, lock files |
| **Auto-Format** | `post-edit-format.sh` | `PostToolUse` → Write/Edit | Runs Prettier (TS/JS/HTML/CSS), `dart format`, ruff/black (Python) |
| **Smart Suggest** | `smart-suggest.sh` | `UserPromptSubmit` | Behavioral coaching — detects intent (debug/review/deploy/scaffold) and injects the right command/agent suggestion before Claude responds. Tier 0 blocks policy violations. |
| **Secrets Scan (Output)** | `output-secrets-scanner.sh` | `PostToolUse` | Scans tool outputs (Bash, Read, WebFetch) for API keys, JWT tokens, DB connection strings, private keys. Closes the read-path gap — catches secrets in git history dumps, env reads, API responses. Warn only, never blocks. |
| **Secret Scan** | `stop-secret-scan.sh` | `Stop` | Warns if changed files contain AWS/GCP/GitHub/OpenAI API keys |
| **Blackbox Log** | `stop-blackbox-log.sh` | `Stop` | Appends session decisions, user constraints, and changed files to `blackbox/session-log.md` |
| **Ralph Loop** | `stop-ralph-loop.sh` | `Stop` | Autonomous iteration — blocks exit and re-feeds prompt until task complete. Opt-in: only active when `/ralph-loop` was called. |
> After cloning: `chmod +x .claude/hooks/*.sh`
#### Two-Layer Hook System
This repo implements a **two-layer hook architecture**:
| Layer | Technology | Purpose | How Rules Are Defined |
|-------|-----------|---------|----------------------|
| **Layer 1 — Core Safety** | Shell scripts (`.claude/hooks/*.sh`) | Non-negotiable guardrails — always enforced | Hardcoded in shell scripts |
| **Layer 2 — Configurable** | Hookify Python engine (`.claude/hookify/`) | Team-customizable rules — enable/disable per project | Markdown rule files (`.claude/hookify.*.local.md`) |
Shell hooks are the baseline — always active, no way to disable them. Hookify sits on top and adds rules you can toggle without touching shell code.
**Layer 2: Hookify Rule Engine**
Rules live in `.claude/hookify.*.local.md` files with YAML frontmatter:
```markdown
---
name: warn-console-log
enabled: true # false to disable without deleting the file
event: file # bash | file | stop | prompt | all
pattern: console\.log\( # regex matched against the relevant field
action: warn # warn (show message) | block (deny the tool call)
---
console.log detected — use the centralized logger instead.
```
**To add a custom rule (slash command — no file editing needed):**
```
/hookify Warn me when I write console.log in a TypeScript file
/hookify Block force-push to main
/hookify # scan conversation for behaviors to prevent
```
Or manage existing rules:
```
/hookify-list # show all rules and their enabled/disabled status
/hookify-configure # interactive toggle — enable or disable rules
```
**Hookify never crashes Claude** — it always exits 0. If Python is unavailable, a rule file is malformed, or any error occurs, Claude continues normally and the error is shown as a `systemMessage`.
**Rule fields reference:**
| Field | Values | Required |
|-------|--------|----------|
| `name` | Any string | Yes |
| `enabled` | `true` / `false` | Yes |
| `event` | `bash`, `file`, `stop`, `prompt`, `all` | Yes |
| `action` | `warn`, `block` | Yes |
| `pattern` | Regex string (shorthand for single condition) | One of pattern or conditions |
| `conditions` | List of `{field, operator, pattern}` | One of pattern or conditions |
### Blackbox — Session Decision Log
The **blackbox** is a persistent, append-only log of every session where decisions were made, code was written, or user constraints were stated. Think of it as a **flight data recorder for your AI sessions** — you don't look at it every day, but when something goes wrong or you need to trace a decision, it's invaluable.
**How it works:**
| Component | Location | Auto-loaded? | Purpose |
|-----------|----------|-------------|---------|
| Policy rule | `.claude/rules/blackbox-policy.md` | ✅ Always | Instructs Claude to write entries at session end |
| Log data | `blackbox/session-log.md` | ❌ Never | Actual entries — grows freely without bloating context |
| Hook script | `.claude/hooks/stop-blackbox-log.sh` | Runs at `Stop` | Mechanically appends git-changed files as backup |
**Each log entry looks like this:**
```
## 2026-02-28T09:00Z
### Decisions
- Used PostgreSQL per user constraint (not AI default)
### Constraints Stated by User
- No mobile app — web only
### Files Modified
- src/db/config.ts — switched connection pool to postgres
### Deferred
- Rate limiting — explicitly deferred to post-launch
---
```
**Key design principles:**
- **Never bloats context** — `blackbox/session-log.md` lives outside `.claude/` so it's never auto-loaded into every session
- **Auto-created** — hook creates the `blackbox/` directory and log file on first session end if missing
- **Monthly rotation** — on month boundary, hook auto-renames to `archive-YYYY-MM.md` and starts fresh
- **Two-layer logging** — Claude writes decisions (policy rule); hook writes git facts (mechanical backup)
- **Committed to git** — full history preserved, team-visible
**When to read it:**
```bash
# "What did we decide last week?"
cat blackbox/session-log.md
# "Why was this file changed?"
grep -A 10 "2026-02-20" blackbox/session-log.md
# Read archived months
cat blackbox/archive-2026-01.md
```
**Diagram Staleness Detection:**
The blackbox also tracks when source code changes may have made an architecture diagram stale. The hook checks if any modified files match a known diagram by folder name and appends a warning automatically:
```
⚠️ Diagrams that may need updating:
- docs/diagrams/auth-flow.md (auth/ was modified)
```
Naming convention: `src/auth/` → `docs/diagrams/auth-flow.md` (folder prefix = diagram prefix). The policy rule instructs Claude to update or create diagrams during the session; the hook warns if it was missed.
```
docs/
└── diagrams/
├── auth-flow.md ← generated after auth feature, updated when auth/ changes
├── payment-flow.md ← generated after payments feature
└── api-contracts.md ← generated after API layer work
```
Reference a diagram in any session with `@docs/diagrams/auth-flow.md` to give Claude instant architectural context without codebase exploration.
### Ralph Loop — Autonomous Iteration
The **ralph loop** is a Stop hook that keeps Claude working on a task autonomously — when Claude tries to exit, the hook intercepts, checks if the task is done, and if not, feeds the same prompt back to start another iteration. Each iteration can see all file changes from previous iterations.
> Named after Ralph Wiggum (*The Simpsons*) — persistent iteration despite setbacks. **High risk. Use deliberately.**
> Adapted from the [`ralph-wiggum`](https://github.com/anthropics/claude-code-samples) plugin in the Anthropic `claude-code-samples` repository.
#### Start
```bash
/ralph-loop "Your task" --max-iterations 10 --completion-promise "DONE"
```
| Flag | Default | Meaning |
|------|---------|---------|
| `--max-iterations N` | `10` | Hard stop after N iterations (safety net — always set this) |
| `--completion-promise "TEXT"` | none | Claude exits ONLY when it outputs `TEXT` and means it |
Monitor progress:
```bash
head -5 .claude/ralph-loop.local.md # iteration: 3, max_iterations: 10, ...
```
#### Stop
```bash
/cancel-ralph # deletes state file — loop exits on next turn
```
#### Regular use
```bash
# Fix all TypeScript errors — loop until clean
/ralph-loop "Run: npx tsc --noEmit. Fix all errors. Repeat until zero errors." \
--max-iterations 15 --completion-promise "ZERO ERRORS"
# Implement all unchecked items in a plan file
/ralph-loop "Read docs/plans/feature.md. Implement the next unchecked item. Repeat." \
--max-iterations 20 --completion-promise "ALL ITEMS DONE"
```
#### With sub-agents
Sub-agents work naturally inside a ralph loop. Each iteration spawns fresh sub-agents; their file changes persist into the next iteration.
```bash
/ralph-loop "Run /review-pr. Fix all CRITICAL findings using specialist agents.
When zero CRITICAL findings remain, output ALL CRITICAL RESOLVED" \
--max-iterations 10 --completion-promise "ALL CRITICAL RESOLVED"
```
#### With Agent teams
Teams are recreated each iteration (previous team sessions end, but TaskList entries and file changes persist). Write prompts that check TaskList state first:
```bash
/ralph-loop "Check TaskList for pending tasks. If tasks remain, create a team and dispatch them.
When all tasks complete and tests pass, output TEAM DONE" \
--max-iterations 5 --completion-promise "TEAM DONE"
```
#### When to use / avoid
| Use | Avoid |
|-----|-------|
| Multi-attempt problems (fix errors, pass tests) | Single-shot tasks that don't need retry |
| Overnight / unattended long work | Tasks requiring human decisions mid-way |
| Iterative refinement over existing files | Tasks with no clear completion signal |
**Always set `--max-iterations`.** Without it, the loop runs until the completion promise is satisfied or you run `/cancel-ralph`. Uncontrolled loops = uncontrolled API costs.
### Autoresearch — Metric-Gated Improvement Loop
**Autoresearch** is an autonomous loop that improves code quality by measuring, changing, and deciding — mathematically. Unlike `/ralph-loop` (which runs blind), autoresearch **only keeps changes that move the metric in the right direction**. Every regression is automatically rolled back with `git reset --hard`.
> Inspired by Andrej Karpathy's `autoresearch` pattern — a self-improving loop that applies ML-style evaluation (keep if better, discard if worse) to codebase quality.
#### Start
```bash
/autoresearch # measure all stacks, fix top issues
/autoresearch --metric nestjs # focus on NestJS only
/autoresearch --metric flutter --max-iterations 5
/autoresearch --metric all --target 10 # aim to cut 10 issues per iteration
```
| Flag | Default | Meaning |
|------|---------|---------|
| `--metric STACK` | `all` | Stack to measure: `flutter`, `nestjs`, `angular`, `python`, `all` |
| `--target N` | `5` | Issues to eliminate per iteration (sets improvement bar) |
| `--max-iterations N` | `10` | Hard stop after N iterations |
#### What it measures
| Stack | Metrics tracked |
|-------|----------------|
| Flutter | `flutter analyze` warnings, TODOs in `lib/` |
| NestJS | `: any` / `as any` type assertions, `console.log` in production code, TODOs |
| Angular | `: any` / `as any`, `console.log` in production code |
| Python | `TODO`/`type: ignore` comments, bare `except:` clauses |
#### How a single iteration works
```
Measure baseline score (e.g. 47 issues)
↓
Pick highest-impact category (e.g. console.log → Logger)
↓
Implementer agent fixes 3–5 easiest instances
↓
Re-measure score (e.g. 41 issues)
↓
41 < 47? ✅ git commit — keep changes, continue
41 ≥ 47? ❌ git reset --hard — discard, try different category next iteration
```
#### Example — NestJS type safety pass
```bash
# Before: 34 `: any` types in src/
/autoresearch --metric nestjs --target 5 --max-iterations 8
# Iteration 1: finds easy fetch responses with `as any` → adds proper types → 34 → 29 ✅ committed
# Iteration 2: tries a complex service, breaks a test → git reset → rollback
# Iteration 3: finds console.log calls → replaces with Logger → 29 → 24 ✅ committed
# ...continues until max-iterations or score hits 0
```
#### Stop
```bash
/cancel-ralph # autoresearch shares the same cancel mechanism as ralph-loop
```
#### How it differs from `/ralph-loop`
| | `/ralph-loop` | `/autoresearch` |
|--|--|--|
| **Stops when** | Completion promise satisfied or max-iterations | max-iterations or score hits 0 |
| **Keeps bad changes?** | ✅ Yes — runs blind, no rollback | ❌ No — `git reset --hard` on any regression |
| **Knows if it helped?** | No — subjective completion promise | Yes — objective metric score |
| **Best for** | Open-ended tasks, implementing features, fixing errors | Quality metric reduction: types, linting, dead code |
| **Risk** | May accumulate wrong changes over many iterations | Self-correcting — regressions never land |
**Rule of thumb:** Use `/ralph-loop` when success is defined by a behaviour ("all tests pass", "feature works"). Use `/autoresearch` when success is defined by a number ("zero `console.log`", "zero `as any`").
#### When to use / avoid
| Use | Avoid |
|-----|-------|
| Eliminating `as any` / `console.log` / TODOs at scale | Tasks requiring business logic decisions |
| Gradual type safety hardening over multiple sessions | New feature implementation |
| Pre-release code hygiene cleanup | Refactors that require architecture judgment |
| Onboarding cleanup of inherited legacy code | Single-file fixes (just do it directly) |
### Lessons Log — Self-Improvement Loop
The **lessons log** is the team's shared record of corrections — mistakes Claude made that you corrected, expressed as rules to prevent recurrence.
Unlike the blackbox (which is never auto-loaded), `lessons.md` lives in `.claude/rules/` so it is **always active** in every session.
| Component | Location | Auto-loaded? | Purpose |
|-----------|----------|-------------|---------|
| Lessons log | `.claude/rules/lessons.md` | Always | Active correction patterns for current sessions |
| Trigger rule | `CLAUDE.md` (Self-Improvement Loop section) | Always | Instructs Claude to write a lesson when corrected |
**How it works:**
1. Claude makes a mistake. You correct it.
2. Before proceeding, Claude writes a 4-line lesson entry to `lessons.md`.
3. You commit and push. All teammates get the lesson on next `git pull`.
4. From that session forward, every Claude instance on the team avoids the same mistake.
**Bloat prevention — three-tier lifecycle:**
```
lessons.md (max 15 entries)
|
| lesson recurs 3x across sessions
v
Promoted to matching rules file (core-behaviors.md, code-standards.md, etc.)
+ deleted from lessons.md
```
`lessons.md` stays lean (~60 lines max). Repeated lessons become permanent rules. One-off mistakes that never recur get pruned at the 15-entry cap.
**Difference from blackbox:**
| | `blackbox/session-log.md` | `.claude/rules/lessons.md` |
|--|--|--|
| Auto-loaded? | Never | Always |
| Records | Decisions + files changed | Correction patterns |
| Grows? | Unboundedly (append-only) | Capped at 15 entries |
| Purpose | Audit trail | Active mistake prevention |
### Model Selection & Cost Awareness
Claude Code supports three Anthropic models, each optimized for different use cases:
| Model | Best For | Cost (1M in/out) | Context | Speed |
|-------|----------|-------------------|---------|-------|
| **Claude Sonnet 4.5** | Balanced quality/cost — 80% of your work | $3 / $15 | 200K (1M beta) | Medium |
| **Claude Haiku 4.5** | Fast, cheap tasks (docs, non-critical work) | $1 / $5 | 200K | Fast |
| **Claude Opus 4.6** | Complex reasoning (expensive, burns tokens fast) | $5 / $25 | 200K (1M beta) | Slow |
**Pricing details:**
- **Opus 4.6**: $5 per million input tokens, $25 per million output tokens. [Source](https://www.anthropic.com/claude/opus)
- **Sonnet 4.5**: $3 per million input tokens, $15 per million output tokens. [Source](https://www.anthropic.com/claude/sonnet)
- **Haiku 4.5**: $1 per million input tokens, $5 per million output tokens. [Source](https://caylent.com/blog/claude-haiku-4-5-deep-dive-cost-capabilities-and-the-multi-agent-opportunity)
- **Long context (>200K tokens)**: Premium rates apply — Opus: $10/$37.50, Sonnet: $6/$22.50 per million tokens. [Source](https://platform.claude.com/docs/en/about-claude/models/overview)
**Recommended default: Sonnet 4.5**
Sonnet balances high performance with efficient response times for coding tasks. Set it as your persistent default in `.claude/settings.json`:
```json
{
"permissions": {},
"model": "sonnet"
}
```
**Switching models:**
Inside a Claude Code session:
```bash
/model sonnet # Switch to Sonnet (default)
/model haiku # Switch to Haiku (fast, cheap)
/model opus # Switch to Opus (complex reasoning)
```
Or use the `--model` flag when starting:
```bash
claude --model sonnet
claude --model haiku
claude --model opus
```
**Cost monitoring:**
```bash
/cost # Token usage and estimated cost for this session
/stats # Usage stats over 7/30 days or all-time
/usage # Plan limits and remaining usage
```
**Cost-saving tips:**
- **Use Sonnet for 80% of work** — code generation, debugging, refactoring
- **Use Haiku for docs** — README updates, comments, non-critical tasks
- **Use Opus sparingly** — complex architecture, critical security reviews (burns tokens quickly)
- Use `/compact` regularly in long sessions — stale context wastes tokens
- Use `@file` references instead of pasting file contents
- Disable unused MCP servers (`/mcp` to check)
## 10. Cheaper Alternative: MiniMax M2.5
[MiniMax M2.5](https://www.minimax.io/news/minimax-m25) is a cost-effective alternative to Claude for agentic coding workflows.
### Why Choose MiniMax M2.5?
MiniMax M2.5 (released February 12, 2026) delivers near-frontier coding performance — matching or approaching Claude Opus 4.6 on key benchmarks like SWE-Bench Verified (80.2%), while being **10-20x cheaper** and often faster in real agentic workflows. It excels at full-stack development across 10+ languages, task decomposition, planning, and tool use via its Forge Framework.
For heavy users of Claude Code CLI, the [**MiniMax Coding Plan**](https://platform.minimax.io/subscribe/coding-plan) turns this into an ultra-cost-effective setup with predictable prompt-based limits instead of per-token bills that can explode during long sessions. Many developers report switching from Claude Max and handling 90%+ of daily coding/agentic work at a fraction of the cost, with seamless integration and built-in extras like MCP server with web search and image understanding.
### Overview of MiniMax M2.5 for Coding
MiniMax M2.5 is a 230B-parameter model (10B active) built for coding and agentic tasks. It supports 10+ languages, handles the full dev lifecycle—from system design to testing—and works across Web, Android, iOS, and Windows. Powered by its Forge Framework for agentic workflows.
- The [**MiniMax M2.5 Coding Plan**](https://platform.minimax.io/subscribe/coding-plan) subscription provides a **dedicated API key** (exclusive to the plan, not interchangeable with pay-as-you-go keys).
- It uses the same **Anthropic-compatible endpoint** (`https://api.minimax.io/anthropic`).
- The model remains **MiniMax-M2.5** (or just `MiniMax-M2.5` in most configs).
- It includes extras like built-in tools (e.g., `web_search`, `understand_image`) via MCP (MiniMax Coding Plan tools), which you can enable in Claude Code.
- Billing is subscription-based with prompt/hour limits (rolling 5-hour window: e.g., Starter = 100 prompts/5h, Plus = 300, Max = 1000), much cheaper and more predictable for heavy coding use than pay-as-you-go or Claude Max.
### Step-by-Step Configuration
**1. Subscribe to the Coding Plan**
- Go to: https://platform.minimax.io/subscribe/coding-plan
- Choose a plan
- After subscription activates, go to your account: https://platform.minimax.io/user-center/payment/coding-plan (or API Keys section).
- Generate/copy your **Coding Plan API Key** (it looks like a standard `sk-...` or similar key, but it's plan-exclusive). Protect it—don't share or commit it.
**2. Clear Any Conflicting Anthropic Variables** (important to avoid your Claude Max auth leaking in)
In your terminal:
```bash
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_BASE_URL
```
**3. Configure Claude Code**
Update the settings.local.json file (`~/.claude/settings.local.json`) as below.
Paste this (replace `` with your actual key):
```json
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.minimax.io/anthropic",
"ANTHROPIC_AUTH_TOKEN": "",
"API_TIMEOUT_MS": "3000000",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
"ANTHROPIC_MODEL": "MiniMax-M2.5",
"ANTHROPIC_SMALL_FAST_MODEL": "MiniMax-M2.5",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "MiniMax-M2.5",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "MiniMax-M2.5",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "MiniMax-M2.5"
}
}
```
**4. (Optional but Highly Recommended) Enable MCP Tools** (web search + image understanding — included in Coding Plan)
MiniMax provides an official MCP server for Claude Code to get these tools working seamlessly.
Install/run it (requires uvx/pipx or similar for Python tools):
```bash
claude mcp add -s user MiniMax --env MINIMAX_API_KEY= --env MINIMAX_API_HOST=https://api.minimax.io -- uvx minimax-coding-plan-mcp -y
```
Or manually add to `~/.mcp.json`:
```json
{
"mcpServers": {
"MiniMax": {
"command": "uvx",
"args": ["minimax-coding-plan-mcp", "-y"],
"env": {
"MINIMAX_API_KEY": "",
"MINIMAX_API_HOST": "https://api.minimax.io"
}
}
}
}
```
- In Claude Code session, type `/mcp` — you should see `web_search` and `understand_image` listed if successful.
**5. Test It**
- Run: `claude`
- Type `/model` inside the session — it should show MiniMax-M2.5.
- Try a coding task: "Plan and implement a full-stack Todo app with Angular + Java Spring boot".
- Test tools: Ask something needing search, like "Search latest Angular features and update this component".
## 11. Multiple Sub Agents
Spwaning Multiple agents that run inside main Claude Code session to handle specific subtasks (like research or verification). They work independently, then report results back to main Claude Code session.
**Example:**
```bash
> Spawn a multiple sub-agents to implement Authentication service
```
## 12. Agent Teams — Coordinated Multi-Agent Collaboration
[Agent Teams](https://code.claude.com/docs/en/agent-teams) is a new experimental feature for Claude Code where multiple Claude Code sessions working in parallel. One **lead** coordinates and assigns tasks. Multiple **Teammates** work independently with separate context windows and communicate via shared tasks and messages.
**Architecture:**
```
Team Lead Session (Main Claude)
↓
Spawns 3 teammate sessions (separate Claude Code instances)
↓
Teammate 1 ←→ Shared Task Board ←→ Teammate 2
↑ ↕ ↑
└────────→ Teammate 3 ←──────────────┘
(Direct P2P messaging)
```
**Key Capabilities:**
- Teammates communicate directly with each other
- Shared task list all teammates can read/write
- Each teammate = separate Claude Code session
- You can interact with individual teammates directly
- Parallel + autonomous coordination
**Key Difference from Sub-Agents:**
| Feature | Sub-Agents | Agent Teams (New) |
|---------|----------------------------------------|-------------------|
| **Architecture** | Single session, sub-processes | Multiple independent Claude Code sessions |
| **Parallel execution** | Claude spawns multiple sub-agents |Spawns multiple teammate sessions |
| **Context** | Isolated but within main session | Separate Claude Code per teammate |
| **Communication** | Report back to main session only | Direct peer-to-peer messaging |
| **Coordination** | All goes through you (main session) | Autonomous via shared task list |
| **Spawn based on task context** | Claude decides automatically | Claude decides automatically |
| **Use case** | Focused individual tasks | Complex multi-component projects |
| **File sharing** | Don't know about each other | Can read each other's outputs |
| **Visibility** | In parent session | Split panes (with tmux) |
**When to Use Agent Teams:**
- Parallel code reviews (security, performance, testing)
- Multi-layer features (frontend + backend + database in parallel)
### How to Enable
Agent Teams are disabled by default. Enable by setting the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable.
**settings.json**
```json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
"teammateMode": "tmux"
}
```
**tmux Setup:**
Agent Teams work best with **tmux mode**, which gives you real-time visibility of all teammates in split panes.
Step 1: Install tmux
```bash
brew install tmux
```
Step 2: Verify installation
```bash
tmux -V
```
Step 3: Start Claude Code in tmux
Start tmux session
```bash
tmux
```
Launch Claude Code inside tmux session
```bash
claude
```
Step 4: Spawn teammates
```bash
> Spawn 3 teammates to refactor authentication module:
> 1. Frontend: Refactor authentication UI components
> 2. Backend: Update JWT token validation in auth service
> 3. Database: Add user session tracking table
```
**What you'll see:**
- **Lead** in main pane (top)
- **Teammate 1** in split pane
- **Teammate 2** in split pane
- **Teammate 3** in split pane
**Known Limitations:**
| Limitation | Impact | Workaround |
|-----------|--------|------------|
| **No session resumption** | Can't `/resume` a team session | Complete tasks in one session or use git to save state |
| **No nested teams** | Can't spawn sub-teams | Flatten hierarchy — use sub-agents instead |
| **Token-intensive** | ~5× context cost for 5 agents | Use only for high-value parallel tasks |
Use Agent Teams when parallelization justifies the cost. For sequential tasks, stick with sub-agents.
## 13. Claude Code Desktop — GUI with Live Preview
[Claude Code Desktop](https://code.claude.com/docs/en/desktop) is a desktop GUI that wraps the same Claude Code engine you use in the terminal — same `CLAUDE.md`, same `.claude/agents`, skills, slash commands, `settings.json`, hooks, and MCP servers. Everything in this kit works in Desktop without changes.
What Desktop adds on top of CLI: an **embedded browser preview** with interactive testing, visual diff review, parallel sessions with Git worktree isolation, background PR monitoring with auto-merge, and the ability to seamlessly switch between Desktop ↔ CLI ↔ VS Code at any time.
### What It Can Do
| Capability | How It Works |
|---|---|
| **Everything Claude Code CLI does** | Same engine — code gen, agents, skills, commands, MCP servers, hooks, git |
| **Start servers + live preview** | Runs `ng serve`, `mvn spring-boot:run`, `flutter run` and opens the app in an embedded browser |
| **Interactive UI testing** | Claude clicks buttons, fills forms, takes screenshots, reads DOM — and self-corrects issues |
| **Auto-verify changes** | After every code edit, Claude screenshots the preview and confirms the fix works |
| **PR lifecycle automation** | Creates PR → monitors CI → auto-fixes failures → auto-merges when green |
| **Visual diff review** | Side-by-side code diffs in the GUI instead of terminal output |
| **Session mobility** | Start in Desktop, continue in CLI (`/desktop` command), or move to web/mobile |
| **Remote SSH debugging** | Connect to EC2/GCP/Azure VMs and debug directly — read logs, fix configs, restart services |
**Note:** Agent Teams are **not supported in Claude Code Desktop** — they are a CLI-only feature that requires `tmux` for split-pane visibility. Agent Teams need the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable and spawn multiple independent Claude Code CLI sessions, which the Desktop GUI doesn't support. Sub-agents (single-session task delegation) work fine in Desktop. If you need Agent Teams, use the CLI.
### Testing Frontend SPAs (Angular, React)
**Sample repo:** [kumaran-is/shopping-list-demo](https://github.com/kumaran-is/shopping-list-demo) — Angular 21 shopping list app pre-configured with agents, skills, and slash commands. Open in Claude Code Desktop and start testing.
Start the dev server and test interactively — Claude can click, type, navigate, and verify DOM changes in the embedded preview with HMR hot-reload:
```
> Start ng serve and open the preview. Add an item "Milk" with quantity 2.
Verify it appears in the list and the counter updates.
> Mark "Milk" as picked up. Switch to Pending filter. Confirm it's hidden.
> Add localStorage persistence. Refresh the preview and verify items persist.
```
Claude takes screenshots, reads the DOM, identifies errors, and fixes them — all within the embedded browser.
### Testing Backend REST APIs (Spring Boot, NestJS)
**Sample repo:** [kumaran-is/claude-desktop-springboot-demo](https://github.com/kumaran-is/claude-desktop-springboot-demo) — Spring Boot 3.5 WebFlux REST API with H2, Swagger UI, and full CRUD. Open in Desktop, launch Swagger UI in preview, and test endpoints.
Launch Swagger UI in the embedded preview and test endpoints using plain English:
```
> Run mvn spring-boot:run and open Swagger UI in the preview.
> In Swagger UI, POST a product: name "Laptop", price 999.99, category "Electronics".
Then GET /api/v1/products and verify it returns.
> Test full CRUD in Swagger UI: POST two products, PUT to rename one,
DELETE the other, GET to confirm final state.
```
Claude expands endpoints, clicks "Try it out", fills JSON bodies, executes requests, and reads responses — all in the embedded browser, no curl needed.
### Testing Flutter Apps (Canvas Limitation)
**Sample repo:** [kumaran-is/claude-desktop-flutter-demo](https://github.com/kumaran-is/claude-desktop-flutter-demo) — Flutter notes app with Riverpod, GoRouter, and Device Preview. Includes the full canvas limitation workaround guide and code-assisted test prompts.
Flutter web renders to a **`