Skip to content
| Marketplace
Sign in
Visual Studio Code>AI>PerchNew to Visual Studio Code? Get it now.
Perch

Perch

seanahn

|
17 installs
| (0) | Free
Claude Code and Codex agents as tabs, each with its own look, with dictation, usage, and backend switching. A shell, not an agent.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

perch

Claude Code and Codex as tabs in VS Code, in the editor area or the sidebar. Any number of sessions, with usage and backend switching built in; a tab can change vendor in the middle of a task.

  • Continue in the other vendor, or another model — the footer's mark hands the conversation to Codex or Claude as text, a model and effort picked from its menu (switching).
  • A backend per tab — subscription, API / Bedrock or an LLM gateway for Claude; ChatGPT, API key or Bedrock for Codex, each tab's own (logins).
  • Codebase search by meaning — an index per workspace folder and a codebase_search tool for both agents, keywords at once and MiniLM once installed, switched per folder (codebase search).
  • Usage in the footer — the plan's windows or the cost, a panel with the detail, the session's threads and sub-agents, and each turn's tokens under its answer (usage).
  • Permissions as the vendor has them — Claude's modes and Codex's sandbox and approval policy, per tab, with the prompts answered in the tab (permissions).

The working layout: the Explorer, files in the middle, a locked group of Perch tabs on the right, the terminal below

Why: the vendors' own agents, so their caching

perch runs the Claude Code CLI and the Codex CLI themselves, one process per tab, through the vendors' own SDKs. It is a shell around them, not an agent of its own. That is the whole design, and the reason is tokens.

The principle

An agent's token use is a function of prompt caching, and prompt caching is a function of a byte-identical prompt prefix.

An agent sends the whole conversation to the model at every step of a turn: system prompt, tool definitions, every message and tool result so far, then the new step. What keeps that affordable is prompt caching: the part of a call's prefix that matches a recent call is billed at a tenth of the input rate (writing the cache costs a quarter more). On a 100k-token conversation a cached step bills the equivalent of about 10k input tokens; a cold one about 125k. A cache hit needs the prefix byte-identical from step to step, and only the program that lays out the prompt can guarantee that. Claude Code and Codex do. A harness that replaces them with its own loop and its own prompt gets its own caching, its own compaction, and API billing instead of your subscription.

The cache itself is the provider's. On the vendors' own APIs it is the reference. On Amazon Bedrock, which hosts the models rather than proxying the vendors, both vendors' caching works as their own does (measured for Codex on Bedrock: every turn after the first read its whole prefix from the cache), with a lag on the newest options (the hour-long Claude cache only on some models, no 5m/1h breakdown). Behind a proxy such as an LLM gateway, whether the markers survive depends on the route; perch shows what came back, and note 103 says what was measured.

PERCH TAB   (the vendor's agent lays out the prompt; perch never touches it)

  turn 1   [system · tools · conversation so far] [new message]  → cache written
  turn 2   [same bytes, unchanged ................] [new message]  → cache hit, 0.1×
  turn 3   [same bytes, unchanged ................] [new message]  → cache hit, 0.1×

A WELL-BUILT HARNESS   (Cursor, measured on the same model and provider)

  turn 1   [system · tools · conversation so far] [new message]  → cache written
  turn 2   [same bytes, unchanged ................] [new message]  → cache hit, 0.1×   (~96 % read back)
  turn 3   [same bytes, unchanged ................] [new message]  → cache hit, 0.1×

A HARNESS THAT RE-RENDERS CONTEXT NEAR THE FRONT   (Continue, as its source lays it out)

  turn 1   [system · editor state A · @context · history] [message]  → cache written
  turn 2   [system · editor state B · @context' · history] [message] → prefix changed: cache miss, 1×

So the cache is not what separates a shell from a harness: a harness that keeps its prefix stable caches as well as the terminal does. What perch guarantees is narrower: it adds nothing that could bust the vendor's cache, and it keeps the vendor's billing. The rest of the difference is the billing path (a subscription applies only to the vendor's own agent; a harness is API billing by construction) and the agent itself (prompt, tools, compaction, permissions, tool-call style).

Where the difference comes from

  1. Prompt assembly. A harness runs its own agent loop over the vendor's model and writes the editor's state into the prompt (the open file, the selection, @-mentioned files, the workspace tree). Where that lands decides the cache: near the front, where it changes between turns, it invalidates everything after it (Continue's context providers, as its source lays them out); behind a stable prefix, it costs nothing (Cursor, measured). perch never builds a request. The prompt an agent sends from a perch tab is the one it would send from a terminal, so a tab's cache hits are the terminal's cache hits, and a tab costs what a terminal session costs. IDE context in perch is appended to the message, at the end, where it changes nothing that came before.

  2. Compaction and sub-agents. A harness that keeps one growing chat buffer re-sends every raw tool output on every turn until the window is full. The vendors' agents compact on their own judgement, keep CLAUDE.md, memory, skills, hooks, and MCP servers in play, and (Claude Code especially) run searches and other side work in sub-agents whose transcripts never enter the main conversation. A perch tab inherits all of that unchanged, because it is that agent.

  3. Sessions across reloads. perch keeps no transcript of its own. A tab remembers the agent's session id and, after a window reload or a backend switch, resumes that session from the agent's own record (~/.claude/projects/, ~/.codex/sessions/), so the prompt prefix is the same bytes as before. Within the cache's life (an hour on a subscription, five minutes on the API) the earlier turns are still cached; beyond it, the next turn re-warms the same prefix once, rather than a reconstructed one. The sessions list, names, transcripts, and usage gauges are all read from those files and ask nothing of a model.

Side by side

perch Cursor Continue
Agent the vendor's own: Claude Code, Codex, through their SDKs Cursor's own loop and middleware, in a forked editor Continue's own harness, in an extension
Prompt laid out by the vendor's agent; perch adds nothing Cursor's own, closed source; its prefix stays stable in practice rebuilt each turn from @-context providers
Cache behaviour the terminal's: a stable prefix, hits turn after turn the same: ~96 % of each turn read back on turns 2+, measured (Claude Code 95 %) dynamic context in the prefix breaks the match (from its source; not measured)
Cost basis your existing subscriptions and logins; API / Bedrock when you switch Cursor's plans and request credits, or an API key your own API key
Compaction, memory, MCP the vendor's: CLAUDE.md, hooks, skills, MCP, sub-agents Cursor's own indexing and context filters Continue's client-side providers
Cost of a long session that of a terminal session about 10 % more than Claude Code on the same model and provider (twice the tool calls, at cached rates), on Cursor's plans rather than your subscription not measured; its prefix re-rendering says more than a terminal session

The Cursor figures are one controlled measurement (Claude Code and Cursor on Opus 5.5 through Bedrock, the same prompts, one price basis, 2026-10-06); an earlier version of this page said "several times a terminal session" on no source, and a public 5.5× figure turns out to be one run on mixed models with no cache analysis. What perch can show is that a tab's cache reads and costs are a terminal's, turn by turn, in its own footer. The full reasoning, with what has and has not been verified, is in the design notes, 102 and 103.

Tab kind Agent How it runs Auth
Claude Claude Code @anthropic-ai/claude-agent-sdk, streaming input, canUseTool for permission prompts your existing claude login
Codex Codex @openai/codex-sdk, one codex exec per turn on one thread your existing codex login

Installed from the marketplace, perch runs the claude and codex programs that come with the Claude Code and ChatGPT extensions, so those two must be installed as well.

Where tabs live

perch.newTabs decides where a new tab opens.

editor (the default): each session is a native editor tab, like a file. The tab row is the first line: there is no container icon row and no view title above it, because those belong to VS Code's sidebars and an extension cannot remove them. Tabs carry the vendor's icon, can be dragged, split, and reordered, and open beside your editor. The + in the editor title bar opens a new one. A working tab's title ends in …, and a tab waiting on a permission prompt while hidden starts with ●. Closing the editor tab closes the session.

sidebar: sessions are tabs inside the Perch view, under the Perch icon in the activity bar.

Both can be used at once. Perch: Move Tab to the Editor Area and Perch: Move Tab to the Sidebar move the active tab; the session, its agent, and its transcript are untouched. There are Move All versions of both. Tabs saved before this setting existed follow it on the next reload.

An editor group that holds only Perch tabs is locked, the way a terminal's is, so a file opened from the Explorer goes to the group beside it and not in among the sessions. When the last Perch tab leaves a group that still has other tabs, Perch takes the lock off again, so files open there as anywhere else (VS Code 1.92 or later). perch.lockGroup turns both off.

After a window reload VS Code brings the editor tabs back where they were, and each resumes its session.

Tabs

Press + to open a Claude or a Codex tab: in the editor title bar, or in the sidebar view's tab bar. Each tab is its own session with its own agent process, context, mode, draft, and transcript. Open as many as you like of either kind. When a gateway file exists (see Logins), a Claude tab can be put on an LLM gateway: a tab whose Claude Code reaches an Anthropic-compatible endpoint of your own, such as a company's LLM proxy, while the other tabs stay on your login. Paste an image into the message box to attach it: up to eight to a message, each scaled down to at most 1568 px on its long side, the most the API keeps as is. A tab is titled from its first message, or by you (see below). While a session works, the foot of its transcript says what it is doing and for how long. A dot on a tab means it is working; a red dot means it is waiting on a permission prompt. Middle-click or × closes a tab and stops its agent.

Tab icons are the vendors' own, read at runtime from the Claude Code and ChatGPT extensions if they are installed. perch ships no logos. It uses each extension's glyph, tinted as the vendor tints it on its own tabs: Claude's spark in orange, the ChatGPT blossom in the theme's text colour. Without a glyph it uses the marketplace image, and without the extension a letter, C or X.

Answers are drawn as Markdown: headings, lists, tables, code, links. A link to a file opens it in the editor, at its line if it names one. Each code block, and each tool call's command, shows a copy button when the pointer is over it. The transcript keeps to its end as more arrives, until you scroll away to read; scroll back to the end and it follows again. A long tool result is clipped and lets the wheel pass, so scrolling the transcript never catches on one; click it to open it and scroll inside, click again to close it.

Agents start lazily: an open tab costs nothing until you send a message.

Tabs survive a window reload. perch saves each tab's session id and the agent resumes its own saved conversation on the next message. The earlier transcript is read back from the agent's own record of the session: the last thousand entries of it, with images as a count and Codex's sealed reasoning left out.

Names and past sessions

A tab is named from its first message until you name it yourself: run Perch: Rename Active Tab…, or double-click a tab's name in the sidebar.

Perch: Sessions… (the clock icon in the title bar) lists the past sessions of the workspace folder, Claude's and Codex's together, newest first. Type to search. Choose one to open a tab on it, or go to the tab already open on it. The pencil on a row renames that session, open or not. The bin deletes it, after asking: the agent's own record of the session is removed from this machine (Claude Code's by the Agent SDK, Codex's by codex delete), and a tab open on it is closed first. A tab you have not named shows the title its agent's record has, so a tab and its row in the list say the same name.

perch keeps no list or names of its own. It reads each agent's records, and writes a name where that agent keeps names: for Claude, in the session's file under ~/.claude/projects/, through the Agent SDK, which is where Claude Code's own /rename writes; for Codex, as a line added to ~/.codex/session_index.jsonl. So a session named in Claude Code has that name here, and the reverse. A tab named before its first message has no record yet; its name is written when its first turn ends.

Tabs do not share history. Hand off (Perch: Hand Off Last Answer to Another Tab…, in the … menu of the title bar and in the command palette) pastes the active tab's last answer into another tab's input box, or into a new tab. That is the only bridge between tabs, on purpose: shared context would defeat each agent's caching. One tab can change vendor, though: the next section.

Switching between Claude and Codex in a tab

A tab can go on with the other vendor: Claude does the work, GPT-6 Astra reviews it and opens the PR, in the same tab. The left of the footer shows the destination vendor's mark: Claude under a Codex tab, ChatGPT under a Claude tab. Click it and choose a model under Continue on Codex or Continue on Claude. Clicking the model row uses that model's default effort; its › menu pins one of the effort levels that model accepts. Perch: Continue This Tab in Codex… and …in Claude… also switch from the command palette and the title bar's … menu, restoring that vendor's remembered effort when it is valid for the model chosen there. The switch is immediate, and nothing is sent until you send. Only an idle tab switches.

Neither vendor can resume the other's session (the records are each vendor's own, and the reasoning in them is sealed to the provider that made it), so the new agent is handed the conversation as text, ahead of your next message: every message of yours and every reply, in full; each tool call as one line (Read src/a.js, Bash: make test → failed), without its output; no thinking. Tool output is three quarters to nine tenths of a working session, so this is about a tenth of its tokens. A task-sized conversation goes whole; a long one sends its latest turns, and Claude's latest compaction summary, inline, up to about 40K tokens, and writes the whole of it to a file under ~/.cache/perch/handoff/, readable by you alone, which the message names. A divider in the transcript, with the new vendor's mark, says how much goes and from where to where (sent from Claude on your Claude subscription to Codex on your ChatGPT login), as a warning when the conversation leaves an account of your own, Bedrock or a gateway, for a vendor's service; its Preview opens the exact text, until the first message has taken it.

The composer, backend and usage readings, and the editor tab's icon follow the vendor the tab is on; the footer's handoff mark names the other vendor. Each vendor keeps its own model, effort, and mode: a vendor the tab has not used starts on its defaults, one it used before gets back what it had, and a permission mode is never carried across. Switching back resumes the vendor's earlier session and hands it only what the other said since, so Claude's prompt cache is still warm if the detour was short. After a window reload the tab reads both records back, in the order it went, dividers included. A tab that has been on both shows the other vendor's dot beside its mark in the sidebar and the way it went in its tooltip and in the sessions list (Claude → Codex → Claude), where any of its records opens it; a name you give it goes to every record. Each switch is logged in the Perch output channel (View › Output › Perch). The design and the measurements are in note 202.

Setup, step by step

  1. VS Code 1.92 or later. Under Remote-SSH or code-server, connect first and do the rest in that window: Perch, the agents and the index run where the workspace is.
  2. Install Perch from the Marketplace; Perch Audio (dictation's recorder, on the local machine) and the Claude Code and ChatGPT extensions (whose programs Perch runs) come with it. Reload, then Ctrl+Alt+P (Cmd+Alt+P on a Mac).
  3. The layout in the picture. Open a file, start a Perch tab, drag its tab to the right edge of the editor area: a second group. Perch locks a group that holds only its tabs, so files from the Explorer go to the middle group — which must stay unlocked: lock it too and every file opens a third group. + in the Perch group's title bar opens the next session there. It all comes back after a reload.
  4. Log in on the first message to a tab of each kind — Claude's subscription or Codex's ChatGPT login in the browser — or set the backend you want from the footer's menu, which is the tab's own: API / Bedrock with Claude Code's credentials, a gateway from an env file of yours, Codex on an API key or on Bedrock. Logins has each one.

In the picture: the Perch group's tabs and title bar (+ new tab, the clock for past sessions); the transcript with a tool card and the turn's result line; the composer with its tools (+ files, / commands, the context ring, the cache clock, the model pill, IDE context, the permission bolt, the microphone, send); and the footer: the other vendor's mark to continue there, the backend pill, usage, index, sub-agents, and the plan's reading. Every control is numbered and named in note 901, which is the same guide at full length.

Install

From the marketplace: install Perch; Perch Audio, the microphone companion, and the Claude Code and ChatGPT extensions come with it. Log in to each vendor when Perch asks, on the first message to a tab of that kind (see Logins below).

From a checkout:

make install     # npm install, syntax check, symlink into the extension dirs

Step by step, from a bare VS Code to the working layout and a login for each vendor and backend: note 901.

Reload the window, then press Ctrl+Alt+P (Cmd+Alt+P on a Mac): Perch: Open brings back the tab you last used, or, with none open, the sessions list, which starts a new tab of either kind at the top. The same is behind the Perch icon in the activity bar and Perch: New Tab… in the command palette.

Logins

Both agents run on the logins already on the machine with the workspace: Claude Code's (~/.claude) and Codex's (~/.codex/auth.json). Nothing is copied from elsewhere, so a fresh remote has neither.

  • Claude, on a subscription: the first message to a Claude tab on a machine with no login is held back, the text put back in the box, and Log In offered: claude auth login in a terminal, run with the claude the tabs run (perch.claude.executable when it is set), and off Bedrock even when ~/.claude/settings.json sets CLAUDE_CODE_USE_BEDROCK=1 (the Claude Code panel only when no program is found). Perch notices when a new login lands and says so; send the message again. One login runs at a time: pressed again while one waits, Log In brings its terminal back, and closing that terminal ends the wait. On Windows the terminal runs claude itself, with no shell in between, and closes when it ends. The footer's "log in" does the same at any time.
  • Claude, on API / Bedrock: the API switch in the footer moves Claude to those credentials. They are Claude Code's, not Perch's: AWS credentials or a profile on the workspace machine (~/.aws, or AWS_* variables), or ANTHROPIC_API_KEY; the region and model go in the env block of ~/.claude/settings.json (AWS_REGION, ANTHROPIC_MODEL, and the small/fast model if you use one). With none of that in place the first message is held back and the offer opens that file, or switches back to the subscription.
  • LLM gateway: a Claude tab can be put on a gateway, an Anthropic-compatible endpoint reached with ANTHROPIC_BASE_URL and a token, as a company's LLM proxy is. The variables live in a file of yours, ~/.config/gateway-claude/env by default (perch.claude.gatewayEnv), written as a shell reads it: export ANTHROPIC_BASE_URL=…, export ANTHROPIC_AUTH_TOKEN=… (or ANTHROPIC_API_KEY), and any model names (ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, …). The same file can drive a terminal launcher. A tab on the gateway runs its Claude Code process with those variables added to its environment, and that is all: nothing is written to ~/.claude/settings.json, the token is never in a file of Perch's, and the session, its record, your CLAUDE.md, memory, and MCP servers are the same as any other tab's. Put a tab on it from the footer's backend menu under any Claude tab, where the entry reads LLM gateway (or with Perch: New Claude Tab on the Gateway); once chosen, new Claude tabs start there until a tab is put back on the subscription or API / Bedrock. The template also sets ENABLE_PROMPT_CACHING_1H=1: on a token Claude Code would keep the prompt cache for five minutes, after which a turn re-sends the whole conversation at the cache-write rate; the hour costs more per write and less by the first pause over five minutes. Remove the line if the gateway rejects the request. The first message to a tab whose file is missing or incomplete is held back, and the offer opens the file (made from a template, readable by you alone) or takes the tab off the gateway; the two choices stay as buttons under the note. The window's own backend does not matter: with Claude set to API / Bedrock in ~/.claude/settings.json, a tab on the gateway still goes to the gateway, because Perch gives its process the gateway's variables (all but the token) as settings of its own, which Claude Code applies over the user's. A tab on the gateway runs its process through a small relay of Perch's on the loopback interface, which forwards each request to the gateway unchanged and reads the header in which a LiteLLM gateway names the model that answered (x-litellm-model-name); a routed name such as auto may send each request anywhere. The line under each answer then says what answered the turn's requests, via gpt-6-luna ×3, grok-4.6, and what the gateway charged for them, $0.0021 this turn, its own figure (x-litellm-response-cost, summed) in place of Claude Code's estimate at Anthropic list prices, which does not apply to a gateway's names; the tooltip has the session's total by the same reckoning. A streamed response carries no price from the gateway, so a turn is priced at list rates for the model that answered each request (LiteLLM's public price table, fetched weekly) and shown with ≈; the tooltip says so, and gives the token's running total as the gateway counts it. The model button's tooltip names the last model. The agent is still Claude Code; the model is whatever the gateway chose.
  • Codex: the first message to a Codex tab on a machine with no login is held back, the text put back in the box, and the login offered two ways. Log In runs codex login on the workspace machine and opens ChatGPT's sign-in page in your browser; the page returns to a local port, which VS Code forwards to the workspace machine when it is remote, so this works for anyone with a browser. Device Code runs codex login --device-auth in a terminal instead: a link and a one-time code, for a machine with no forwarding, which ChatGPT has to allow first (Settings → Security and login → App security → "Enable device code sign-in"). On Windows that terminal runs codex itself, with no shell in between, and closes when it ends; closing it ends the wait. Either way Perch notices when the login lands and says so; send the message again. A login can also end later: ChatGPT ends the session on a logout, a password change, a revoked session, or when the same login is refreshed on another machine. Give each machine its own login: never copy ~/.codex/auth.json from one machine to another, since the two copies share one session and the first to refresh it ends the other's. When Codex reports its login refused (token_revoked, refresh_token_invalidated, "Your session has ended"), the tab puts the message, and any queued behind it, back in the box, says why under the error with Log In and Device Code, and holds further messages on that machine until there is a new login (or until another Codex there refreshes the file), across window reloads. The login waits for a new auth.json, so signing in again works though the old file is still there. One login runs at a time (it listens on a fixed port): pressed again while one waits, from the note, the notification, or another tab, a button opens the same sign-in page again, or brings back the Device Code terminal; once the login lands, every login note in every Codex tab says so in place of its buttons. On the gateway the model menu is the gateway's own list (GET /v1/models), one entry per model, grouped Claude, OpenAI and routers; the effort menu offers the levels the gateway names (opus-high), and the choice is sent as that name. The default is ANTHROPIC_MODEL. When the gateway does not answer, the menu is the file's names: opus, sonnet and haiku as ANTHROPIC_DEFAULT_*_MODEL map them. A tab moved onto the gateway with another model chosen starts from the file's default. The choice sticks: once a tab is put on the gateway, new Claude tabs start there, until a tab is put back on the subscription or API / Bedrock.

Permissions

Claude: the SDK calls back on every tool use and perch shows Allow / Always / Deny. The request reads as what it is: for an edit, the file and the change as a diff, removed lines then added; for a new file, the file and what goes in it; for a command, the command and what it is for. Deny, like Skip on a question Claude asks, ends the turn and hands it back to you, as No does in Claude Code's terminal; answering a question, with No or anything else, lets Claude carry on. The default mode for new tabs is a setting (perch.claude.permissionMode) and each tab can switch live.

Codex: the SDK runs codex exec, which is non-interactive. Approvals resolve by policy (perch.codex.approvalPolicy) and the sandbox (perch.codex.sandboxMode). There is no per-command prompt.

Codex's sandbox on Linux is bubblewrap, which needs unprivileged user namespaces; a container that forbids them (a JupyterHub pod, say) fails every command with bwrap: No permissions to create a new namespace, and Codex has no other sandbox there. When that happens Perch asks whether to run Codex without a sandbox, for that tab or for every tab on that machine from then on; the choice is remembered by hostname, and such tabs say so when they open.

The composer

Each kind of tab takes its own vendor's look, so a Claude tab feels like Claude Code and a Codex tab like Codex.

Claude tab, left to right:

Tool What it does
+ Pick files and mention them by path, as @src/a.js.
/ Slash commands, read from Claude Code. Typing / opens the same list, filtered as you type; Enter completes.
ring How full the context window is. Amber at 80%, red at 95%.
clock Minutes until the prompt cache goes cold. A message sent before then is billed at the cached rate. One hour on a subscription, five minutes on API or Bedrock, unless you set promptCacheTtl.
pill Model and effort. Opens a menu for both.
bolt Permission mode: Ask, Edits, Plan, Auto, Bypass.
square Send. While Claude is working it becomes Stop.

Codex tab: +, then the sandbox behind a shield (Read only, Workspace, Full access, the last in amber), the model with its effort, IDE context, and a round send button. Codex runs on this machine through the SDK; Codex Cloud tasks are not offered (the SDK has no way to run a thread there), so there is no "Work locally" chooser as in the Codex extension.

ChatGPT apps and plugins in a Codex tab (Gmail, SharePoint, and the rest of ChatGPT's plugin directory) are Codex's own: perch runs codex exec, which takes the plugins installed in the ChatGPT account it is logged in with and the apps connected there. Two things happen outside perch, once, on the machine where the tab's Codex runs (over Remote-SSH, the remote host, as the remote user):

  1. Install the plugin with the same codex perch runs there (the one in the ChatGPT extension when perch's own is not packaged): codex plugin list, then codex plugin add sharepoint@openai-curated-remote. It is recorded in the ChatGPT account and cached under ~/.codex/plugins/.
  2. Connect the app on chatgpt.com, in your browser, signed in to the same ChatGPT account and workspace as that machine's ~/.codex/auth.json. The first call to an app that is not connected shows a note with a Connect on ChatGPT button: the link Codex gives, which its own reply does not show. Microsoft's sign-in happens there; nothing of it passes through perch or the host.

To keep an app read-only, block its tools that say they write, in ~/.codex/config.toml on that machine: [apps.<connector_id>] destructive_enabled = false (SharePoint's id is connector_1e4f6a44acf14e3ca1d96672f8c945bc).

When a Codex turn starts sub-agents, each shows as a line in the transcript when it starts, reports, takes a follow-up task, and finishes (⤷ desktop_audio_transport started), and the line at the foot says how many are working (sub-agents: 2 working, 1 done, each by name in its tooltip). Click that count for a table of them: each one's model and reasoning effort, turns, and tokens, read from the sub-agent's own thread file as it grows; a sub-agent's end line says the same, as does a past turn's when a session is read back, and the line that ends the turn opens to the same table. What they report is encrypted, so only that they reported can be shown. A question Codex asks without waiting shows as a card that says so: the turn carries on, and your answers go to it as your next message, queued behind the turn if it is still working. The SDK streams neither, so perch reads them from the thread's own record in ~/.codex/sessions/ as the turn runs.

For the whole session's usage, click sub-agents in the footer of a tab. It opens a table with one row per thread: the main thread, each sub-agent it started, and the totals. Codex's threads are read from their rollout files, Claude's from the session's file and the sub-agent files Claude Code keeps beside it. Each row has the model and effort, turns, input (the cached part shown too), output, and what those tokens would cost at OpenAI's list prices (LiteLLM's public price table), with each one's share of the session. Click a column to sort the sub-agents by it. The table is read from the session's files when you open it, and again at the end of each turn while it is open. On a ChatGPT plan nothing is billed per token, so the cost says where the work went, not what you pay.

A web search shows what it searched for, or the page it opened or looked in, once it completes, with the pages it found under it. Codex says what a search was only when it ends, so until then the card reads web search … and the foot of the transcript Searching the web.

IDE context, on both kinds of tab, is on by default for new tabs (perch.ideContext) and remembered per tab. The toggle is green when on and grey when off. When on, each message carries the active file and, if there is one, the selection with its line numbers, as the vendors' own panels do. The transcript shows your message with a small tag, the file's name and the lines if any, not the attachment itself. The context is read when you write the message, so a queued message keeps the file that was open then. A Perch tab in the editor area takes the focus while you type, so the file attached is the one last focused, as long as it is still open on screen; the tag on your message says which.

Earlier messages. The arrow keys walk the tab's earlier messages, as a shell does: Up from the first line of the box goes back, Down from the last line comes forward, and past the newest the draft you were writing returns.

Queueing. Enter always sends. While the agent is working, the message is queued behind the current turn and marked so. Claude Code queues it itself; Codex takes one turn at a time, so perch holds the queue and feeds it as each turn ends. The × on a queued message takes it back until its turn starts (its words stay in the box's history: press the up arrow to get them back); once a turn has taken it up, the tab says it was too late. Stop ends the turn and drops what is queued.

Not included: Codex's microphone. A webview cannot open the microphone; Codex does it with a companion extension that records natively. perch could do the same, but dictation also needs a speech-to-text service, which is a choice for you to make.

Model and effort

The model and effort menu opens from the pill (Claude) or the model name (Codex).

The lists come from the agents themselves, so they match your account:

Models from Efforts from Default labels
Claude the Claude Code CLI, asked at startup without sending a message each model's supported levels default · Sonnet 4.6 names the model Claude Code starts on, then the one the session reports
Codex ~/.codex/models_cache.json each model's supported levels default · GPT-5.6-Sol and default · ultra come from ~/.codex/config.toml

The effort list follows the selected model. A model with no effort control says so in the menu, and an effort the new model does not accept resets to default. Perch: Refresh Model Lists re-reads both.

Claude: model, effort, and mode all change live, from the next message. Hover the model selector to see the model actually running.

On default, Claude Code starts on ANTHROPIC_MODEL if it is set, else the model in its settings, else its own default (Opus 5.5 today), and the pill names that model. Once the session runs, the pill and the effort list follow the model the session reports. Choosing default in a running session gives Claude Code's own default, not the model the session started on; the option's tooltip says which is which.

Claude Code itself can move a session to another model. When a model's safeguards refuse a response, it retries the response on a fallback model and keeps the session there: Opus 5.5 to Opus 4.8, say. The pill then names the model running, in the warning colour, with the reason in its tooltip, and Claude Code's notice is in the transcript, also when the session is opened again later. A turn answered by a model other than the one chosen ends its line with answered by Opus 4.8: each response names the model that gave it. A new session starts on the chosen model again.

Codex: model, effort, and sandbox change from the next message too. Codex runs each turn as a process of its own, so perch takes the thread up again with the new choice. Codex itself notes in the transcript when a thread recorded with one model is carried on with another. The sandbox menu also shows the approval policy.

A model chosen by its id rather than from the list, Bedrock's us.anthropic.claude-fable-5-1 or a [1m] form, is named as the catalog names the same model (Fable 5.1 (1M)), offers that model's efforts, and is sent under the name the tab's backend knows it by.

Defaults for new tabs: perch.claude.model, perch.claude.effort, perch.claude.permissionMode, perch.codex.model, perch.codex.reasoningEffort, perch.codex.sandboxMode.

Codebase search

Claude and Codex tabs get one more tool, codebase_search: a question in plain words finds the files that answer it, even when they share no names with it. It is Cursor's codebase index, done the Perch way: a tool the agent calls, so results come after the cached prompt, never into it. The design and the measurements are in note 201.

  • Off by default. perch.codebaseIndex.enabled turns it on, for every workspace or for one; Perch: Toggle Codebase Search flips it. A change reaches each tab from its next message: a Claude tab restarts, after its turn if one is running (its tool list is part of its cached prompt, so the cache starts over once); a Codex tab's next turn is a process of its own anyway.
  • Keywords at once, meaning once installed. Keyword search (BM25) needs only the machine's python3, 3.8 or newer with SQLite FTS5. Search by meaning needs an embedding model, MiniLM, in a private environment of about 300 MB under ~/.local/share/perch/codeindex: Perch offers it once, as the first tab starts, and Perch: Install Codebase Search by Meaning installs it later. A tab's search server moves onto it by itself, without a restart.
  • Every folder of the workspace, in the Explorer's order, each with an index of its own; a folder's own .vscode/settings.json can turn it off or on for that folder alone, and with several folders the results carry full paths. The tool takes a folder to search one of them by name, and returns 8 hits instead of 5 when there are more than two.
  • The index stays on the machine with the code. It is kept in ~/.cache/codebase-index/, outside the repository, private to you, and brought up to date from the files that changed. Under Remote-SSH it is built on the remote, where the agents run; nothing leaves that machine but the one-time download. The first index of a repository of about 1,500 files takes seconds by keywords and a few minutes by meaning, on a CPU, in the background: until then the tool says how far it has got and the agent goes on with grep.
  • What is left out: whatever git ignores, lockfiles, binaries, files over 256 KB, secrets by name, every hidden file and directory of a folder that is no repository (a home directory opened as the workspace: the repositories inside it are each taken by git's own view), and the patterns in a .codebaseignore at the repository root (dir/ for a directory, else a path pattern such as *.min.js). A .codebaseignore that is just * turns search off for that repository; the tool stays, and says so.
  • Codex may need telling. Claude reaches for the tool by itself; Codex, in testing, kept to rg. A line in the repository's AGENTS.md ("use codebase_search when you do not know the names involved") changes that.
  • In a terminal too. The server is Perch's codeindex/server.py; claude mcp add -s user codebase -- python3 <it> or codex mcp add codebase -- python3 <it> gives the CLIs the same tool outside Perch.
  • perch.codebaseIndex.python names the Python to run it on, if not python3.
  • Its switches and its state, in the footer. Under a tab, the index button next to sub-agents opens a table of the workspace's folders: each with its setting, a switch that writes the folder's own .vscode/settings.json, and its index — files and sections indexed, how many sections have vectors, whether it is searched by keywords or by meaning, and whether it is being built. A switch in the header turns search on or off for the workspace, as the command does. The table is read from the indexes' files every few seconds while the panel is open, so a first build shows its counts growing; it only reads, and never starts a build.

Whether it pays depends on the repository, which is why it is off until you turn it on. On a well-documented one of 1,500 files, Claude and Codex found nine answers in ten without it, and the tool cost Claude a step or two a question; it helps where the names in the code are not what you would ask for.

Usage, in the footer

The footer follows the active tab.

Under a Codex tab: a backend menu (ChatGPT, API or Bedrock), the usage button, and the plan's usage: percent remaining and time to reset for the five-hour window and the week. The menu moves Codex between your ChatGPT login, an OpenAI API key and Amazon Bedrock. Choosing the key the first time asks for it and keeps it in VS Code's secret storage, never in a file of perch's; Codex gets it in its environment, per turn, so open tabs move on their next message with nothing restarted. Bedrock uses Codex's own Bedrock provider with the AWS credentials on the machine (a profile, AWS_* variables, or AWS_BEARER_TOKEN_BEDROCK); the region and profile come from perch.codex.bedrock.region and .profile, else from the environment or the env block of ~/.claude/settings.json, where a machine set up for Claude on Bedrock has them. By default Codex goes through the Bedrock runtime's OpenAI-compatible endpoint in your region, with models named us.openai.<model> and the same bedrock:* permissions Claude uses; perch.codex.bedrock.endpoint: mantle uses Bedrock Mantle instead (us-east-1 by default, openai.<model>, its own IAM action). The ChatGPT connector apps are off on Bedrock, where they cannot work; left on, their schemas cost about 25 K tokens a request. The model menu stays Codex's; each name is sent in Bedrock's form. On the key or on Bedrock there is no plan and no limit to show, only per-token billing on that account. Perch: Set OpenAI API Key for Codex… and Perch: Forget the OpenAI API Key for Codex manage the key. Codex records these in its session files after every turn, so perch reads them from ~/.codex/sessions/ and makes no request. The figure is as of the last Codex turn on this machine, from any Codex client, and the tooltip says when that was. A window whose reset time has passed is shown as full again. perch re-reads after each Codex turn it runs.

Under a Claude tab:

  • a backend button, sub, API, or gw. Click it for a menu of three, each this tab's own: subscription (login), API / Bedrock, and LLM gateway (see Logins). The choice goes to the tab's next process as settings of its own, which Claude Code applies over ~/.claude/settings.json, so two tabs can run on different backends side by side and nothing is written to the file. The window's default — what a tab that has not chosen runs on, and what claude in a terminal gets — is env.CLAUDE_CODE_USE_BEDROCK in that file, switched by Perch: Toggle Claude Backend; tabs that follow it come along with the switch, tabs with a choice of their own stay put. Either way a tab's process ends (after its current turn, if one is running) and the next message resumes the same conversation on the new backend, as after a window reload; the prompt cache starts over, being the backend's. A tab on a backend the window is not on shows — for the usage, which is the window's reading, not the tab's. Under a tab on the gateway the button reads gw, with a warning while its file is missing or incomplete, and the gauge shows nothing: the gateway's usage is not reported here, and the line under each answer shows its tokens and which models answered.
  • a usage gauge. On a subscription: percent remaining and time to reset for the 5-hour session, the week, and any model-scoped weekly limit, amber or red when one runs low. On API / Bedrock: the model in use and today's tokens and estimated cost, from the local transcripts. Hover for detail.
  • the usage button, beside index and sub-agents; it and the gauge open the same panel. Under either vendor the panel has the same shape: the backend; the plan as the vendor reports it (ChatGPT names yours, Pro, with its credits; Anthropic's usage endpoint names none, so none is shown); each window with its percent remaining, a word for a low one beside its colour, and its reset time; when the reading was made (a Codex reading is as of the last Codex turn on this machine); refresh, or log in when that is what is missing; a link to the account's usage page; and session breakdown, which opens the sub-agents table. On the API key or on Bedrock it says there are no plan limits, only the account's bill, and under Claude's API / Bedrock it shows the cost estimate, marked as one; through the gateway it says nothing is reported. A stale reading is kept and marked stale. One of the three panels is open at a time; Escape closes it.

This is AI Meter merged into perch. The gauge lives in the footer of each tab; perch puts nothing in the status bar. AI Meter can stay installed for a gauge that is visible whatever editor is open.

Privacy is unchanged from AI Meter. Subscription mode reads the OAuth token Claude Code stores and sends it only to api.anthropic.com/api/oauth/usage. Cost mode makes no network requests. Costs are estimates at Anthropic list prices; Bedrock or partner billing may differ.

Switching models pins: a Bedrock model id saved in the settings file is set aside when you switch to subscription, which cannot use it, and put back when you switch to API. A settings file that is not valid JSON is never overwritten; perch tells you instead.

The usage endpoint rate-limits. When it does, perch keeps the last reading, marks it stale in the tooltip, and leaves the endpoint alone for at least a minute, doubling up to half an hour. Clicking refresh during that pause makes no request.

Settings: perch.meter.mode, pollMinutes, display, showModelWeekly, warnBelow, errorBelow.

Dictation

The microphone in the composer dictates into the message box. Click to start, click again to finish, Escape to discard.

Speech-to-text is Whisper, running locally. Nothing you say leaves your machines. The first use asks to set it up: about 4 GB, into a private environment under ~/.local/share/perch/voice. It needs a python3; one without venv/pip support (Debian and Ubuntu before python3-venv is installed) is fine, pip is fetched from bootstrap.pypa.io into the private environment.

Recording is done by a second extension, Perch Audio, which must be installed on the computer you sit at, because that is where the microphone is:

You work Install Perch Audio on Whisper runs on
Directly on this machine this machine (make install-audio) this machine
From a computer with an NVIDIA GPU, over Remote-SSH that computer (it comes with Perch) that computer, in Perch Audio; only the text goes to the remote
From a laptop with no GPU, over Remote-SSH the laptop the remote machine; the audio goes there

perch.voice.runOn overrides the choice (local or remote). Perch Audio carries the same engine as Perch, so a GPU under your desk is used even when the workspace is a CPU-only container far away.

If no microphone is connected, the button says so. Perch Audio: Choose Microphone picks among several.

Bluetooth ear buds and headsets work too. In their music profile (A2DP) they have no microphone at all, so Perch Audio lists them from the sound server's card list, switches them to the headset profile for the recording (mSBC, 16 kHz, when the device offers it) and back to music when it ends. Music through them pauses for the length of the dictation. A plugged-in microphone is preferred when there is one; pick the headset by name to dictate into it regardless.

The model follows the machine: large-v3-turbo on an NVIDIA GPU, small on a CPU (perch.voice.model names one instead). On a CPU the turbo model's encoder alone takes seconds; small returns a sentence in about one, at a little less accuracy. Setting perch.voice.language (en, ko, …) halves the wait again, because detecting the language is a second pass over the audio.

Verified end to end on 2026-09-30, dictating messages into a tab, on this machine (GPU) and over Remote-SSH to a CPU-only container.

A web address in an error or a note is a link. The other vendor's mark at the left of the footer is only for continuing the tab on that vendor (see Switching); the plan badge under a Codex tab (Plus, Pro) opens your ChatGPT usage page, where limits and credits are managed.

Cost

Both agents run on your subscriptions through their normal logins. This is for personal use on your own machine. Shipping it to other people would require API-key billing under both vendors' terms.

Packaging and publishing

make package builds perch-<version>.vsix, about 8 MB. It carries the two SDKs but not the claude and codex programs they run: those are hundreds of megabytes, and built for one platform. A packaged Perch runs the programs inside the Claude Code and ChatGPT extensions, so those two extensions must be installed where Perch is: they are in Perch's extensionPack, so the marketplace installs them with it, on the workspace side, and either can be removed if only one vendor is wanted. perch.claude.executable and perch.codex.executable name a program of your own instead. In this checkout, installed from npm, the SDKs bring their own programs and those are used.

Install the file on another machine with code --install-extension perch-<version>.vsix.

To publish to the marketplace, as AI Meter is: create the publisher named in package.json, run make login once (or keep the token in ~/.ssh/azure-dev.pat, or put VSCE_PAT=<token> in .env), then make publish. make publish-patch and make publish-minor bump the version, commit, and tag first.

Perch Audio, the microphone companion, is an extension of its own, because it has to run on the computer you sit at while Perch runs with the workspace. Perch names it in its extensionPack, so installing Perch from the marketplace installs Perch Audio too, each on the machine it belongs on. make publish publishes Perch Audio first if its version is new. Installed from a .vsix file, Perch does not fetch it: build it with make package-audio and install that file as well.

Layout

  • src/extension.js — the view, sessions, tab state, persistence, commands
  • src/claudeAgent.js — Claude Agent SDK session, no VS Code dependency
  • src/gateway.js — the gateway file: reading it, what makes it usable, the environment a tab gets; no VS Code dependency
  • src/relay.js — the loopback relay a gateway tab's process goes through, which reads which model answered; no VS Code dependency
  • src/codexAgent.js — Codex SDK thread, no VS Code dependency
  • src/models.js — model catalogs read from the agents, no VS Code dependency
  • src/meter.js — Claude usage, cost, and the backend switch, no VS Code dependency
  • src/binaries.js — where the agents' programs are: the SDK's own, or the vendor extension's
  • src/codexMeter.js — ChatGPT plan usage, read from Codex's session files
  • src/markdown.js — an answer's Markdown, drawn as DOM nodes; written into the page as source
  • src/sessionStore.js — past sessions and their names, read from and written to the agents' own records
  • src/handoff.js — a tab's conversation as text the other vendor's agent can read, for a switch; no VS Code dependency
  • src/meterHost.js — polling, the backend switch, login
  • src/voice.js, src/voiceHost.js — the speech-to-text engine, and dictation
  • voice/server.py — Whisper behind JSON lines
  • src/codeIndex.js — codebase search's Perch side: the Python it runs on, the server a tab gets, the install of search by meaning
  • codeindex/indexer.py, codeindex/server.py — the codebase index (BM25, and vectors when installed) and its MCP server
  • audio/ — Perch Audio, the recording companion, an extension of its own
  • src/webview.js — the page: tab bar, per-tab panes, compose box
  • test/meter.test.js — usage, cost, and the switch, against throwaway home directories
  • test/codexMeter.test.js — Codex usage, against throwaway session directories
  • test/markdown.test.js — what each construct becomes, and that nothing written becomes markup
  • test/sessionStore.test.js — listing and naming, against throwaway directories and a fake Agent SDK
  • test/handoff.test.js — the handoff text, against made-up transcripts and a throwaway Claude config directory
  • test/models.test.js — catalog parsing, no model calls
  • test/voice.test.js — the engine, against a stand-in server
  • test/codeIndex.test.js — codebase search's install and server choice, against a stand-in Python
  • test/codeindex_test.py — the index and the MCP server, against throwaway git repositories, no model
  • audio/test/recorder.test.js — the recorder, with a library that plays back frames
  • test/host.test.js — host logic against a stubbed VS Code API, no model calls
  • test/page.test.js — the real page script in a DOM, no model calls
  • test/harness.mjs — one live turn through each agent, uses your logins

make test-offline runs everything except the live harness. make test runs all of it.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft