Agent Shells
Launch and manage Claude, Codex, and opencode sessions in VS Code editor
terminals. Sessions open as editor tabs, survive window reloads, and come back
with their titles and activity in the Activity Bar view.
Features
- Native terminal sessions: Each agent runs in a real VS Code editor
terminal, so scrollback, wheel scrolling, and text selection behave exactly
as in a normal terminal.
- Sessions survive reloads: Reloading the window reconnects the live agent
process. Quitting VS Code ends the agent, and the next launch resumes the
same conversation in its original working directory.
- Live session view: The Activity Bar lists every active session, with a
spinner while the agent works, an attention icon while it waits for your
approval or input, and a title generated from the first prompt.
- Past Sessions: Resume any previous Claude, Codex, or opencode session
from the history picker. The trash action hides an unwanted entry without
touching provider data.
/usage dashboard: A terminal-style editor tab shows Claude and Codex
token usage, limits, and credit state from local provider records, refreshed
every minute.- Full session control: Rename, close, interrupt, and copy session IDs from
the view. Ctrl+C interrupts the running agent. A second Ctrl+C within one
second closes the session. Option+Command+C copies all selected session IDs
from the view, or the active one while a managed terminal is focused.
- Phone supervision (experimental): A paired iPhone on the same Wi-Fi lists
your sessions, reads their transcripts, and can send a prompt or answer a
Codex or opencode permission request. A phone prompt reaches the agent the
same way your keyboard does: Codex through its local protocol, opencode
through its own server when the extension launched the session, and both
Claude and an opencode session without a known server port as text pasted
into their own terminal followed by Enter. A Claude prompt first clears up to
64 lines of draft already typed in the Mac composer, so a draft left there is
never submitted alongside it. See the
agentShells.experimentalLocalWifiSupervision setting below.
- Read-only: The extension reads provider transcript stores and never
modifies them.
Requirements
- VS Code 1.85 or newer
- macOS, Linux, or Windows
- The CLI for each agent you use:
claude, codex, or opencode, reachable
from the login shell
- Node 22.13 or newer for opencode history (it reads the opencode SQLite store
through
node:sqlite; on older hosts history is empty and everything else
keeps working)
Quick Start
- Install Agent Shells from the Marketplace.
- Click the Agent Shells icon in the Activity Bar.
- Select the Claude, Codex, or opencode symbol to start a session.
- Select
/usage to open the usage dashboard.
Commands
| Command |
What it does |
Agent Shells: Start Claude |
Launch a Claude session in a terminal editor tab |
Agent Shells: Start Codex |
Launch a Codex session in a terminal editor tab |
Agent Shells: Start opencode |
Launch an opencode session in a terminal editor tab |
Agent Shells: Past Sessions |
Open the history picker for previous sessions |
/usage |
Open the usage dashboard |
Agent Shells: Rename Session |
Set a custom session title |
Agent Shells: Close Session |
End a session and remove its row from the view |
Agent Shells: Interrupt Active Session |
Interrupt the agent; a second Ctrl+C within one second closes the session |
Agent Shells: Copy Session ID |
Copy the selected provider session identifiers |
Agent Shells: Pair iPhone |
Show a QR code and confirmation code to pair a new iPhone |
Agent Shells: Revoke iPhone |
Pick a paired iPhone and revoke its access |
Every pairing outcome, approval decision, and connection refusal writes one
reasoned line to the "Agent Shells" output channel (View: Output, then pick the
channel), so a phone that only sees a closed socket still leaves a readable
record on the Mac. Every routed phone request also writes one line: a completed
request at info level with its action, latency, and frame size, a failed one at
warning level with its status and reason. State events sent to the phone,
frames refused for size, and connector disconnects between windows each write
one reasoned line as well.
The two iPhone commands appear in every window while
agentShells.experimentalLocalWifiSupervision is on: only one window owns the
local Wi-Fi listener at a time, but every window can ask it to pair or revoke.
Clicking Pair iPhone in a window already paired with a device shows "already
paired" with a Revoke button instead of a QR; clicking it before any window has
finished winning the listener shows a message asking you to try again in a few
seconds. The flag is read once when the extension activates, so after turning
it on or off, reload each open window (Developer: Reload Window) for the
change to take effect.
Settings
| Setting |
Default |
Description |
agentShells.semanticMetadataModel |
codex-luna |
Model that generates session titles |
agentShells.semanticMetadataFallbackModel |
opencode-deepseek-v4 |
Model used when the primary title model cannot run |
agentShells.experimentalCodexAttention |
true |
Show an attention icon while Codex waits for approval or input |
agentShells.experimentalRemoteSupervision |
false |
Experimental, disabled by default. Exposes session titles, activity, semantic state pages, and explicit actions to other local windows through an owner-only Unix socket with no network listener; never terminal bytes, file paths, or provider identifiers. A gap or overflow forces a fresh snapshot. |
agentShells.experimentalLocalWifiSupervision |
false |
Experimental, disabled by default. Lets a paired iPhone on the same Wi-Fi supervise selected windows through the elected window's authenticated, encrypted TCP listener. Pair a device with Agent Shells: Pair iPhone, which shows a QR code; revoke access with Agent Shells: Revoke iPhone. A paired phone can type into your agents: a prompt it sends is written to that session's provider process, clearing up to 64 lines of draft already in a Claude terminal first and going through a launched opencode session's own TUI server. The connection carries only opaque identifiers, semantic state, and prompt text; no terminal output. |
Privacy
Agent Shells runs locally. It reads Claude, Codex, and opencode transcript
stores on your machine and modifies only its own extension state. Title
generation sends the first prompt through your installed CLI, exactly as a
normal agent session would. With local Wi-Fi supervision enabled, a phone you
paired can send prompts and permission answers into your running agents; the
extension writes that text to the agent process and nowhere else. The extension
itself makes no external calls; your agent CLIs connect to their own services
under your accounts.
Development
The module map, architecture notes, and the full check suite live in
DEVELOPMENT.md.
Change Ledger
CHANGELOG+.md records why each shipped change exists. Add a draft entry
before a behavior, contract, stored-state, or build-path change when the intent
is not clear from the diff: - [DRAFT] [YYYY-MM-DD] Type: sentence. Type is
Added, Changed, Fixed, or Removed; the sentence states the outcome in one
checkable line. Keep entries newest first. An entry drops [DRAFT] when the
change ships. Record the intent date; Git records the commit date.
License
MIT
| |
