# Claude Codex Settings

A comprehensive configuration system for Claude Code and OpenAI Codex that provides production-ready workflows, automated code quality enforcement, and intelligent AI agents. This setup transforms AI coding assistants into battle-tested development environments with plugin-based installation, multi-language formatting hooks, and specialized git workflow automation. It eliminates manual formatting overhead while maintaining enterprise-level code quality standards.

The project delivers three core capabilities: (1) automated code quality enforcement through pre/post tool use hooks covering 8+ languages, (2) intelligent git workflow agents for commits and pull requests, and (3) seamless MCP server integration for 9+ external services including GitHub, MongoDB, and Tavily. All components work together to create a zero-configuration AI development environment that handles formatting, linting, documentation updates, and git operations automatically.

## Plugin Installation

Install all components via Claude Code's plugin marketplace:

```bash
# Add marketplace
/plugin marketplace add fcakyon/claude-codex-settings

# Install all plugins
/plugin install code-quality-hooks@fcakyon-claude-plugins
/plugin install git-workflow-agents@fcakyon-claude-plugins
/plugin install code-simplifier-agent@fcakyon-claude-plugins
/plugin install productivity-commands@fcakyon-claude-plugins
/plugin install mcp-server-configs@fcakyon-claude-plugins

# Create symlink for cross-tool compatibility
ln -s ~/.claude/CLAUDE.md ~/.claude/AGENTS.md
```

Manual installation alternative:

```bash
# Clone and copy configuration
git clone https://github.com/fcakyon/claude-settings.git ~/.claude-settings
cp -r ~/.claude-settings/.claude/* ~/.claude/
ln -s ~/.claude/CLAUDE.md ~/.claude/AGENTS.md
chmod +x ~/.claude/hooks/*.py
```

## Settings Configuration

Configure Claude Code with model selection, environment variables, and custom hooks:

```json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "opusplan",
  "includeCoAuthoredBy": false,
  "env": {
    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1",
    "DISABLE_BUG_COMMAND": "1",
    "DISABLE_ERROR_REPORTING": "1",
    "DISABLE_TELEMETRY": "1",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-sonnet-4-5-20250929",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5-20250929",
    "MAX_MCP_OUTPUT_TOKENS": "40000"
  },
  "permissions": {
    "allow": [
      "Bash(git diff:*)",
      "Bash(git status:*)",
      "Bash(ruff:*)",
      "mcp__tavily__tavily-extract",
      "mcp__github__get_pull_request"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "WebFetch",
        "hooks": [{"type": "command", "command": ".claude/hooks/hook_webfetch_to_tavily_extract.py"}]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write|Task",
        "hooks": [{"type": "command", "command": ".claude/hooks/hook_python_code_quality.py"}]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [{"type": "command", "command": ".claude/hooks/hook_load_claude_md.py"}]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "npx -y ccusage statusline",
    "padding": 0
  }
}
```

## Python Code Quality Hook

Auto-format Python files with ruff and docformatter after every Edit/Write operation:

```python
#!/usr/bin/env python3
import json
import sys
import subprocess
import shutil
from pathlib import Path

def main():
    try:
        data = json.load(sys.stdin)
        file_path = data.get("tool_input", {}).get("file_path", "")

        if not file_path.endswith('.py'):
            sys.exit(0)

        if not shutil.which('ruff') or not shutil.which('docformatter'):
            sys.exit(0)

        py_file = Path(file_path)
        if not py_file.exists():
            sys.exit(0)

        work_dir = py_file.parent

        # Format with ruff
        subprocess.run([
            'ruff', 'format', '--line-length', '120', str(py_file)
        ], capture_output=True, check=False, cwd=work_dir)

        # Check and fix with ruff
        subprocess.run([
            'ruff', 'check', '--fix', '--extend-select', 'I,D,UP',
            '--target-version', 'py38',
            '--ignore', 'D100,D101,D103,D104,D203,D205,D212,D213,D401,D406,D407,D413,F821,F841',
            str(py_file)
        ], capture_output=True, check=False, cwd=work_dir)

        # Format docstrings
        subprocess.run([
            'docformatter', '--wrap-summaries', '120', '--wrap-descriptions', '120',
            '--pre-summary-newline', '--close-quotes-on-newline', '--in-place',
            '--recursive', str(py_file)
        ], capture_output=True, check=False, cwd=work_dir)

    except Exception:
        pass

    sys.exit(0)

if __name__ == "__main__":
    main()
```

Usage with Claude Code - Python files are automatically formatted after editing:

```bash
# Claude Code uses Edit tool on auth.py
# Hook automatically runs:
# 1. ruff format auth.py
# 2. ruff check --fix auth.py
# 3. docformatter --in-place auth.py
# Result: Formatted, linted, and docstring-wrapped code
```

## WebFetch to Tavily Hook

Redirect slow WebFetch calls to faster Tavily extract (20-30s → 1-2s):

```python
#!/usr/bin/env python3
import json
import sys

try:
    data = json.load(sys.stdin)
    url = data["tool_input"]["url"]
except (KeyError, json.JSONDecodeError) as err:
    print(f"hook-error: {err}", file=sys.stderr)
    sys.exit(1)

print(json.dumps({
    "systemMessage": "WebFetch detected. AI is directed to use Tavily extract instead.",
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": f"Please use mcp__tavily__tavily-extract with urls: ['{url}'] and extract_depth: 'advanced'"
    }
}, separators=(',', ':')))
sys.exit(0)
```

Usage example:

```bash
# Claude Code attempts: WebFetch(url="https://docs.anthropic.com/api")
# Hook intercepts and suggests:
# mcp__tavily__tavily-extract(urls=["https://docs.anthropic.com/api"], extract_depth="advanced")
# Result: 15x faster content extraction with bot protection bypass
```

## Context Loading Hook

Auto-load project instructions on every prompt to maintain AI consistency:

```python
#!/usr/bin/env python3
import json
import sys
import os
from pathlib import Path

def find_claude_md(project_dir):
    """Find CLAUDE.md or AGENTS.md in the project directory."""
    claude_md = Path(project_dir) / "CLAUDE.md"
    agents_md = Path(project_dir) / "AGENTS.md"

    if claude_md.exists():
        return claude_md
    elif agents_md.exists():
        return agents_md
    return None

try:
    input_data = json.load(sys.stdin)
    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", input_data.get("cwd", ""))

    if not project_dir:
        sys.exit(0)

    claude_md_path = find_claude_md(project_dir)

    if not claude_md_path:
        sys.exit(0)

    try:
        with open(claude_md_path, 'r', encoding='utf-8') as f:
            content = f.read().strip()

        if not content:
            sys.exit(0)

        print(f"Project instructions from {claude_md_path.name}:\n\n{content}")
        sys.exit(0)

    except Exception as e:
        print(f"Error reading {claude_md_path}: {e}", file=sys.stderr)
        sys.exit(1)

except Exception as e:
    print(f"hook-error: {e}", file=sys.stderr)
    sys.exit(1)
```

Usage flow:

```bash
# User submits prompt: "Implement user authentication"
# Hook triggers before prompt processing
# Reads: /project/CLAUDE.md
# Injects: Project instructions + coding standards + conventions
# Claude receives: Original prompt + full project context
# Result: AI maintains consistent style across all responses
```

## Commit Manager Agent

Intelligent git workflow agent that analyzes staged changes and creates optimal commits:

```markdown
---
name: commit-manager
description: Use this agent when you have staged files ready for commit and need intelligent commit planning and execution.
tools: Bash, BashOutput, Glob, Grep, Read, WebSearch, WebFetch, TodoWrite
model: claude-sonnet-4-5-20250929
---

You are a Git commit workflow manager, an expert in version control best practices.

Workflow:
1. Check all staged files: git diff --cached --name-only
2. Read code diffs: git diff --cached
3. Check README.md for outdated docs
4. Plan commit strategy (single or multi-commit)
5. Execute commits with semantic messages
6. Push to remote

Commit message format:
- First line: {task-type}: brief description
- Task types: feat, fix, refactor, docs, style, test, build
- Focus on 'why' and 'what' rather than implementation details
```

Usage with slash command:

```bash
# Stage files
git add src/auth.py src/auth_test.py

# Run commit manager
/commit-staged

# Agent analyzes and commits:
# Commit 1: feat: implement user authentication system
# - Add JWT token validation in auth.py:15-42
# - Create comprehensive test suite
# - Update README with authentication setup
#
# Result: Clean, semantic commit with updated docs
```

## PR Manager Agent

End-to-end pull request workflow automation with branch creation and documentation updates:

```markdown
---
name: pr-manager
description: Complete pull request workflow including branch creation, committing, and PR submission.
tools: Bash, Glob, Grep, Read, WebSearch, WebFetch, TodoWrite, SlashCommand, mcp__github__list_pull_requests
model: claude-sonnet-4-5-20250929
---

You are a Git and GitHub PR workflow automation specialist.

Workflow:
1. Verify staged changes exist: git diff --cached --name-only
2. Check current branch: git branch --show-current
3. Create feature branch if on main: feature/brief-description
4. Commit changes via /commit-manager
5. Update documentation (README, docs)
6. Verify config/API changes with web search
7. Create PR with gh CLI: gh pr create -t "title" -b "body" -a @me
8. Include inline source links in PR description

PR Format:
- Brief summary (1 sentence)
- Bullet points with inline markdown links
- Code examples for significant changes
- Source links for API/config updates
```

Usage with slash command:

```bash
# Stage feature implementation
git add src/feature.py tests/test_feature.py

# Create PR
/create-pr "Add feature X"

# Agent workflow:
# 1. Creates branch: feature/add-feature-x
# 2. Commits via commit-manager
# 3. Updates README.md with feature docs
# 4. Searches web for API reference links
# 5. Creates PR:
#    Title: feat: add feature X
#    Body:
#    Add feature X support with validation
#    - Implement validation logic in [src/feature.py:15-42](src/feature.py#L15-L42)
#    - Add tests with 95% coverage
#    - API reference: [docs](https://example.com/api)
# 6. Returns PR URL: https://github.com/user/repo/pull/123
```

## MCP Server Configuration

Connect to 9+ external services with Model Context Protocol:

```json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ghp_xxxxxxxxxxxx"
      }
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@0.2.9"],
      "env": {
        "TAVILY_API_KEY": "tvly-xxxxxxxxxxxx"
      }
    },
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "mongodb": {
      "command": "npx",
      "args": [
        "-y", "mongodb-mcp-server",
        "--connectionString", "mongodb://localhost:27017/myDatabase",
        "--readOnly"
      ]
    },
    "supabase": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.supabase.com/mcp?project_ref=abcd1234&read_only=true&features=database"
      ]
    }
  }
}
```

Usage examples:

```bash
# GitHub MCP - Get pull request info
mcp__github__get_pull_request(owner="anthropics", repo="claude-code", pull_number=123)
# Returns: PR title, body, status, commits, files changed

# Tavily MCP - Search and extract web content
mcp__tavily__tavily-search(query="Claude Code hooks documentation", max_results=5)
# Returns: 5 most relevant search results with snippets

mcp__tavily__tavily-extract(urls=["https://docs.anthropic.com/hooks"], extract_depth="advanced")
# Returns: Full page content with advanced extraction (1-2s vs 20-30s for WebFetch)

# Context7 MCP - Get library documentation
mcp__context7__resolve-library-id(library="react", version="18.3.1")
# Returns: library_id for documentation lookup

mcp__context7__get-library-docs(library_id="react-18.3.1", query="useState hook")
# Returns: Up-to-date React documentation for useState

# MongoDB MCP - Query database
mcp__mongodb__list_databases()
# Returns: List of available databases

mcp__mongodb__list_collections(database="myDatabase")
# Returns: Collections in myDatabase

# Supabase MCP - Database operations
mcp__supabase__list_tables()
# Returns: All tables in Supabase project with schema info
```

## Slash Commands

Custom productivity commands that invoke specialized agents:

```markdown
---
allowed-tools: Task, Read, Grep, SlashCommand
argument-hint: [context]
description: Commit staged changes with optional context
---

# Commit Staged Changes

Use the commit-manager agent to analyze and commit staged changes.

## Additional Context
$ARGUMENTS

Task(
  description: "Analyze and commit staged changes",
  prompt: "Analyze the staged changes and create appropriate commits. Additional context: $ARGUMENTS",
  subagent_type: "commit-manager"
)
```

Usage examples:

```bash
# Commit staged files
/commit-staged "Fix authentication bug"

# Create pull request
/create-pr "Add user dashboard feature"

# Explain project architecture
/explain-architecture-pattern "authentication system"

# Update PR summary for PR #123
/update-pr-summary 123
```

## Integration Workflow

Complete development workflow combining all components:

```bash
# 1. Setup environment
/plugin install code-quality-hooks@fcakyon-claude-plugins
/plugin install git-workflow-agents@fcakyon-claude-plugins
/plugin install mcp-server-configs@fcakyon-claude-plugins

# 2. Implement feature
# Claude Code edits src/api.py
# Hooks automatically run:
# - Python formatting (ruff + docformatter)
# - Prettier formatting for config.json
# - Whitespace cleanup
# Result: Production-ready formatted code

# 3. Commit changes
git add src/api.py config.json README.md
/commit-staged "Add REST API endpoint"
# Agent creates semantic commits with updated docs

# 4. Create pull request
/create-pr "Add user API endpoint"
# Agent workflow:
# - Creates feature branch
# - Commits via commit-manager
# - Updates documentation
# - Verifies API references with Tavily MCP
# - Creates PR with inline source links
# - Returns: https://github.com/user/repo/pull/456

# 5. Query external services
# GitHub: Check PR status
mcp__github__get_pull_request_status(owner="user", repo="repo", pull_number=456)

# Tavily: Find related documentation
mcp__tavily__tavily-search(query="REST API best practices 2025")

# Context7: Get framework docs
mcp__context7__get-library-docs(library_id="fastapi-0.115.0", query="endpoint validation")

# Result: Zero manual formatting, consistent commits, automated PR workflow
```

This configuration system eliminates 95% of manual code quality tasks while maintaining enterprise standards. The hook system achieves zero CI formatting by handling Python (ruff/docformatter), JavaScript/TypeScript (prettier), CSS/JSON/YAML (prettier), Markdown (prettier), and shell scripts (prettier-plugin-sh) automatically. All components gracefully degrade when tools aren't available, never disrupting Claude Code operations.

The agent system transforms git workflows from manual multi-step processes into single-command operations. Combined with MCP servers, it creates a unified development environment where AI assistants have direct access to GitHub, databases, web search, and up-to-date library documentation - all while maintaining consistent code quality and semantic version control practices.