Skip to content

AI_SETUP.md

Latest commit

 

History

History
486 lines (359 loc) · 23.5 KB

AI_SETUP.md

File metadata and controls

486 lines (359 loc) · 23.5 KB
title AI Agent Setup Guide
description Configure Claude, Gemini, Copilot, and Codex for this project
audience
contributors
ai-agents
tags
ai
setup
configuration

AI Agent Setup Guide

This template is designed primarily for Claude Code, which is the only agent that ships the full slash-command workflow and acts as the orchestrator in single-agent and dual-agent flows. Gemini CLI is supported in a narrower role (second-opinion planner/reviewer inside Claude-orchestrated commands). GitHub Copilot CLI is supported as a standalone alternative that auto-discovers the full slash-command workflow from .claude/commands/. Codex CLI is supported as a standalone alternative without slash commands. See the comparison table below for the per-agent breakdown.

New here? Start with the First 5 Minutes walkthrough for a narrative tour of the AI agent workflow. This page is the configuration reference.

Supported AI Agents

Agent comparison

Agent Permission model Hooks support Slash commands LSP Dual-agent role
Codex CLI TOML approval policies (.codex/config.toml) plus repo skills (.agents/skills/) Project-level tools/hooks/ai/ apply via Codex hooks Built-in only; repo workflow uses skills Not documented Standalone alternative (not part of dual-agent flow)
Gemini CLI JSON allowlists + lifecycle hooks (.gemini/settings.json) Project-level hooks apply; Gemini lifecycle hooks supported 5 (/ghissue-plan, /ghissue-implement, /ghissue-finalize standalone; /ghissue-plan-stdout, /ghissue-review-pr orchestration-only) Not documented Standalone alternative; second-opinion reviewer / planner in dual-agent flow
GitHub Copilot CLI JSON hook config (.github/hooks/copilot-hooks.json) Project-level hooks apply; Copilot preToolUse hook wired Auto-discovers from .claude/commands/ Not documented Standalone alternative (auto-discovers Claude commands)
Claude Code Layered permissions (.claude/settings.local.json + .claude/settings.json PreToolUse hooks) Project-level hooks plus Claude PreToolUse hooks 8 (ghissue-plan, ghissue-implement, ghissue-finalize, ghissue-close, ghissue-plan-both, ghissue-review-both, ghissue-gemini-review, ghissue-status) Supported Primary orchestrator in single-agent and dual-agent flows

The project-level dangerous-command hooks under tools/hooks/ai/ apply to all four agents regardless of per-agent config and cannot be bypassed by editing .claude/settings.local.json, .codex/config.toml, .gemini/settings.json, or .github/hooks/copilot-hooks.json. See AI Enforcement Principles and Command Blocking.

1. Codex CLI (OpenAI)

Configuration: .codex/config.toml

Note: Project-level dangerous-command hooks under tools/hooks/ai/ apply to this agent regardless of the per-agent config below. See AI Enforcement Principles and Command Blocking.

Codex CLI directly reads AGENTS.md from the project root. The configuration file whitelists common development commands.

Whitelisted commands:

  • git - All git operations
  • gh - GitHub CLI
  • uv - UV package manager
  • doit - Task automation
  • File operations: ls, cat, tree, find, grep, wc, mkdir

Setup:

# Codex CLI will automatically use .codex/config.toml if present
# Or copy to global config:
cp .codex/config.toml ~/.codex/config.toml

# Initialize or regenerate AGENTS.md with Codex:
codex
/init

Documentation:

Codex parity status: Codex does not use repo-defined slash commands in this template. Instead, it uses repo-scoped workflow skills checked into .agents/skills/ and invoked through Codex's built-in skill surface such as /skills or explicit mentions like $ghissue-plan, $ghissue-implement, and $ghissue-finalize. LSP integration is not documented for Codex here. Codex is not part of the dual-agent workflow (Claude and Gemini are); it works as a standalone alternative for contributors who prefer the OpenAI CLI. The shared dangerous-command hook at tools/hooks/ai/block-dangerous-commands.py applies to Codex via .codex/config.toml, and the approval-policy rules remain a secondary defense layer. For the broader workflow picture, see Slash Commands and Workflows.

2. Gemini CLI (Google)

Configuration: .gemini/settings.json

Note: Project-level dangerous-command hooks under tools/hooks/ai/ apply to this agent regardless of the per-agent config below. See AI Enforcement Principles and Command Blocking.

Gemini CLI can read AGENTS.md (or GEMINI.md) from the project root. The configuration file uses allowlists for tools and shell commands, and configures lifecycle hooks.

Allowlisted commands:

  • git, gh, uv, doit - Development tools
  • python, pytest, ruff, mypy - Python tools
  • File operations: ls, cat, tree, find, grep, wc, mkdir

Core tools enabled:

  • ShellTool - Execute shell commands
  • ReadFileTool, WriteFileTool - File operations
  • LSTool, GrepTool - File exploration

Token Efficiency

.gemini/settings.json ships with a compression default aimed at token efficiency in long sessions, mirroring the Claude tuning:

Setting Value Effect Rationale
chatCompression.contextPercentageThreshold 0.5 Compression triggers at 50% of context window usage. Reclaims token space earlier to avoid hitting hard context limits in long sessions.

Setup:

# Gemini CLI automatically uses .gemini/settings.json if present
# Or copy to global config:
cp .gemini/settings.json ~/.gemini/settings.json

# Ensure hooks are enabled in settings.json:
# {
#   "hooks": { "enabled" : true }
# }

# Use YOLO mode to skip all permission prompts (use with caution):
gemini --yolo
# Or toggle auto-approve with Ctrl+Y during a session

Documentation:

3. Claude Code (Anthropic)

Configuration: .claude/ directory

Note: Project-level dangerous-command hooks under tools/hooks/ai/ apply to this agent regardless of the per-agent config below. See AI Enforcement Principles and Command Blocking.

Claude Code uses a reference file (.claude/claude.md) that imports AGENTS.md.

Whitelisted commands:

  • git:* - All git commands
  • gh:* - All GitHub CLI commands
  • uv:* - All uv commands
  • doit:* - All doit commands
  • File operations: ls, cat, tree, find, grep, wc, mkdir

Setup:

# Claude Code automatically detects .claude/ directory
# No additional setup needed

Files:

  • .claude/claude.md - Imports AGENTS.md
  • .claude/settings.local.json - Command permissions
  • .claude/settings.json - Status line and PreToolUse hooks

LSP Support (Recommended):

Claude Code supports Language Server Protocol for enhanced code intelligence:

  • Document symbols (functions, classes, variables)
  • Go to definition / find references
  • Hover information and type checking
  • Call hierarchy navigation

Quick LSP Setup:

# 1. Install the LSP plugin from marketplace
/install-plugin @anthropic-ai/claude-code-lsp

# 2. Install development dependencies (includes language server)
doit install_dev

# 3. Enable LSP tool in .envrc.local
echo 'export ENABLE_LSP_TOOL=1' >> .envrc.local
direnv allow

# 4. Start Claude Code
claude

For complete setup instructions and troubleshooting, see .claude/lsp-setup.md in the repository root.

Environment Variables

.claude/settings.json ships an env block with three Claude Code defaults aimed at token efficiency and session survival on long-running work. These propagate to downstream consumers via the template-sync mechanism, so all projects derived from this template inherit the same defaults.

Var Value Effect Risk
ENABLE_PROMPT_CACHING_1H 1 Extends prompt cache TTL from 5 minutes to 1 hour. Cuts cost on repeated reads of the same context within a session. None — pure efficiency flag.
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 50 Auto-compaction triggers at 50% of the context window instead of the default (~92%). Sessions compact earlier, leaving more headroom for the post-compact continuation. More frequent compaction churn; mitigated by the PreCompact handoff hook which preserves context across compaction events.
CLAUDE_CODE_SUBAGENT_MODEL claude-sonnet-4-6 Subagents (e.g. those spawned by /ghissue-implement) default to Sonnet 4.6 instead of inheriting the parent's Opus model. Subagent output quality drops below Opus on hard reasoning tasks. Mitigate per-agent (see below).

Per-agent model overrides:

CLAUDE_CODE_SUBAGENT_MODEL is a default. Any agent file under .claude/agents/ that declares an explicit model: in its YAML frontmatter wins:

---
name: high-stakes-reviewer
model: claude-opus-4-7   # overrides the env-var default for this agent only
---

Agents without a model: line inherit the env-var default. This template's .claude/agents/implement-worker.md deliberately does not override — implement-worker runs on Sonnet 4.6 as an explicit cost/quality trade-off. Future high-stakes subagents (e.g. design review, security review) can opt into Opus on a per-file basis.

Per-developer overrides:

To opt out or tune values for your local environment, override them in .claude/settings.local.json (already gitignored, used elsewhere in this template for personal config). Example:

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75"
  }
}

Cross-references:

  • The 50% autocompact threshold is paired with the PreCompact handoff hook — earlier compaction has lower cost because the hook preserves context across compaction events automatically.
  • For operators who need more aggressive token reduction, see AI Agent Token-Efficiency Add-Ons — a catalogue of opt-in external tools (RTK, Headroom, Caveman) with tipping-point guidance and trust caveats.

4. GitHub Copilot CLI

Configuration: .copilot/ directory

Note: Project-level dangerous-command hooks under tools/hooks/ai/ apply to this agent regardless of the per-agent config below. See AI Enforcement Principles and Command Blocking.

GitHub Copilot CLI reads AGENTS.md directly and auto-discovers project skills from .claude/commands/, so the full slash-command workflow (/ghissue-plan, /ghissue-implement, /ghissue-finalize, /ghissue-close, /ghissue-status, etc.) is available in Copilot sessions without any parallel command files. It also natively discovers per-stack instruction files from .github/instructions/*.instructions.md; see .github/instructions/README.md for the scaffold and format. The implement-worker subagent used by /ghissue-implement is shared with Claude (defined in .claude/agents/implement-worker.md).

Hook wiring:

The dangerous-command hook is wired in .github/hooks/copilot-hooks.json:

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "python3 ../../tools/hooks/ai/block-dangerous-commands.py",
        "cwd": ".github/hooks",
        "timeoutSec": 10
      }
    ]
  }
}

Setup:

# Copilot CLI automatically picks up .github/hooks/copilot-hooks.json
# and reads AGENTS.md; no additional setup needed.
copilot

Files:

  • .copilot/README.md - Description of the Copilot CLI config directory
  • .github/hooks/copilot-hooks.json - preToolUse hook wiring
  • .github/instructions/*.instructions.md - Copilot-native per-stack instruction files (auto-discovered)
  • .github/instructions/README.md - Instruction-file scaffold and format reference
  • .claude/commands/*.md - Slash commands (auto-discovered by Copilot CLI)
  • .claude/agents/implement-worker.md - Shared subagent definition

Documentation:

Copilot parity status: Copilot CLI ships no parallel command or agent files — it auto-discovers from .claude/commands/ and .claude/agents/, so every Claude slash command works unchanged in Copilot sessions. Copilot is not part of the dual-agent workflow (Claude and Gemini are); it works as a standalone alternative for contributors who prefer GitHub Copilot. The project-level hooks under tools/hooks/ai/ apply to Copilot via .github/hooks/copilot-hooks.json — see Command Blocking. For the broader slash-command picture, see Slash Commands and Workflows.

5. Other AI Tools

The AGENTS.md file serves as general-purpose documentation for any AI coding assistant:

  • Cursor: Reference in .cursorrules
  • Codeium: Reference in project settings
  • Tabnine: Reference in configuration

Note: For the slash commands and dual-agent workflow this template ships with, see Slash Commands and Workflows.

AGENTS.md - Universal Context File

The AGENTS.md file provides comprehensive project context including:

  • Repository structure and architecture
  • Development workflows and commands
  • Code style and conventions
  • Testing expectations
  • CI/CD workflows
  • Troubleshooting guides

This file is:

  • Read directly by Codex CLI, Gemini CLI, and GitHub Copilot CLI
  • Imported by Claude Code via .claude/claude.md
  • Referenceable by other AI tools

Context files and precedence

This template ships several files that influence agent behavior. They fall into two categories: context/instruction files (markdown) and settings/config files (JSON or TOML). Knowing which is which — and which one wins on conflict — matters when adapting the template for a new project.

File inventory:

  • AGENTS.md (project root, ~20 KB) — universal source of truth for architecture, workflow, tooling hierarchy, and security rules. Read directly by Codex CLI, Gemini CLI, and GitHub Copilot CLI; imported by Claude Code via @../AGENTS.md in .claude/CLAUDE.md.
  • .claude/CLAUDE.md (~2 KB) — Claude-specific complement. First line is @../AGENTS.md, which imports the universal rules; the rest adds Claude-specific layers (token-efficiency guidance, the mandatory TodoWrite plan-test-code loop, the development workflow reminder, and the commit workflow reminder).
  • GEMINI.md (project root, ~1 KB) — Gemini-specific complement. Covers Gemini's stdout-only collaboration mode (so Claude handles GitHub writes), the output signing footer, and Gemini's tool-usage rules. Read alongside AGENTS.md by Gemini CLI, not instead of it.
  • .copilot/README.md — describes the Copilot CLI config directory. Copilot CLI reads AGENTS.md directly, auto-discovers slash commands from .claude/commands/, and uses .github/instructions/*.instructions.md for Copilot-native per-stack instruction files.
  • .codex/config.toml — Codex approval policy file (TOML). Not a context file; configures permissions only. Codex reads AGENTS.md directly for instructions.
  • .claude/settings.json — Claude PreToolUse hooks and statusline configuration. Committed.
  • .claude/settings.local.json — local Claude permissions overlay. Not committed.
  • .gemini/settings.json — Gemini tool allowlists and lifecycle hook configuration.
  • .github/hooks/copilot-hooks.json — Copilot CLI preToolUse hook wiring that routes shell commands through tools/hooks/ai/block-dangerous-commands.py.

Precedence rules:

  • All four agents treat AGENTS.md as the architectural and workflow source of truth.
  • Agent-specific markdown files (.claude/CLAUDE.md, GEMINI.md) complement AGENTS.md — they cover behaviors specific to that agent's interaction model and do not override the universal rules.
  • Settings/config files (.codex/config.toml, .gemini/settings.json, .claude/settings*.json, .github/hooks/copilot-hooks.json) configure permissions and tooling, not workflow rules. They cannot grant an agent permission to do something AGENTS.md forbids.
  • Project-level hooks under tools/hooks/ai/ apply to all agents and cannot be bypassed by per-agent config. This is the strongest layer.

Conflict resolution: if an agent-specific file conflicts with AGENTS.md, AGENTS.md wins for cross-cutting concerns (workflow, architecture, security). An agent-specific file may further restrict its own agent's behavior, but it should not loosen a universal rule.

Customization

For Your Project

When using this template for a new project:

  1. Update AGENTS.md: Customize project-specific details
  2. Adjust permissions: Modify .codex/config.toml and .claude/settings.local.json as needed
  3. Add project commands: Include any custom scripts or tools

Adding New Commands

Codex CLI (.codex/config.toml):

approval_policy = "untrusted"

[features]
codex_hooks = true

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = 'python3 "$(git rev-parse --show-toplevel)/tools/hooks/ai/block-dangerous-commands.py"'
timeout = 30
statusMessage = "Checking Bash command"

Use the shared hook script to control dangerous command patterns. The older [[approval_policy]] command-rule examples are not part of the current Codex config schema.

Gemini CLI (.gemini/settings.json):

{
  "tools": {
    "allowed": [
      "run_shell_command(your-command)"
    ]
  }
}

Claude Code (.claude/settings.local.json):

{
  "permissions": {
    "allow": [
      "Bash(your-command:*)"
    ]
  }
}

GitHub Copilot CLI (.github/hooks/copilot-hooks.json):

Copilot CLI does not use a per-command allowlist — the dangerous-command hook blocks unsafe patterns; everything else is allowed. To adjust what is blocked, edit the shared hook at tools/hooks/ai/block-dangerous-commands.py (which applies to Claude, Gemini, and Copilot alike). New slash commands added under .claude/commands/<name>.md are automatically discovered by Copilot CLI — no additional configuration is needed.

Security Considerations

All configuration files are set up with security in mind.

Note: This template enforces security rules in code and settings, not just instructions. See AI Enforcement Principles for details.

Note: For the architectural rules AI agents must follow when generating code, see Architectural Conventions.

Whitelisted Operations:

  • Read-only file operations
  • Safe git operations (status, diff, log, add, commit, push, pull)
  • Package management (uv)
  • Testing and linting (pytest, ruff, mypy)
  • Task automation (doit)

Protected Information:

  • API keys and tokens are excluded from environment variables
  • No dangerous operations (rm -rf, format, etc.) are pre-approved
  • Network operations require approval in some modes

Troubleshooting

Codex CLI

Commands still prompt for approval:

# Check current config
cat ~/.codex/config.toml

# Copy project config to global
cp .codex/config.toml ~/.codex/config.toml

# Or use project-specific config
codex --config .codex/config.toml

Regenerate AGENTS.md:

codex
/init

Claude Code

Permissions not working:

  • Ensure .claude/settings.local.json exists
  • Check file is valid JSON
  • Restart Claude Code

Context not loading:

  • Verify .claude/claude.md contains @AGENTS.md
  • Check AGENTS.md exists in project root

Gemini CLI

Commands still prompt for approval:

# Check current config
cat ~/.gemini/settings.json

# Copy project config to global
cp .gemini/settings.json ~/.gemini/settings.json

# Or use YOLO mode (auto-approve all)
gemini --yolo

# Or toggle auto-approve during session
# Press Ctrl+Y

Context not loading:

  • Ensure AGENTS.md or GEMINI.md exists in project root
  • Check .gemini/settings.json has "context": {"files": ["AGENTS.md"]}
  • Verify settings.json is valid JSON

Copilot CLI

Hook not firing (dangerous commands going through):

  • Verify .github/hooks/copilot-hooks.json exists and is valid JSON
  • The hook uses a relative bash path (python3 ../../tools/hooks/ai/block-dangerous-commands.py) and a cwd of .github/hooks; both must match your layout
  • Run python3 tools/hooks/ai/test_hook.py to confirm the shared hook script still passes its test suite

Slash commands not appearing:

  • Copilot CLI auto-discovers skills from .claude/commands/ — make sure that directory exists and contains .md files with the CLI file format (no YAML frontmatter; leading # Title and ## Instructions sections)
  • Restart the Copilot CLI session after adding new command files

.copilot/ auto-detection:

  • The .copilot/ directory exists primarily to document Copilot-specific wiring; Copilot CLI does not require any config files there
  • Copilot CLI also auto-discovers .github/instructions/*.instructions.md without any import or directive
  • If you move the repository, Copilot CLI still loads AGENTS.md from the repo root, the hook from .github/hooks/copilot-hooks.json, and instruction files from .github/instructions/

Resources

Codex CLI

Gemini CLI

Claude Code

GitHub Copilot CLI

General AI Coding

Note: The .codex/, .gemini/, .claude/, and .copilot/ directories should be committed to version control to share consistent AI assistant configuration across the team. .local files should not be committed.