claudeforcodex

name: claudeforcodex description: "Claude Code CLI configuration guide for Codex. Use when users ask about: claude code config, ~/.claude/settings.json, claude plugins, claude agents, claude skills, claude hooks, claude mcp servers, or integrating tools with Claude Code."

Claude Code CLI Configuration Guide

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

Quick Reference

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:

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

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:

Reference Files

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