Build a Local Multi-Agent Codex System on Your MacBook

Build a Local Multi-Agent Codex System on Your MacBook

I have not posted here in about six months.

No dramatic disappearance. No secret monastery. Just the usual combination of customer work, multiple projects, delivery pressure, experiments, and life doing what life does: taking a clean schedule and turning it into a tab explosion.

Also, tracking AI evolution right now is almost impossible.

By the time you finish one “complete guide,” three tools ship, two APIs change, one startup pivots into agents, and someone online announces that everything from last Tuesday is obsolete.

So instead of pretending this is another final answer, I want to share something more useful:

My current playbook for running Codex locally as a structured multi-agent environment.

This is the setup I wish I had before my local machine became a pile of:

• scattered repos
• half-finished prompts
• old config files
• duplicated instructions
• unclear permissions
• project-specific rules living in my head
• local notes I forgot existed
• AI agents with too much freedom and not enough structure

The current challenge is context management.

That is the fact.

Codex can read instructions, use subagents, work with skills, run commands, and operate across local files. But if the context is messy, the work gets messy. If your rules are scattered, Codex will behave inconsistently. If every repo has a different setup, every task becomes rediscovery.

This article shows how to build a cleaner local structure.

What we are building

The goal is not “make Codex smarter.”

The goal is to make Codex more consistent.

You want a setup where Codex knows:

• how you work
• what it can touch
• what it must never touch
• where repo-specific rules live
• when to use subagents
• when to stop and ask
• how to verify its own claims
• how to avoid hallucinating local setup details

OpenAI’s Codex documentation supports this kind of structure through layered AGENTS.md files, permission profiles, rules, skills, and subagents:

• Codex AGENTS.md documentation
• Codex permissions
• Codex rules
• Codex subagents
• Codex skills
• OpenAI hallucination guardrails cookbook

💡 Pro Tip:
Do not start by giving Codex unrestricted access to your whole machine. Start by giving it better structure.

The local Codex architecture

Here is the structure I recommend.

~/
├── .codex/
│   ├── AGENTS.md
│   ├── AGENTS.override.md
│   ├── config.toml
│   ├── rules/
│   │   └── default.rules
│   └── agents/
│       ├── local-discovery.toml
│       ├── repo-inventory.toml
│       ├── config-architect.toml
│       ├── guardrail-reviewer.toml
│       └── implementation-runner.toml
├── .agents/
│   └── skills/
│       ├── hallucination-guardrail/
│       │   └── SKILL.md
│       ├── codex-environment-auditor/
│       │   └── SKILL.md
│       └── repo-cleanup-planner/
│           └── SKILL.md
└── Developer/
    ├── active/
    ├── clients/
    ├── automations/
    ├── experiments/
    ├── learning/
    ├── archive/
    ├── reference/
    └── _inbox/

This gives you five layers:

The point is simple:

Codex should not rediscover your standards every time you open a repo.

Layer 1: Global guidance with ~/.codex/AGENTS.md

Your global AGENTS.md is the base operating agreement.

It should answer:

• How should Codex behave by default?
• What requires approval?
• What files are off-limits?
• How should it handle dependencies?
• What tests should it run?
• How should it summarize changes?

Example:

# Global Codex guidance

## Operating posture

- Treat this machine as a multi-repo automation and development workstation.
- Always identify the active workspace, repo root, branch, package manager, relevant config files, and active instruction files before changing files.
- Prefer direct implementation over abstract advice when the requested change is safe and reversible.
- Use subagents for complex discovery, repo inventory, config design, security review, verification, and multi-repo planning.
- Work in small, reviewable batches.
- Preserve unrelated user changes.
- Keep an audit trail for environment-level changes.

## Approval rules

Proceed without asking for approval for:

- read-only discovery
- creating audit reports
- backing up files before editing
- creating missing Codex/user skill directories
- creating or safely merging global Codex guidance
- creating instruction-only user skills
- drafting repo-level AGENTS.md files into an audit folder
- running harmless verification commands

Ask before:

- deleting files or folders
- moving or renaming repos
- editing project repos in bulk
- editing shell startup files
- modifying secrets or credential files
- installing dependencies
- adding production dependencies
- changing git history
- using :danger-full-access
- enabling broad network access
- changing global machine state

OpenAI’s docs describe global guidance as living in the Codex home directory, which defaults to ~/.codex unless you set CODEX_HOME.

The same docs also describe AGENTS.override.md as a temporary override. That matters.

Use:

~/.codex/AGENTS.md

for stable guidance.

Use:

~/.codex/AGENTS.override.md

only when you need a temporary global override.

⚠️ Warning:
Do not turn AGENTS.override.md into your permanent rules file. It is too easy to forget it exists and wonder why Codex keeps following stale instructions.

Layer 2: Repo-level AGENTS.md

Global guidance is not enough.

A React app, a Python automation repo, and a client-specific workflow project should not share the exact same project rules.

Each active repo should eventually get its own:

<repo>/AGENTS.md

A strong repo-level file should include:

• package manager
• install command
• test command
• lint command
• typecheck command
• build command
• important directories
• files to avoid
• deployment notes
• known project risks

Example:

# AGENTS.md

## Repository overview

- Purpose: Internal workflow automation project.
- Main language/framework: TypeScript and Node.js.
- Main directories:
  - `src/`
  - `scripts/`
  - `docs/`

## Package manager

- Use `pnpm`.
- Do not use npm or yarn unless asked.
- Respect `pnpm-lock.yaml`.

## Commands

- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Build: `pnpm build`

## Codex working rules

- Run `git status --short` before editing.
- Preserve unrelated user changes.
- Ask before adding production dependencies.
- Run relevant tests after changes.
- Report skipped verification and why.

## Files to avoid

Do not modify without explicit approval:

- `.env`
- `.env.*`
- private keys
- generated files
- build outputs
- deployment secrets

This is where Codex starts feeling less like a generic model and more like a teammate who actually knows the project.

Layer 3: Fallback instruction filenames

Some repos already have team instruction files.

Examples:

TEAM_GUIDE.md
.agents.md
CODEX.md

Instead of duplicating everything into AGENTS.md, you can configure fallback filenames so Codex treats those files as instructions.

Example ~/.codex/config.toml:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md", "CODEX.md"]
project_doc_max_bytes = 65536

This tells Codex to check for those files after AGENTS.override.md and AGENTS.md.

✅ Action Step:
Do not add README.md as a fallback by default. Most README files are too broad and will add noise. Use fallback names only for instruction-like files.

Layer 4: Permission profiles

This is where the setup gets serious.

Codex can run local commands. That means permissions matter.

A practical setup uses different profiles for different jobs:

Example intent:

default_permissions = "workspace-edit"

[permissions.audit-readonly]
description = "Read-only local audit profile."
extends = ":read-only"

[permissions.workspace-edit]
description = "Workspace-scoped editing with secrets denied."
extends = ":workspace"

[permissions.workspace-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"**/.env.*" = "deny"
"**/*id_rsa*" = "deny"
"**/*id_ed25519*" = "deny"
"**/*.pem" = "deny"
"**/*.key" = "deny"
"**/.npmrc" = "deny"

[permissions.workspace-edit.network]
enabled = false

The important part is not the exact file.

The important part is the posture:

• default to least privilege
• deny secrets
• write only where needed
• keep network intentional
• never make unrestricted access your default

⚠️ Warning:
Permission profiles are a powerful safety layer, but they should be verified against your installed Codex version. Do not blindly copy config keys into production without testing.

Layer 5: Rules for dangerous commands

Permissions define boundaries.

Rules define approval behavior.

For example, you can make Codex prompt before high-risk commands like:

• rm -rf
• git reset --hard
• git clean -fd
• git push --force
• package installs
• Homebrew changes
• chmod
• chown

Example rule:

prefix_rule(
    pattern = ["git", "reset", "--hard"],
    decision = "prompt",
    justification = "Hard resets can destroy local work.",
    match = [
        "git reset --hard",
        "git reset --hard HEAD",
    ],
)

Another example:

prefix_rule(
    pattern = [["npm", "pnpm", "yarn", "bun"], "install"],
    decision = "prompt",
    justification = "Dependency installs can change lockfiles and supply-chain surface.",
    match = [
        "npm install",
        "pnpm install",
        "yarn install",
        "bun install",
    ],
)

You can test a rules file with:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- git reset --hard

💡 Pro Tip:
Rules are not a replacement for judgment. They are a tripwire. Use them to force a pause before commands that can destroy work, change dependencies, or mutate the machine globally.

Layer 6: Skills for reusable workflows

Skills package repeatable procedures.

Instead of rewriting the same prompt every time, you can create a skill.

A skill directory looks like this:

~/.agents/skills/
└── hallucination-guardrail/
    └── SKILL.md

A skill can include:

• instructions
• references
• optional scripts
• assets
• reusable checklists

For this setup, I recommend three user-level skills.

Example skill frontmatter:

---
name: hallucination-guardrail
description: Use before finalizing any audit, config recommendation, repo cleanup plan, documentation update, implementation summary, or factual claim about files, repos, settings, tests, logs, APIs, command behavior, or external docs. Checks claims against evidence and labels unsupported claims.
---

Then the skill tells Codex to classify claims as:

This idea comes from the same discipline behind hallucination guardrails: define the failure mode, create criteria, test against examples, and improve the guardrail over time.

Layer 7: Subagents for parallel cleanup

Subagents are where this gets useful.

Instead of one long Codex thread trying to inspect everything, split the job.

Use one subagent per workstream:

Trigger prompt:

You are Codex running locally on my MacBook.

Act as my aggressive but safety-aware local environment architect, Codex setup engineer, repo organizer, permissions designer, automation designer, and implementation agent.

This is not a passive audit. I want you to discover, design, implement safe changes, create reusable Codex layers, create skills, create subagent workflows, and prepare repo-level cleanup actions.

My local setup is messy. Codex files, local files, config files, repos, instruction files, package managers, notes, and project folders seem scattered across my Mac. I do not know my current canonical local root folder. Assume things are all over the place and you need to find the truth from the filesystem.

Use subagents aggressively where useful.

Proceed without asking for approval for read-only discovery, audit reports, backups, global Codex guidance, instruction-only user skills, repo-level drafts in an audit folder, and harmless verification commands.

Ask before deleting, moving, renaming, bulk-editing project repos, editing shell startup files, modifying secrets, installing dependencies, changing git history, using :danger-full-access, enabling broad network access, or applying repo changes across many repos.

Spawn one subagent per workstream:
- Discovery Agent
- Repo Inventory Agent
- Config Architect Agent
- Instruction Layer Agent
- Permissions and Rules Agent
- Skills Agent
- Hallucination Guardrail Agent
- Verification Agent

Wait for all subagents, consolidate their results, implement safe global changes, draft repo-level changes, and ask me for batch approval for risky changes.

Start now by creating a timestamped audit folder under ~/codex-setup-audit-YYYYMMDD-HHMM and running read-only discovery.

That prompt does three important things:

1. It gives Codex authority to act.
2. It blocks destructive behavior.
3. It forces structured delegation.

That is the sweet spot.

The first audit folder Codex should create

I like forcing Codex to write its work down.

Start with a timestamped audit folder:

~/codex-setup-audit-YYYYMMDD-HHMM/
├── 00-executive-summary.md
├── 01-current-state.md
├── 02-repo-inventory.csv
├── 03-repo-inventory.md
├── 04-codex-config-findings.md
├── 05-instruction-layers.md
├── 06-permissions-and-rules.md
├── 07-skills-and-guardrails.md
├── 08-target-architecture.md
├── 09-changes-made.md
├── 10-repo-level-drafts/
├── 11-migration-plan.csv
├── 12-migration-plan.md
├── 13-verification.md
├── 14-approval-needed.md
└── backups/

This makes the work inspectable.

It also gives you a rollback trail.

✅ Action Step:
Make Codex create drafts in the audit folder first. Then approve which files should be applied to your real repos.

What Codex should be allowed to do automatically

Here is my aggressive-but-safe default.

Codex can proceed without extra approval for:

• read-only discovery
• creating audit reports
• backing up Codex-related files
• creating ~/.codex
• creating ~/.agents/skills
• creating global ~/.codex/AGENTS.md
• creating instruction-only skills
• drafting repo-level AGENTS.md files into the audit folder
• running harmless verification commands

Codex must ask before:

• deleting anything
• moving repos
• renaming repos
• editing project repos in bulk
• changing shell startup files
• modifying secrets
• installing dependencies
• changing lockfiles
• changing git history
• enabling unrestricted access
• applying repo-level files across many repos

This is not timid.

It is controlled.

Verification commands

After setup, verify it.

Check global instructions:

codex --ask-for-approval never "Summarize the current instructions."

Check active instruction files from a repo root:

codex --ask-for-approval never "Show which instruction files are active."

Check nested overrides:

codex --cd services/payments --ask-for-approval never "Show which instruction files are active."

Check logs if enabled:

codex -c log_dir=./.codex-log

Then inspect:

./.codex-log/codex-tui.log

Check rules:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- rm -rf ./build

Check skills:

codex --ask-for-approval never "List available skills relevant to hallucination guardrails and local environment audits."

⚠️ Warning:
--ask-for-approval never is useful for verification prompts. It is not the mode I recommend for broad cleanup or repo migration.

What I packaged for members

I prepared a full downloadable starter kit for this system.

It includes:

The package is designed to help you build this locally without starting from a blank page.

It does not delete files.

It does not move repos.

It does not install dependencies.

It gives you a structure Codex can operate inside.

Member download

✅ Member Resource:
I prepared the Codex Local Multi-Agent Starter Kit so you can copy the structure, prompts, skills, rules, and templates into your own workflow.

You can get it inside The Architects of Intelligence membership.

The Architects of Intelligence — $19/month

You are not just supporting the future — you are becoming one of the architects of the AI revolution.

This is not just a membership. It is a movement.

Shape the future, master AI, and automate everything.

Membership includes:

• Step-by-Step AI Mastery — guided instructions for setting up chatbots, AI assistants, and workflow automations.
• Early Access to Cutting-Edge Tools — test and implement new AI-driven solutions before they hit the mainstream.
• Private Member-Only Content — strategies, systems, and implementation notes that are not available publicly.
• Direct Access to AI Experts — get support when you get stuck.
• A Network of Visionaries — connect with people building beyond the obvious use cases.

I prepared this starter kit for paid members.

You can join for $19/month, download it, use it, and cancel anytime — including right after the purchase if this is the only resource you need.

Join The Architects of Intelligence and download the starter kit →

Final thought

The future of local AI work is not one giant prompt.

It is structure.

A good local Codex system needs:

• persistent global guidance
• repo-level instructions
• permission boundaries
• command rules
• reusable skills
• subagents for parallel work
• verification habits
• guardrails against unsupported claims

That is the difference between “I asked AI to clean my laptop” and “I built a repeatable local agent operating system.”

The tools will keep changing.

The architecture matters more.