Documentation

Requirements

OctropsCode requires one of the following development environments:

• Visual Studio Code version 1.85.0 or later
• Other VS Code-Compatible IDEs (such as Cursor, VSCodium, Windsurf, Positron, or any editor with VSIX extension support)
• Any VS Code-compatible editor fork supporting .vsix installation

You will also need at least one API key from any of the 17+ supported providers. OctropsCode is entirely serverless - no local gateway servers, extra proxy apps, or daemon background services are required.

Installation

Method 1: Direct VSIX Install

Download the latest .vsix package from the download link.

VS Code:

1. Open VS Code and launch Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
2. Click the ··· (More Actions) menu at the top right of the panel
3. Select Install from VSIX…
4. Choose the downloaded octropscode-1.2.2.vsix file
5. Reload VS Code when prompted

Other VS Code-Compatible IDEs (Cursor, VSCodium, Windsurf, etc.):

1. Open your preferred IDE
2. Navigate to the Extensions side panel
3. Select Install from VSIX
4. Choose the downloaded octropscode-1.2.2.vsix bundle to complete installation

Method 2: Command Line CLI

API Key Setup

After installing OctropsCode, add your API key for your preferred AI model:

1. Click the OctropsCode icon in the Activity Bar (left sidebar)
2. Click the gear/settings icon to expand Provider Configuration
3. Paste your API key into the corresponding provider input field
4. Click Save & Validate Key

API keys are stored securely using VS Code's local encrypted SecretStorage engine. They are never routed through any OctropsCode intermediary servers.

Many supported providers offer generous free API key tiers:

• Google AI Studio - free tier for Gemini 2.0 Flash & Gemini 1.5 Pro
• Groq Console - ultra-fast Llama 3 & Mixtral inference
• SambaNova Cloud - free access to Llama 3.1 & DeepSeek R1
• OpenRouter - free & pay-as-you-go router access

Agentic Framework: 21 Workspace Tools

OctropsCode v1.2.2 equips AI models with a comprehensive suite of 21 workspace tools to inspect, modify, and verify your codebase autonomously:

Tool Name	Function & Purpose	Primary Use Case
view_file / read_file	Reads contents of workspace files with line slice controls.	Inspecting code implementation before editing.
write_to_file	Creates new files or overwrites existing workspace assets.	Generating new components, modules, or config files.
replace_file_content	Executes targeted single-block sub-string code replacements.	Refactoring specific functions or updating imports.
multi_replace_file_content	Applies multiple non-contiguous block edits across a file.	Simultaneous multi-location code refactoring.
list_dir	Recursively inspects directory trees and file structures.	Mapping project layout and discovering files.
grep_search	Runs ultra-fast ripgrep pattern searches across the workspace.	Finding symbol definitions, references, and usages.
run_command	Executes local shell commands (sync or background daemon).	Running test suites, build scripts, or dev servers.
manage_task	Manages background execution tasks (status, stdin, kill).	Interacting with long-running background processes.
schedule	Sets one-shot timers or recurring cron triggers.	Periodic health checks or automated reminders.
multiLanguageSkeletonizer	Extracts tree-sitter AST skeletons (class/method signatures).	Generating low-token structural context overviews.
web_search New	Real-time DuckDuckGo web search without dependencies or API keys.	Researching up-to-date APIs, docs, and error solutions.
fetch_url New	Fetches and parses public web page contents into clean Markdown.	Reading documentation articles and reference specifications.
find_references New	Finds all symbol references via native VS Code LSP provider.	Safe workspace-wide refactoring and impact analysis.
go_to_definition New	Jumps to symbol declarations via native VS Code LSP provider.	Tracing function definitions and interface contracts.
git_diff New	Inspects unstaged working tree diffs, staged changes, or file diffs.	Auditing proposed modifications and commit verification.
git_log New	Queries commit history with branch targets and count limits.	Investigating regression points and change history.
list_workspace	Recursive file tree with metadata and directory summaries.	Workspace architectural mapping.
get_diagnostics	Live VS Code language service errors, warnings, and hints.	Automated self-correction and post-edit verification.
find_symbols	Workspace-wide symbol search across classes, functions, and types.	Discovering declarations across multi-file repositories.
get_open_editors	Enumerates open editor tabs with dirty states and languages.	Contextualizing developer's active workspace session.
detect_tech_stack	Auto-detects frameworks, package managers, and configuration files.	Tailoring code generation to project conventions.

Autonomous ReAct Reasoning Loop

When handling complex tasks, OctropsCode operates on an iterative Reason + Act (ReAct) loop:

1. Plan: The agent analyzes your prompt, queries workspace knowledge, and formulates an implementation plan.
2. Act: Executes specific workspace tools (e.g. `grep_search` to find symbols, `view_file` to read logic).
3. Observe: Evaluates tool execution outputs and error tracebacks.
4. Self-Correction: If a build or test fails during execution, the agent analyzes the failure log and automatically generates a corrected edit pass.

Multi-Agent QA System

OctropsCode features specialized agent roles that collaborate during multi-phase requests:

• Architect Agent: Analyzes codebase structure and plans component boundaries.
• QA Reviewer Agent: Audits proposed diffs for syntax errors, edge cases, and security vulnerabilities.
• Accessibility (a11y) Agent: Checks HTML/JSX markup against WCAG 2.1 contrast, ARIA, and focus guidelines.
• Prompt Optimizer: Refines complex user prompts to maximize AI model accuracy.

v1.2.2 Release: Autonomous Web Agent & Evolution

OctropsCode v1.2.2 elevates the agentic studio from purely local workspace awareness to live external web intelligence. Below is a complete breakdown of what is newly introduced in v1.2.2 alongside an evolutionary comparison of what existed previously in v1.2.1 and v1.0.0.

Newly Added in v1.2.2 (Autonomous Web Agent)

The headline capability of v1.2.2 is live internet research without third-party tracking, intermediate servers, or additional API keys:

• Live Web Search (web_search): Queries DuckDuckGo directly via HTML extraction, retrieving clean search snippets, page titles, and source URLs. The model uses this to lookup contemporary API documentation, library deprecation notices, and community solutions to compiler errors.
• Remote Web Ingestion (fetch_url): Ingests external documentation pages, GitHub files, and web specifications directly into model context as stripped, token-efficient Markdown with line-slice windowing.
• Autonomous Web Research Workflow: When encountering runtime errors or unfamiliar dependencies, the agent independently queries the web, reads solutions, and applies verified code fixes without user prompting.
• Parallel Batch Calling: Read-only web queries and workspace operations can be dispatched concurrently in a single agent turn via Promise.allSettled(), drastically reducing multi-turn latency.
• Real-Time Streaming Parser Support: Live regex streaming parsers detect and execute web tool invocations on-the-fly as tokens arrive from the model.

Evolution: What Was Before vs What Is New in v1.2.2

The table below outlines how OctropsCode has evolved across its major releases:

Capability Area	v1.0.0 (Foundation)	v1.2.1 (Local Studio)	v1.2.2 (Web Agent - Latest)
Autonomous Tools	None (Chat & context-menu only)	15 Local Workspace Tools (file read/write/edit, grep, terminal, tasks)	21 Tools (+ live web search, URL fetch, LSP references/definitions, git diff/log)
External Intelligence	None (Bounded to model training cutoff)	None (Restricted to local workspace files)	Autonomous Web Agent (Live DuckDuckGo search & remote URL markdown ingestion)
Reasoning Protocol	Single-turn prompt/response	ReAct reasoning loop (Think -> Act -> Observe -> Reflect)	ReAct reasoning with real-time web research integration
Error Resolution	Manual copy-pasting into chat	Automated diagnostics verification & self-correction loop	Self-correction augmented with live web error searches
Tool Concurrency	Sequential execution	Sequential execution	Safe parallel batch execution for concurrent read-only queries
Project Memory	Active editor selection context	Local RAG memory (.octrops/project_memory.json) & AST skeletons	Local RAG memory + live external documentation ingestion
Safety & Control	Confirmation dialogs	HITL safety gates, tool risk tiers, side-by-side colorized diffs	HITL safety gates with sanitized web URL fetching bounds
Provider Ecosystem	17+ AI Providers (Serverless)	17+ Providers with automated provider failover	17+ Providers with dynamic model cascading and failover

Local RAG Project Memory

OctropsCode maintains a persistent vector knowledge index stored locally at .octrops/project_memory.json in your workspace root.

During conversation turns, relevant project snippets, architectural summaries, and past decisions are retrieved automatically using local semantic similarity matching. All vector indexing and storage occur 100% on your local machine.

Workspace Rules (.octrops/rules.md)

Enforce project-specific coding conventions by creating an .octrops/rules.md file in your repository:

OctropsCode automatically ingests these rules into every agent reasoning pass, ensuring generated code aligns with your team's standards.

Token Optimization Engine

To optimize speed and minimize API costs, OctropsCode employs surgical context compression:

• Surgical Block Edits: Uses `replace_file_content` instead of returning full-file rewrites, saving up to 70% of output token generation.
• AST Structural Pruning: Automatically strips method implementation bodies from dependency files, sending only function signatures to the LLM.
• Dynamic Context Trimming: Intelligent context window sliding prevents token overflow crashes.

Side-by-Side Diff Modal

Before saving any file edits to disk, OctropsCode presents an interactive VS Code side-by-side diff preview. You can review additions (green) and deletions (red), accept individual blocks, or reject changes completely with a single click.

Terminal Execution Safeguards

When the agent requests shell execution via `run_command`, an explicit authorization dialog appears. Potentially dangerous operations (such as broad file deletion or git resets) require confirmation, preventing unintended terminal actions.

SecretStorage Security

API keys are encrypted and managed via VS Code's OS-native credential storage (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux). Keys are never committed to version control or saved in plain text files.

Extension Settings

Configure OctropsCode via VS Code Settings (Ctrl+, / Cmd+,) or directly in .vscode/settings.json:

Setting Key	Description	Default
octrops.defaultModel	Primary AI model for chat and tool execution.	gemini-2.0-flash
octrops.temperature	Sampling creativity (0.0 = deterministic, 1.0 = creative).	0.3
octrops.maxTokens	Maximum completion response tokens.	8192
octrops.autoIncludeActiveFile	Automatically include active file content as prompt context.	true
octrops.autoIncludeSelection	Automatically include highlighted editor text as prompt context.	true
octrops.enableAgenticTools	Enable 15 workspace tools for autonomous execution.	true
octrops.enableRAGMemory	Enable local project vector indexing (`.octrops/project_memory.json`).	true
octrops.diffViewerMode	Display interactive side-by-side diff modal before saving.	"interactive"
octrops.terminalApproval	Require manual user confirmation before executing terminal commands.	"always"
octrops.tokenOptimization	Enable AST skeletonization and block-diff generation.	true

Supported Providers Ecosystem (17+ Platforms)

OctropsCode connects directly to all major AI provider APIs without intermediary servers:

Google Gemini

Models: gemini-2.0-flash, gemini-1.5-pro, gemini-2.0-flash-thinking-exp
Get Google Gemini API Key →

OpenAI

Models: gpt-4o, gpt-4o-mini, o3-mini, o1-preview
Get OpenAI API Key →

Anthropic Claude

Models: claude-3-5-sonnet-20241022, claude-3-5-haiku, claude-3-opus
Get Anthropic Claude API Key →

DeepSeek

Models: deepseek-chat (V3), deepseek-reasoner (R1)
Get DeepSeek API Key →

Qwen / QwenCloud

Models: qwen2.5-coder-32b-instruct, qwen-max, qwen-plus
Get Qwen API Key →

Kimi / Moonshot AI

Models: kimi-k2.7-code, kimi-k2.6, moonshot-v1-8k
Get Kimi API Key →

Cerebras AI

Models: llama-3.3-70b, gpt-oss-120b
Get Cerebras API Key →

NVIDIA NIM

Models: nvidia/llama-3.1-nemotron-70b-instruct
Get NVIDIA NIM API Key →

OpenRouter

Models: openrouter/auto, meta-llama/llama-3.3-70b-instruct
Get OpenRouter API Key →

Mistral AI

Models: codestral-latest, mistral-large-latest
Get Mistral API Key →

Cohere

Models: command-r-plus, command-r
Get Cohere API Key →

Zhipu AI (GLM)

Models: glm-4-flash, glm-4-air, codegeex-4
Get Zhipu GLM API Key →

SambaNova Cloud

Models: Meta-Llama-3.1-405B-Instruct, DeepSeek-R1
Get SambaNova API Key →

Groq Cloud

Models: llama-3.3-70b-versatile, mixtral-8x7b-32768
Get Groq API Key →

Together AI

Models: meta-llama/Llama-3.3-70B-Instruct-Turbo
Get Together AI API Key →

Aion Labs

Models: aion-3.0, aion-coder
Get Aion Labs API Key →

Amazon Bedrock

Models: amazon.nova-lite-v1:0, amazon.nova-pro-v1:0
Get Amazon Bedrock Credentials →

MIMO v2

Models: mimo-v2.5, mimo-v2-pro
Get MIMO API Key →

Sidebar Chat Interface

Open the sidebar panel by clicking the OctropsCode logo in the Activity Bar or pressing Ctrl+Shift+A (Cmd+Shift+A on macOS). The chat interface supports multi-turn streaming, inline code copying, model switching, and real-time tool execution logs.

Context Menu Actions

Highlight code in your editor, right-click, and select an OctropsCode shortcut:

• Explain Selection: Generates a step-by-step logic walkthrough of highlighted code.
• Fix & Repair Code: Detects syntax issues, type mismatches, and edge-case bugs.
• Refactor & Optimize: Restructures code for performance, readability, and modern syntax.
• Generate Unit Tests: Creates comprehensive unit test suites for highlighted functions.

Keyboard Shortcuts

Action	Windows / Linux	macOS
Open OctropsCode sidebar	Ctrl+Shift+A	Cmd+Shift+A
Clear chat session	Command Palette → "OctropsCode: Clear Chat"
Re-index local RAG memory	Command Palette → "OctropsCode: Rebuild RAG Index"

Managing Sessions

Conversation states are held locally during your active workspace session. To reset memory context and start a clean session, run OctropsCode: Clear Chat from the Command Palette (Ctrl+Shift+P).

Troubleshooting Guide

API key verification failures

Verify that your key has not expired and has active billing or quota remaining. Ensure there are no leading or trailing whitespace characters when pasting your key into VS Code SecretStorage settings.

HTTP 429 Rate Limit Errors

If a provider rate-limits your requests, OctropsCode allows instant model switching. Use the model dropdown in the sidebar header to switch to an alternative provider (e.g. Gemini 2.0 Flash or Groq).

Tool execution permission prompts

If terminal commands require approval repeatedly, adjust the octrops.terminalApproval setting in your settings.json file.

Frequently Asked Questions

Is OctropsCode completely free?

Yes. OctropsCode is 100% free and open source under the MIT License. You pay only for direct API usage from your chosen model providers (many of which provide free quotas).

Does OctropsCode collect telemetry or code data?

No. OctropsCode operates without backend servers, analytics tracking, or crash report collection. Code snippets and prompts travel directly from your editor to the model provider API you select. See the Privacy Policy.

Can I use OctropsCode in Cursor or other VS Code-compatible IDEs?

Yes. OctropsCode works in any editor supporting VS Code .vsix extension packages, including Cursor, VSCodium, Windsurf, and Positron.