AI Coding Agents Skill

Expert knowledge for Codex CLI and Claude Code CLI — the two leading AI coding agents.

Note: This skill documents both tools for reference. VMark development primarily uses Claude Code CLI. The Codex CLI sections are retained for completeness and cross-tool workflows.

When to Use

• Orchestrating complex coding tasks via CLI
• Configuring MCP servers for either tool
• Setting up automation pipelines (CI/CD)
• Troubleshooting authentication or sandbox issues
• Comparing capabilities between agents
• Custom agent/subagent configuration

Quick Reference

Starting Sessions

Safety Modes

Model Selection

Codex CLI (OpenAI)

Installation

bash
1npm i -g @openai/codex
2# or
3brew install --cask codex

Authentication

bash
1codex login              # OAuth via ChatGPT
2codex login --with-api-key   # Read API key from stdin
3codex login status       # Check auth status
4codex logout             # Remove credentials

Core Commands

codex - Interactive Mode

bash
1codex                           # Start TUI
2codex "fix all TypeScript errors"  # With initial prompt
3codex -i screenshot.png "explain"  # With image
4codex --full-auto "refactor"    # Low-friction mode
5codex --search "find docs"      # Enable web search

codex exec - Non-Interactive

bash
1codex exec "write tests"        # Run and exit
2codex e "task"                  # Short alias
3echo "task" | codex exec -      # From stdin
4codex exec --json "task"        # JSONL output
5codex exec -o result.txt "task" # Save to file
6codex exec --output-schema schema.json "task"  # Validate output

codex resume - Continue Sessions

bash
1codex resume                    # Interactive picker
2codex resume --last             # Most recent
3codex resume --all              # Show all (any directory)
4codex resume <session-id>       # Specific session
5codex resume <id> "continue with this"  # With prompt

codex review - Code Review

bash
1codex review                    # Review current branch vs main
2codex review --uncommitted      # Review uncommitted changes
3codex review --base develop     # Against specific branch
4codex review --commit abc123    # Review specific commit
5codex review "focus on security"  # Custom instructions

codex apply - Apply Cloud Task

bash
1codex apply <task-id>           # Apply diff from cloud task

codex cloud - Cloud Tasks (Experimental)

bash
1codex cloud                     # Browse cloud tasks
2codex cloud exec "task" --env <env-id>  # Submit task
3codex cloud status <task-id>    # Check status
4codex cloud diff <task-id>      # Show diff
5codex cloud apply <task-id>     # Apply changes

codex mcp - MCP Server Management

bash
1codex mcp list                  # List servers
2codex mcp list --json           # JSON output
3codex mcp get <name>            # Server details
4codex mcp add <name> -- npx my-server   # Add stdio server
5codex mcp add <name> --url https://... # Add HTTP server
6codex mcp add <name> --env API_KEY=xxx -- cmd  # With env vars
7codex mcp remove <name>         # Remove server
8codex mcp login <name> --scopes read,write  # OAuth for HTTP
9codex mcp logout <name>         # Remove OAuth

codex sandbox - Run Sandboxed Commands

bash
1# macOS
2codex sandbox macos -- npm test
3codex sandbox seatbelt --full-auto -- ./script.sh
4
5# Linux
6codex sandbox linux -- npm test
7codex sandbox landlock -- ./script.sh

codex completion - Shell Completions

bash
1codex completion bash >> ~/.bashrc
2codex completion zsh >> ~/.zshrc
3codex completion fish > ~/.config/fish/completions/codex.fish

Slash Commands (Interactive)

Configuration (~/.codex/config.toml)

toml
1model = "gpt-5-codex"
2approval_policy = "on-request"
3
4[sandbox]
5mode = "workspace-write"
6
7[features]
8web_search = true
9
10[profiles.ci]
11model = "gpt-4.1"
12approval_policy = "never"

Global Flags

-m, --model <MODEL>          Model selection
-s, --sandbox <MODE>         read-only|workspace-write|danger-full-access
-a, --ask-for-approval <P>   untrusted|on-failure|on-request|never
-c, --config <KEY=VALUE>     Override config
-C, --cd <DIR>               Working directory
-i, --image <FILE>           Attach image(s)
-p, --profile <NAME>         Config profile
--full-auto                  Low-friction mode
--yolo                       Bypass all safety (DANGEROUS)
--search                     Enable web search
--add-dir <DIR>              Grant additional write access
--enable <FEATURE>           Enable feature flag
--disable <FEATURE>          Disable feature flag
--oss                        Use local OSS model

Claude Code CLI (Anthropic)

Installation

bash
1npm install -g @anthropic-ai/claude-code

Authentication

bash
1claude                      # First run prompts login
2claude setup-token          # Set up long-lived token
3# Requires Claude Pro/Max subscription OR API key

Core Commands

claude - Interactive Mode

bash
1claude                          # Start REPL
2claude "explain this project"   # With prompt
3claude -c                       # Continue last conversation
4claude -r "session-name"        # Resume by name/ID
5claude --model opus             # Select model
6claude --chrome                 # Enable Chrome integration
7claude --ide                    # Auto-connect to IDE

claude -p - Print Mode (Non-Interactive)

bash
1claude -p "explain this function"   # Query and exit
2cat file | claude -p "explain"      # Process piped input
3claude -p --output-format json "q"  # JSON output
4claude -p --output-format stream-json "q"  # Streaming JSON
5claude -p --max-turns 3 "task"      # Limit agent turns
6claude -p --max-budget-usd 5 "task" # Spending limit
7claude -p --json-schema '{...}' "q" # Validate output schema

claude mcp - MCP Server Management

bash
1claude mcp list                 # List servers
2claude mcp get <name>           # Server details
3claude mcp add <name> <cmd>     # Add stdio server
4claude mcp add -t http <name> <url>  # Add HTTP server
5claude mcp add -e KEY=val <name> -- cmd  # With env vars
6claude mcp add -H "Auth: Bearer x" <name> <url>  # With headers
7claude mcp add -s project <name> <cmd>  # Project scope
8claude mcp remove <name>        # Remove server
9claude mcp serve                # Run as MCP server
10claude mcp add-from-claude-desktop   # Import from desktop app
11claude mcp reset-project-choices     # Reset approvals

claude plugin - Plugin Management

bash
1claude plugin list              # List plugins
2claude plugin install <name>    # Install plugin
3claude plugin install <name>@marketplace  # From specific marketplace
4claude plugin uninstall <name>  # Remove plugin
5claude plugin enable <name>     # Enable disabled plugin
6claude plugin disable <name>    # Disable plugin
7claude plugin update <name>     # Update plugin
8claude plugin validate <path>   # Validate manifest
9claude plugin marketplace       # Manage marketplaces

claude update - Self-Update

bash
1claude update                   # Check and install updates

claude doctor - Diagnostics

bash
1claude doctor                   # Check health/issues

claude install - Native Build

bash
1claude install                  # Install native build
2claude install stable           # Specific version
3claude install latest           # Latest version

Slash Commands (Interactive)

Custom Commands

Create .claude/commands/fix-issue.md:

markdown
1Fix GitHub issue #$ARGUMENTS
2
31. Read the issue details
42. Identify the problem
53. Implement the fix
64. Write tests
75. Create a commit

Usage: /project:fix-issue 1234

Configuration

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

json
1{
2  "model": "claude-sonnet-4-5-20250929",
3  "verbose": false,
4  "theme": "dark"
5}

Project settings (.claude/settings.json):

json
1{
2  "allowedTools": ["Bash(git:*)", "Read", "Edit"],
3  "disallowedTools": ["Bash(rm:*)"]
4}

CLI Flags

Core

-p, --print                 Non-interactive mode
-c, --continue              Continue last conversation
-r, --resume <ID>           Resume specific session
-v, --version               Show version

Model & Config

--model <MODEL>             sonnet|opus|haiku or full name
--fallback-model <MODEL>    Fallback when overloaded
--settings <FILE>           Load settings JSON
--setting-sources <LIST>    user,project,local
--session-id <UUID>         Use specific session ID

System Prompt

--system-prompt <TEXT>      Replace default prompt
--append-system-prompt <T>  Append to default
--system-prompt-file <F>    Replace with file (print only)
--append-system-prompt-file Replace with file (print only)

Agent & Tools

--agent <NAME>              Specify agent
--agents <JSON>             Define custom subagents
--tools <LIST>              Restrict built-in tools
--allowedTools <LIST>       Auto-approve tools
--disallowedTools <LIST>    Remove tools from context

Permissions

--permission-mode <MODE>    acceptEdits|bypassPermissions|default|delegate|dontAsk|plan
--dangerously-skip-permissions  Skip all prompts (DANGEROUS)
--allow-dangerously-skip-permissions  Enable bypass option

Output

--output-format <FMT>       text|json|stream-json
--input-format <FMT>        text|stream-json
--include-partial-messages  Include streaming chunks
--verbose                   Verbose logging
--debug [FILTER]            Debug mode with filtering

Advanced

--max-turns <N>             Limit agent turns (print only)
--max-budget-usd <AMT>      Spending limit (print only)
--json-schema <SCHEMA>      Validate JSON output
--chrome / --no-chrome      Chrome integration
--ide                       IDE auto-connect
--fork-session              Create new session on resume
--no-session-persistence    Don't save session
--add-dir <DIRS>            Additional directories
--plugin-dir <DIRS>         Load plugins
--disable-slash-commands    Disable all skills
--mcp-config <FILES>        MCP server configs
--strict-mcp-config         Only use specified MCP
--betas <HEADERS>           Beta API headers

Custom Subagents

bash
1claude --agents '{
2  "reviewer": {
3    "description": "Code reviewer. Use after changes.",
4    "prompt": "You are a senior code reviewer...",
5    "tools": ["Read", "Grep", "Glob"],
6    "model": "sonnet"
7  }
8}'

Common Patterns & Edge Cases

CI/CD Integration

Codex in GitHub Actions:

yaml
1- name: Run Codex
2  run: |
3    echo "${{ secrets.OPENAI_API_KEY }}" | codex login --with-api-key
4    codex exec --json -o result.txt "fix linting errors"

Claude in CI:

yaml
1- name: Run Claude
2  env:
3    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
4  run: |
5    claude -p --output-format json "review this PR" > review.json

Handling Rate Limits

Codex: Automatic backoff built-in.

Claude: Use --fallback-model:

bash
1claude -p --fallback-model haiku "quick task"

Working with Large Codebases

bash
1# Codex: Use /compact to free context
2# In session: /compact
3
4# Claude: Use /compact or start fresh
5claude --no-session-persistence -p "analyze src/"

Multi-Directory Access

bash
1# Codex
2codex --add-dir ../shared-lib --add-dir ../config
3
4# Claude
5claude --add-dir ../shared-lib ../config

Structured Output

Codex:

bash
1codex exec --output-schema schema.json "generate API spec"

Claude:

bash
1claude -p --json-schema '{"type":"object","properties":{"name":{"type":"string"}}}' "extract data"

Image Input

Codex:

bash
1codex -i screenshot.png "explain this UI"
2codex -i img1.png -i img2.png "compare these"

Claude:

bash
1# Via file reference in prompt
2claude "analyze the image at ./screenshot.png"

Session Forking

bash
1# Codex: /fork in session
2
3# Claude
4claude -r "session-id" --fork-session "try alternative approach"

MCP Server Debugging

Codex:

bash
1codex mcp list --json | jq .

Claude:

bash
1claude --debug "mcp" --mcp-config ./mcp.json

Troubleshooting

Authentication Issues

Sandbox Issues

MCP Server Issues

Performance Issues

Best Practices

1. Start with read-only for exploration, escalate as needed
2. Use sessions - resume work instead of starting fresh
3. Create AGENTS.md/CLAUDE.md for project-specific instructions
4. Leverage MCP servers for external integrations
5. Use structured output in CI/CD for parsing
6. Set spending limits with --max-budget-usd
7. Review diffs before applying (/diff, codex cloud diff)
8. Commit checkpoints before major changes