Isolated Codex daemon profile playbook

Web developers constantly repeat narrow CLI work around local dev servers, deploy previews, browser QA, GitHub checks, and framework tooling. An isolated Codex daemon profile turns one repetitive tool workflow into a cheap, warm, low-context helper instead of dragging a full general agent through every small task.

Original source pages and recordings require authorized access. The full article text here is public.

Web developers constantly repeat narrow CLI work around local dev servers, deploy previews, browser QA, GitHub checks, and framework tooling. An isolated Codex daemon profile turns one repetitive tool workflow into a cheap, warm, low-context helper instead of dragging a full general agent through every small task.

Core principles

Copy-paste workflow

When to use: When a repetitive, well-scoped CLI task should run on a cheap, fast, low-context warm agent instead of a full general agent. This wraps one CLI in a single-purpose Codex SDK profile with a tight context ceiling.

Copy-paste prompt

You are my coding agent. Generate a new isolated "pro-<TOOL>" Codex daemon profile for the <TOOL> CLI, following the codex-daemons pattern. The point is a cheap, fast, low-context warm agent that does ONE thing — target ~6-10K input tokens.

1. Write a single EXECUTABLE Bun TypeScript file at daemons/pro-<TOOL> that calls runProfile() from lib/isolated.ts. Use this prompt shape inside developerInstructions:
     ## Operating rule  -> run <TOOL> via exec_command before any final answer; never answer from memory
     ## Command map     -> KEYWORD -> <TOOL> COMMAND  (e.g. status -> <TOOL> status; help -> <TOOL> --help)
     ## Workflow        -> narrowest read-only command first; mutate only when target+action are explicit; on usage error run --help then retry once
     ## Command rules   -> use only <TOOL>; no web, no images, no file edits unless explicitly asked
     ## Output          -> be terse; report what you found/changed
   Keep the command map LITERAL — do not dump --help text. Use a low-reasoning model (reasoningEffort default "low"; default model gpt-5.3-codex-spark).

2. The isolation is applied by runProfile() — it sets: base_instructions replaced, developer_instructions custom, skills.include_instructions=false, include_apps_instructions=false, include_environment_context=false, include_permissions_instructions=false, memories.use_memories=false, mcp_servers={}, web_search="disabled", features {plugins, apps, image_generation, tool_search, tool_suggest} all false (features.apps=false alone saves ~14K tokens), CODEX_HOME redirected to a disposable /tmp dir, and auth.json symlinked from real ~/.codex so token refreshes propagate.

3. After generating, run these steps:
     chmod +x daemons/pro-<TOOL>
     bun daemons/pro-<TOOL> --help        # smoke test
     # add daemons/pro-<TOOL> to package.json "bin", then:
     bun link                              # put it on PATH

Prereqs: Bun runtime; @openai/codex-sdk; an authenticated @openai/codex CLI.

How it works

  • A profile is a single executable Bun TS file using runProfile() from lib/isolated.ts, with the Oracle-tuned prompt shape: Operating rule -> Command map -> Workflow -> Command rules -> Output.
  • The context ceiling comes from real isolation keys: base_instructions replaced, custom developer_instructions, skills.include_instructions=false, apps/environment/permissions instructions off, memories.use_memories=false, mcp_servers={}, web_search="disabled", and features (plugins/apps/image_generation/tool_search/tool_suggest) all false — features.apps=false alone saves ~14K tokens.
  • CODEX_HOME is redirected to a disposable /tmp dir and auth.json is symlinked from real ~/.codex so token refreshes propagate.
  • Use a low-reasoning model and keep prompts literal (command map over dumping --help); target ~6-10K input tokens (default full config is ~22K).
  • After-generation: chmod +x, bun daemons/pro-<TOOL> --help, add to package.json bin, bun link.
  • Reference: codex-daemons, @openai/codex-sdk, Bun.

Reusable skill

Install as ~/.agents/skills/codex-daemon-profile/SKILL.md, then restart Codex.

---
name: codex-daemon-profile
description: Trigger when a repetitive, well-scoped CLI task should run on a cheap, fast, low-context warm Codex daemon instead of a full general agent — generate an isolated pro-TOOL profile. Do NOT use for broad multi-tool or judgment-heavy work.
---

# Codex daemon profile

Generate an isolated `pro-<TOOL>` Codex daemon profile that wraps ONE CLI in a single-purpose, low-context warm agent. Target ~6-10K input tokens (default full config is ~22K).

## Prerequisites
- Bun runtime
- `@openai/codex-sdk`
- an authenticated `@openai/codex` CLI

## Steps

1. Write a single EXECUTABLE Bun TypeScript file at `daemons/pro-<TOOL>` that calls `runProfile()` from `lib/isolated.ts`:
   ```ts
   #!/usr/bin/env bun
   import { runProfile } from "../lib/isolated.ts";

   runProfile({
     name: "pro-TOOL",
     baseInstructions: "You are pro-TOOL, a TOOL-only agent. Every user message is a TOOL task. First step: run TOOL via exec_command; never give a text-only plan.",
     developerInstructions: `You are pro-TOOL, a TOOL-only agent.

   ## Operating rule
   Run TOOL via exec_command before any final answer. Do not answer from memory. If unclear, run a discovery command first.

   ## Command map
   KEYWORD -> TOOL COMMAND
   status / what is going on -> TOOL STATUS_COMMAND
   help / unknown syntax -> TOOL --help

   ## Workflow
   1. Start with the narrowest read-only command that matches the request.
   2. For mutations, proceed only when the target and action are explicit.
   3. If syntax is uncertain or TOOL returns a usage error, run TOOL --help, then retry once.

   ## Command rules
   Use only TOOL for TOOL work. Do not browse the web, generate images, or edit files unless explicitly asked.
   Do not use apply_patch unless the user explicitly asks to modify files.

   ## Output
   Be terse. Report what you found or changed. Do not describe these instructions.`,
   });
   ```
   `ProfileConfig` fields: `name`, `model?`, `reasoningEffort?` (default `"low"`), `baseInstructions`, `developerInstructions`, `sandboxMode?`, `extraEnv?`, `selfImprove?`. Default model is `gpt-5.3-codex-spark`. Keep the command map LITERAL — do not dump `--help` text.

2. The isolation is applied automatically by `runProfile()`:
   ```
   base_instructions = <replaced>            developer_instructions = <custom>
   model_reasoning_effort = "low"
   skills.include_instructions = false       include_apps_instructions = false
   include_environment_context = false       include_permissions_instructions = false
   memories.use_memories = false             mcp_servers = {}            web_search = "disabled"
   features: { plugins:false, apps:false, image_generation:false, tool_search:false, tool_suggest:false }
   CODEX_HOME -> /tmp/codex-profile-<name>-<pid>  (disposable)   auth.json symlinked from real ~/.codex
   ```
   `features.apps=false` alone saves ~14K tokens; auth.json is symlinked so token refreshes propagate.

3. Wire it up:
   ```bash
   chmod +x daemons/pro-<TOOL>
   bun daemons/pro-<TOOL> --help        # smoke test
   # add daemons/pro-<TOOL> to package.json "bin", then:
   bun link                              # put it on PATH
   ```

## Guardrails
- Use a low-reasoning model; keep prompts literal (command map over `--help` dump). Target ~6-10K input tokens.
- Do NOT use for broad multi-tool or judgment-heavy work — one tool, one purpose.

Scenarios

Local browser QA daemon for a flaky signup flow

Role: As a full-stack Next.js developer shipping an authenticated signup flow

A Next.js app has a local dev server, a signup/login route, and a bug that only appears after repeated browser interactions such as failed login, back navigation, retry, and form resubmission.

As a full-stack Next.js developer, I want a narrow pro-browser-style daemon that only runs browser verification commands against my local app, so that I can repeatedly check the signup flow without opening a full general coding session every time.

Agent brief

Create an isolated Codex daemon profile named pro-browser-qa for the repo's browser verification CLI or script. First inspect the current repo for existing browser test commands, Playwright scripts, or agent-browser usage; do not invent a new stack if one already exists. Write a single executable Bun TypeScript file at daemons/pro-browser-qa that calls runProfile() from lib/isolated.ts. Use the developerInstructions shape: Operating rule, Command map, Workflow, Command rules, Output. The operating rule must require running the browser QA command through exec_command before any final answer. The command map should include only the local commands this repo actually has, such as dev server health check, run signup flow, run login flow, capture console output, capture screenshot, and help. Keep the map literal; do not paste full --help output. Mutations are not allowed: this daemon verifies and reports only. After creating it, run chmod +x daemons/pro-browser-qa, run bun daemons/pro-browser-qa --help, add it to package.json bin if the repo uses that pattern, and run bun link. Expected output: a terse report with command run, route tested, pass/fail, browser evidence path, console errors, and next action.

Implementation references

Open reference

Open reference

Open reference

daemons/pro-<TOOL>
lib/isolated.ts
package.json
chmod +x daemons/pro-browser-qa
bun daemons/pro-browser-qa --help
bun link

Browser verification

Use a local browser verification move because this is a browser-visible bug: start the app with the repo's dev command, then have the daemon run the existing browser script or agent-browser-style flow to snapshot the signup page, fill the email/password fields, click submit, navigate back, retry, and collect screenshot plus console output. If CMUX is available, open the app in a browser pane and keep the daemon terminal visible beside it.

Definition of done

  • daemons/pro-browser-qa exists, is executable, and calls runProfile() from lib/isolated.ts
  • bun daemons/pro-browser-qa --help runs without crashing
  • The profile prompt has Operating rule, Command map, Workflow, Command rules, and Output sections
  • The daemon performs read-only browser verification before answering
  • A verification receipt includes tested URL, exact command, pass/fail, screenshot or trace path, console errors, and any failed selector or step
  • package.json bin and bun link are updated only if the repo uses that executable profile pattern

Failure modes and mitigations

  • Mistake: the agent builds a broad browser-and-code-editing assistant. Mitigation: keep this daemon browser-QA-only, no file edits unless explicitly requested, and no web browsing beyond the local app.
  • Mistake: the daemon answers from memory or source inspection without running the browser flow. Mitigation: the operating rule must require exec_command first and the final answer must name the command and artifact path.
  • Mistake: the profile dumps full Playwright or tool help into developerInstructions. Mitigation: use a curated keyword-to-command map and fall back to --help only on syntax errors.
  • Mistake: authenticated flow assumes normal browser cookies exist. Mitigation: script login/setup explicitly or use a seeded test account path documented in the repo.

Preview deployment triage daemon

Role: As a frontend lead reviewing preview builds before merge

A pull request deploys a preview URL, but every review requires the same narrow checks: list the current deployment, inspect status, open the preview route, confirm key pages render, and summarize only the blocking issues.

As a frontend lead, I want a pro-deploy-check daemon around my deployment CLI, so that preview triage is fast, repeatable, and limited to deployment status plus browser proof instead of turning into a broad coding session.

Agent brief

Create an isolated Codex daemon profile named pro-deploy-check for the repo's deployment CLI or existing preview-check script. Inspect package.json and repo scripts first. If the repo already uses a specific deploy CLI, wrap that one CLI only. Write daemons/pro-deploy-check as a single executable Bun TypeScript file using runProfile() from lib/isolated.ts. The daemon must start with the narrowest read-only command: deployment status or preview URL discovery. The command map should cover status, current preview, logs, inspect URL, and help, using exact repo commands. For mutations, require explicit target and action; default to read-only. Disable broad behavior in the prompt: no web search, no image generation, no unrelated file edits, no apply_patch unless explicitly asked. After generation, run chmod +x daemons/pro-deploy-check, bun daemons/pro-deploy-check --help, test one real prompt such as 'status for the current PR preview', then add package.json bin and bun link if appropriate. Expected output: current deployment state, preview URL, failing route if any, command evidence, and browser proof path.

Implementation references

Open reference

Open reference

Open reference

package.json scripts
daemons/pro-deploy-check
lib/isolated.ts
chmod +x daemons/pro-deploy-check
bun daemons/pro-deploy-check --help
bun link

Browser verification

Use browser proof after the daemon discovers the preview URL: open the preview in a CMUX browser pane or run the repo's browser automation to snapshot the homepage and one changed route, then record status code, visible error text, console errors, and screenshot path. Browser proof is useful here because deployment status alone does not prove the UI renders.

Definition of done

  • The profile wraps one deployment or preview-check CLI only
  • The first command is read-only status or preview discovery
  • bun daemons/pro-deploy-check --help succeeds
  • A real prompt returns deployment status, preview URL, and exact commands run
  • Browser evidence exists for at least the homepage and one changed route
  • The final report is terse and separates blocker, warning, and clean result

Failure modes and mitigations

  • Mistake: the agent creates a general CI/CD bot with many tools and broad permissions. Mitigation: one CLI, one profile, read-only first, mutate only when target plus action are explicit.
  • Mistake: it trusts a green deployment status without checking the rendered app. Mitigation: require browser proof for at least one preview route before final answer.
  • Mistake: it hardcodes a vendor-specific command not present in the repo. Mitigation: inspect package.json and existing scripts first, then map only verified local commands.
  • Mistake: it bloats context with full docs or --help output. Mitigation: keep a small curated command map and use --help only as a retry path.

Create a focused accessibility audit daemon

Role: As a frontend platform engineer supporting multiple product teams

Several teams ship React pages with recurring accessibility regressions: missing form labels, buttons without accessible names, skipped headings, and modals that trap focus inconsistently. The work is repetitive and command-driven, but each audit still needs a concise human-readable report.

As a frontend platform engineer, I want a narrow Codex daemon that runs the project accessibility checks and browser proof steps, so that teams get consistent reports without asking a general assistant to rediscover the workflow each time.

Agent brief

Build or use an isolated Codex daemon profile for accessibility triage only. Keep the command map narrow: inspect package scripts, run the existing accessibility or browser-test command if present, start the local dev server only when required, open the target route in a browser, capture an accessibility snapshot, and report missing labels/headings/focus problems with file or route pointers. The daemon should write one markdown report under `.notes/a11y/<route-slug>.md` with commands run, browser route, snapshot summary, issues found, false positives, and recommended next fixes. It must not edit files unless explicitly asked after the audit report is reviewed.

Implementation references

Open reference

Open reference

package.json scripts
target app route/component files
cmux browser snapshot or existing Playwright accessibility checks

Browser verification

Use browser proof because accessibility is runtime UI behavior. Open the target localhost route, take an accessibility snapshot, click or tab through the primary form/modal/menu path, evaluate focus state where useful, and save the route plus snapshot summary in the daemon report. If no browser surface is available, state that runtime accessibility proof is missing rather than claiming success from source inspection.

Definition of done

  • The daemon profile has one narrow responsibility and a small command map.
  • A markdown report exists under .notes/a11y/ with exact commands, route, browser proof, and prioritized issues.
  • The daemon did not edit source files during audit-only mode.
  • The report distinguishes confirmed runtime issues from possible source-level concerns.

Failure modes and mitigations

  • The daemon becomes a broad product assistant; mitigate by keeping its profile limited to accessibility triage commands and reports.
  • The daemon claims accessibility from static source reading; mitigate by requiring browser snapshot/focus evidence for runtime findings.
  • The daemon mutates code during audit; mitigate by making audit-only mode the default and requiring explicit follow-up approval for fixes.

Implementation notes

  • Keep each daemon wrapped around exactly one CLI or one repo-local script family. The whole point is a narrow helper, not another giant assistant.
  • Use the runProfile() shape from lib/isolated.ts: one executable Bun TypeScript file, low reasoning by default, literal developerInstructions, and a curated command map.
  • The prompt order matters: Operating rule first, then Command map, then Workflow, Command rules, and Output.
  • Make the daemon run a command before answering. A daemon that summarizes from memory is just a small hallucination machine with a fancy name.
  • Default to read-only discovery. Require explicit target plus action for mutations, especially deploy, Docker, database, cloud, or file-editing tools.
  • Do not paste full --help output into instructions. Keep the command map tight and use --help only when syntax is uncertain or a usage error occurs.
  • For web app work, pair command receipts with browser receipts when the user-visible app matters: local URL, route, action sequence, screenshot or trace path, console errors, and pass/fail.
  • Treat self-improvement as experimental and narrow. It fits predictable CLI/API failure modes better than broad product implementation.

Boundaries and caveats

  • Do not introduce unrelated workflow tools only mentioned in the lesson as if they were taught implementation steps.
  • Do not build an all-purpose autonomous swarm. Parallel agents need an analysis or synthesis step, and this topic is exactly one toolkit technique.
  • Do not claim arbitrary line-count rules for agent-readable code. The taught guidance favors clear state machines, named cases, and English-readable conditions.
  • Do not make browser automation unbounded or credential-casual. Keep it scoped to local app verification or explicit preview URLs with clear proof artifacts.
  • Do not use daemon profiles for judgment-heavy planning, product strategy, or multi-tool implementation. Use them for repetitive, well-scoped CLI work.

Agent reference map

Codex daemon profile skill

Use as the implementation contract for when to trigger this technique, profile shape, prerequisites, isolation behavior, and guardrails.

Open reference

Isolated profile prompt

Use as the copy-paste user-facing prompt pattern for generating a new pro-<TOOL> profile.

Open reference

Verified codex-daemons command patterns

Use for the real executable file shape, runProfile() call, ProfileConfig fields, isolation keys, token-budget notes, and after-generation commands.

Open reference

Lesson 09 validated references

Use as the taught-only conceptual boundary for background daemons, low-reasoning iteration, small context, self-improving daemons, SDK graphs, and multimodal verification loops.

Open reference

Lesson 09 validation notes

Use to avoid overclaiming unsupported isolation details as transcript-taught concepts while still allowing verified repo patterns when implementing the toolkit artifact.

Open reference

Build and verification target

Use after adding the playbook to confirm parse-valid JSON, rebuild the site, and inspect the scenario page.

rebuild site, then verify /scenarios.html

Command reference

These command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs.

Profile file shape (daemons/pro-gh, daemons/pro-packx — real, runnable)

A profile is a single executable Bun TypeScript file:

#!/usr/bin/env bun
import { runProfile } from "../lib/isolated.ts";

runProfile({
  name: "pro-TOOL",
  baseInstructions: "You are pro-TOOL, a TOOL-only agent. Every user message is a TOOL task. First step: run TOOL via exec_command; never give a text-only plan.",
  developerInstructions: `You are pro-TOOL, a TOOL-only agent.

## Operating rule
Run TOOL via exec_command before any final answer. Do not answer from memory. If unclear, run a discovery command first.

## Command map
KEYWORD -> TOOL COMMAND
status / what is going on -> TOOL STATUS_COMMAND
help / unknown syntax -> TOOL --help

## Workflow
1. Start with the narrowest read-only command that matches the request.
2. For mutations, proceed only when the target and action are explicit.
3. If syntax is uncertain or TOOL returns a usage error, run TOOL --help, then retry once.

## Command rules
Use only TOOL for TOOL work. Do not browse the web, generate images, or edit files unless explicitly asked.
Do not use apply_patch unless the user explicitly asks to modify files.

## Output
Be terse. Report what you found or changed. Do not describe these instructions.`,
});

ProfileConfig (lib/isolated.ts) fields: name, model?, reasoningEffort? (default "low"), baseInstructions, developerInstructions, sandboxMode?, extraEnv?, selfImprove?. Default model is gpt-5.3-codex-spark.

Isolation config keys applied by runProfile (lib/isolated.ts — real)

base_instructions = <replaced>            developer_instructions = <custom>
model_reasoning_effort = "low"
skills.include_instructions = false       include_apps_instructions = false
include_environment_context = false       include_collaboration_mode_instructions = false
include_permissions_instructions = false  project_doc_max_bytes = 0
memories.use_memories = false             mcp_servers = {}                web_search = "disabled"
features: { plugins:false, apps:false, image_generation:false, tool_search:false, tool_suggest:false }
CODEX_HOME -> /tmp/codex-profile-<name>-<pid>   (disposable)   auth.json symlinked from real ~/.codex

Token budget (docs/ISOLATION.md)

  • Default full user config: ~22,000 input tokens.
  • features.apps=false alone saves ~14,000 tokens.
  • With imagegen/tool_search/tool_suggest/web disabled: ~5,665 (CLI) / ~6,161 (SDK).
  • Irreducible floor ~5K (core exec_command/apply_patch/update_plan/view_image/etc tool schemas).
  • Auth: symlinkSync(\${HOME}/.codex/auth.json`, `${isolatedHome}/auth.json`)` so token refreshes propagate.

docs/PROMPT.md after-generation steps (real)

  1. Save to daemons/pro-your-tool. 2. chmod +x daemons/pro-your-tool.
  2. Test bun daemons/pro-your-tool --help. 4. Test with a real prompt.
  3. Add to package.json bin. 6. bun link to put it on PATH.

Dependency: @openai/codex-sdk (also requires authenticated @openai/codex CLI). Runtime: Bun.

Source references