Chepio Agents for VS Code

Connect Codex and Claude Code through your installed CLIs for personal local use, with independent project conversations. Open the Chepio tab (CT icon) in the right sidebar, follow a full-height chat above a separate composer, tool activity, approval requests and reported model. The header opens Agents, New Chat, Current Processes and settings. The editor stays available for your code.

To display the brand icon instead of the tab label, run Chepio: Show Sidebar Icons. VS Code applies this display mode to all tabs in the secondary sidebar. The native tab uses a COLR/CPAL icon font to preserve the original blue and dark background. The extension listing uses the full-color PNG. To regenerate the font after changing the brand artwork, run scripts/build-brand-font.py with build-only fonttools==4.68.0 (MIT).

Until a validated CMIE benchmark generation exists, fixed rules choose the model for each request and the chat labels that choice as provisional, not measured. An installed, validated generation replaces the rules with strict evidence-based routing. Existing manual conversations remain usable. See runtime contracts and limits.

0.6.2 changes

• When a model needs usage credits, Chepio now steps down to the next weaker model and keeps going until one accepts the request. It never switches to a stronger model and tries each model once, before any reply or action.
• Claude Fable models count as the most capable tier, so regular tasks no longer start on them.
• A model-access error after Claude Code's "requesting" status now triggers the switch instead of failing the chat.

0.6.1 changes

• Parallel commands no longer stop a chat with "Invalid or excessive Codex requests". Each process keeps up to sixteen pending approvals and questions; another chat cannot use its allowance. A request beyond the limit is declined with an explanation, and the chat continues (ADR-0030).
• Permission requests show the action, exact command, file and folder; the original parameters stay under Technical details. Waiting for your decision no longer counts toward the turn timeout.
• Always allow approves action requests for the selected running process only and resets when it ends.
• Prompt history at the top lists every prompt of the chat. Thinking summaries are saved and grouped per turn.
• If a model needs usage credits or is unavailable, Chepio tries one other eligible model before any work starts.

0.6.0 changes

• New chats run a provisional model chosen by fixed rules: short questions prefer a fast model, regular tasks a balanced one and complex tasks the most capable signed-in model with remaining capacity (ADR-0027).
• After an extension update, an older background runtime is replaced automatically before the next message; one that is still running agents asks first (ADR-0028). This fixes "Runtime disconnected" when a runtime from an earlier version was still running.
• Delete on a Current processes card removes an inactive chat from Chepio memory (ADR-0029).
• The canvas has no bottom bars; zoom with a trackpad pinch or Alt+scroll, or press +, − or 0 while it is focused.
• Files from a refused request stay in the draft and no longer block later messages in that chat.

0.5.0 changes

Native Claude/Codex questions share a stepwise bottom sheet. Answers retain Markdown structure; tool calls are grouped by turn with visible progress. New Chat preserves running work, Current processes links local branches and chats, and Add agent is in Settings. Prepared Agents cards now ship with the current read-only model catalog.

The cards were absent from the 0.4.0 source commit because their redesign remained in an uncommitted worktree; changing the version alone could not include that work. This version includes the ported implementation. File/image input and image previews use private snapshots and explicit capability checks; details and unsupported native features are listed in chat capability coverage.

Install and start

Requires desktop VS Code 1.143 or newer, on macOS/Linux or connected to a Linux Dev Container. Packages are platform-specific: macOS ARM64/x64, Linux ARM64/x64 and Alpine ARM64/x64.

The Marketplace extension ID is chepiotech.chepio-agents. Install by ID for automatic Marketplace updates, or use a matching VSIX for a local build.

# Either command installs from Marketplace:
chepio install-vscode
code --install-extension chepiotech.chepio-agents

# Direct installation from an existing local package:
chepio install-vscode --vsix /path/to/chepio-agents-darwin-arm64-0.5.0.vsix
# Or use VS Code's own installer:
code --install-extension /path/to/chepio-agents-darwin-arm64-0.5.0.vsix

The Chepio terminal menu also offers Install extension for VSCode. --code /path/to/code selects a launcher; CHEPIO_VSCODE_CODE and CHEPIO_VSCODE_VSIX also work from the menu. Without an override, the installer uses code (code.cmd on Windows), with the standard macOS application path as a fallback. It never launches a shell or forces a downgrade. Windows can install a Linux remote package through VS Code; running the bundled runtime on Windows is not yet supported.

1. Install Codex and/or Claude Code on the VS Code workspace host. Set their executable paths in Chepio settings if they are not on the editor's PATH.
2. Open Chepio in the right sidebar or run Chepio: Open Chat. With no connected agents, a welcome page replaces the chat and composer.
3. Choose Add Codex or Add Claude Code. Codex opens its official browser flow and updates the view after completion. Claude Code opens its native sign-in terminal and browser; finish there, then select Finish sign-in (or close the completed terminal). Cancel stops the pending connection. Use an existing CLI sign-in verifies and reuses a login you already have.
4. After a verified connection, chat appears. Adding an agent creates no worktree and sends no model request. Open Agents to see your account, inspect the read-only model catalog, or check usage. There is one connection per provider on this host; signing in again changes the shared native CLI account.
5. Send your first message from a trusted open project folder. With multiple folders, choose the project. Connected providers can contribute to the same conversation; each chat retains its own history. Each reply notes which model was chosen and why, or the reason execution is unavailable. Eligible execution uses that directory, existing files and native project instructions without creating a branch or worktree. Older manual/worktree chats remain under Conversations on Agents.
6. New Chat opens an empty draft without stopping other processes. Its first task receives a name from your message. A parallel launch proposes a feature/fix branch and requires confirmation before creating a separate worktree. That folder starts from committed HEAD, without uncommitted changes or ignored local instructions.
7. Current Processes opens a canvas of local branches and associated chats. Click a process to return to its chat; Open workspace opens its working folder separately. Dashed lines indicate the shared project, not merge ancestry. Pinch on a trackpad or hold Alt and scroll to zoom around the pointer; with the canvas focused, +, − and 0 zoom in, out and reset. Delete removes a stopped chat after confirmation: its messages and attachments leave Chepio memory, a clean worktree folder is removed, and its branch and commits stay. A worktree with uncommitted or untracked changes keeps the chat until you commit or discard them.
8. Enter sends; Shift+Enter inserts a newline. Drafts are retained per conversation. The same composer button becomes Stop response while sending or working; stopping terminates the process tree and preserves history and workspace. Approval requests appear below the conversation. Structured questions slide up in a bottom sheet: answer each question, use Back/Next, then send all answers together. Hiding the sheet keeps the request pending; Cancel questions sends an explicit cancellation.

Models and usage

Agents displays the CLI-reported account email, plan and sign-in method when available, plus its model catalog. A catalog entry is not a guarantee of access; the CLI checks that when a model turn starts. No hardcoded model list or paid availability probe is used. Missing catalog or capacity evidence cannot enable automatic execution.

Codex reports usage through its official account methods. Each window shows the actual provider period (for example, 5 hours or a week), percentage remaining and used, reset time and observation time. These are not calendar-day allowances. Refresh usage fetches account metadata again without starting a model turn.

Claude Code supplies Session (5hr) and Weekly (7 day) through its native usage metadata, so both bars can appear before you start a conversation. Additional supported windows appear when reported. Opening Agents or using Refresh usage fetches the account snapshot, including activity in other clients, without a model turn. This CLI method is experimental; if unavailable, update Claude Code or use Open official Usage. Conversation observations remain a fallback. The newest observation wins; missing or expired values never become an invented 100% allowance. Old conversation observations are excluded after extension restart or a detected sign-in change. Usage failures do not prevent recording a chat request, but unknown capacity prevents automatic execution.

The runtime continues when the chat or VS Code closes. Reopening Chepio reconnects to it. Chepio: Stop Runtime and All Agents explicitly shuts it down. It is not registered as a system service and does not restart after reboot. After a runtime crash, interrupted turns are marked for review; they are never automatically repeated.

On Agents, CLI reports is the last model ID reported by the executor. Configured … · not yet reported is a request/default, not proof of the actual model. Each reply shows its provider's installed extension icon and the model reported at that point in the conversation. When the icon is unavailable, the label reads Codex (model) or Claude Code (model); without model evidence it says model not reported. Replaying history preserves earlier model labels. Icons are read locally from installed official extensions, never downloaded or bundled by Chepio. Only provider-emitted reasoning summaries are displayed; hidden or encrypted reasoning is never inferred. The preview retains legacy manual sessions and gates shared-chat execution on CMIE evidence; it does not yet decompose a task, assign subtasks or automatically merge their changes.

The chat starts with the conversation; account status and workspace links remain on Agents. Opening or selecting a chat focuses its message field and preserves the draft. Background replies and account refreshes leave your current keyboard focus alone. The history scrollbar ends above the composer, including when drafts or approval requests grow. Long conversations mount only the visible rows and a small surrounding buffer (at most 80 rows); other rows are created on demand during scrolling. Collapsed tool payloads are created only when expanded. The native event transport still uses its existing bounded pages and cache.

Rich messages

Assistant responses retain headings, bold text, lists, code, tables and explicit links. Inline code and commit hashes use orange emphasis. Commands are grouped into one expandable activity block per turn, with counts for running, completed, failed or interrupted actions. Nested output stays collapsed until requested. The work indicator distinguishes thinking, command activity, permission waiting and unanswered questions. Plans, diffs, native tool results and returned images have dedicated interpretations. See the capability matrix for the supported native messages and explicit limitations.

File attachments

Use the paperclip below the message field to select files, or paste/drop them into the composer. Attach up to four files of 20 MiB each, inspect their names and sizes, and remove any before sending. Enter sends; Shift+Enter inserts a new line. Failed or refused requests keep their draft and attachments.

Provisional model selection sends images, documents and other files; it refuses audio, video and media generation. With a validated CMIE generation, the selected model, client and tools need verified support for the input format and requested result; reading an image does not imply image generation. The chat explains every refusal. Native raster input is supported by the transport; other formats use private file references and require verified tools. See attachment behavior and limits.

Dev Containers

Include the extension ID in .devcontainer/devcontainer.json:

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "customizations": {
    "vscode": {
      "extensions": ["chepiotech.chepio-agents"]
    }
  }
}

VS Code selects the Linux/Alpine package for the container's architecture and runs Chepio in its workspace extension host. Install Git and the desired Codex/Claude Code CLI inside the container, then authenticate there through the CLI. Chepio never copies host credentials. Use a persistent volume for the runtime home if conversations should survive container recreation; set the machine-scoped chepioAgents.home in remote user settings to a directory outside the Git repository. Rebuilding or stopping the container stops its processes; closing only the editor leaves them running while the container remains alive.

For a local build, use Extensions → … → Install from VSIX in the connected container window with the matching Linux/Alpine artifact. A local macOS VSIX cannot run in a Linux container. VS Code Dev Container customization.

Appearance and updates

The header gear opens settings with an Agents → Add agent section, the running extension version, Appearance and Check for updates. Chepio Light and Chepio Dark use the canvas colors, mesh gradients and grid from chepio.tech; Follow VS Code selects the matching scheme. High-contrast editor themes retain native colors and omit decoration. Advent Pro is bundled locally under SIL OFL 1.1, including Cyrillic; tool output and filesystem paths remain monospace. The font's license is included under media/advent-pro/OFL.txt and in the third-party notices. The original logo blue #0d67a5 remains the composer focus glow and send button color. User message text is logo blue in light mode and light blue in dark mode; agent replies are dark green in light mode and lime in dark mode. Native high contrast overrides both for readability.

Opening the gear checks Marketplace for a newer stable release compatible with the current editor version and host platform; successful checks are cached for five minutes. Offline and unpublished states are shown explicitly. Update to … delegates the exact checked version to VS Code's built-in installer; after success, Reload VS Code activates it. Reloading detaches the UI and keeps the runtime running. VS Code's own automatic extension update settings continue to apply. There is no custom binary download or executable replacement in the extension.

Settings

All settings use the chepioAgents prefix. Runtime settings have machine scope and cannot be overridden by a project to substitute an executable. Appearance has application scope and does not change the editor theme.

After upgrading from an earlier runtime, stop the old runtime with Chepio: Stop Runtime and All Agents when its work is finished, then reconnect to enable shared project conversations. Reloading the extension alone keeps the previous runtime alive. Restart the runtime to apply executable, process-limit or timeout changes. Restart the extension window after changing home. If a CLI cannot start, check its executable with --version and select a working absolute path. Chepio does not repair global installations or copy credentials. Remote SSH, WSL, browser VS Code and native Windows runtime execution remain unsupported.

Privacy and limits

History and previously created worktrees live under <home>/agent-runtime. A first non-concurrent conversation works in the open project; confirmed parallel launches use separate worktrees. A shared conversation excludes other Chepio writers in that workspace while a process owns it; unrelated external programs remain outside this guard. History is plaintext private local data; CLI-owned transcripts can also exist in the executor's own storage. Messages and project content can reach the configured CLI's provider under its own authentication and policies. A worktree isolates concurrent edits, not arbitrary programs. Only use trusted projects and trusted CLI configuration, including plugins, hooks and permission rules.

Chepio preserves normal CLI permission checks and forwards supported requests. Codex uses untrusted approval policy, workspace-write sandbox and user review; Claude uses default permission mode. No bypass flags are used. Actions the CLI already permits need not produce a UI approval. Unsupported interactions and approval details too large to display are refused. Disconnecting the UI leaves approvals pending; waiting for your decision pauses the turn deadline. Always allow resolves pending and future action requests only for the selected running process. Questions still require answers. The switch resets when the process ends and does not change other chats.

Limits: 64 retained sessions, 8 MiB text / 30,000 events per session, 64 MiB total text, 1 MiB local socket frames, 16 MiB provider frames for bounded image payloads, sixteen combined pending interactions per process, 32 KiB of full approval details and 64 KiB of total pending data per process. Structured questions have their own typed 32 KiB limit; they do not use the permission-display limit. Pending-request overflow declines/cancels only the new request and explains how to continue; history limits stop work and retain history. There is no automated retention deletion; Delete on the canvas removes one stopped chat at a time. A truncated/corrupt history file stops runtime startup for manual recovery; it is not silently rewritten. SIGTERM and explicit shutdown terminate owned process groups; an uncatchable daemon kill can leave orphaned tools and requires inspection before resuming.

Build and verify

From the repository root:

cargo build -p chepio-orchestrator --locked
npm --prefix vscode-extension ci --ignore-scripts
npm --prefix vscode-extension test
python3 tests/test_agent_runtime.py
python3 tests/test_shared_conversation.py
npm --prefix vscode-extension run test:host
python3 tests/test_vscode_build.py
python3 vscode-extension/scripts/prepare-runtime.py
npm --prefix vscode-extension run package -- --target darwin-arm64
# Output: publications/vscode/0.6.1/chepio-agents-darwin-arm64-0.6.1.vsix
python3 tests/test_vscode_package.py

test:host uses an isolated VS Code profile, temporary Git repository, temporary data home and fake CLIs. Set VSCODE_EXECUTABLE_PATH to an existing VS Code executable to avoid downloading the test editor. On macOS its path is /Applications/Visual Studio Code.app/Contents/MacOS/Code. On headless Linux run the host tests under xvfb-run -a. prepare-runtime.py --target <Rust triple> builds that target and verifies its native executable header before packaging. It remaps the builder's home directory to ~ in embedded source paths. --binary <path> accepts an already-built binary with the same checks; build it with the same --remap-path-prefix, because package tests reject absolute home paths. Static musl builds can serve both Linux and Alpine; the script rejects an ELF interpreter for those packages. The sidecar records the target and SHA-256, checked against the VSIX target during package tests. Never label an ARM binary as x64.

This version is approved for personal local use. Commercial distribution needs a separate authentication decision; see ADR-0022.

The Package VS Code extension workflow builds the six platform variants and uploads artifacts for review. It does not publish. After owner approval, publish each reviewed VSIX through vsce publish --packagePath <artifact.vsix> using the chepiotech publisher; publisher access must be established separately. Do not put Marketplace credentials in the repository.

To inspect the same fixture interactively, set CHEPIO_UI_REVIEW=1 when running host tests. The test log prints the preview's temporary path; create its continue file to close it and clean up, or close the test window. This mode pauses for up to 30 minutes after assertions pass and never calls real models.

Validation on 2026-10-28: deterministic runtime/adapter tests and VS Code 1.143.1 extension-host tests with fake CLIs on macOS arm64, including first-run welcome gating, adding without worktrees, first-message send without a branch prompt, account/model/usage display, real webview layout, 5,000-message virtualization, lazy tool expansion, historical reply identity, autofocus, draft isolation, settings/update states, theme persistence and bundled font loading. Native OAuth exchanges are not exercised by these tests. A separate metadata-only manual check on Claude Code 2.1.170 returned both real subscription windows on 2026-10-28 without a model prompt. A disposable Alpine ARM64 Dev Container (Dev Containers CLI 0.89.0) passed runtime/client conversation, model, denial and shutdown checks using fake CLIs. This does not establish remote extension-host UI acceptance or Marketplace auto-installation before first publication. Initialization-only handshakes passed against Codex 0.163.0-alpha.10.2 and Claude Code 2.1.170 in temporary unauthenticated homes. Protocol definitions were also checked against the installed clients. Authenticated model turns remain a separate, owner-approved acceptance check; fake tests do not prove account access or compatibility with every CLI release.

The collapsed Prompt history at the top shows the first line of the initial request. Open it to browse every prompt in this chat, in order, fifty per page. Emitted Thinking summary fragments are saved and grouped per turn. Commands awaiting permission show their action, exact command, target and folder; original parameters remain under Technical details. Errors explain the cause and keep the original diagnostic available.

If a model rejects a new turn for access or usage credits, Chepio steps down to the next weaker eligible model from the current CLI catalog, and keeps stepping down until one accepts, before any reply, tool event or interaction. It never switches to a stronger model, tries each model once per request, records every switch in the same chat and never repeats started actions. Unavailable models are skipped in that chat for five minutes; a failed chat refreshes catalogs before the next request. This does not purchase credits or update your global CLI installation. A compatible runtime is required for these controls; protocol 2 replaces older idle runtimes through the existing runtime-upgrade flow.