Claude Code

Common CLI Invocations

# Start with specific model
claude --model claude-opus-4-6

# Resume a previous session
claude --resume "session-id" "continue working on this"

# Agent mode with budget limit
claude --agent --max-budget-usd 100

# Restrict tools for safety
claude --allowedTools "Read,Write(src/**),Bash(git *)"

# Verbose logging with additional directories
claude --model opus --verbose --add-dir src/

Interaction Modes

Claude Code operates in three primary modes, cycled via Shift+Tab:

CLAUDE.md File Placement

CLAUDE.md Best Practices

# Project Name

## Tech Stack
- Framework: Next.js 14, React 18
- Language: TypeScript
- Styling: Tailwind CSS

## Code Conventions
- Use functional components with hooks
- Prefer named exports over default exports
- All files use 2-space indentation

## Project Structure
- /src/components -- React components
- /src/lib -- Utility functions
- /src/app -- Next.js app router pages

## Testing
- Run `npm test` before committing
- Maintain >80% coverage

## Git Workflow
- Branch naming: feature/, fix/, chore/
- Commit format: Conventional Commits

.claude Directory Structure

settings.json Examples

User Settings (~/.claude/settings.json)

{
  "model": "claude-opus-4-6",
  "maxBudgetUsd": 50,
  "permissions": {
    "allowedTools": [
      "Read",
      "Write(src/**)",
      "Bash(git *)",
      "Bash(npm *)"
    ],
    "disallowedTools": [
      "Read(.env*)",
      "Write(production.config.*)",
      "Bash(rm *)",
      "Bash(sudo *)"
    ]
  }
}

Project Settings (.claude/settings.json)

{
  "addFiles": ["src/**/*.ts", "README.md"],
  "hooks": {
    "PostToolUse": {
      "type": "command",
      "command": "prettier --write {filePath}",
      "match": { "tool": "Write" }
    }
  }
}

Permission Rules Syntax

Rules are evaluated in order: deny → ask → allow. The first matching rule wins, so deny rules always take precedence.

{
  "permissions": {
    "deny": [
      "Read(.env*)",              // Block reading .env files
      "Bash(rm *)",               // Block rm commands
      "Bash(sudo *)"              // Block sudo commands
    ],
    "ask": [
      "Write(database/**)",       // Prompt before database changes
      "Bash(npm install *)"       // Prompt before installing packages
    ],
    "allowedTools": [
      "Read",                     // Allow all reads (except denied)
      "Write(src/**)",            // Allow writes in src/ only
      "Bash(git *)",              // Allow all git commands
      "Edit"                      // Allow all edits
    ]
  }
}

Tool Name Patterns

Configuring MCP Servers

MCP servers are configured in ~/.claude/settings.json under the mcpServers key:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mcp-server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

Using MCP Resources

Type @ in your prompt to see available resources from all connected MCP servers. Resources appear alongside files in the autocomplete menu:

# Reference MCP resources in prompts using @
@database/users          # Query users table
@github/PR-123           # Reference GitHub PR
@notion/ProjectDocs      # Access Notion docs

Auto Memory System

• Automatic -- Claude writes to memory throughout your session, no manual action needed
• Project-scoped -- each git repository gets its own memory directory, derived from the repo root path
• Structure -- MEMORY.md as entrypoint, plus optional topic files (e.g., git-workflow.md, testing-patterns.md)
• Shared within repo -- all subdirectories within the same repository share one auto-memory directory

Context Management Commands

Subagents & Task Tool

Subagents enable parallel execution of up to 7 agents simultaneously, dramatically speeding up complex workflows. The Task tool coordinates work across sessions using directed acyclic graphs (DAGs).

Task Tool Key Capabilities

• Parallel execution -- spawn multiple sub-agents working on independent features simultaneously
• Dependency management -- Task 3 waits until Task 1 and Task 2 complete (DAG-based)
• Scoped access -- restrict each agent to specific directories
• State persistence -- tasks written to ~/.claude/tasks
• Background execution -- use run_in_background: true for long-running work

Creating Custom Subagents

Store custom subagent definitions in .claude/skills/<agent-name>/SKILL.md:

---
name: code-reviewer
description: Specialized code review agent for security and performance
agent: true
---

# Code Review Instructions

When reviewing code:
1. Check for security vulnerabilities
2. Analyze performance implications
3. Verify test coverage
4. Ensure style guide compliance

Hooks

Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. They provide deterministic control -- ensuring actions always happen rather than relying on the LLM to choose them.

Common Hook Events

• PostToolUse -- fires after Claude uses any tool (e.g., auto-format after file write)
• PostBash -- fires after bash command execution
• PostTaskComplete -- fires when a background task finishes

Example: Auto-Format on File Write

{
  "hooks": {
    "PostToolUse": {
      "type": "command",
      "command": "prettier --write {filePath}",
      "match": { "tool": "Write" }
    }
  }
}

Example: Run Tests After Code Changes

{
  "hooks": {
    "PostToolUse": {
      "type": "command",
      "command": "npm test -- {filePath}",
      "match": {
        "tool": "Write",
        "path": "src/**/*.ts"
      }
    }
  }
}

Background Tasks

Run long-running commands without blocking your workflow. Claude Code maintains process continuity across sessions.

# Start a background task
Bash(command: "npm run dev", run_in_background: true)

# Start a background subagent
Task(prompt: "Run full test suite", run_in_background: true)

# Check results later
TaskOutput(task_id)

• Returns a task ID immediately -- continue working while it runs
• Use TaskOutput(task_id) to retrieve results when ready
• Process continues even if you close your session
• Ideal for: dev servers, test suites, build processes, long compilations

Custom Skills

Skills are the recommended approach for reusable workflows, commands, and knowledge. They're stored in .claude/skills/ and support features that commands do not.

SKILL.md Format

---
name: api-endpoint
description: Scaffolds a new REST API endpoint with tests
invocation: manual       # or auto-load
agent: false
---

# Create API Endpoint

When invoked, follow these steps:
1. Create endpoint in src/api/endpoints/{name}.ts
2. Use template from template.ts in this skill folder
3. Add route to src/api/router.ts
4. Create tests in tests/api/{name}.test.ts
5. Update OpenAPI schema
6. Run tests to verify

Skill Discovery

• User skills: ~/.claude/skills/ -- available across all projects
• Project skills: .claude/skills/ -- specific to one repository
• Monorepo auto-discovery: nested .claude/skills/ in subdirectories automatically discovered when editing files there
• If a skill and command share the same name, the skill takes precedence

Combined Examples

# Start with Opus, verbose logging, and load src/ directory
claude --model opus --verbose --add-dir src/

# Resume session with specific tools allowed
claude --resume abc123 --allowedTools "Read,Write(src/**),Bash(git *)"

# Agent mode with budget limit in a container
claude --agent --max-budget-usd 100 --dangerously-skip-permissions

Effective Prompting

Make a UI for the app

Create a Linear-style dashboard with:
- Dark mode using our existing theme tokens
- Table view with sortable columns
- Sidebar nav matching our design system

Use Structured Prompting

Claude excels with XML structure -- it provides more context than unstructured prompts:

<task>
  <goal>Add user authentication to API</goal>
  <requirements>
    - Use JWT tokens
    - Hash passwords with bcrypt
    - Rate limit login attempts
    - Add refresh token rotation
  </requirements>
  <constraints>
    - Follow existing auth patterns
    - Maintain backwards compatibility
  </constraints>
</task>

Workflow Optimization

Run Multiple Sessions in Parallel

Claude Code's creator (Boris Cherny) runs 5 local + 5-10 web sessions simultaneously, each with its own context and task. Use separate git worktrees to avoid conflicts:

# Terminal 1: Frontend work
cd ~/project && claude --add-dir src/components

# Terminal 2: Backend (separate worktree)
cd ~/project && git worktree add ../project-api main
cd ../project-api && claude --add-dir src/api

# Terminal 3: Testing
cd ~/project && claude --add-dir tests

Custom Commands = Time Savers

Custom commands are the #2 time saver after CLAUDE.md. Experienced developers maintain around 15 custom commands across projects.

Permission Mode Strategy

Cost Management

1. Set budget limits -- use --max-budget-usd or configure in settings.json
2. Track with /cost -- monitor spending during each session
3. Choose the right model -- Haiku for simple tasks, Sonnet for most work, Opus for complex reasoning
4. Compact regularly -- reduced context means reduced costs
5. MCP Tool Search -- 2026 feature automatically reduces MCP tool context by 85%

Security Best Practices

1. Never commit secrets -- use disallowedTools: ["Read(.env*)"] to block access to environment files
2. Restrict dangerous commands -- block rm, sudo, and destructive git operations in your permission rules
3. Use Plan Mode for sensitive areas -- review before modifying production configs, database schemas, or infrastructure
4. Audit hooks -- review custom hooks for security implications before deploying
5. Bypass mode only in isolation -- never use --dangerously-skip-permissions on a development machine

Context Window Management

1. Monitor with /context -- check consumption regularly throughout your session
2. Compact proactively -- run /compact before hitting limits (works better with headroom)
3. Use targeted reads -- specify line ranges when reading large files to conserve context
4. Reference with @ -- using @filename is more efficient than pasting content
5. Use /add-dir carefully -- only add directories you actually need

Fastest Path to Productivity