Tool Configuration Reference

This page is the single source of truth for how each major agentic coding tool implements the universal patterns described in this guide. Every concept — configuration files, skills, sub-agents, context management — exists in some form across all tools. The names and file paths differ; the ideas do not.

Bookmark this page. When another section says “see your tool’s configuration file” or “use the plan mode for your tool,” come here for specifics.

1. Configuration Files

The “agent configuration file” is a markdown file that loads automatically at the start of every session. It is the always-available context: project structure, build commands, coding conventions, and anything the agent needs to know in every interaction. See Agent Configuration Files for what to put in this file.

Tool	File	Location	Hierarchy Support
Claude Code	`CLAUDE.md`	Project root + subdirectories	Yes — auto-loads root, then working directory, plus any `@import`ed files
OpenAI Codex	`AGENTS.md`	Project root; `~/.codex/AGENTS.md` for global	Yes — global → project → subdirectory override chain
Gemini CLI	`GEMINI.md` or `AGENT.md`	Project root; `~/.gemini/GEMINI.md` global	Yes — global → project; more-specific files override general ones
Aider	`CONVENTIONS.md`	Project root (loaded via `--read`)	Partial — manual inclusion; `.aider.conf.yml` for auto-loading
Cursor	`.cursorrules` or `.cursor/rules/*.mdc`	Project root / `.cursor/rules/` directory	Yes — per-directory rule files with glob-based auto-attach
Windsurf	`.windsurfrules`	Project root; `global_rules.md` for global	Yes — global rules + project rules merged
GitHub Copilot	`.github/copilot-instructions.md`	`.github/` directory	Partial — single file per project, no subdirectory hierarchy
opencode	Agent config in `opencode.json`	Project root	Yes — custom agents with per-agent system prompts

Configuration File Examples

File: CLAUDE.md in the project root. Subdirectories can contain their own CLAUDE.md files, which are loaded in addition to the root when the agent’s working directory is inside that subdirectory. Use @path/to/file to import other files.

# Project: Payments API

## Tech Stack
- Runtime: Node.js 22 / TypeScript 5
- Framework: Fastify
- Database: PostgreSQL via Drizzle ORM
- Testing: Vitest + Supertest
- Package manager: pnpm

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Test single: `pnpm vitest run path/to/test`
- Typecheck: `pnpm tsc --noEmit`
- Lint: `pnpm lint`

## Architecture
- src/routes/ — Fastify route handlers, one file per resource
- src/services/ — Business logic, no direct DB access
- src/repos/ — Database layer via Drizzle
- src/types/ — Shared TypeScript interfaces

## Conventions
- Result<T, E> pattern for error handling — never throw
- All endpoints must have integration tests in tests/integration/
- Use zod for all external input validation

Global instructions go in ~/.claude/CLAUDE.md and apply to every project.

File: AGENTS.md in the project root. Codex loads a chain: ~/.codex/AGENTS.md (global) → AGENTS.md (project root) → AGENTS.md in any subdirectory closer to the current task. Later files in the chain override earlier ones on conflicting points.

# Payments API

## Stack
Node.js 22, TypeScript, Fastify, PostgreSQL, Vitest, pnpm

## Test commands
- All tests: `pnpm test`
- Single file: `pnpm vitest run <path>`

## Coding conventions
- Use Result<T, E> for errors, never throw
- Validate all inputs with zod
- Integration tests required for every endpoint

The global file at ~/.codex/AGENTS.md is good for personal preferences (preferred languages, universal style rules) that apply across all your projects.

File: GEMINI.md (preferred) or AGENT.md in the project root. The global file lives at ~/.gemini/GEMINI.md. More-specific files override more-general ones; both are loaded when present.

# Project Context

You are working on a Fastify/TypeScript payments API.

## Build & test
- Install: `pnpm install`
- Test: `pnpm test`
- Typecheck: `pnpm tsc --noEmit`

## Key conventions
- Error handling: Result<T, E> pattern
- Input validation: zod everywhere
- No direct DB access outside src/repos/

Aider does not auto-load a configuration file by default. The most common patterns:

Option 1 — --read flag: Pass a read-only context file that the agent can reference but not edit.

aider --read CONVENTIONS.md src/payments.ts

Option 2 — .aider.conf.yml: Create a config file that automatically passes --read on startup.

read:
  - CONVENTIONS.md
  - docs/architecture.md

## Coding conventions for this project
- TypeScript strict mode
- Result<T, E> for error handling
- zod for input validation
- Vitest for tests; run with `pnpm test`

Cursor supports two configuration formats:

Legacy: .cursorrules in the project root (single flat file, still supported).

Modern: .cursor/rules/*.mdc — one file per concern, each with YAML frontmatter controlling when it activates.

---
description: Backend API conventions
globs: ["src/routes/**", "src/services/**", "src/repos/**"]
alwaysApply: false
---

## Backend conventions
- Fastify route handlers in src/routes/
- Business logic in src/services/ (no direct DB access)
- Database layer in src/repos/ via Drizzle ORM
- Result<T, E> for error handling, never throw

The globs field makes rules auto-attach when the agent edits matching files. Set alwaysApply: true for rules that should be active in every conversation.

File: .windsurfrules in the project root. A global rules file can be configured in Windsurf settings as global_rules.md. Both are loaded and merged for every session.

# Project Rules

## Tech stack
Node.js 22, TypeScript, Fastify, Vitest, pnpm

## Commands
- Test: `pnpm test`
- Typecheck: `pnpm tsc --noEmit`

## Conventions
- Result<T, E> error handling
- zod validation on all inputs
- Integration tests for every endpoint

File: .github/copilot-instructions.md. This is a single file for the entire project — no subdirectory hierarchy, no global user-level file.

# Copilot Instructions

This is a Fastify/TypeScript payments API.

## Tech stack
- Node.js 22, TypeScript strict mode
- Fastify for HTTP, Drizzle ORM for PostgreSQL
- Vitest for testing, pnpm as package manager

## Conventions
- Use Result<T, E> pattern, never throw exceptions
- Validate all inputs with zod
- Every API endpoint needs an integration test in tests/integration/
- Database access only through src/repos/; services must not query DB directly

## Commands
- Tests: `pnpm test`
- Single test: `pnpm vitest run <path>`
- Typecheck: `pnpm tsc --noEmit`

opencode uses a JSON/TOML configuration file (opencode.json or opencode.toml) where you define custom agents with their own system prompts. Each agent gets a system field that acts as its configuration file.

{
  "agents": {
    "backend": {
      "model": "claude-opus-4-5",
      "system": "You are working on a Fastify/TypeScript payments API.\n\nCommands:\n- Test: pnpm test\n- Typecheck: pnpm tsc --noEmit\n\nConventions:\n- Result<T, E> error handling\n- zod validation everywhere"
    }
  }
}

2. Skills / On-Demand Context

A skill is context loaded only when relevant — not every session. This keeps the always-loaded configuration file small and high-signal, while still making detailed domain knowledge available when needed. See Skills & Agents Architecture for the full pattern.

The concept is universal; the file paths and invocation mechanisms vary by tool.

Location: .claude/skills/<name>/SKILL.md

Invocation: Skills double as slash commands — /skill-name invokes the skill. The agent also loads relevant skills automatically based on the task description.

---
name: db-migrations
description: Database migration conventions and procedures
---

# Database Migration Conventions

## Creating a migration
1. Run `pnpm drizzle-kit generate` to create migration files
2. Review the generated SQL in drizzle/migrations/
3. Test against a local Postgres instance: `pnpm db:migrate:dev`
4. Never hand-edit generated migration files

## Naming conventions
- Migrations are auto-named by Drizzle based on schema diff
- Add descriptive comments to complex migrations

## Rollback
- All migrations must have a corresponding down migration
- Test rollbacks in local environment before deploying

Invoke with: /db-migrations or reference by name in a prompt.

Codex has a built-in skills system accessible via the /skill command in interactive sessions. Skills are pre-defined workflows that Codex recognizes.

For custom project-specific skills, use additional AGENTS.md files in subdirectories — each subdirectory’s AGENTS.md is loaded only when the agent is working in that area, acting as on-demand context.

src/
  payments/
    AGENTS.md   ← loaded only when working in src/payments/
  auth/
    AGENTS.md   ← loaded only when working in src/auth/

## Payment processing conventions
- All payment operations must be idempotent (use idempotency keys)
- Log every state transition to payment_audit_log table
- Never store raw card numbers — use Stripe payment method IDs

@FILENAME includes: Prefix any file path with @ in your prompt to inject its contents as context.

# Load a conventions file for this specific task
gemini "@docs/api-conventions.md Design the new webhook endpoint"

For structured skills, create markdown files and include them on demand:

gemini "@.ai/skills/deployment.md How do I deploy the staging environment?"

This is a manual inclusion model — the developer decides which skills to load per task.

Aider uses the --read flag to include read-only context files that act as skills:

# Load API conventions for this session
aider --read .ai/skills/api-conventions.md src/routes/webhooks.ts

# Load multiple skill files
aider --read .ai/skills/api-conventions.md \
      --read .ai/skills/db-migrations.md \
      src/repos/payments.ts

Add frequently used skills to .aider.conf.yml under the read: key to auto-load them. Unlike Claude Code, Aider has no automatic relevance detection — skill selection is always manual.

.cursor/rules/*.mdc with glob patterns — this is Cursor’s native skill mechanism.

---
description: Payment processing domain knowledge
globs: ["src/payments/**", "src/routes/payment*"]
alwaysApply: false
---

## Payment processing rules
- All operations must be idempotent — use idempotency keys
- Log all state transitions to payment_audit_log
- Never store raw card numbers — use Stripe payment method IDs
- Retry logic must use exponential backoff with jitter

When alwaysApply: false, this rule attaches automatically whenever the agent edits a file matching the glob pattern. Effectively, the agent gets domain knowledge only when working in the payments area.

Windsurf stores reusable workflows in .windsurf/workflows/. These are markdown files that describe multi-step procedures the Cascade agent can follow.

# Add a New API Endpoint

Follow these steps to add a new endpoint:

1. Create the route handler in src/routes/<resource>.ts
2. Add the service method in src/services/<resource>Service.ts
3. Add the repository method in src/repos/<resource>Repo.ts
4. Write integration tests in tests/integration/<resource>.test.ts
5. Run `pnpm test` and `pnpm tsc --noEmit` to verify

Reference workflows in prompts: “Follow the add-endpoint workflow for the new /v1/subscriptions endpoint.”

Copilot’s skill support is limited. The primary mechanism is multiple instruction files in different contexts:

.github/copilot-instructions.md — repository-wide (always loaded)
Per-file comments and docstrings — file-scoped context loaded with the file

For task-specific context, paste the relevant conventions directly into your prompt. Copilot does not have an automatic skill/on-demand context mechanism equivalent to other tools.

3. Custom Agents / Sub-Agents

Sub-agents are specialized AI instances that run in their own context window with their own tool permissions. The key benefit is context isolation: research or review work does not pollute the main agent’s conversation history. See Sub-Agent Context Isolation for the architecture rationale.

Location: .claude/agents/<name>.md

Claude Code sub-agents are defined as markdown files with YAML frontmatter. The orchestrating agent spawns them via the Task tool; they run in isolated context and return a result.

---
name: security-reviewer
description: Reviews code changes for security vulnerabilities and returns a structured report
tools: Read, Grep, Glob, Bash
model: claude-sonnet-4-5
---

You are a senior security engineer. Review the specified code for:

## Checklist
- [ ] Injection vulnerabilities (SQL, XSS, command injection)
- [ ] Authentication and authorization flaws
- [ ] Secrets or credentials hardcoded in source
- [ ] Insecure data handling (PII exposure, missing encryption)
- [ ] CSRF protection on state-changing endpoints

## Output Format
For each finding: Severity (Critical/High/Medium/Low), file:line, description, suggested fix.

The main agent invokes this with: “Use the security-reviewer agent to review the changes in src/payments/.”

Codex supports multi-agent workflows via the Agent SDK and MCP (Model Context Protocol) server mode.

Agent SDK: Build orchestration logic in code using the OpenAI Agents Python/TypeScript SDK. Define specialized agents programmatically and hand off tasks between them.

MCP server mode: Run Codex as an MCP server, allowing it to be orchestrated by other agents (including Claude Code) as a tool.

# Python example using the OpenAI Agents SDK
from agents import Agent, Runner

security_reviewer = Agent(
    name="security-reviewer",
    instructions="Review code for security vulnerabilities. "
                 "Check for injection, auth flaws, and data exposure.",
    model="gpt-4o",
)

result = await Runner.run(
    security_reviewer,
    "Review the changes in src/payments/checkout.py"
)

Interactive Codex does not support custom declarative agent files — multi-agent patterns require the SDK or MCP integration.

Gemini CLI extends via Extensions and MCP tools, which act as specialized capability providers rather than full sub-agents.

# Enable an MCP server as a tool provider
gemini --mcp-server path/to/mcp-server

# Extensions provide domain-specific tools
# configured in ~/.gemini/settings.json

For true sub-agent patterns (isolated context, parallel execution), use the Gemini API directly or orchestrate multiple Gemini CLI sessions via shell scripts. The interactive CLI is primarily a single-agent interface.

Cursor has a built-in Agent mode that allows the AI to use tools (file reads, terminal commands, web search) autonomously. However, Cursor does not support custom declarative agent definitions — you cannot define a “security-reviewer agent” as a file.

The workaround is to start a new Cursor chat with a specialized system prompt or use .cursor/rules/*.mdc files scoped to the review task. For true multi-agent patterns, orchestrate multiple Cursor sessions or pair Cursor with Claude Code/Codex for orchestration.

Windsurf’s Cascade is a built-in agentic system with access to tools (file edits, terminal, web). Like Cursor, Windsurf does not support custom agent definition files — Cascade is the single built-in agent.

For specialized workflows, use .windsurf/workflows/ files that give Cascade specific instructions for a task, effectively constraining its behavior to act like a specialized agent.

opencode supports custom named agents defined in opencode.json. Each agent has its own system prompt, model selection, and tool configuration.

{
  "agents": {
    "reviewer": {
      "model": "claude-sonnet-4-5",
      "system": "You are a senior code reviewer. Focus on logic errors, security issues, and consistency with existing patterns. Provide specific file:line references and suggest fixes."
    },
    "architect": {
      "model": "claude-opus-4-5",
      "system": "You are a software architect. Evaluate designs for scalability, maintainability, and alignment with system constraints. Do not write code — produce analysis and recommendations only."
    }
  }
}

Switch between agents in the opencode session by specifying the agent name.

Aider is a single-agent tool — it does not support custom sub-agents or multi-agent orchestration natively.

For multi-agent patterns, use Aider alongside an orchestrating tool:

Run multiple Aider sessions in separate terminal windows (manual parallelism)
Use Claude Code or Codex as the orchestrator and call Aider as a subprocess via Bash tool
Use git worktrees to give each Aider session an isolated working copy

Aider’s strength is focused, precise edits to specific files — lean into that rather than trying to replicate multi-agent patterns.

4. Context Management Commands

How each tool handles the most common context management operations:

Action	Claude Code	OpenAI Codex	Gemini CLI	Aider	Cursor	Windsurf
Clear context	`/clear`	Start new session	`/clear`	`/clear`	New chat	New chat
Compact context	`/compact`	Automatic	Automatic	N/A	Automatic	Automatic
Plan / read-only mode	`Ctrl+G` or say “plan mode”	`--approval-mode plan`	N/A (use prompting)	`/architect`	Agent mode toggle	Cascade (always agentic)
Named sessions	`--session <name>`	Tab management in UI	Session tabs	N/A	Chat history panel	Chat history panel
Show token usage	Shown in UI	Shown in UI	`--debug` flag	Shown in UI	Shown in UI	Shown in UI
Abort current action	`Escape`	`Ctrl+C`	`Ctrl+C`	`Ctrl+C`	`Escape`	`Escape`

Plan Mode Details

Plan mode (read-only / no-edit mode) is one of the highest-leverage context management techniques in this guide. It prevents the agent from making premature edits and forces research and planning to happen in a separate phase.

Toggle plan mode with Ctrl+G or by saying “enter plan mode” / “let’s plan this without making changes.” In plan mode, Claude Code can read files and reason but will not edit them.

The three-phase workflow (Research → Plan → Implement) uses plan mode explicitly between phases. See The Three-Phase Workflow.

Start with --approval-mode plan to enter a mode where Codex explains what it would do without executing:

codex --approval-mode plan "Add rate limiting to the auth endpoints"

Codex will produce a step-by-step plan for your review. Approve individual steps or switch to full execution mode to implement.

Gemini CLI does not have a dedicated plan mode flag. Achieve the same effect with prompting:

Do NOT make any file changes. Research how authentication works in this
codebase and produce a numbered implementation plan. Stop after the plan.

/architect mode uses a stronger model to reason and plan, then passes specific edit instructions to a smaller “editor” model. This separates thinking from execution:

# Start in architect mode
aider --architect

# Or switch during a session
/architect Add rate limiting to the auth endpoints

Cursor Agent mode is always potentially agentic. For plan-only behavior, use prompting:

Do not make any changes. Analyze the current auth system and write
a numbered plan for adding rate limiting. Stop after the plan.

Review the plan in chat, then ask Cursor to implement it in a follow-up message.

Like Cursor, Windsurf Cascade is always agentic. Use explicit prompting to get plan-only output:

Research only — do not edit any files. Describe how you would
implement rate limiting on the auth endpoints, step by step.

5. CLI Quick Reference

Common operations across tools for headless / scripted / session usage:

Start a Session

# Interactive session
claude

# Named session (resumable)
claude --session my-feature

# Start with an initial prompt
claude "Research how the payment flow works"

# Non-interactive / pipe a prompt
echo "List all TODO comments in src/" | claude --print

# Interactive session
codex

# Non-interactive with a prompt
codex "Add input validation to the registration endpoint"

# Plan-only mode
codex --approval-mode plan "Refactor the auth module"

# Full auto (no approval prompts)
codex --approval-mode full-auto "Fix the failing tests"

# Interactive session
gemini

# Non-interactive with a prompt
gemini "Explain the payment flow in this codebase"

# Include file context
gemini "@src/payments/checkout.ts Explain this file"

# Pipe input
echo "What does this error mean?" | gemini

# Start session with specific files
aider src/payments.ts src/routes/checkout.ts

# With read-only context
aider --read CONVENTIONS.md src/payments.ts

# Auto-commit mode (commits after each change)
aider --auto-commits src/payments.ts

# Non-interactive / message mode
aider --message "Add error handling to processPayment" src/payments.ts

Cursor is a GUI application — it does not have a CLI for starting sessions. Use the keyboard shortcut Cmd+L (macOS) / Ctrl+L (Windows/Linux) to open the AI chat panel.

For scripted or headless workflows, use Claude Code, Codex, or Aider instead.

Specify a Model

# Use a specific model
claude --model claude-opus-4-5

# Or set in environment
export ANTHROPIC_MODEL=claude-opus-4-5
claude

In agent definition files, set model: in the YAML frontmatter to assign a model per sub-agent — use a more capable model for complex reasoning, a lighter model for read-only review tasks.

# Specify model via flag
codex --model gpt-4o "Implement the webhook handler"

# Or set via environment variable
export OPENAI_MODEL=gpt-4o
codex

# Specify model
gemini --model gemini-2.0-flash "Quick question about this file"

gemini --model gemini-2.5-pro "Complex refactoring task"

# Specify model
aider --model gpt-4o src/payments.ts

# Use Claude via Anthropic
aider --model claude-opus-4-5 src/payments.ts

# Set default in .aider.conf.yml
# model: claude-opus-4-5

Run Non-Interactive / Headless

Headless mode is useful for CI pipelines, automated review tasks, or chaining agents in shell scripts.

# Print mode — outputs result to stdout, no interactive loop
claude --print "Review src/payments.ts for security issues"

# Pipe output to a file
claude --print "Generate a test plan for the checkout flow" > test-plan.md

# In CI — combine with --no-interactive
claude --print --no-interactive "Run the linter and fix any errors"

# Full-auto mode — no approval prompts, runs to completion
codex --approval-mode full-auto "Fix all TypeScript errors"

# Quiet mode — suppress progress output
codex --quiet "Add JSDoc comments to src/payments.ts"

# Non-interactive with a prompt (exits after response)
gemini "Summarize the architecture of this project"

# Pipe to file
gemini "Generate a README for this project" > README.md

# Message mode — runs one instruction and exits
aider --message "Add error handling to processPayment" \
      --yes \
      src/payments.ts

# --yes auto-approves all confirmations
# Useful in CI, but use with caution