Skip to content

profiles.md

Latest commit

 

History

History
159 lines (102 loc) · 4.71 KB

profiles.md

File metadata and controls

159 lines (102 loc) · 4.71 KB
Raw

Profiles

Codexkit ships 6 profiles that configure the Codex CLI for different work modes. Each profile sets the model, sandbox level, approval policy, and defaults appropriate for a specific workflow.

Quick Reference

Profile Model Sandbox Approval Use Case
default gpt-5.5 workspace-write on-request Daily driver
explore gpt-5.4-mini read-only never Codebase understanding
plan gpt-5.5 read-only never Architecture & planning
build gpt-5.5 workspace-write on-request Implementation
review gpt-5.5 read-only never Code review & audit
ship gpt-5.5 workspace-write on-request Release & PR prep

Usage

codex --profile <name>

Examples:

# Default — default profile (no flag needed)
codex "fix the login bug"

# Read-only exploration
codex --profile explore "how does the auth system work?"

# Architecture planning with gpt-5.5
codex --profile plan "design the new payments module"

# Implementation with auto-approval on failure
codex --profile build "implement the payments API"

# Code review — read-only, high-reasoning model
codex --profile review "review the last 3 commits"

# Ship — implement, verify, and prepare PR
codex --profile ship "ship the payments feature"

When to Use Each Profile

default

The daily driver. Use when you need a mix of reading and writing with manual approval for commands. Suitable for most tasks where you want oversight.

explore

Read-only mode for understanding code. No writes are permitted, so there's zero risk of unintended changes. Use when onboarding to a codebase, investigating unfamiliar modules, or tracing data flows.

plan

Uses gpt-5.5 with high reasoning for architecture work. Read-only sandbox prevents accidental changes while planning. Use for designing systems, writing RFCs, or creating implementation plans before coding.

build

Implementation mode with on-request approval. Use when you have a clear spec and want focused implementation with user approval on escalations.

review

Read-only with gpt-5.5 and high reasoning for thorough code review. The higher-reasoning model catches subtle issues. Use for formal code reviews, security audits, or pre-merge checks.

ship

Write-enabled with on-request approval. Designed for the full ship cycle: implement, verify, review, and prepare a PR. Use when you're ready to take a feature from code to merge request.

Customizing Profiles

Define profiles in user-level config (~/.codex/config.toml). Project-local .codex/config.toml is for shared repo settings and should not define [profiles.*].

To customize a profile, edit or create:

[profiles.my-custom]
model = "gpt-5.5"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

You can override any profile setting via CLI flags:

# Use explore profile but with a different model
codex --profile explore --model gpt-5.5

Sandbox Levels

  • read-only — Agent can read files but cannot write or execute commands that modify the workspace.
  • workspace-write — Agent can read and write files within the workspace directory.

Approval Policies

  • never — No command approval needed (read-only profiles only).
  • on-request — Agent asks before executing commands.

Optional Tool Profiles (Flywheel Mode)

These optional tools enhance the Flywheel workflow:

UBS (Ultimate Bug Scanner)

Pre-ship static analysis catching 1000+ bug patterns:

# Full scan before shipping
ubs . --format=json --severity=high,critical

# CI mode with exit codes
ubs . --ci

Add to pre-ship workflow for automated quality gates. See UBS Integration.

CASS + CM (Session Memory)

Cross-agent learning from session history:

# Before starting work
cm context "your task" --json

# Search past sessions
cass search "similar problem" --robot --days 30

Optional pilot recommended before full integration. See CASS Integration and CM Integration.

bv (Beads Triage)

Graph-aware task selection for swarms:

# Get optimal next task
bv next --json

# Get N tasks for parallel agents
bv suggest 5 --json

# Show execution waves
bv waves

Essential for multi-agent swarm coordination. See bv Integration.

Asynchronous coordination for 2+ agents:

  • Thread messaging with bead IDs
  • File reservations before editing
  • Structured handoffs

Only needed for multi-agent concurrent execution.