Concepts
Architecture
How the agents are built to run — one local service, several interfaces, an isolated copy for every governed change, task states, evidence, and what the model sees.
This page describes how the agents work from the outside: the pieces you meet in every interface and how they fit together. The engine's source isn't published; everything here comes from the agents' public documentation.
One service, several interfaces
Each agent runs as a small service on your own computer, at 127.0.0.1. You talk to it through its interfaces, and they all see the same tasks, sessions and settings.
| AlbertCode SWE Agent | mini-AlbertCode SWE Agent | |
|---|---|---|
| Terminal | albertcode (full screen); albertcode classic |
albert-mini (full screen); --mini inline |
| Browser | albertcode web (or albertcode --ui) |
albert-mini web |
| VS Code | The AlbertCode panel (extension from each release) | — |
| Service | Starts on first use; albertcode stop stops it |
Listens on 127.0.0.1:8778; albert-mini status, albert-mini stop |
The first command you run starts the service in the background. It keeps running between sessions, so a task started in the browser can be followed in the terminal, and a run keeps going when you close a window.
Only that installation can use its service. Each installation has its own access token in a file only you can read. The terminal sends it for you; the browser command signs your browser in once, and the page then keeps the token in a cookie that scripts can't read and other websites can't send. Other programs and web pages on your computer are refused.
Asking and changing
Everything you type is either a question — answered from the repository's own files, changing nothing — or a change, handled the way the current mode says. Start a request with /plan (governed) or /do (direct) to decide for it.
| Mode | A change… |
|---|---|
| Governed (default) | starts with a plan for your approval, is built in an isolated copy, tested and reviewed, and reaches your files only when you accept the diff |
| Direct, ask each write | is made in your real files, and each write waits for your OK |
| Direct, auto | is made in your real files; writes apply as they come |
| Ask only | is offered, never started until you say go |
Direct needs the folder to be a Git repository, because Git is how you undo a direct change.
The life of a governed change
Plan ─▶ ① you approve the plan ─▶ Build ─▶ Verify ─▶ Review ─▶ ② you accept the diff ─▶ Applied- Plan. The agent reads the repository and writes a plan: the goal, the files it expects to change and how, the steps, how it will test the change, the risk, and how to undo it. Nothing is written.
- Approval 1 — the plan. Approve it, ask for changes, or reject it. Rejecting discards the task.
- Build. The change is made in an isolated copy of your repository, never in your working tree.
- Verify. Your project's own tests and checks run in the copy:
pytest, npm scripts,go test,cargo test, Maven, Gradle,dotnet testand so on. - Review. An independent security review and an independent quality review read the change. (AlbertCode SWE Agent skips them at its fast pace.)
- Approval 2 — the diff. You see the diff, what passed and what failed, and the reviews. Accept, ask for changes, or discard.
- Applied. Accepting copies the change into your files. Discarding deletes the isolated copy.
Accepted changes are ordinary edits in your working tree. Review them with git diff, commit them, and undo them with Git.
Task states
AlbertCode SWE Agent documents the states a task moves through (albertcode show <task> prints them as JSON):
| State | Meaning |
|---|---|
received, planning_queued, analysing |
Planning; nothing written |
plan_ready |
Waiting for approval 1 |
queued, implementing |
Building in the isolated copy |
verifying, reviewing |
Your checks, then the reviews |
completed |
Waiting for approval 2 |
review_blocked |
A review blocked the change |
accepted |
Applied to your repository |
rejected, failed, rolled_back, cancelled |
Ended without applying |
The run planner reads this JSON and shows where a task stands.
Tasks, sessions and evidence
- A task is one change: its request, plan, build, checks, reviews and diff.
- A session is one conversation. It can hold several questions and several tasks. Sessions belong to the service, not to a window.
- Evidence (AlbertCode SWE Agent): every task keeps a record of the plan you approved, every command it ran and its result, every check and review, the diff, and who approved what and when. The evidence ledger holds these records in order, each linked to the one before it, so a changed or deleted entry is detected. Read it with
/ledger; export one change's evidence for an auditor withalbertcode compliance <task>.
The boundary
In AlbertCode SWE Agent, a repository can carry a contract that limits which paths may change, which commands may run, which checks must pass and who may approve. It is read from your repository, never from the isolated copy, so a task cannot widen its own limits.
In both agents, commands a task runs are limited to what the engine allows and run with a cleaned environment: the keys you saved are not handed to them. AlbertCode SWE Agent documents further that every command runs with no shell and a time limit.
What the model sees
To work on your code, the agent sends your chosen model the parts of the repository a task needs, your messages, and files you attach. Provider keys go only to their own provider. With a local model, nothing leaves your computer. There is no telemetry.
What runs where
| Your computer | The service, the interfaces, the isolated copies, your tests, your keys |
| Your model provider | The model's reasoning, if you use a hosted model |
| MCP servers you add | Whatever their tools are given |
| albertcode.dev | Nothing of yours. This website never runs the agents; the run planner works entirely in your browser |
A guide written for this site, covering both agents. For every command and setting, see the full reference for AlbertCode SWE Agent and mini-AlbertCode.