Team and Enterprise Tips

Your team of twelve developers each has a different Codex setup. One developer runs --yolo on everything. Another has approval_policy = "untrusted" and approves every file read individually. A third has five MCP servers configured that nobody else uses, consuming context tokens on every session. When they share prompts or workflows, results are wildly inconsistent. Standardizing Codex configuration across a team is the single highest-leverage improvement you can make for team productivity.

What You’ll Walk Away With

A Team Config deployment strategy with shared config.toml, rules, and skills
Onboarding templates that get new team members productive in a day
Prompt library patterns for sharing proven workflows
Enterprise governance tips for RBAC, requirements.toml, and compliance
Cost management strategies that keep the team’s credit burn predictable

Team Config

Codex reads configuration from multiple layers. Team Config lives alongside your code and provides shared defaults that every team member inherits automatically.

The Three Shared Files

Type	Path	Purpose
Config	`.codex/config.toml`	Model, sandbox, approval policy, MCP servers
Rules	`.codex/rules/`	Which commands Codex can run outside the sandbox
Skills	`.agents/skills/`	Shared skills available to all team members

Commit a Project-Level Config

# .codex/config.toml -- Shared team defaults
model = "gpt-5.3-codex"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"

# Shared MCP servers
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"

# Disable web search for security-sensitive projects
web_search = "disabled"

Individual developers can override these in their personal ~/.codex/config.toml, but the project config establishes the baseline everyone starts from.

Add Shared Rules

Create .codex/rules/team.toml to control which commands the agent can run:

# Allow common development commands
[[prefix_rules]]
pattern = [{ any_of = ["npm", "pnpm", "yarn"] }]
decision = "allow"

[[prefix_rules]]
pattern = [{ token = "git" }]
decision = "allow"

[[prefix_rules]]
pattern = [{ token = "make" }]
decision = "allow"

# Prompt before potentially destructive commands
[[prefix_rules]]
pattern = [{ token = "rm" }]
decision = "prompt"
justification = "Deletion requires review"

Shared AGENTS.md Conventions

Structure for Teams

AGENTS.md                           # Repository-wide conventions
  |-- packages/api/AGENTS.md        # API team conventions
  |-- packages/web/AGENTS.md        # Frontend team conventions
  |-- services/payments/AGENTS.md   # Payments team conventions

What Goes in the Root

The root AGENTS.md should cover conventions that apply across the entire codebase:

# Team Conventions

## Code Style
- Use TypeScript strict mode for all new files
- Follow error handling patterns in src/lib/errors.ts
- All API routes must have OpenAPI annotations

## Workflow
- Run pnpm lint && pnpm test before committing
- New endpoints need integration tests in tests/integration/
- Database changes need a migration file in migrations/

## Review
- Security-sensitive changes require two human reviewers
- Performance changes need benchmark results in the PR description

What Goes in Package-Level Files

Package-level AGENTS.md files should only add rules specific to that package:

## API-Specific Rules
- Use the centralized error handler, never throw raw errors
- Rate limiting must be added to all public endpoints
- Authentication middleware is in src/middleware/auth.ts

Shared Skills

Create Team-Wide Skills

Check skills into .agents/skills/ at the repository root:

---
name: pr-ready
description: Prepare the current changes for a pull request by running
  all checks, fixing issues, and generating a PR description.
---

# PR Readiness Check

1. Run pnpm lint and fix any issues
2. Run pnpm test and fix any failures
3. Run pnpm type-check and fix any errors
4. Generate a PR description with:
   - Summary of changes
   - Testing approach
   - Breaking changes (if any)
5. Report the results

Team members invoke it with $pr-ready in any Codex surface.

Skill Organization

.agents/skills/
  pr-ready/SKILL.md          # PR preparation
  review-security/SKILL.md   # Security-focused review
  migrate-db/SKILL.md        # Database migration helper
  onboard/SKILL.md           # New developer orientation

Personal vs. Team vs. Organization Skills

Personal: ~/.agents/skills/ — Your private productivity shortcuts
Team: .agents/skills/ in the repo — Shared with everyone who clones the repo
Organization: /etc/codex/skills/ — Deployed via configuration management for all machines

Onboarding New Team Members

The Onboarding Checklist

Install the Codex App and CLI (npm install -g @openai/codex)
Run codex login to authenticate with the team’s ChatGPT workspace
Clone the repository (which includes .codex/config.toml and AGENTS.md)
Install recommended MCP servers: codex mcp add linear --url https://mcp.linear.app/mcp
Run a test task: codex "Summarize the current instructions and list available skills"
Review the team’s shared skills with /skills

The Onboarding Skill

Create a skill that guides new team members:

---
name: onboard
description: Guide a new team member through the project setup and conventions.
---

# Onboarding Guide

1. Summarize the repository structure and key directories
2. List all AGENTS.md files and summarize the team conventions
3. List all available skills and explain what each one does
4. Run the test suite and report the results
5. Identify the most recently changed files to show current work areas
6. Suggest the first 3 tasks a new team member should tackle

New developers run $onboard as their first Codex interaction.

Prompt Libraries

Maintain Proven Prompts

Check a collection of battle-tested prompts into the repository:

.github/codex/prompts/
  review.md          # PR review prompt
  fix-ci.md          # CI failure auto-fix
  migration.md       # Database migration template
  security-scan.md   # Security audit prompt
  perf-check.md      # Performance regression check

Developers reference them in conversations or use them as skill instructions.

The CI Fix Prompt Template

The CI pipeline failed on this branch. Here is the error output:
[paste CI output]

Diagnose the failure. If it is a test failure, find the root cause in the
source code and fix it. If it is a linting or type error, fix it. Run the
full test suite after the fix to verify no regressions. Report what you
changed and why.

Enterprise Governance

Requirements.toml for Security

Administrators can enforce security constraints that developers cannot override:

# /etc/codex/requirements.toml (or deployed via MDM)
allowed_approval_policies = ["untrusted", "on-failure"]
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Only allow specific MCP servers
[mcp_servers.linear]
identity = { url = "https://mcp.linear.app/mcp" }

This prevents any developer from running --yolo or enabling danger-full-access sandbox mode.

RBAC with ChatGPT Business/Enterprise

Enterprise workspaces support role-based access control:

Admin: Full configuration access, environment management, analytics
Member: Standard Codex usage within admin-defined constraints
Restricted: Read-only access, limited model usage

Restrict login to a specific workspace:

forced_chatgpt_workspace_id = "your-workspace-uuid"
forced_login_method = "chatgpt"

Governance APIs

Enterprise plans include APIs for monitoring usage:

Analytics API: Track token consumption, task completion rates, and per-user activity
Compliance API: Audit which commands the agent ran, what files it modified, and approval decisions

Use these to build dashboards, detect anomalous usage, and generate compliance reports.

Cost Management

Per-Team Budget Strategies

Strategy	How It Works
Model tiering	Use GPT-5.1-Codex-Mini for simple tasks, GPT-5.3-Codex for complex ones
Profile-based routing	Create `quick` and `deep` profiles with different models
Cloud task limits	Reserve cloud tasks for critical work (approx. 25 credits each)
Context discipline	Keep AGENTS.md concise, disable unused MCP servers

Monitor Usage

# Check remaining credits
codex login status

# Track cloud task costs
codex cloud list --json | jq '.tasks[] | {title, status}'

Credit-Efficient Patterns

Start with mini, escalate to full: Use --profile quick for initial exploration, then switch to --profile review for the final pass
Batch similar changes: Process related files in one session instead of separate sessions
Resume instead of restart: A resumed session avoids re-reading the codebase
Disable web search when not needed: Web search uses credits and adds latency

When This Breaks

Team config conflicts with personal config: Personal config takes precedence. If a developer’s settings override critical team settings, discuss standardization or use requirements.toml to enforce.
AGENTS.md too large: The combined size of all AGENTS.md files is capped at 32 KB. Split guidance into nested files and increase project_doc_max_bytes if needed.
New team member gets different results: Verify they have the same MCP servers configured and that their personal config does not override critical team settings.
Requirements.toml ignored: Ensure the file is in the correct location (/etc/codex/requirements.toml or deployed via your workspace admin). Check file permissions.
Skills not visible to team: Skills must be in .agents/skills/ directories in the repository. Ensure they are committed and pushed.

What’s Next

Setup and Configuration — Individual config that complements team settings
AGENTS.md Optimization — Scale AGENTS.md for team use
Advanced Techniques — Power user features for team leads