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

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