Board-based thread management · Inspector and logs · Loop-aware operations · Codex-linked workflow control
Note: This extension requires Codex to be installed, authenticated, and able to run properly. CMA is designed to manage and complement Codex workflows, not replace Codex itself.
Codex-Managed-Agent is built for people who want to work across many Codex threads without treating the official Codex sidebar as the only control surface.
It turns VS Code into a working surface for:
- scanning many threads at once
- grouping and pinning active work
- surfacing
Needs Humanitems - inspecting logs and conversation context
- managing local runtime behavior
- operating across more than one project root
Use the dashboard to:
- search, filter, sort, and pin threads
- inspect conversation and log context
- manage lifecycle actions
- move between list, board, and inspector views
Use the board when you need a higher-signal operating workspace:
- attach important threads to the board
- keep intervention work visible
- resize and reorganize cards
- scan active state without opening every thread manually
When paired with the local codex_manager service, the extension helps with:
- server reachability checks
- local service startup
- degraded-state recovery visibility
- local dashboard integration on
8787
- Native VS Code dashboard in the editor, sidebar, or bottom panel
- Thread search, filter, sort, grouping, and pin workflows
- Board view for active, attached, and intervention work
- Inspector drawer with logs, conversation context, and actions
- Local server awareness with startup and recovery support
- Loop and background-control surfaces for ongoing work
- Cross-surface navigation between dashboard and Codex thread views
The current version of CMA communicates through a few parallel paths rather than one single API:
- CMA webview talks to the extension host through
postMessage - the extension host talks to the local
codex_managerservice over HTTP - the extension host opens or routes Codex native threads through VS Code commands and URI routes
- background prompt continuation uses
codex exec resume - Codex open/focused thread state is inferred from the VS Code tab system
flowchart LR
user["User in VS Code"]
cma["CMA Dashboard Webview<br/>threads / board / inspector"]
host["CMA Extension Host<br/>VS Code API + local state"]
service["Local codex_manager Service<br/>HTTP API on 127.0.0.1:8787"]
cli["Codex CLI<br/>codex exec resume"]
codex["Codex VS Code Extension<br/>conversation editor + sidebar"]
tabs["VS Code Tab System<br/>tabGroups + URIs"]
user -->|"click / inspect / board actions"| cma
cma -->|"postMessage"| host
host -->|"GET / POST / rename / lifecycle"| service
service -->|"thread list / detail / status"| host
host -->|"state payload"| cma
host -->|"vscode.openWith(openai-codex://route/local/:threadId)"| codex
host -->|"chatgpt.openSidebar + vscode://openai.chatgpt/local/:threadId"| codex
host -->|"spawn background resume"| cli
cli -->|"resume existing thread by threadId"| codex
codex -->|"open conversation tabs"| tabs
tabs -->|"inspect openThreadIds + focusedThreadId"| host
host -.->|"effective link state"| cma
classDef cma fill:#17324d,stroke:#8dd8ff,color:#ffffff
classDef service fill:#183626,stroke:#54f2b0,color:#ffffff
classDef codex fill:#3a2a16,stroke:#ffd479,color:#ffffff
classDef infra fill:#2c263d,stroke:#c4a3ff,color:#ffffff
class cma,host cma
class service,cli service
class codex,tabs codex
class user infra
Source files for this diagram:
Files live under docs/screenshots/ so GitHub renders them without external image hosts. Each capture below is one image per row with a short caption.
Overview — Agent Task Summary & coordination queue
High-level counts (threads, board, tabs), the coordination queue (running / handoff / loop), and a snapshot strip for Threads, Board, Live, Inspector, Service, and Loop daemon.
Overview — full dashboard layout
Same Agent Control Surface in a wider layout, including the footer branding strip so you can see the full visual chrome of the dashboard.
Threads — Thread Explorer
Search, sort, filters, batch selection, and actions such as New Thread, Refresh, and Scan Sessions—built for scanning many threads without opening each conversation first.
Threads — grouped list
Threads grouped by status or workspace root; each row shows status, Inspector, Board, Codex, Pin, and token/size/cmd metadata at a glance.
Board — canvas
Board Canvas with cards for active work: size presets, Codex shortcut, status (e.g. IDLE / ATTACHED), and optional tab groups when you organize cards into colored rails.
Board — tab groups
Board Tab Groups (e.g. custom tabs with counts) so you can split workstreams while keeping cards independent within each group.
Loop — daemon list
All discovered codex-loop workspaces in one list: RUNNING / STOPPED CLEANLY / EXITED UNEXPECTEDLY, with PID, interval, heartbeat, thread id, and quick actions (logs, prompt, tmux, start/stop).
Loop — daemon detail
Expanded view of a single daemon: path, metadata chips, last tick summary, and action buttons for recovery and inspection.
Loop — with terminal log
Loop UI alongside integrated terminal (e.g. tailing daemon_stdout.log) so you can correlate UI state with live log lines.
Insights — usage report
Token headline metrics, trend chart, and top threads by token usage so you can see where spend concentrates.
Insights — topic map & vibe advice
Topic Map (themes + threads) and Vibe Advice cards grounded in observed prompt and compaction signals.
Insights — behavior signals & heatmap
Behavior Signals (token pace, token mix, topic map, work rhythm) and Vibe Interaction heatmap from direct user inputs (see in-app basis text for counting rules).
Dashboard — alternate framing
Additional full-width dashboard capture for README / release notes.
If you are updating marketing screenshots or preparing a release, the capture workflow is organized in five layers:
- capture inventory:
SCREENSHOT_INVENTORY.md - execution checklist:
docs/screenshots/CAPTURE_CHECKLIST.md - UI preparation plan:
docs/screenshots/RESOURCE_PLAN.md - shoot order:
docs/screenshots/SCREENSHOT_SHOOT_ORDER.md - per-shot scene design:
docs/screenshots/SCENE_DESIGN.md
Search for:
Codex-Managed-Agent
Publisher:
harzva
code --install-extension codex-managed-agent-1.0.3.vsixOr inside VS Code:
- Open Extensions
- Click
... - Choose
Install from VSIX... - Select the generated package
The extension works best with the local codex_manager service.
Start it like this:
cd <your-workspace>/codex_manager
source .venv/bin/activate
uvicorn codex_manager.app:app --reload --port 8787If the service is not reachable, the extension can try to start it automatically.
- Open this extension folder in VS Code
- Press
F5 - Choose
Run Codex Agent Extensionif prompted - In the Extension Development Host, run:
Codex-Managed-Agent: Open Dashboard
Useful placement commands:
Codex-Managed-Agent: Open DashboardCodex-Managed-Agent: Show in SidebarCodex-Managed-Agent: Show in Bottom PanelCodex-Managed-Agent: Open to SideCodex-Managed-Agent: Full ScreenCodex-Managed-Agent: Move to New Window
- default:
http://127.0.0.1:8787/ - use this when your local dashboard is running on a different URL or port
- default:
true - attempts to start the local service when the panel cannot connect
- optional override for the Python executable used to launch the local service
- optional absolute path to the local
codex_managerservice root
Codex-Managed-Agent: Open DashboardCodex-Managed-Agent: Show in SidebarCodex-Managed-Agent: Show in Bottom PanelCodex-Managed-Agent: Open to SideCodex-Managed-Agent: Full ScreenCodex-Managed-Agent: Move to New WindowCodex-Managed-Agent: Refresh PanelCodex-Managed-Agent: Open in BrowserCodex-Managed-Agent: Start Local Server
Package locally:
npm run packageBefore calling a build release-ready, use:
This extension is published as a stable 1.x build.
The current focus is to make it:
- operationally reliable
- smoother as a board-based control surface
- more usable for multi-thread Codex work inside VS Code
- Source:
https://github.com/Harzva/codex-managed-agent