Pixa Agent

Your AI coding agent. Your models. Your machine.

An open-source AI coding agent for VS Code that plans, reads your codebase, and edits multiple files — with every change staged as a diff you approve. Point it at OpenRouter, your company gateway, or a model running on your own laptop. No vendor lock-in. No telemetry. No required server.

See it in action

https://github.com/user-attachments/assets/33ce7f38-5ffe-463e-aa8a-7bb7286dd979

_{Install → connect a model, cloud or local → describe a task → review the diff → approve.}

Why Pixa?

Most AI coding assistants decide which model you use and where your code goes. Pixa doesn't.

If you can host a model, Pixa can use it — and your code never leaves your network.

What it does

• Agent tasks — describe a goal in plain English; Pixa plans it, reads the relevant code, and makes the changes.
• Nothing lands without approval — edits are staged as a change set. View the diff, then Apply, Reject, or Revert per file.
• Commands are gated — terminal commands and git commits never run without an explicit click.
• Add any provider from the UI — presets for Ollama, LM Studio, vLLM, and NVIDIA NIM, or add a custom endpoint. Pixa asks your server which models it has, so you don't guess at model names.
• Reasoning-effort control — for models that support it, choose how hard the model thinks (low/medium/high), trading speed and cost for quality.
• Batch review — Apply all or Reject all staged changes at once, or go file by file.
• Semantic code search — find code by meaning ("where do we handle retries"), not just exact text. Optional; see Current status.
• Real cost tracking — actual billed cost per request and a running session total, when your provider reports it.
• Project memory — notes and decisions persist across chat sessions.
• MCP support — connect third-party tool servers.

Install

From the VS Code Marketplace (easiest):

Search "Pixa Agent" in the Extensions view (Ctrl+Shift+X), or:

code --install-extension PIXAFLIP.pixa-agent

From a release build:

code --install-extension pixa-agent-<version>.vsix

From source:

git clone https://github.com/WisdomBoost-LLC/PixaAgent.git
cd PixaAgent
npm install
npm run compile -w pixa-agent
npm run package -w pixa-agent
code --install-extension packages/pixa-agent/pixa-agent-*.vsix --force

Requires Node.js 20+ and VS Code 1.90+.

Quick start

1. Open a project folder in VS Code.

2. Click the Pixa icon in the activity bar.

3. Set up a model — pick one:

   Fastest — a hosted model Ctrl+Shift+P → Pixa: Set OpenRouter API Key (free key at openrouter.ai/keys)

   Fully local — nothing leaves your machine Install Ollama, then:

   ollama pull llama3.1:8b
   

   In Pixa, click the ⚙ icon → Ollama preset → Fetch models → select your model → Add provider → Reload window.

4. Pick your model from the dropdown and describe what you want.

Model size and runtime both matter for agent work. Models under ~7B often imitate tool calls as plain text instead of making real ones, so the agent appears to do nothing — Pixa detects this and tells you rather than failing silently. Reliability also varies by runtime, not just size: we've seen qwen2.5-coder return tool calls as text through Ollama even though it's a genuinely capable model, while llama3.1 calls tools natively and reliably. If a local model seems to "talk about" what it's going to do instead of doing it, try llama3.1:8b or a cloud model for that task.

Using your own provider

Everything is configurable from the ⚙ Providers panel — no JSON editing required. Prefer config files? The same settings live in pixa.providers:

// settings.json
"pixa.providers": {
  "ollama": {
    "name": "Ollama (local)",
    "baseUrl": "http://localhost:11434/v1",
    "requiresApiKey": false,
    "models": {
      "llama3.1:8b": { "name": "Llama 3.1 8B", "contextWindow": 32768 }
    }
  }
}

Anything speaking the OpenAI chat-completions API works: Ollama, vLLM, LM Studio, llama.cpp, NVIDIA NIM, Groq, Together, or your own gateway.

Config reference

Custom models appear as provider:model (e.g. ollama:qwen2.5-coder:7b) — use that id for pixa.defaultModel.

API keys are stored in VS Code's encrypted secret storage, never in your settings file.

Settings

How it works

Chat panel  →  Agent loop  →  your chosen model (the only outbound call)
                   │
                   ├─ Tools: read, search, edit, terminal, git, diagnostics
                   ├─ Index: file map, symbols, semantic search
                   └─ Every edit → staged change set → you approve → disk

Everything except the model request runs locally. Independent read-only tools run in parallel; anything that changes state runs one at a time, in order.

Pixa is provider-agnostic by construction: the agent and UI only ever talk to a ModelProvider interface, so adding a backend never touches agent logic.

Current status

Pixa is usable today and we run it on its own codebase — but it's young, and we'd rather you know exactly where the edges are.

Solid

• Agent loop, planning, multi-file editing with diff approval
• Provider system — hosted and self-hosted, configurable from the UI
• Command-safety policy — known-destructive commands are blocked before you're even asked; everything else still requires your approval
• Secret redaction and an audit log
• Cost tracking, chat history, MCP, project memory
• Reasoning-effort control, batch Apply all / Reject all
• 204 tests passing offline

Early / rough

• Semantic search is optional and off by default. It needs @huggingface/transformers (~150MB plus a native binary), which is too large to bundle. Without it, everything else works normally — you just lose meaning-based search.
• The UI is functional, not beautiful. A visual overhaul is planned but not started.
• Local model reliability for agent tasks varies by model and runtime (see the note in Quick start). Pixa detects a failure to call tools and explains it, but can't fix a model/runtime combination that won't cooperate.

Not built yet

• Inline completion (ghost text) — designed, not implemented
• Full process-level command isolation — a destructive-command policy ships today (see Security), but approved commands still run in your own shell

We'd rather ship an honest README than a flattering one. If something here is wrong or out of date, that's a bug — please open an issue.

Security

What protects you today:

• The agent cannot write to disk without you clicking Apply.
• Terminal commands and git commits always require explicit approval.
• Known-destructive commands are hard-blocked — patterns like rm -rf /, curl … | sh, disk-overwrite, and force-push to main are refused before you're even asked, so they can't slip through an over-eager Approve.
• File access is restricted to the open workspace folder.
• API keys live in VS Code secret storage, never in config files.

⚠️ Approved commands still run with your normal user permissions. The command policy is a guardrail against careless destruction, not a hard boundary against a deliberately adversarial model — it's pattern-based and won't catch obfuscated commands. Read commands before approving them, and prefer trusted workspaces.

Found a security issue? Please report it privately — see SECURITY.md.

Contributing

Contributions are genuinely welcome, and good first issues are labelled as such.

npm install
npm run compile -w pixa-agent       # build
npm run test:offline -w pixa-agent  # fast test suite (~2s)
npm run typecheck -w pixa-agent     # types

Press F5 in VS Code to launch an Extension Development Host with Pixa loaded from source.

Two things to know:

• npm test runs the full suite, which downloads a small embedding model and can be slow or flaky offline. Use npm run test:offline for day-to-day work — it's what CI gates on.
• Keep pure logic free of vscode imports. That separation is why most of the codebase is unit-testable.

See CONTRIBUTING.md for the full guide.

License

MIT — use it, fork it, ship it.