Opico Agent

A full-stack, autonomous AI coding agent built as a VS Code extension

Overview

Opico Agent is a fully autonomous AI coding assistant that lives inside your VS Code sidebar.

Powered by the Vercel AI SDK, it utilizes a custom-built streaming agent loop to iteratively explore your codebase, execute commands, and refactor files. Whether you prefer Anthropic, OpenAI, Google Gemini, or a local open-source model, Opico Agent adapts to your workflow with a polished React UI, real-time diff previews, and a safe command execution gate.

✨ Features

• Autonomous Multi-Step Execution: Give the agent an objective, and it will iterate up to 25 times per session—chaining tools, reading context, and verifying results autonomously.
• Provider Agnostic: Out-of-the-box support for the leading AI providers plus 50+ pre-configured models. Easily plug in any OpenAI-compatible endpoint for local offline inference (e.g., Ollama, LM Studio).
• File Mention Autocomplete (@): Instantly pull files or folders into the LLM context using @ in the prompt box, backed by a fuzzy scoring engine and smart .gitignore filtering.
• Persistent Branching History: All conversations are saved natively to VS Code. You can branch a conversation from any previous message to explore a different architectural path without losing context.
• Live Action & Reasoning: Watch the agent think and act in real-time. Reasoning traces are tucked into collapsible blocks, and tool executions merge seamlessly into the chat stream.

Built-in Workspace Tools

Opico Agent comes equipped with a core set of file-system tools allowing it to act as an independent developer:

⚙️ Configuration

Set up your preferred provider, model, and API keys via the extension's Settings modal (the gear icon) or through your VS Code settings.json:

Prompts are external. Agent prompts are loaded at runtime from a public GitHub repository (with cache + bundled fallback), not hardcoded. See PROMPTS.md for the repository layout, how to pin a prompt version, caching, and how to edit prompts locally while developing.

🛠️ Under the Hood (Architecture & Engineering)

Opico Agent spans two distinct build targets communicating over a typed bidirectional message bridge: a Node.js extension host (esbuild-bundled TypeScript) and a React webview frontend (Vite + Tailwind v4).

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    VS Code Extension Host                   │
│                                                             │
│ extension.ts ──► ChatWebviewProvider ◄──► AgentService      │
│                       │                         │           │
│                       │                 ┌───────┴───────┐   │
│                       │                 │ ToolRegistry  │   │
│                       │                 │  ┌─────────┐  │   │
│                       │                 │  │BaseTool │  │   │
│                       │                 │  │(generic)│  │   │
│                       │                 │  └────┬────┘  │   │
│                       │                 │  ┌────┴────┐  │   │
│                       │                 │  │5 Tools  │  │   │
│                       │                 │  └─────────┘  │   │
│                       │                 └───────────────┘   │
│                       │                         │           │
│             HumanLoop (reusable HITL layer)    │           │
│             (approval + question interactions) │           │
│                       │                                     │
│             CommandProcessManager               │           │
│             (abortable running processes)       │           │
│                       │                                     │
│             VS Code GlobalState                             │
│             (conversation persistence)                      │
└───────────────────────┬─────────────────────────────────────┘
                        │ postMessage bridge (typed)
┌───────────────────────┴─────────────────────────────────────┐
│                    React Webview (Vite)                     │
│                                                             │
│ App.tsx ──► useExtensionBridge (state machine hook)         │
│               │                                             │
│     ┌─────────┼─────────┬──────────────┐                    │
│     ▼         ▼         ▼              ▼                    │
│ ChatMessage ToolBadge HistoryPanel PromptInputBox           │
│ (markdown + (diff     (slide-over  (@ file                  │
│  reasoning)  preview)  panel)       autocomplete)           │
└─────────────────────────────────────────────────────────────┘

Engineering Highlights

• Type-Safe Tool System: Every tool extends a generic BaseTool<T> abstract class where T is a Zod schema. This provides compile-time type safety (execute(params: z.infer<T>)) and runtime validation, seamlessly bridging TypeScript interfaces to LLM function calling.
• Reusable Human-in-the-Loop Layer: The HumanLoop service is a generic interaction primitive that pauses agent execution to collect human input, then resumes. It powers two flows today: the allow/deny approval gate for execute_command (the old command-only guardrail, now reusable for any tool), and the ask_user tool for raw, single-select, or multi-select questions the user can dismiss. Running shell processes are tracked separately by CommandProcessManager so the user can abort them mid-execution.
• Event-Driven Streaming: The AI stream utilizes the fullStream async iteration API. Text deltas, reasoning chunks, and tool-call states are dispatched individually across the postMessage bridge for fluid, real-time UI rendering without bubble-wrapping.

Project Structure

opico-agent/
├── src/                          # Extension (Node.js) source
│   ├── extension.ts              # Activation entry point
│   ├── llm/
│   │   └── AgentService.ts       # Agent loop, provider factory, streaming
│   ├── providers/
│   │   └── ChatWebviewProvider.ts # Webview bridge, history, file scanning
│   ├── hitl/
│   │   └── HumanLoop.ts          # Reusable human-in-the-loop interaction layer
│   ├── prompts/                  # External prompt system (PromptLoader abstraction)
│   │   ├── bundled/*.md          # Claude-Code-adapted prompts (offline fallback/seed)
│   │   ├── GitHubPromptSource.ts # Public-repo fetcher (no auth, text-only)
│   │   ├── CachingPromptLoader.ts# cache → source → stale-cache → bundled → fail
│   │   └── vscode/               # VS Code config + cache wiring
│   ├── tools/
│   │   ├── BaseTool.ts           # Generic abstract base class
│   │   ├── ToolRegistry.ts       # Tool registration & AI SDK adapter
│   │   ├── CommandProcessManager.ts # Abortable running-process lifecycle
│   │   └── AskUserTool.ts        # Ask-the-human tool (raw/single/multi)
│   └── utils/
│       └── diffHelper.ts         # Diff stats & unified diff generation
├── webview/                      # React webview frontend
│   ├── src/
│   │   ├── components/           # UI (Chat, Badges, History, Settings)
│   │   ├── contexts/             # React Contexts (HumanLoop)
│   │   └── hooks/
│   │       └── useExtensionBridge.ts # Typed VS Code message bridge
│   └── vite.config.ts
├── esbuild.js                    # Extension build config
└── package.json                  # Extension manifest & dependencies

🚀 Development & Setup

Prerequisites

• Node.js 18+
• VS Code 1.85+

Build & Run

# 1. Install dependencies
npm install
cd webview && npm install && cd ..

# 2. Start the watch compiler (builds extension + webview in parallel)
npm run dev

Open the project in VS Code and press F5 to launch the Extension Development Host.

Extending with Custom Tools

The tool system is built for modularity. Extend BaseTool and define a Zod schema to add capabilities:

import { z } from "zod";
import { BaseTool, ToolResult } from "./tools/BaseTool";

const MySchema = z.object({
  target: z.string().describe("What the tool acts on"),
});

export class MyTool extends BaseTool<typeof MySchema> {
  name = "my_tool";
  description = "Description the LLM uses to decide when to invoke this tool.";
  schema = MySchema;

  async execute(params: z.infer<typeof MySchema>): Promise<ToolResult> {
    return { content: `Acted on: ${params.target}` };
  }
}

🧠 Design Decisions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.