Claude Code CLI Configuration Guide

Configure and extend Anthropic's Claude Code CLI for optimal development workflows.

Quick Reference

| Task | Command/Location | |------|------------------| | Config file | ~/.claude/settings.json | | Project config | .claude/settings.json (in project root) | | Plugins | ~/.claude/plugins/ or marketplace | | Add MCP server | Edit .mcp.json or plugin | | Skills location | Plugin skills/ directories |

Core Configuration

Edit ~/.claude/settings.json for global settings:

{
  "permissions": {
    "allow": ["Bash(*)", "Read(*)", "Write(*)"],
    "deny": []
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-..."
  }
}

Project-level: Create .claude/settings.json in project root to override.

Permission System

Claude Code uses explicit tool permissions:

{
  "permissions": {
    "allow": [
      "Bash(*)",           // All bash commands
      "Read(*)",           // All file reads
      "Write(~/projects/*)", // Write only in projects
      "mcp:server_name:*"  // All tools from MCP server
    ],
    "deny": [
      "Bash(rm -rf *)"     // Block dangerous commands
    ]
  }
}

Permission patterns:

• Tool(*) - Allow all uses of tool
• Tool(/path/*) - Allow with path prefix
• mcp:server:tool - Specific MCP tool

Plugin System

Claude Code has two plugin patterns:

Standalone Plugin (entire repo = one plugin)

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # Required for standalone
├── commands/
├── agents/
├── skills/
│   └── my-skill/
│       └── SKILL.md     # ONE level deep only!
├── hooks/
└── .mcp.json

Marketplace Plugin (repo contains multiple plugins)

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json     # Lists all plugins
└── plugins/
    ├── plugin-a/
    │   ├── plugin.json      # AT ROOT (not .claude-plugin/)
    │   └── skills/
    │       └── skill-name/
    │           └── SKILL.md
    └── plugin-b/
        └── plugin.json

Critical Rules:

1. Marketplace plugins: plugin.json at plugin root, NOT in .claude-plugin/
2. Skills ONE level deep: skills/name/SKILL.md - NO skills/a/skills/b/
3. No plugin.json per skill - only one per plugin
4. Explicit skills array in marketplace.json (recommended)

Install plugin:

claude plugins add /path/to/plugin
claude plugins add https://github.com/user/plugin

# Install specific branch or tag (v2.0.28+)
claude plugins add https://github.com/user/plugin#develop
claude plugins add https://github.com/user/plugin#v1.0.0

Team sharing: Add to .claude/settings.json:

{
  "extraKnownMarketplaces": [
    "https://github.com/company/plugins#stable"
  ]
}

Commands (Slash Commands)

Create commands/name.md:

---
description: Brief description for autocomplete
argument-hint: "[optional args]"
model: sonnet
allowed-tools:
  - Bash
  - Read
context: fork
hooks:
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/scripts/notify.sh"
---

# Command Name

Instructions Claude follows when user types /name

Frontmatter fields:

• description (required) - Help text (<60 chars)
• argument-hint - Document expected arguments
• model - Override model (opus/sonnet/haiku)
• allowed-tools - Restrict available tools (YAML list)
• context: fork - Run in forked sub-agent
• agent - Agent type for execution
• hooks - Command-scoped hooks
• disable-model-invocation - Prevent SlashCommand tool calls

Invoke: /plugin-name:command-name or /command-name

Agents (Subagents)

Create agents/name.md:

---
name: agent-name
description: "What this agent specializes in. Include trigger phrases."
model: sonnet
tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
skills:
  - skill-name
permissionMode: default
disallowedTools:
  - WebSearch
hooks:
  Stop:
    - hooks:
        - type: prompt
          prompt: "Verify work is complete before stopping."
---

# Agent Name

System prompt and instructions for the agent.

Frontmatter fields:

• name (required) - Agent identifier (lowercase, hyphens)
• description (required) - When/why to use, include trigger phrases
• model - opus/sonnet/haiku (default: inherit)
• tools - Restrict available tools (YAML list, omit for all)
• skills - Auto-load specific skills
• permissionMode - default/acceptEdits/plan/bypassPermissions
• disallowedTools - Explicitly block tools
• hooks - Agent-scoped hooks (PreToolUse, PostToolUse, Stop)

Invoke: claude --agent plugin-name:agent-name

Spawn from Claude:

Task(subagent_type="plugin:agent", prompt="Do something")

Skills (Auto-Knowledge)

Create skills/name/SKILL.md:

---
name: skill-name
description: "When to trigger this skill. Be specific about keywords and contexts."
user-invocable: true
model: sonnet
context: fork
allowed-tools:
  - Read
  - Write
  - Bash
hooks:
  PostToolUse:
    - matcher: "Write"
      hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
---

# Skill Name

Knowledge and instructions loaded when skill triggers.

Frontmatter fields:

• name (required) - Skill identifier (lowercase, hyphens)
• description (required) - Trigger phrases and usage context
• user-invocable - Show in slash command menu (default: true)
• model - Override model (opus/sonnet/haiku)
• context: fork - Run in forked sub-agent
• agent - Agent type for execution
• allowed-tools - Restrict available tools (YAML list)
• hooks - Skill-scoped hooks

Key features:

• Hot-reload (v2.1.0+): Skills in ~/.claude/skills or .claude/skills reload without restart
• Unified with commands (v2.1.3+): Skills visible in / menu by default
• Progress display: Tool uses shown while skill executes

Critical: Skills must be ONE level deep:

skills/
├── skill-a/          # ✅ Correct
│   └── SKILL.md
└── skill-b/          # ✅ Correct
    └── SKILL.md

# ❌ WRONG - nested skills won't be discovered:
skills/
└── parent/
    └── skills/       # Nesting breaks discovery!
        └── child/
            └── SKILL.md

Note: Skills auto-load based on conversation context matching the description.

Hooks (Event Handlers)

Create hooks/hooks.json or define in component frontmatter:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh",
        "timeout": 30000
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "prompt",
        "prompt": "Verify all tests pass before stopping.",
        "model": "haiku"
      }]
    }]
  }
}

Hook events: | Event | When | Special Features | |-------|------|------------------| | PreToolUse | Before tool execution | Can modify updatedInput, return ask | | PostToolUse | After tool execution | Access tool_use_id | | PermissionRequest | Permission dialog shown | Can auto-approve/deny | | UserPromptSubmit | User submits prompt | additionalContext output | | Notification | Notifications sent | Supports matcher values | | Stop | Claude attempts to stop | Prompt-based hooks supported | | SubagentStop | Subagent stops | agent_id, agent_transcript_path | | SubagentStart | Subagent starts | - | | SessionStart | Session begins | agent_type if --agent used | | SessionEnd | Session ends | systemMessage supported | | PreCompact | Before history compacted | - |

Hook types:

• command - Execute shell scripts
• prompt - LLM-driven evaluation (can specify model)

Hook configuration:

• matcher - Tool/event pattern (regex, * wildcard)
• timeout - Timeout in ms (default: 10 minutes)
• once: true - Run only once per session
• model - Model for prompt-based hooks

MCP Server Integration

Create .mcp.json in plugin or project root:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@company/mcp-server"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

Use MCP tools:

mcp-cli tools                    # List all MCP tools
mcp-cli info server/tool         # Get tool schema
mcp-cli call server/tool '{}'    # Call tool

Claude Code vs Codex

| Aspect | Claude Code | Codex | |--------|-------------|-------| | Provider | Anthropic | OpenAI | | Config | ~/.claude/settings.json | ~/.codex/config.toml | | Plugins | Full plugin system | Skills only | | Skills | Plugin-based | ~/.codex/skills/ | | Agents | Plugin agents | N/A | | Hooks | Plugin hooks | N/A | | MCP | .mcp.json or plugin | config.toml sections | | Permissions | JSON allow/deny | Sandbox modes |

Common Workflows

Run with Full Permissions

claude --dangerously-skip-permissions

Use Specific Agent

claude --agent conductor:code-reviewer

Install Marketplace Plugin

claude plugins add marketplace-name

Debug Plugin Loading

claude --debug

Auditing Plugin Structure

When auditing a Claude Code plugin/marketplace for issues:

# Find all SKILL.md files
find plugins -name "SKILL.md" | sort

# Find nested skills (WRONG structure)
find plugins -path "*/skills/*/skills/*" -name "SKILL.md"

# Find all plugin.json files
find plugins -name "plugin.json" | sort

# Find orphaned plugin.json in skill dirs (should be 0)
find plugins -path "*/skills/*/plugin.json" | wc -l

# Check marketplace.json has skills arrays
cat .claude-plugin/marketplace.json | jq '.plugins[].skills'

Common Issues: | Issue | Symptom | Fix | |-------|---------|-----| | Nested skills | Skills not loading | Flatten to skills/name/SKILL.md | | plugin.json in skill dirs | Confusion | Remove, only one per plugin | | Missing skills array | Skills not discovered | Add to marketplace.json | | Wrong plugin.json location | Plugin not loading | Move to plugin root |

Reference Files

• references/plugin-structure.md - Complete plugin layout