Team Collaboration and Shared Configuration

Your team of eight developers each has their own Codex configuration. One uses approval_policy = "never" with full access. Another has strict read-only mode. A third has five MCP servers configured that nobody else uses. When they share prompts or workflows, they get wildly different results. Team configuration solves this by establishing a shared baseline while preserving individual flexibility.

What You’ll Walk Away With

• A Team Config deployment strategy using shared config.toml, rules, and skills
• AGENTS.md conventions that work for teams of 5-50 developers
• Collaborative patterns for sharing prompts, skills, and review workflows
• Onboarding templates that get new team members productive with Codex in a day

Team Config

Codex reads configuration from multiple layers. Team Config lives alongside your code and provides shared defaults:

Type	Path	Purpose
Config	.codex/config.toml	Sandbox mode, model, 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

Commit .codex/config.toml to your repository:

# .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 team baseline.

Prompt: Generate a team config

“Analyze this repository’s structure and create a .codex/config.toml that: sets workspace-write sandbox mode, configures the Linear MCP server, enables shell_snapshot for faster commands, and sets the review model to gpt-5.3-codex. Also create a rules file that allows npm, pnpm, git, and make commands but prompts for anything else.”

Shared AGENTS.md Conventions

For teams, structure your AGENTS.md hierarchy:

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 AGENTS.md

# 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 AGENTS.md

packages/api/AGENTS.md

## 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

Create team-wide skills in .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.

Onboarding New Team Members

Create an onboarding checklist:

1. Install the Codex App and CLI
2. Run codex login to authenticate with your team’s ChatGPT workspace
3. Clone the repository (which includes .codex/config.toml and AGENTS.md)
4. Install recommended MCP servers: codex mcp add linear --url https://mcp.linear.app/mcp
5. Run a test task: codex "Summarize the current instructions and list available skills"
6. Review the team prompt library for common workflows

Prompt: Onboarding verification

“Verify my Codex setup: check that AGENTS.md is loaded correctly, list all configured MCP servers, verify the sandbox mode is workspace-write, and run pnpm test to confirm the development environment works. Report any issues.”

Collaborative Patterns

Prompt Libraries

Maintain a collection of proven prompts in your 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

Reference them in GitHub Actions or share them in team documentation.

Skill Sharing

Skills checked into .agents/skills/ are available to everyone on the team. For personal skills, use ~/.agents/skills/. For organization-wide skills, deploy to /etc/codex/skills/ via your configuration management.

When This Breaks

• Team config conflicts with personal config: Personal config takes precedence. If a developer’s personal settings override team settings inappropriately, discuss standardization.
• AGENTS.md too large: The combined size of all AGENTS.md files is capped at 32KB by default. 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.
• Skills not appearing: Skills must be in .agents/skills/ directories. Codex scans from the current directory up to the repository root. Restart Codex if a newly added skill does not appear.

What’s Next

• Prompt Engineering — Write prompts that work across your team
• Review Strategies — Standardize review practices
• Enterprise Governance — Scale team config to the organization