Codex-Managed-Agent

A VS Code control surface for managing Codex threads, board workflows, and the built-in local Node backend.

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.

What this extension is for

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 Human items
• inspecting logs and conversation context
• monitoring the built-in local backend
• operating across more than one project root

Core workflows

Thread management inside VS Code

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

Board-based active work

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

Local backend control

The extension ships with a built-in Node backend and helps with:

• backend reachability checks
• local backend startup
• degraded-state recovery visibility
• local dashboard integration on 8787

Feature highlights

• 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 Node backend awareness with startup and recovery support
• Loop and background-control surfaces for ongoing work
• Cross-surface navigation between dashboard and Codex thread views

Interface Preview

Overview Dashboard

Open with a compact summary of active sessions, service health, board state, and high-level workspace signals.

Thread Explorer

Search, group by project directory, inspect metadata, and jump into Codex-linked threads from one native VS Code surface.

Agent Board

Pin important work, keep stopped-but-attached threads visible, and manage card actions directly from the board.

Insights

Review token usage, model activity, tool calls, and session-level summaries across loaded Codex work.

Loop Control

Monitor loop daemon state and background continuation workflows without leaving VS Code.

Current Interaction Architecture

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 built-in local Node backend 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 Node Backend<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 / 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:

• figures/cma-codex-interaction.mmd
• figures/cma-codex-interaction.md

Screenshots

Thread Explorer

Search, group, filter, and inspect Codex threads from a Node-native dashboard.

Agent Board

Keep important work visible with board cards, attached loops, and human-intervention cues.

Insights

Review token, model, and tool-use summaries across loaded sessions.

Loop Control

Monitor loop state and background coordination surfaces without leaving VS Code.

Installation

Install from Marketplace

Search for:

• Codex-Managed-Agent

Publisher:

• harzva

Install from VSIX

code --install-extension codex-managed-agent-1.0.29.vsix

Or inside VS Code:

1. Open Extensions
2. Click ...
3. Choose Install from VSIX...
4. Select the generated package

Local backend setup

The extension starts its built-in local Node backend automatically.

By default it binds to:

http://127.0.0.1:8787/

If that port is unavailable, the extension probes nearby local ports and reports the active backend in the dashboard health line.

Legacy backend rollback

The extension is now Node-native. Users who still need the removed legacy backend should stay on, or locally check out, a build before the Remove Python backend surface change (9622c43) while migrating their workflow.

Development workflow

1. Open this extension folder in VS Code
2. Press F5
3. Choose Run Codex Agent Extension if prompted
4. In the Extension Development Host, run:
   • Codex-Managed-Agent: Open Dashboard

Useful placement commands:

• Codex-Managed-Agent: Open Dashboard
• Codex-Managed-Agent: Show in Sidebar
• Codex-Managed-Agent: Show in Bottom Panel
• Codex-Managed-Agent: Open to Side
• Codex-Managed-Agent: Full Screen
• Codex-Managed-Agent: Move to New Window

Configuration

codexAgent.baseUrl

• default: http://127.0.0.1:8787/
• use this when the built-in local backend should bind to a different URL or port

codexAgent.defaultSurface

• default: editor
• controls the first dashboard placement

codexAgent.smartMode

• default: false
• enables API/model-aware status surfacing such as usage-limit warnings

Commands

• Codex-Managed-Agent: Open Dashboard
• Codex-Managed-Agent: Show in Sidebar
• Codex-Managed-Agent: Show in Bottom Panel
• Codex-Managed-Agent: Open to Side
• Codex-Managed-Agent: Full Screen
• Codex-Managed-Agent: Move to New Window
• Codex-Managed-Agent: Refresh Panel
• Codex-Managed-Agent: Open in Browser
• Codex-Managed-Agent: Start Local Backend

Release workflow

Package locally:

npm run package

Before calling a build release-ready, use:

• SMOKE_CHECKLIST.md
• CHANGELOG.md
• SCREENSHOT_INVENTORY.md

Current status

This extension is still a preview 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

Repository

• Source: https://github.com/Harzva/codex-managed-agent