AlbertCode SWE Agent for Visual Studio Code
Governed AI software engineering. The agent proposes, you decide, and every
action is recorded.
How to use
An AI coding agent in a chat panel beside your code: ask about your code, or say what to change, and
AlbertCode plans it, makes the change and shows you the diff. The agent runs on your own computer, with the
model you choose.
Open your project folder (File → Open Folder…).
Open the AlbertCode panel. Click the AlbertCode icon in the Activity Bar on the left, or press
Ctrl+Shift+P (Cmd+Shift+P on a Mac) and run View: Open View → AlbertCode SWE Agent. To keep it on
the right, beside Chat, drag the icon into the right-hand side bar.
Let it start AlbertCode. The panel starts AlbertCode for you and connects in a few seconds. The first
time, if AlbertCode is not on your computer yet, click Install AlbertCode on the panel's top line: the
installer runs in a terminal, shows its plan and asks Proceed? [Y/N]; answer Y, and the panel connects by
itself when it is done.
Connect a model. Click the model chip under the message box (or type /connect), pick a provider
(OpenAI, Anthropic, OpenRouter, a local model through Ollama or LM Studio, or any OpenAI-compatible service)
and paste its API key. The key is checked before it is saved, and stays on your computer.
Choose how it works, at the top of the panel:
- Ask only: answers questions about your code and offers a change for your go.
- Direct: changes your files straight away, asking before each write (or not, with Auto-approve); Git is
the undo.
- Governed: a plan you approve, the change built in an isolated copy and checked, then the diff to accept.
Type what you want and press Enter, for example:
- Explain this repository
- Where is the login handled?
- Add input validation to the signup form, with tests
Approve the plan or each write when asked, review the diff, and accept it. The stop button ends a run at any
time, and + starts a new chat.
Useful in the message box: /model to change the model, /connect to add a provider, /plan or /do to start a
change in Governed or Direct mode, and the paperclip to attach files or pictures.
AlbertCode and this extension are free to use under the
AlbertCode SWE Agent End User Licence Agreement,
included as LICENSE.txt. AI can be wrong: review every change before you accept it. To install AlbertCode
yourself instead, see the installation guide.
Overview
AlbertCode SWE Agent is an enterprise-oriented, model-independent AI software engineering
agent. It is built for work that has to stand up to review afterwards: code in
regulated products, billing systems, and anything an auditor, a security team,
or a future incident review will eventually read.
The product owns the engineering workflow — repository analysis, structured
planning, isolated implementation, deterministic verification, independent
review, and human acceptance. The model you choose supplies reasoning inside
that workflow and holds no authority of its own.
In the governed flow, nothing reaches your repository until you accept a diff.
That property is enforced by the service, not requested in a prompt.
Design
Many coding agents inherit the full authority of the person who launched them:
the working tree, the shell, the credentials. Their constraints live in a
system prompt, and their record is a chat transcript. AlbertCode SWE Agent is built on a
different premise.
| Concern |
Approach |
| Where work happens |
The governed lane works in an isolated copy of the repository. The direct lane works in your files, with per-write approval and Git as the undo. |
| Where authority comes from |
A contract file kept under version control in the repository declares what may change, what may run, and who must approve. |
| Where rules are enforced |
At the tool boundary, before an action happens. Neither enforcement surface consults the model. |
| What the record is |
A hash-chained, tamper-evident evidence ledger holding every action, including every refusal. |
| What checks the result |
Deterministic verification runs the repository's own tests and checks, and two independent reviewers — security and quality — read the change on fresh context, optionally using a different model. |
| Which model is used |
OpenAI, Anthropic, OpenRouter, Kimi, Hugging Face, any OpenAI-compatible endpoint, or a model on your own machine. Switchable per task, and per phase. |
Capabilities
- Engineering contracts.
albertcode.contract.toml, versioned with your code:
allowed and forbidden paths, permitted commands, required checks, approval
rules. The contract is read from the original repository and SHA-256-pinned
to each task, so an agent cannot widen its own boundary.
- Two enforcement surfaces. A preventive guard refuses out-of-scope writes and
commands before they happen. A detective evaluation produces a machine-checked
verdict, clause by clause, before anything can be accepted.
- Isolated execution. A governed task works on a copy, and acceptance
re-checks that your files have not changed underneath the task since it was
planned.
- Structured planning. Objective, files expected to change, steps, tests,
security considerations, and rollback. Writes outside the approved plan's
declared files are refused mechanically.
- Deterministic verification. Your repository's own test, type-check, lint and
build configuration is detected and run. Python, JavaScript and TypeScript,
Go, Rust, Java and .NET toolchains are recognised.
- Independent review. Security and quality reviewers run in parallel on fresh
context. A blocking finding stops the task without asking anyone.
- Evidence ledger. A per-tenant hash chain over every governance event, so any
later edit to the history is detectable and the first altered record is
named. Each task can produce a complete evidence bundle: contract, plan,
verdict, diff, verification results, reviews, and every tool call.
- A control plane above the repository. Actions are modelled as capability by
resource by conditions, with deterministic risk scoring, layered policies
where a refusal at any level ends the request, and signed execution grants
bound to the exact plan a person approved.
- Model independence per phase. The planner, implementer and reviewers can each
use a different model, so a reviewer that is not the implementer's model is a
genuinely independent reviewer.
- One desktop or an organisation. The same product runs single-user (SQLite,
in-process) or multi-tenant (PostgreSQL, OIDC, RBAC, worker pools, hardened
command sandboxes, Prometheus metrics).
Three ways to work
The panel offers three modes: Governed, Direct and Ask. Ask answers questions and
offers to turn a request into a task; the other two are the lanes a task can run
in. There is deliberately no gate-free lane here — a change made from an editor
should be one somebody approved.
| Lane |
Where it works |
Gates |
Undo |
| Governed |
An isolated copy |
Plan approval, then diff acceptance, with verification and two reviews in between |
Nothing is applied until you accept |
| Direct |
Your working tree |
Each write asks first, or auto-approve if you choose |
Git, after the fact |
A declared contract outranks the lane chosen in the panel. Where a contract is
declared, Direct is offered as a visible decision rather than run silently: run
the governed flow, cancel, or disregard the contract. Disregarding
is honoured only where the contract's own override clause permits it, and is
recorded in the task history and the audit log either way.
What the extension adds
The governed workflow inside VS Code: a chat and planning panel in the Activity
Bar, live narration of the agent's actions while it plans and implements, a
live-growing diff as writes land in the isolated copy, the reviewed result in
VS Code's native multi-file diff view, and both approval gates as cards that do
not block what you are reading. Conversations carry into tasks, so the planner
is briefed by what was already discussed.
While a task runs, the panel shows the current action, a progress bar with an
estimate based on how long comparable runs have taken, and a collapsible
step-by-step record. Finished tasks are marked as completed in the thread.
The governed flow asks for two approvals: the plan, and the final diff.
Per-step permission prompts train people to approve without reading, so the
work in between is made mechanically safe rather than repeatedly supervised.
Commands
| Command |
Purpose |
| AlbertCode SWE Agent: Start Task |
The governed flow from the Command Palette |
| AlbertCode SWE Agent: Check Service |
Confirm the backend is reachable |
| AlbertCode SWE Agent: Configure Enterprise API Key |
Store a service key in SecretStorage, for authenticated deployments |
| AlbertCode SWE Agent: Choose Model |
Search and pick a model: recent ones, every connected provider's, or any model ID (also the model chip in the panel, or /model) |
| AlbertCode SWE Agent: Connect a Provider |
Pick a provider, give its key or address — checked before it is saved (also /connect) |
| AlbertCode SWE Agent: Disconnect a Provider |
Remove a provider's key from this machine |
| Open in AlbertCode SWE Agent |
Right-click a folder in the Explorer to work in it (a file stands for its folder) |
Settings
| Setting |
Default |
Purpose |
expertCodingAgent.serverUrl |
http://127.0.0.1:8765/api |
Where the AlbertCode SWE Agent service is reachable |
expertCodingAgent.provider |
backend-default |
Pin a model instead of choosing one in the panel |
Troubleshooting
| Symptom |
Resolution |
| Service unreachable |
The panel starts AlbertCode by itself and keeps trying. If it says AlbertCode isn't installed, click Install AlbertCode; if it cannot start it, click Start it in a terminal |
albertcode-server is not found |
AlbertCode is not installed, or the terminal was open before it was. Run the installer for your system, then open a new terminal |
| No model connected |
Click the model chip in the panel (or type /connect) to connect a provider, or run albertcode configure |
| Open a repository folder before starting |
Use File then Open Folder. The flow needs to know which repository it is working on |
| Direct is unavailable here |
Direct uses Git as its undo. Run git init, or send the request through the governed flow |
| A command was refused as not allowlisted |
The refusal names the contract clause that would grant it. Add that clause to albertcode.contract.toml if the repository should permit the command |
| Connection dropped during a long task |
The service keeps working. The extension follows the task and resumes the flow automatically |
Security model
The panel cannot write to anything. It talks to the AlbertCode SWE Agent service, and
every write the service makes is governed: in an isolated copy for the governed
lane, and under per-write approval in the direct lane, with the
contract enforced at the tool boundary in all cases. Model API keys live on the
service and never in the extension. The service key, where one is used, lives
in VS Code SecretStorage and never in a settings file. The webview holds no
credentials and reaches the network only through the extension host.
| |