Codexa — VS Code Extension

AI-powered agentic coding assistant with full Cursor/Kilo-style capabilities, routing all model calls through the Codexa LiteLLM billing proxy.

Demo

Screenshots

Chat sidebar

Agentic task in progress

Diff review

Installation

From the VS Code Marketplace

Search for Codexa in the VS Code Extensions panel, or install directly:

ext install codexa.codexa-vscode

From a .vsix file

code --install-extension codexa-vscode-0.1.0.vsix

Features

• Agentic loop — reads files, edits code, runs commands, observes output, and iterates autonomously
• Full repo context — explores your workspace, searches across files
• Terminal integration — runs build commands, tests, and scripts; captures stdout/stderr
• Multi-file edits — creates and modifies files across the project in one task
• Billing gate — 402 (no subscription) and 429 (quota exceeded) surface as VS Code notifications with one-click upgrade
• Single API key — no provider selection; just your Codexa key

Getting Started

1. Install the extension from the Marketplace
2. Click the Codexa icon in the activity bar
3. Open Settings and enter your Codexa API key and base URL
4. Start a task — for example: "List the files in this project"

Get a Codexa API key from the billing dashboard.

Configuration

The API key is stored securely in VS Code's SecretStorage (system keychain).

Models

All requests route through the Codexa LiteLLM proxy. Available models depend on your plan:

Billing Errors

The extension surfaces billing errors from the LiteLLM proxy:

Clicking Upgrade Plan opens the Codexa billing dashboard in the browser.

Local Development

Prerequisites

• Node.js 18+
• pnpm
• VS Code 1.90+

1. Install dependencies

pnpm install

2. Build the extension

pnpm --filter @codexa/vscode build

3. Launch in Extension Development Host

1. Open packages/codexa-vscode/ in VS Code
2. Press F5 to launch the Extension Development Host
3. A new VS Code window opens with Codexa installed
4. Click the Codexa icon in the activity bar
5. Enter your API key in Settings

4. Start local Codexa stack

docker compose up -d

Then send a message in the Codexa sidebar: "List the files in this project."

5. Refresh Marketplace screenshots

The screenshots in assets/screenshots/ are rendered from the live webview HTML and CSS using a headless browser. Run this whenever the UI changes to keep the Marketplace listing in sync:

# Install Playwright browsers once (only needed on a fresh checkout)
pnpm --filter @workspace/e2e exec playwright install chromium

# Capture all three screenshots
pnpm --filter @codexa/vscode screenshots

The script (scripts/capture-screenshots.mjs) launches a headless Chromium, loads media/main.js and media/style.css in a standalone page (no VS Code required), steps through three UI states (chat idle, agentic task in progress, diff review), and writes 01-sidebar-chat.png, 02-agentic-task.png, and 03-diff-review.png to assets/screenshots/.

To replace assets/screenshots/demo.gif with a genuine VS Code screen recording, follow the step-by-step instructions in RECORDING.md.

Packaging for Distribution

pnpm --filter @codexa/vscode package

Produces codexa-vscode-0.1.0.vsix.

Architecture

packages/codexa-vscode/
├── src/
│   ├── extension.ts            # Activation point; registers sidebar + commands
│   ├── CodexaViewProvider.ts   # Webview lifecycle, SecretStorage, routing
│   ├── CodexaAgent.ts          # Agentic loop: chat → tool calls → observe → repeat
│   ├── api/
│   │   └── LiteLLMClient.ts    # OpenAI-compatible streaming client, billing errors
│   └── tools/
│       ├── index.ts            # Tool registry + dispatcher
│       ├── readFile.ts         # Read workspace files
│       ├── writeFile.ts        # Write/create files
│       ├── createDirectory.ts  # Create directories
│       ├── executeCommand.ts   # Run shell commands via child_process
│       ├── listFiles.ts        # Directory listing
│       └── searchFiles.ts      # Text search across files
├── media/
│   ├── main.js                 # Webview JavaScript (vanilla, no framework)
│   └── style.css               # Webview styles (VS Code theme-aware)
└── assets/
    ├── icon.svg                # Activity bar icon
    ├── icon.png                # Marketplace listing icon (128×128)
    └── screenshots/            # Marketplace listing screenshots (embedded in README)
        ├── 01-sidebar-chat.png
        ├── 02-agentic-task.png
        └── 03-diff-review.png