Team Collaboration and Shared Configuration

Team workflows in Codex standardize every developer’s session through three committed files: .codex/config.toml for model, sandbox, and MCP servers, .codex/rules/ for what runs outside the sandbox, and .agents/skills/ for shared skills. AGENTS.md carries the conventions, requirements.toml enforces what individuals cannot override, and profile routing keeps credit burn predictable.

Twelve developers, twelve Codex setups. One runs --yolo on everything. Another uses a restrictive approval policy and reviews every unfamiliar command by hand. A third has five MCP servers configured that nobody else uses, spending context tokens on every session. When they share a prompt, the results are wildly inconsistent, and nobody can tell whether the prompt was bad or the configuration was.

Standardizing configuration across a team is the single highest-leverage improvement available here, and it costs one afternoon. The baseline is shared; individual flexibility survives where it should.

What a shared team setup gives you

A deployment strategy for shared config.toml, rules, and skills, and the precedence order that decides which layer wins
AGENTS.md conventions that work for teams of 5-50 developers
Onboarding templates and a skill that get a new team member productive in a day
Prompt library patterns for sharing proven workflows
Governance controls for RBAC, requirements.toml, and compliance reporting
Cost management strategies that keep the team’s credit burn predictable

The three files a team commits

Codex reads configuration from multiple layers. The simplest way to standardize one repository is to commit the project-scoped layer alongside the code:

Type	Path	Purpose
Config	`.codex/config.toml`	Model, sandbox mode, 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

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"

Keep the baseline model compatible with everyone who will use it. Free and Go expose Terra; eligible Plus, Pro, Business, and Enterprise users can choose Sol, Terra, or Luna, and a managed-workspace admin can narrow that further by role. Treat Sol as an optional profile, never as the universal default in a file everyone inherits.

That version keeps the shared file portable and puts Sol in a separate config a developer opts into. On a team where everyone is entitled to Sol, you can fold the review model into the same file instead:

When you paste either generated file, sanity-check two keys: shell_snapshot lives under the [features] table ([features] then shell_snapshot = true), not as a top-level key, and the /review override is the top-level review_model key.

Which layer wins

The committed project .codex/config.toml outranks profile and personal config, which is what makes it the team baseline. Only CLI flags and -c key=value override it for a single run; a --profile layer sits below project config. If a developer marks the project untrusted, Codex skips the project-scoped .codex/ layers entirely and falls back to profile, personal, system, and built-in defaults — which is the first thing to check when one person’s results do not match everyone else’s. For constraints nobody may bypass, use requirements.toml rather than the project config.

Rules files, and why they are not TOML

Rules are .rules files written in Starlark, a Python-like config language, placed under .codex/rules/. They control which commands the agent may 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, and a nested list such as ["npm", "pnpm", "yarn"] matches any of those alternatives at that position. Decisions are allow, prompt, or forbidden, and when several rules match, Codex applies the most restrictive. Restart Codex after editing rules.

Shared AGENTS.md conventions

Structure the hierarchy so each file only carries what is true at its level:

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

Conventions that apply across the entire codebase:

# Team Conventions

## Code Style
- Use TypeScript strict mode for all new files
- Follow the 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

Only the rules specific to that package — anything repeated from the root is wasted budget against the 32 KB cap:

## 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
- Test utilities are in tests/utils/api-helpers.ts

Shared skills

A team skill anyone can invoke

A skill is a directory containing a SKILL.md. Check them 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 into .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. A useful starting set looks like this:

.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

Where skills live: personal, team, organization

Personal: ~/.agents/skills/ — private productivity shortcuts
Team: .agents/skills/ in the repo — shared with everyone who clones it
Organization: /etc/codex/skills/ — deployed via configuration management to all machines

Onboarding a new team member

The 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 and the prompt library in .github/codex/prompts/

The onboarding skill

Better than a document nobody reads: a skill that walks the new developer through the project on their first Codex interaction.

---
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 before anything else.

Prompt libraries

Check the prompts that have proven themselves into the repository, where they can be reviewed and improved like code:

.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, use them as skill instructions, or wire them into GitHub Actions. The CI fixer is the one most teams reach for first:

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.

Governance that individuals cannot bypass

Project config sets the default; requirements.toml sets the limit. Administrators deploy it to /etc/codex/requirements.toml (or through MDM) to enforce constraints no developer can 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" }

That is what stops anyone running --yolo or enabling danger-full-access. ChatGPT Business and Enterprise workspaces add role-based access control on top — Admin with full configuration, environment management, and analytics; Member with standard usage inside admin-defined constraints; Restricted with read-only access and limited model usage — and login itself can be pinned to one workspace:

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

Enterprise plans also expose two APIs worth wiring into a dashboard: the Analytics API for token consumption, task completion rates, and per-user activity, and the Compliance API for auditing which commands the agent ran, what files it modified, and which approvals were granted.

Cost management

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

For the actual numbers, use the ChatGPT/Codex usage dashboard — that is where the account-specific allowance and credit balance live. codex login status verifies authentication and is not a credit meter, and codex cloud list --json inventories tasks without replacing billing data.

Four habits do most of the saving:

Start small, escalate deliberately. Use --profile quick for initial exploration, then --profile review for the final pass.
Batch similar changes. Related files in one session beat one session per file.
Resume instead of restarting. A resumed session does not re-read the codebase.
Disable web search when it is not needed. It adds tool calls, context, latency, and exposure to untrusted content.

Where team Codex setups break down

Team config conflicts with personal config. The committed project .codex/config.toml takes precedence over profile and personal config, and only CLI flags or -c outrank it. If the project is marked untrusted, the project layers are skipped entirely. Check trust state and one-off CLI overrides first, and move anything that must hold to requirements.toml.
AGENTS.md is too large. The combined size of all AGENTS.md files is capped at 32 KB by default. Split guidance into nested files, cut what the root already says, and raise project_doc_max_bytes only if it is genuinely needed.
A new team member gets different results. Verify project trust, model entitlement, which external profile is selected, MCP availability, and stray CLI overrides — in that order.
requirements.toml appears to be ignored. Confirm it is in the right location (/etc/codex/requirements.toml or deployed by your workspace admin) and check the file permissions.
Skills are not visible to the team. Skills must live in .agents/skills/ directories in the repository, and Codex scans from the current directory up to the repository root. Make sure they are committed and pushed, and restart Codex if a newly added skill does not appear.

Where to go next with team Codex setup

Setup and Configuration — individual config that complements the team settings
AGENTS.md Optimization — scale AGENTS.md for team use
Enterprise Governance — take these controls organization-wide
Review Strategies — standardize review practices on top of the shared config