CodexMonitor

CodexMonitor is a Tauri app for orchestrating multiple Codex agents across local workspaces. It provides a sidebar to manage projects, a home screen for quick actions, and a conversation view backed by the Codex app-server protocol.

Features

Workspaces & Threads

• Add and persist workspaces, group/sort them, and jump into recent agent activity from the home dashboard.
• Spawn one codex app-server per workspace, resume threads, and track unread/running state.
• Worktree and clone agents for isolated work; worktrees live under the app data directory (legacy .codex-worktrees supported).
• Thread management: pin/rename/archive/copy, per-thread drafts, and stop/interrupt in-flight turns.
• Optional remote backend (daemon) mode for running Codex on another machine.
• Remote setup helpers for self-hosted connectivity (Tailscale detection/host bootstrap for TCP mode).

Composer & Agent Controls

• Compose with image attachments (picker, drag/drop, paste) and configurable follow-up behavior (Queue vs Steer while a run is active).
• Use Shift+Cmd+Enter (macOS) or Shift+Ctrl+Enter (Windows/Linux) to send the opposite follow-up action for a single message.
• Autocomplete for skills ($), prompts (/prompts:), reviews (/review), and file paths (@).
• Model picker, collaboration modes (when enabled), reasoning effort, access mode, and context usage ring.
• Dictation with hold-to-talk shortcuts and live waveform (Whisper).
• Render reasoning/tool/diff items and handle approval prompts.

Git & GitHub

• Diff stats, staged/unstaged file diffs, revert/stage controls, and commit log.
• Branch list with checkout/create plus upstream ahead/behind counts.
• GitHub Issues and Pull Requests via gh (lists, diffs, comments) and open commits/PRs in the browser.
• PR composer: "Ask PR" to send PR context into a new agent thread.

Files & Prompts

• File tree with search, file-type icons, and Reveal in Finder/Explorer.
• Prompt library for global/workspace prompts: create/edit/delete/move and run in current or new threads.

UI & Experience

• Resizable sidebar/right/plan/terminal/debug panels with persisted sizes.
• Responsive layouts (desktop/tablet/phone) with tabbed navigation.
• Sidebar usage and credits meter for account rate limits plus a home usage snapshot.
• Terminal dock with multiple tabs for background commands (experimental).
• In-app updates with toast-driven download/install, debug panel copy/clear, sound notifications, plus platform-specific window effects (macOS overlay title bar + vibrancy) and a reduced transparency toggle.

Requirements

• Node.js + npm
• Rust toolchain (stable)
• CMake (required for native dependencies; dictation/Whisper uses it)
• LLVM/Clang (required on Windows to build dictation dependencies via bindgen)
• Codex CLI installed and available as codex in PATH (or configure a custom Codex binary in app/workspace settings)
• Git CLI (used for worktree operations)
• GitHub CLI (gh) for GitHub Issues/PR integrations (optional)

If you hit native build errors, run:

npm run doctor

Getting Started

Install dependencies:

npm install

Run in dev mode:

npm run tauri:dev

iOS Support (WIP)

iOS support is currently in progress.

• Current status: mobile layout runs, remote backend flow is wired, and iOS defaults to remote backend mode.
• Current limits: terminal and dictation remain unavailable on mobile builds.
• Desktop behavior is unchanged: macOS/Linux/Windows remain local-first unless remote mode is explicitly selected.

iOS + Tailscale Setup (TCP)

Use this when connecting the iOS app to a desktop-hosted daemon over your Tailscale tailnet. Canonical runbook: docs/mobile-ios-tailscale-blueprint.md.

1. Install and sign in to Tailscale on both desktop and iPhone (same tailnet).
2. On desktop CodexMonitor, open Settings > Server.
3. Set a Remote backend token.
4. Start the desktop daemon with Start daemon (in Mobile access daemon).
5. In Tailscale helper, use Detect Tailscale and note the suggested host (for example your-mac.your-tailnet.ts.net:4732).
6. On iOS CodexMonitor, open Settings > Server.
7. Enter the desktop Tailscale host and the same token.
8. Tap Connect & test and confirm it succeeds.

Notes:

• The desktop daemon must stay running while iOS is connected.
• If the test fails, confirm both devices are online in Tailscale and that host/token match desktop settings.

Headless Daemon Management (No Desktop UI)

Use the standalone daemon control CLI when you want iOS remote mode without keeping the desktop app open.

Build binaries:

cd src-tauri
cargo build --bin codex_monitor_daemon --bin codex_monitor_daemonctl

Examples:

# Show current daemon status
./target/debug/codex_monitor_daemonctl status

# Start daemon using host/token from settings.json
./target/debug/codex_monitor_daemonctl start

# Stop daemon
./target/debug/codex_monitor_daemonctl stop

# Print equivalent daemon start command
./target/debug/codex_monitor_daemonctl command-preview

Useful overrides:

• --data-dir <path>: app data dir containing settings.json / workspaces.json
• --listen <addr>: bind address override
• --token <token>: token override
• --daemon-path <path>: explicit codex-monitor-daemon binary path
• --json: machine-readable output

iOS Prerequisites

• Xcode + Command Line Tools installed.
• Rust iOS targets installed:

rustup target add aarch64-apple-ios aarch64-apple-ios-sim
# Optional (Intel Mac simulator builds):
rustup target add x86_64-apple-ios

• Apple signing configured (development team).
  • Set bundle.iOS.developmentTeam and identifier in src-tauri/tauri.ios.local.conf.json (preferred for local machine setup), or
  • set values in src-tauri/tauri.ios.conf.json, or
  • pass --team <TEAM_ID> to the device script.
  • build_run_ios*.sh and release_testflight_ios.sh automatically merge src-tauri/tauri.ios.local.conf.json when present.

Run on iOS Simulator

./scripts/build_run_ios.sh

Options:

• --simulator "<name>" to target a specific simulator.
• --target aarch64-sim|x86_64-sim to override architecture.
• --skip-build to reuse the current app bundle.
• --no-clean to preserve src-tauri/gen/apple/build between builds.

Run on USB Device

List discoverable devices:

./scripts/build_run_ios_device.sh --list-devices

Build, install, and launch on a specific device:

./scripts/build_run_ios_device.sh --device "<device name or identifier>" --team <TEAM_ID>

Additional options:

• --target aarch64 to override architecture.
• --skip-build to reuse the current app bundle.
• --bundle-id <id> to launch a non-default bundle identifier.

First-time device setup usually requires:

1. iPhone unlocked and trusted with this Mac.
2. Developer Mode enabled on iPhone.
3. Pairing/signing approved in Xcode at least once.

If signing is not ready yet, open Xcode from the script flow:

./scripts/build_run_ios_device.sh --open-xcode

iOS TestFlight Release (Scripted)

Use the end-to-end script to archive, upload, configure compliance, assign beta group, and submit for beta review.

./scripts/release_testflight_ios.sh

The script auto-loads release metadata from .testflight.local.env (gitignored). For new setups, copy .testflight.local.env.example to .testflight.local.env and fill values.

Release Build

Build the production Tauri bundle:

npm run tauri:build

Artifacts will be in src-tauri/target/release/bundle/ (platform-specific subfolders).

Windows (opt-in)

Windows builds are opt-in and use a separate Tauri config file to avoid macOS-only window effects.

npm run tauri:build:win

Artifacts will be in:

• src-tauri/target/release/bundle/nsis/ (installer exe)
• src-tauri/target/release/bundle/msi/ (msi)

Note: building from source on Windows requires LLVM/Clang (for bindgen / libclang) in addition to CMake.

Type Checking

Run the TypeScript checker (no emit):

npm run typecheck

Note: npm run build also runs tsc before bundling the frontend.

Validation

Recommended validation commands:

npm run lint
npm run test
npm run typecheck
cd src-tauri && cargo check

Codebase Navigation

For task-oriented file lookup ("if you need X, edit Y"), use:

• docs/codebase-map.md

Project Structure

src/
  features/         feature-sliced UI + hooks
  features/app/bootstrap/      app bootstrap orchestration
  features/app/orchestration/  app layout/thread/workspace orchestration
  features/threads/hooks/threadReducer/  thread reducer slices
  services/         Tauri IPC wrapper
  styles/           split CSS by area
  types.ts          shared types
src-tauri/
  src/lib.rs        Tauri app backend command registry
  src/bin/codex_monitor_daemon.rs  remote daemon JSON-RPC process
  src/bin/codex_monitor_daemon/rpc/  daemon RPC domain handlers
  src/shared/       shared backend core used by app + daemon
  src/shared/git_ui_core/      git/github shared core modules
  src/shared/workspaces_core/  workspace/worktree shared core modules
  src/workspaces/   workspace/worktree adapters
  src/codex/        codex app-server adapters
  src/files/        file adapters
  tauri.conf.json   window configuration

Notes

• Workspaces persist to workspaces.json under the app data directory.
• App settings persist to settings.json under the app data directory (theme, backend mode/provider, remote endpoints/tokens, Codex path, default access mode, UI scale, follow-up message behavior).
• The interface language can be changed under Settings > Display & Sound; English and Simplified Chinese are available, and the selection is stored locally for immediate startup use. The Chinese catalog currently covers the settings shell plus the full Display & Sound, Codex, Composer, Dictation, Projects, Environments, Open in, Shortcuts, Server, Agents, Features, Git, and About settings pages. It also covers the complete Home experience, including workspace actions, latest-agent activity, local usage analytics, and account limits, plus the complete sidebar experience, including navigation, search, sorting, conversation states, workspace actions, account usage, and utility controls. Workspace clone, worktree creation, URL import, and remote-directory prompts are localized as well, together with the main header worktree, branch, terminal, copy-thread, and diff-view controls. The core composer is also localized, including input and queue controls, collaboration/model/reasoning selectors, agent access, dictation, context status, follow-up behavior, attachments, autocomplete groups and slash-command descriptions, and inline review presets for branches, commits, and custom instructions. Thread renaming and the primary message surface are localized too, including empty/loading/working states, message actions, image previews, reasoning, reviews, answered-input summaries, tool summaries, exploration activity, and plan export controls. Update and error toasts are localized as well, together with agent-completion, agent-error, approval-request, user-question, and plan-ready system notifications. The workspace file browser and file-preview controls are localized, including filtering, counts, empty states, selection hints, and add-to-chat actions. Approval cards, user-input and plan-ready follow-ups, launch-script editors, compact navigation, loading labels, and right-panel tabs are localized too. Desktop and tablet layout accessibility labels now follow the selected language, including sidebar visibility, pane resizing, window controls, back navigation, and server refresh actions. Remaining sidebar paging, search tooltips, native context menus, tray fallback labels, and launch-script validation and terminal titles are localized as well. The Git change view now localizes repository discovery and initialization, commit-message generation, pull/push/sync controls, clean-state text, and staged/unstaged section labels. Git panel mode selection, status summaries, push-conflict guidance, discard confirmations, commit and pull-request menus, file context menus, and repository fallback labels are localized too. Git file and section actions, commit controls, branch and repository metadata, agent-edit empty states, commit lists, issues, pull requests, draft badges, and relative timestamps now follow the selected language. Branch switching, Git initialization, GitHub repository options, and branch-name validation messages are localized, including branch validation used by the main header. Diff cards, image comparisons, discard actions, line-review actions, clean and unavailable states, pull-request summaries, checkout controls, descriptions, comment activity, and relative times are localized as well. Native workspace-path validation, batch-add summaries, workspace/worktree deletion dialogs, dictation processing status, and Markdown code-copy controls now follow the selected language too. Debug, workspace-home run/model controls, Git setup prompts, mobile server setup, shared file-editor actions, and terminal tabs are localized as well. The prompts panel now localizes filtering, counts, creation/editing, validation, send actions, native menus, deletion confirmation, scopes, and empty states. Plan states, workspace run/thread history, thread status, About details, project-drop guidance, ignored Codex-argument warnings, reasoning options, and mobile connection feedback are localized too. Workspace-home run failures, clone and URL-import validation, worktree rename notices, review validation, and Git repository initialization errors now follow the selected language as well. File-link menus and open failures, workspace-open failures, and pull-request review actions and errors are localized too. Destructive Git confirmations, Git initialization details, initial-commit guidance, remote repository setup errors, and workspace-change safeguards now follow the selected language. Native image-picker filters and Markdown plan-export save dialogs are localized as well. Terminal idle, preparation, startup, ready, and failure status messages are localized too. Agents settings loading, update, creation, deletion, config-file, and AI-generation fallback errors now follow the selected language as well. Compact-layout workspace empty states and Git navigation, plus plan, context-compaction, and pending-file-change tool fallbacks, are localized too. Remaining composer notices, Git diff refresh/review controls, open-editor actions, workspace-file metadata, pull-request composer actions, thread interruption/error fallbacks, feature settings errors, and server remote-management validation and status feedback now follow the selected language as well.
• Feature settings are supported in the UI and synced to $CODEX_HOME/config.toml (or ~/.codex/config.toml) on load/save. Stable: Collaboration modes (features.collaboration_modes), personality (personality), and Background terminal (features.unified_exec). Experimental: Apps (features.apps). Steering capability still follows Codex features.steer, but follow-up default behavior is controlled in Settings → Composer.
• On launch and on window focus, the app reconnects and refreshes thread lists for each workspace.
• Threads are restored by filtering thread/list results using the workspace cwd.
• Selecting a thread always calls thread/resume to refresh messages from disk.
• CLI sessions appear if their cwd matches the workspace path; they are not live-streamed unless resumed.
• The app uses codex app-server over stdio; see src-tauri/src/lib.rs and src-tauri/src/codex/.
• The remote daemon entrypoint is src-tauri/src/bin/codex_monitor_daemon.rs; RPC routing lives in src-tauri/src/bin/codex_monitor_daemon/rpc.rs and domain handlers in src-tauri/src/bin/codex_monitor_daemon/rpc/.
• Shared domain logic lives in src-tauri/src/shared/ (notably src-tauri/src/shared/git_ui_core/ and src-tauri/src/shared/workspaces_core/).
• Codex home resolves from workspace settings (if set), then legacy .codexmonitor/, then $CODEX_HOME/~/.codex.
• Worktree agents live under the app data directory (worktrees/<workspace-id>); legacy .codex-worktrees/ paths remain supported, and the app no longer edits repo .gitignore files.
• UI state (panel sizes, reduced transparency toggle, recent thread activity) is stored in localStorage.
• Custom prompts load from $CODEX_HOME/prompts (or ~/.codex/prompts) with optional frontmatter description/argument hints.

Tauri IPC Surface

Frontend calls live in src/services/tauri.ts and map to commands in src-tauri/src/lib.rs. The current surface includes:

• Settings/config/files: get_app_settings, update_app_settings, get_codex_config_path, get_config_model, file_read, file_write, codex_doctor, menu_set_accelerators.
• Workspaces/worktrees: list_workspaces, is_workspace_path_dir, add_workspace, add_clone, add_worktree, worktree_setup_status, worktree_setup_mark_ran, rename_worktree, rename_worktree_upstream, apply_worktree_changes, update_workspace_settings, remove_workspace, remove_worktree, connect_workspace, list_workspace_files, read_workspace_file, open_workspace_in, get_open_app_icon.
• Threads/turns/reviews: start_thread, fork_thread, compact_thread, list_threads, resume_thread, archive_thread, set_thread_name, send_user_message, turn_interrupt, respond_to_server_request, start_review, remember_approval_rule, get_commit_message_prompt, generate_commit_message, generate_run_metadata.
• Account/models/collaboration: model_list, account_rate_limits, account_read, skills_list, apps_list, collaboration_mode_list, codex_login, codex_login_cancel, list_mcp_server_status.
• Git/GitHub: get_git_status, list_git_roots, get_git_diffs, get_git_log, get_git_commit_diff, get_git_remote, stage_git_file, stage_git_all, unstage_git_file, revert_git_file, revert_git_all, commit_git, push_git, pull_git, fetch_git, sync_git, list_git_branches, checkout_git_branch, create_git_branch, get_github_issues, get_github_pull_requests, get_github_pull_request_diff, get_github_pull_request_comments.
• Prompts: prompts_list, prompts_create, prompts_update, prompts_delete, prompts_move, prompts_workspace_dir, prompts_global_dir.
• Terminal/dictation/notifications/usage: terminal_open, terminal_write, terminal_resize, terminal_close, dictation_model_status, dictation_download_model, dictation_cancel_download, dictation_remove_model, dictation_request_permission, dictation_start, dictation_stop, dictation_cancel, send_notification_fallback, is_macos_debug_build, local_usage_snapshot.
• Remote backend helpers: tailscale_status, tailscale_daemon_command_preview, tailscale_daemon_start, tailscale_daemon_stop, tailscale_daemon_status.