Dev Companion AI

A VS Code sidebar that explains failed terminal commands, lists the API endpoints of a backend project, and draws its architecture. It works with a local Ollama model or a hosted provider (Gemini, OpenRouter, Groq, OpenAI, or any OpenAI-compatible endpoint).

Features

• Terminal failure analysis. When a command in the integrated terminal fails, the Terminal tab shows the likely root cause, the files involved and a suggested fix you can copy. Common errors (a mistyped command, a missing module, a port in use, a TypeScript or Rust compiler error) are diagnosed instantly by built-in rules; everything else goes to the AI provider. If the provider cannot be reached, the built-in diagnosis is shown instead.
• Wrong-folder detection. When a command fails because a file is missing (for example npm run dev in a folder with no package.json) and that file exists elsewhere in the workspace, the suggested fix is the cd to the right folder followed by the command.
• One diagnosis per terminal. Each terminal keeps its own latest diagnosis, and the Terminal tab shows the one for the terminal you are looking at. Run a frontend in one terminal and a backend in another, and switching terminals switches the diagnosis.
• API Explorer. Finds the HTTP endpoints in TypeScript, JavaScript, Python, Go, Java and C# source files, with filtering, a cURL command per endpoint, and export to an OpenAPI 3.0 openapi.json.
• Architecture visualizer. Draws the module dependency graph, the folder hierarchy and a layer diagram of the workspace as Mermaid diagrams, with an AI summary.
• AI usage budget. Counts tokens per day and month, shows the provider's remaining quota where the provider reports it, and pauses requests when a budget is used up.

Requirements

• VS Code 1.93 or later. Terminal analysis uses the shell integration API, so shell integration must be active in the terminal (it is by default for bash, zsh, fish and PowerShell).
• A trusted workspace. The extension is disabled in Restricted Mode and in virtual workspaces.
• One AI provider:
  • Ollama (default): install Ollama, then run ollama pull llama3.
  • A hosted provider: an API key from Gemini, OpenRouter, Groq or OpenAI, or the base URL of an OpenAI-compatible endpoint.

Setup

1. Install Dev Companion AI from the Extensions view.
2. Open a project folder and click the Dev Companion icon in the activity bar.
3. Open the Settings tab, pick the provider and model, and enter the API key if the provider needs one. With Ollama, Scan Local Models lists the models you have installed.
4. Click Test connection, then Save Settings.

Then run a command that fails in the integrated terminal; the diagnosis appears in the Terminal tab.

Where settings and keys are stored

• API keys are stored in VS Code's secret storage (the operating system keychain), one per provider and endpoint. They are never written to a file. A key saved for one endpoint is not sent to a different one.
• Other settings (provider, model, URLs, budgets, API scan scope) are stored in .devcompanion.json in the root of the open folder. With no folder open they are kept in VS Code's global extension state and no file is written. The file holds no secrets; commit it to share the settings with your team, or add it to .gitignore to keep them personal.
• Earlier versions kept the settings in config.json. They are copied to .devcompanion.json once; config.json is no longer read and is left as it is, apart from the next point.
• A config.json written by an earlier version that still contains API keys is migrated once: the keys move to secret storage and are removed from the file.

What is sent to the AI provider

With Ollama everything below stays on your machine. With a hosted provider it is sent to that provider.

Background terminal analysis

Background analysis is on by default. When a command fails (a non-zero exit code, or an error pattern in its output) and the built-in rules do not recognise the error, the extension sends this to the configured AI provider:

• the command line that was run,
• the last 1,500 characters of the command's output,
• file paths found in that output,
• the folder the command ran in: the names of the files and folders directly inside it, and the scripts and dependency names from its project manifests (package.json, pyproject.toml, requirements.txt, Cargo.toml, go.mod, Makefile, compose files). Other files, including .env, are listed by name only and never read.

Do not leave it on with a hosted provider in terminals that print secrets.

A folder is read once and remembered until it changes. After a cd, the extension waits 7 seconds before reading the new folder, so a folder you only pass through is not read. A command that fails there sooner reads it at that moment.

To turn background analysis off: Settings tab, clear Enable Background Terminal Analysis, then Save Settings.

Other features

• Architecture analysis sends the folder and file names of the workspace (not file contents) to the provider, and only when you click Analyze Architecture.
• The API Explorer does not use the AI provider.
• Wrong-folder detection searches the workspace on your machine and sends nothing.

Commands

Known limitations

• PowerShell with a Python virtual environment active. The venv's prompt makes VS Code report every command as successful, so a failure is only noticed when its output contains a recognised error (a PowerShell error record, a stack trace, an Error: line and similar). A command that fails silently is missed.
• Background terminals. A failure in a terminal you are not looking at is analysed but not announced; it is shown when you switch to that terminal.
• Wrong-folder detection covers a missing file reported by Node/npm, Python, pip, Cargo and Go, and only suggests a folder inside the open workspace.
• "Requires auth" is read from the source, not from running the app. It recognises guard decorators and attributes (@UseGuards, [Authorize], @PreAuthorize, @login_required, @jwt_required) and, in FastAPI, a Depends(...) or Security(...) whose name suggests authentication (get_current_user, verify_token, require_admin, a bearer or OAuth2 scheme). A FastAPI dependency with an unrelated name, or one applied through include_router(..., dependencies=[...]), is not recognised.
• Architecture analysis covers the first workspace folder only, and the dependency graph covers JavaScript and TypeScript files.
• The exported OpenAPI document describes paths, methods, path parameters and whether an endpoint requires authentication. Request and response schemas are not inferred.
• .devcompanion.json is read at startup and when settings are saved; edits made by hand need a window reload.

Development

• docs/MANUAL_TESTING.md: building, running the Extension Development Host and testing each feature by hand.
• docs/RELEASE.md: the checklist for publishing a version to the Marketplace.
• STATUS.md: test coverage and requirement status.
• CHANGELOG.md: what changed in each version.

License

MIT