Codex App Mastery

You have a monorepo with a frontend, a backend API, and a shared library. You need to refactor an interface in the shared lib, update the API consumers, and fix the resulting frontend type errors — all without the three tasks stepping on each other’s files. Doing this sequentially means waiting; doing it in one thread means confusion. The Codex App was built for exactly this kind of parallel orchestration.

Codex App v260416 (April 16, 2026)

The Codex App added several new capabilities in April 2026 that change what’s possible:

• In-app browser: Pull up local or public pages without signing in; comment directly on rendered pages.
• Computer use (macOS): The app can click, type, and interact visually — useful for UI testing flows or driving another app alongside your code.
• Chats: Project-agnostic threads for research and analysis. Start a Chat when you want a conversation that’s not tied to any specific repo.
• Thread automations: Schedule wake-ups that preserve conversation context — the app resumes the thread on your schedule and does the work.
• Task sidebar: Plans, sources, artifacts, and summaries live alongside the active thread instead of scrolling past.
• GitHub PR reviews: Inspect diffs and review comments inside the app — no browser round-trip.
• Artifact viewer: PDFs, spreadsheets, documents, and presentations render inline.
• Memories: Carry context from past tasks into new threads.
• Remote connections (SSH, alpha): Connect the app to a remote machine; Codex runs there while you drive from local.
• Multi-terminal and multi-window: Fan out parallel work without juggling one-at-a-time.
• Intel Mac and Windows system tray: First-class support on those platforms.

What You’ll Walk Away With

• A workflow for managing multiple projects and parallel threads in a single Codex App window
• Techniques for leveraging IDE sync, voice dictation, and inline diff review to cut review time in half
• A strategy for combining Local, Worktree, and Cloud modes in the same session
• Production-ready patterns for skills integration and MCP server configuration in the App

Multi-Project Orchestration

The Codex App sidebar is your control center. Each project maps to a directory on disk, and you can switch between them instantly. The key insight is that each project maintains its own sandbox, worktree state, and thread history.

1. Add your projects. Click the ”+” in the sidebar and point to each codebase directory. For a monorepo, split distinct packages into separate projects so the sandbox only includes relevant files.

2. Launch parallel threads. Within a single project, open multiple threads — one in Local mode for quick edits, one in Worktree mode for an experimental feature, one in Cloud mode for a heavy refactor that should not block your machine.

3. Monitor the inbox. Automation results and completed cloud tasks surface in the Triage section. Filter to “unread” to focus on what needs your attention.

Prompt: Set up parallel feature work

Open three Worktree threads in the same project with these prompts:

Thread 1: “Refactor the UserService interface to accept a generic ID type. Update all direct consumers in this package. Run the type checker after each change.”

Thread 2: “Add integration tests for the payment webhook handler. Follow the patterns in tests/integration/. Run the test suite to verify.”

Thread 3: “Update the API documentation in docs/api/ to reflect the new UserService interface. Cross-reference the existing OpenAPI spec.”

IDE Sync: Bridging App and Editor

When the Codex IDE Extension is installed in VS Code or Cursor and both the App and IDE are pointed at the same project, they sync automatically. This gives you two superpowers:

Auto context — The App tracks which files you have open in your editor. When you ask “What’s this file about?” in the App, it knows you mean the file you are looking at in VS Code.

Bidirectional thread visibility — Threads started in the App appear in the IDE Extension sidebar and vice versa. You can start a heavy task in the App, switch to the IDE to continue coding, and watch the thread progress without context-switching.

When sync causes confusion

If the App includes context you did not expect, toggle off “Auto context” in the composer and re-ask the question. Auto context is helpful for reactive work but can add noise when you are focused on a specific file that is not currently open in your editor.

Choosing the Right Mode

Every new thread in the Codex App asks you to pick a mode. Here is how to decide:

Mode	Use When	Trade-off
Local	Quick edits, debugging, exploring code	Changes happen directly in your working directory — risk of conflicts if multiple threads touch the same files
Worktree	Feature work, experiments, parallel tasks	Git worktree isolation means no conflicts, but you need to sync or merge changes back
Cloud	Heavy refactors, tasks you want to delegate, mobile triage	Runs remotely, needs a configured environment, cannot access local-only tools

Prompt: Delegate a refactor to the cloud

“Migrate all class components in src/components/ to functional components with hooks. Preserve all existing prop interfaces and test coverage. Use the existing ESLint and Prettier configs for formatting. Run the full test suite before finishing.”

Built-in Git Workflow

The App includes a complete Git workflow: diff review, inline commenting, staging, committing, pushing, and PR creation. The diff pane shows a standard unified diff of your changes. You can:

• Add inline comments that Codex will address in a follow-up turn
• Stage or revert specific chunks or entire files
• Commit, push, and open a PR without leaving the App

For worktree threads, use “Create branch here” to turn a detached HEAD into a named branch, then push directly to your remote.

Skills in the App

The App supports the same agent skills as the CLI and IDE Extension. Click “Skills” in the sidebar to browse available skills across your projects. To trigger a skill explicitly in a thread, prefix it with $:

$recent-code-bugfix

Combine skills with automations for recurring tasks. For example, a $dependency-audit skill paired with a weekly automation keeps your dependencies reviewed without manual effort.

Advanced Keyboard Shortcuts

Shortcut	Action
Cmd + J	Toggle the integrated terminal
Cmd + K	Open the command palette
Ctrl + M (hold)	Voice dictation
Ctrl + L	Clear the terminal

The integrated terminal is scoped to the current project or worktree. Use it to run tests, check git status, or execute any command without leaving the App.

Prompt: Voice-driven bug triage

Hold Ctrl + M and say: “Look at the error in the Sentry screenshot I’m about to paste. Find the root cause in the codebase, propose a fix, and write a regression test.”

Then drop the screenshot into the composer while the transcription is visible.

Permission Profiles (CLI v0.128+)

The April 30, 2026 release introduced permission profiles — named sandbox + filesystem policies you switch between per-task without rewriting config.toml. They sit on top of the two-layer security model (sandbox + approvals), so a single named profile captures a whole posture.

Built-in profiles

Built-ins carry a leading colon. Custom profiles you define drop it.

Profile	What it allows	Typical use
:read-only	Read filesystem; no edits, no shell writes	Code review, security audit
:workspace	Read + write inside the active workspace roots	Default for most coding tasks
:danger-full-access	Removes local sandbox restrictions — no approvals	Throwaway environments, CI runners

Switching profiles

# Inside the TUI — switch posture mid-session
/permissions

# Load a config profile that pins a permission profile (per-invocation)
codex --profile review

Define custom profiles under [permissions.<name>] in config.toml, then set a default with the top-level default_permissions key. Prefer extending a built-in so baseline protections carry forward — a custom profile can extend :read-only or :workspace, but never :danger-full-access.

# config.toml — a review posture that extends :read-only
[permissions.review]
extends = ":read-only"

# Make it the default for this project
default_permissions = "review"

Plugin Marketplace

Recent CLI releases added a plugin system: a codex plugin command tree with a nested marketplace subcommand for managing the sources you install from. Marketplaces are added first, then you install plugins from a configured marketplace snapshot.

# Register a marketplace source
# Accepts owner/repo, owner/repo@ref, an HTTPS/SSH git URL, or a local dir
codex plugin marketplace add my-org/my-plugin
codex plugin marketplace add my-org/my-plugin@v2          # pin a ref inline...
codex plugin marketplace add my-org/my-plugin --ref v2    # ...or with the equivalent flag
codex plugin marketplace add ./local-plugin/ --sparse plugins/

# List configured marketplaces and refresh their snapshots
codex plugin marketplace list
codex plugin marketplace upgrade

# Install a plugin from a configured marketplace
codex plugin add openai-docs
codex plugin list

# Remove an installed plugin, or a marketplace source
codex plugin remove openai-docs
codex plugin marketplace remove my-org/my-plugin

Inside the TUI, /plugins opens the management panel with tabbed browsing, inline toggles, and one-click install/uninstall.

AWS Bedrock Authentication

Codex CLI ships a built-in amazon-bedrock model provider (SigV4 signing, AWS credential chain). Point Codex at it with the top-level model_provider key, then configure the AWS profile and region under the provider’s [model_providers.amazon-bedrock.aws] table.

config.toml

model_provider = "amazon-bedrock"

[model_providers.amazon-bedrock.aws]
profile = "codex-bedrock"   # a named profile in ~/.aws/credentials
region  = "eu-central-1"    # or your Bedrock region

Two auth paths

1. Bedrock API key — export AWS_BEARER_TOKEN_BEDROCK with your Bedrock API key. If it is set, Codex uses it first.
2. AWS SDK credential chain — if no bearer token is present, Codex falls back to the standard SDK chain, which honors the named profile above (and env vars, instance roles, SSO, etc.).

Select a Bedrock-served model with /model gpt-5.5 (or whichever Bedrock model id your account exposes — ids look like openai.gpt-5.5 or openai.gpt-oss-120b). Combine with permission profiles to keep the blast radius small — a :read-only profile plus the Bedrock provider gives you a fully isolated review agent.

When This Breaks

• Worktree branch conflicts: Git only allows a branch to be checked out in one worktree at a time. If you create a branch on a worktree and try to check it out locally, Git will error. Use “Sync with local” instead of manually checking out the branch.
• Disk space from worktrees: Each worktree copies your entire repo. Archive threads you no longer need so Codex can clean up worktrees automatically (older than 4 days or when you exceed 10 worktrees).
• IDE sync not working: Both the App and IDE Extension must point at the same project root. Check that neither is pointing to a parent or child directory of the other.
• Notifications not firing: Verify notification settings in the App preferences. On macOS, also check System Settings > Notifications for the Codex App.

What’s Next

• Worktrees deep dive — Master the sync, branch, and merge workflows
• Automations — Set up recurring background tasks that report to your inbox
• Cloud Environments — Configure remote execution for heavy workloads