File Analysis with @ Syntax

The Codex MCP Tool supports powerful file referencing through the @ syntax, allowing you to quickly include files and directories in your prompts. This feature works seamlessly with both the Codex CLI and our MCP server implementation.

Overview

The @ syntax enables you to reference files directly in your prompts without manually copying content. When you type @, Codex provides an interactive file picker, and the selected path is automatically inserted into your prompt.

Basic Usage

With Codex CLI

bash

codex "explain @src/index.ts"
codex exec "analyze @README.md and suggest improvements"

With MCP Tool (ask-codex)

javascript

// Natural language in Claude
"analyze @src/utils/logger.ts and suggest performance improvements"

// Direct tool invocation
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "review @src/server.ts for security vulnerabilities"
  }
}

Advanced Patterns

Multiple Files

Reference multiple files in a single prompt:

bash

codex "compare @src/server.ts @src/client.ts and explain their interaction"

Directories and Glob Patterns

Analyze entire directories or use patterns:

bash

# Entire directory
codex "summarize the architecture of @src/"

# All TypeScript files
codex "find potential bugs in @src/**/*.ts"

# Specific file types in directory
codex "review all tests in @tests/**/*.test.js"

Current Directory

Reference the current working directory:

bash

codex "analyze @. and create a project overview"

Best Practices

1. Be Specific with Context

Combine file references with clear instructions:

bash

# Good: Specific task with context
codex "@src/auth/login.ts explain the authentication flow and identify security risks"

# Better: Multiple related files for complete context
codex "@src/auth/*.ts @src/middleware/auth.js review the entire auth system"

2. Use Structured Queries

Break complex analyses into focused questions:

bash

# Architecture review
codex "@src/**/*.ts identify the 3 most critical refactoring opportunities"

# Performance audit
codex "@src/database/*.js find N+1 queries and suggest optimizations"

# Security assessment
codex "@src/api/**/*.ts check for OWASP top 10 vulnerabilities"

3. Leverage Pattern Matching

Use glob patterns effectively:

*.ts - All TypeScript files in current directory
**/*.test.js - All test files recursively
src/**/index.ts - All index files under src
{src,lib}/**/*.js - JavaScript files in src or lib

4. Handle Large Codebases

For large projects, focus your queries:

bash

# Step 1: Overview
codex "@src/**/index.ts summarize the module structure"

# Step 2: Deep dive into specific areas
codex "@src/core/**/*.ts analyze the core business logic"

# Step 3: Targeted improvements
codex "@src/api/users.ts optimize database queries"

Working with Different File Types

Code Files

bash

# JavaScript/TypeScript
codex "@src/**/*.{js,ts} identify unused exports"

# Python
codex "@app/**/*.py check PEP 8 compliance"

# Go
codex "@pkg/**/*.go review error handling patterns"

Configuration Files

bash

# Package dependencies
codex "@package.json @package-lock.json audit dependencies for vulnerabilities"

# Docker setup
codex "@Dockerfile @docker-compose.yml optimize container configuration"

# CI/CD
codex "@.github/workflows/*.yml improve CI pipeline efficiency"

Documentation

bash

# Markdown files
codex "@docs/**/*.md check for broken links and outdated information"

# API docs
codex "@api-docs/*.yaml validate OpenAPI specifications"

Integration with MCP Features

With Sandbox Mode

Enable full-auto mode for file operations:

javascript

{
  "prompt": "@src/**/*.ts add JSDoc comments to all exported functions",
  "fullAuto": true
}

With Model Selection

Use specific models for different tasks:

javascript

{
  "prompt": "@src/algorithm.ts optimize this complex algorithm",
  "model": "gpt-5.1-codex-max"  // Use for complex reasoning
}

With Change Mode

Get structured edits:

javascript

{
  "prompt": "@src/components/*.tsx convert class components to hooks",
  "changeMode": true
}

Tips and Tricks

Path Resolution

Paths are resolved relative to Codex's working directory
Use --cd flag to change the working directory:
bash
```
codex --cd /path/to/project "analyze @src/"
```

Performance Optimization

Start broad, then narrow: Begin with directory overviews, then focus on specific files
Use appropriate models: gpt-5.1-codex-max for complex analysis, gpt-5.1-codex-mini for quick reviews
Batch related files: Include all relevant context in one prompt rather than multiple queries

Common Patterns

bash

# Find TODOs and FIXMEs
codex "@src/**/*.{js,ts} list all TODO and FIXME comments with priority"

# Generate tests
codex "@src/utils/*.ts generate comprehensive unit tests"

# Documentation
codex "@src/api/**/*.ts generate API documentation in OpenAPI format"

# Refactoring
codex "@src/legacy/*.js modernize to ES6+ syntax"

# Dependencies
codex "@package.json identify unused dependencies"

Troubleshooting

File Not Found

Verify the path exists: ls <path>
Check working directory: pwd
Ensure correct relative path from working directory

Large File Handling

For files over 100KB, consider splitting the analysis
Use specific line ranges when possible
Focus on relevant sections rather than entire files

Pattern Matching Issues

Test glob patterns with ls first: ls src/**/*.ts
Escape special characters when needed
Use quotes for complex patterns

Examples by Use Case

Code Review

bash

codex "@feature/new-api/**/*.ts perform a thorough code review focusing on:
- Code quality and best practices
- Performance considerations
- Security vulnerabilities
- Test coverage"

Refactoring

bash

codex "@src/old-module/*.js refactor to:
- Use TypeScript
- Apply SOLID principles
- Add proper error handling
- Include unit tests"

Documentation Generation

bash

codex "@src/**/*.ts generate:
- README with setup instructions
- API documentation
- Architecture diagram in Mermaid format
- Usage examples"

Bug Investigation

bash

codex "@src/payment/*.ts @logs/error.log investigate the payment processing bug:
- Analyze error patterns
- Identify root cause
- Suggest fixes with tests"

File Analysis with @ Syntax ​

Overview ​

Basic Usage ​

With Codex CLI ​

With MCP Tool (ask-codex) ​

Advanced Patterns ​

Multiple Files ​

Directories and Glob Patterns ​

Current Directory ​

Best Practices ​

1. Be Specific with Context ​

2. Use Structured Queries ​

3. Leverage Pattern Matching ​

4. Handle Large Codebases ​

Working with Different File Types ​

Code Files ​

Configuration Files ​

Documentation ​

Integration with MCP Features ​

With Sandbox Mode ​

With Model Selection ​

With Change Mode ​

Tips and Tricks ​

Path Resolution ​

Performance Optimization ​

Common Patterns ​

Troubleshooting ​

File Not Found ​

Large File Handling ​

Pattern Matching Issues ​

Examples by Use Case ​

Code Review ​

Refactoring ​

Documentation Generation ​

Bug Investigation ​

See Also ​

File Analysis with @ Syntax

Overview

Basic Usage

With Codex CLI

With MCP Tool (ask-codex)

Advanced Patterns

Multiple Files

Directories and Glob Patterns

Current Directory

Best Practices

1. Be Specific with Context

2. Use Structured Queries

3. Leverage Pattern Matching

4. Handle Large Codebases

Working with Different File Types

Code Files

Configuration Files

Documentation

Integration with MCP Features

With Sandbox Mode

With Model Selection

With Change Mode

Tips and Tricks

Path Resolution

Performance Optimization

Common Patterns

Troubleshooting

File Not Found

Large File Handling

Pattern Matching Issues

Examples by Use Case

Code Review

Refactoring

Documentation Generation

Bug Investigation

See Also