Team and Enterprise Tips

Team and enterprise tips cover Team Config deployment through a shared config.toml, rules files, and skills that every member inherits automatically, shared AGENTS.md conventions split between repository-wide and package-level files, onboarding checklists and skills for new hires, prompt libraries for proven workflows, enterprise governance through requirements.toml and RBAC, and cost management strategies like model tiering and profile-based routing. Standardizing configuration across a team is the highest-leverage productivity improvement available.

Your team of twelve developers each has a different Codex setup. One developer runs --yolo on everything. Another uses a restrictive approval policy and manually reviews unfamiliar commands. 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 team-wide Codex standardization gives you

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
# Portable baseline; eligible users can add a separate Sol profile file.
model = "gpt-5.6-terra"
approval_policy = "on-request"
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"

Trusted project config outranks profile and personal config. Developers can still use a one-off CLI flag/-c, while administrators can enforce constraints with requirements.toml.

Add Shared Rules

Rules files are not TOML — they are .rules files written in Starlark (a Python-like config language), placed under .codex/rules/. Create .codex/rules/team.rules to control which commands the agent can run outside the sandbox:

# Allow common package managers (a union of literals at the first position)
prefix_rule(
    pattern = [["npm", "pnpm", "yarn"]],
    decision = "allow",
)

# Allow git and make
prefix_rule(pattern = ["git"], decision = "allow")
prefix_rule(pattern = ["make"], decision = "allow")

# Prompt before potentially destructive commands
prefix_rule(
    pattern = ["rm"],
    decision = "prompt",
    justification = "Deletion requires review",
)

Each rule is a prefix_rule() call. pattern is a list matched against the command’s argument list; a nested list like ["npm", "pnpm", "yarn"] matches any of those alternatives at that position. Decisions are allow, prompt, or forbidden (Codex applies the most restrictive when multiple rules match). Restart Codex after editing rules.

Model choice in a shared config must match every intended user’s entitlement. Free and Go expose Terra; eligible Plus, Pro, Business, and Enterprise users can choose all three GPT-5.6 tiers, and managed-workspace policy can restrict them further.

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

A skill is a directory with a SKILL.md file. Check skills into .agents/skills/ at the repository root — the example below is the contents of .agents/skills/pr-ready/SKILL.md (not a loose markdown file dropped directly in .agents/skills/):

---
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 ChatGPT desktop and the CLI (curl -fsSL https://chatgpt.com/codex/install.sh | sh; use the official PowerShell installer on Windows)
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-request"]
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.6 Terra for simple tasks, GPT-5.6 Sol for complex ones
Profile-based routing	Create `quick` and `deep` profiles with different models
Cloud task limits	Budget from the current token-based rate card and workspace dashboard
Context discipline	Keep AGENTS.md concise, disable unused MCP servers

Monitor Usage

Use the ChatGPT/Codex usage dashboard for the account-specific allowance and credit balance. codex login status verifies authentication; it is not a credit meter. codex cloud list --json can inventory tasks but does not replace billing data.

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: It can add tool calls, context, latency, and exposure to untrusted content

Where team Codex setups break down

Team config conflicts with personal config: Trusted project config takes precedence over profile and personal config. Check CLI overrides and project trust; use requirements.toml for non-bypassable constraints.
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 project trust, model entitlement, external profile selection, MCP availability, and stray CLI overrides.
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.

Where to go next with team Codex setup

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