Install  ·  Quick start  ·  How it works  ·  Docs  ·  Releases  ·  Community

_{A task in the AlbertCode browser workspace, waiting at the second approval gate.}

Contents

Get started Install Update and uninstall Quick start

Learn See it in action Why AlbertCode How it works Using AlbertCode Models

Reference Troubleshooting Privacy and security Benchmarks Documentation · FAQ

Install

One command installs AlbertCode for your user. Pick your system:

macOS and Linux  _Terminal

curl -fsSL https://raw.githubusercontent.com/huynvic/albertcode-swe-agent/main/installer/install.sh | sh

Windows  _PowerShell

irm https://raw.githubusercontent.com/huynvic/albertcode-swe-agent/main/installer/install.ps1 | iex

The installer picks the build for your machine and verifies its SHA-256 checksum. It then shows what it will do and asks Proceed? [Y/N] before it changes anything. It installs everything AlbertCode needs, including Python, for your user only. No pip, virtual environments or PATH editing. It takes a minute or two.

Tip

When it finishes, open a new terminal, then check it:

albertcode --version     # AlbertCode SWE Agent 1.42.2
albertcode doctor        # which build tools AlbertCode can find

Requirements

Windows	Windows 10 or 11, x64 (the x64 build also runs on ARM PCs). PowerShell 5.1 or 7
macOS	A current macOS, on Apple silicon or Intel
Linux	x86-64 with glibc: Ubuntu 20.04+, Debian 10+, Fedora, RHEL 8+, openSUSE, Arch. Not Alpine or other musl systems, and not ARM yet
Disk	About 1 GB free
Network	pypi.org and github.com while installing; your model provider while working
Git	Recommended. The installer offers to install it if it's missing

You don't need Python: the installer uses your Python 3.12 if you have it, and otherwise downloads one for AlbertCode alone.

Step by step

macOS  ·  Terminal, or the downloadable .zip

1. Open Terminal (Applications → Utilities, or press ⌘ Space and type Terminal).
2. Paste the macOS command above and press Return.
3. Read the plan, then type Y.
4. Close Terminal and open a new window, then run albertcode --version.

Prefer a download? From the latest release, take the .zip for your Mac: macos-arm64 for Apple silicon (M1 and later), macos-x86_64 for Intel. Not sure which you have? Open the Apple menu → About This Mac. Open the zip, then double-click the installer inside it.

[!NOTE] The installers aren't code-signed yet, so the first time macOS says it can't verify the installer. Choose Done, open System Settings → Privacy & Security, click Open Anyway, then open the installer again. The one-line command above avoids this.

Windows  ·  PowerShell, or the downloadable .cmd

1. Open PowerShell: press the Windows key, type PowerShell, and press Enter. You don't need "Run as administrator".
2. Paste the Windows command above and press Enter.
3. Read the plan, then type Y.
4. Close PowerShell and open a new window, then run albertcode --version.

Prefer a download? From the latest release, take Install-AlbertCode-<version>-windows-x64.cmd and double-click it.

[!NOTE] The installers aren't code-signed yet, so SmartScreen may say it protected your PC. Choose More info → Run anyway. If your organisation blocks PowerShell scripts, use the downloaded .cmd installer instead.

Linux  ·  any terminal, or the downloadable .sh

1. Open a terminal. Make sure curl is installed (sudo apt install curl on Ubuntu and Debian).
2. Paste the Linux command above and press Enter. Run it as yourself, not with sudo.
3. Read the plan, then type Y. It asks for your password only if it needs to install Git.
4. Open a new terminal, then run albertcode --version.

Prefer a download? From the latest release, take Install-AlbertCode-<version>-linux-x86_64.sh and run bash Install-AlbertCode-<version>-linux-x86_64.sh.

VS Code extension and installer options

VS Code extension. Download albertcode-<version>.vsix from the latest release, then in VS Code choose Extensions → … → Install from VSIX. Install AlbertCode itself first: the extension uses it.

Installer options: --check only shows the plan, --yes installs without asking (for scripts and CI), and --version X.Y.Z installs a specific release. On Windows, put options in ALBERTCODE_INSTALL_ARGS, as in the uninstall command below. Manual checksum checks, proxies and more are in Installation.

Update and uninstall

Update

Run the install command again. It shows what will change, then replaces the old version.

macOS and Linux  _Terminal

curl -fsSL https://raw.githubusercontent.com/huynvic/albertcode-swe-agent/main/installer/install.sh | sh

Windows  _PowerShell

irm https://raw.githubusercontent.com/huynvic/albertcode-swe-agent/main/installer/install.ps1 | iex

Important

Saved model keys are cleared the first time a new version starts, so after updating, reconnect with /connect.

Uninstall

On any system (macOS, Linux and Windows). It needs nothing from the internet:

albertcode uninstall

Or with the install script

macOS and Linux  _Terminal

curl -fsSL https://raw.githubusercontent.com/huynvic/albertcode-swe-agent/main/installer/install.sh | sh -s -- --uninstall

Windows  _PowerShell

$env:ALBERTCODE_INSTALL_ARGS = '--uninstall'; irm https://raw.githubusercontent.com/huynvic/albertcode-swe-agent/main/installer/install.ps1 | iex

Uninstalling lists what it will remove and asks first. Your settings are kept: with albertcode uninstall, --all also removes your settings, saved keys and task history, and --check only shows the plan.

Quick start

cd your-project
albertcode

The first time, AlbertCode asks you to connect a model: paste an API key, or point it at a model running on your machine. Then describe what you want:

› The login endpoint returns 500 when the password is empty. Fix it and add a test.

AlbertCode reads the repository and proposes a plan. You approve the plan. It makes the change in an isolated copy, runs your tests, reviews the result, and shows you the diff. You accept it, and only then does the change reach your files.

Tip

Getting started walks through a first task in about five minutes.

See it in action

One request, from plan to proof. Every screen below is from the same task in AlbertCode; the model's answers were scripted for these pictures.

1 · You approve the plan The goal, the files it will change, how, and the risk. Nothing is written yet.	2 · It shows you the exact diff Built in an isolated copy of your repository, never in your working tree.
3 · With the evidence Your own tests, independent reviews and safety checks, all recorded.	4 · In your terminal, too The same task in the terminal (albertcode). Your repository stays unchanged until you accept.

Watch the terminal walkthrough

_{Recorded from albertcode, with the model's answers scripted to keep it short.}

Why AlbertCode

Approval built in Two clear decision points, so nothing reaches your repository by surprise.	Changes are proven, not just written AlbertCode runs your own toolchain (pytest, npm scripts, go test, cargo, Maven, Gradle, dotnet) and shows what passed and what didn't.
Choose your pace Governed for changes you care about, direct to work in your files with a prompt before each write (or none, with auto), and ask to explore a codebase without changing anything.	Any model Connect a hosted provider or a local model, and switch at any time.
Three interfaces Terminal (albertcode), browser (albertcode web) and VS Code, all driving the same local service.	Private by default It runs on your machine, with no account and no telemetry.
A record of every change Each task keeps its plan, test results, review and diff together, in a tamper-evident log you can export.	Extensible MCP servers, plus custom commands and agents written as Markdown files.

How it works

	Step	What you see
1	Plan	The goal, the files it expects to touch, the test plan and the risk. Nothing is written yet.
2	Approve  you decide	You accept the plan, or reject it and rephrase.
3	Build	The change is made in an isolated copy of your repository, never in your working tree.
4	Verify	Your project's own tests and checks run, and the change is reviewed.
5	Accept  you decide	You read the diff and the results, then apply it, or discard it.

Note

If you edited a file the change also touches, acceptance is refused rather than overwriting your work. Accepted changes are ordinary edits: commit them, or undo them, with Git.

Using AlbertCode

Three interfaces, one agent

All three use the same local service, so a task started in one can be followed in another. The terminal and the browser also share their sessions: one started in either is in the other at once.

Interface	Start it	Good for
Terminal	albertcode in your project folder	Working where you already are: your sessions, the conversation with its gates, and every list on one screen. albertcode classic opens the classic terminal
Browser	albertcode web	Reading plans and diffs side by side, with your files, your app, its tests and a shell beside the conversation
VS Code	The AlbertCode panel, or right-click a folder → Open Here	Staying in your editor

See Terminal and Browser interface.

Three modes

Switch with /mode, or use one for a single request with /plan or /do.

Mode	What happens	Use it for
Governed default	You approve a plan; it works in an isolated copy, runs your tests and reviews the result; you approve the diff	Changes you care about
Direct	It works in your files, asking before each write, or applying writes as they come with auto. Needs Git	Quick changes you're watching
Ask	It answers questions and changes nothing	Understanding a codebase

Everyday commands

Type /help for all of them.

Command	What it does
/connect	Connect a model provider: its key, or the address of a local model
/model	Choose a model
/plan <request>	Start a governed change
/attach <paths>	Give it files or screenshots
/tasks	Every task by where it stands; open one to answer its gate
/test	Browser tests for your app: write them, install what they need, run them
/status	The service, the engine and what is connected
/exit	Leave. Sessions and runs keep going; albertcode stop stops the service

albertcode models test checks that a model can drive AlbertCode. Every step is also a subcommand (albertcode create, approve, diff, accept), and albertcode run sends one request without the interface, so AlbertCode fits scripts and CI. See Using AlbertCode.

Files panel

In the browser (albertcode web), the inspector's Files tab shows the repository's files beside the conversation; click a file to read it. Make a new file or folder, rename, duplicate, copy, cut and paste, copy a path, or move something to the Trash, from the toolbar, the ⋯ menu on each row, a right-click, or the keyboard.

Shortcut	What it does
F2	Rename
Delete (⌘ ⌫ on a Mac)	Move to the Trash, after you confirm
Ctrl/⌘ C, X, V	Copy, cut, paste into the selected folder
Arrow keys, Enter	Move around, open a folder or file

Note

The panel only works inside the open repository and never through a link. Git's own folder is hidden, and files that look like they hold secrets, such as .env or keys, are shown with a lock and never opened or changed. Nothing is overwritten, and anything you delete can be restored from the Trash or Recycle Bin.

Terminal

Terminal in the Project menu (or Ctrl `) opens a real shell under the conversation: zsh or bash on macOS and Linux, PowerShell on Windows, in the open repository. Drag its top edge to make it taller; AlbertCode remembers the height. Open more as tabs, and hide it whenever you like: your shells keep running, even across a page reload. Colours, clickable links, full-screen programs, and copy and paste all work as in your own terminal, in light and dark. Run your project's tests and other checks here.

Shortcut	What it does
Ctrl `	Show or hide the terminal
Ctrl Shift `	New terminal tab
Ctrl C	Copy the selection, or interrupt when nothing is selected (⌘ C on a Mac)
Ctrl Shift C / V	Copy, paste (⌘ C / V on a Mac)

Important

The terminal is off until you turn it on, and the panel explains what it allows first: what you type runs on your computer as you, outside the limits AlbertCode puts on the agent. Only your own AlbertCode page can connect to it, and a shared AlbertCode server never offers it. Opening and closing a shell are recorded in the evidence ledger; what you type is not. Turn it off at any time from the panel's ⋯ menu.

Preview

Run the app, in the Project menu (or /preview), starts your app if it is not running and shows it in the inspector's App tab, beside the conversation. If the project has no dev script, it asks for the start command once. Before the app starts, AlbertCode checks its port: when something else is using it, the app gets the next free one, so it never shows another project's app. Switch between desktop, tablet and phone widths, restart or stop it, and open its logs. The status line says whether the app is answering and how (Running · localhost:5173 · 200 · 12 ms). When something is wrong it says so above the app: it did not start, it stopped, it answers with an error page, or its own output reports an error now. Ask Albert to fix puts the error into the chat for you to send.

Edit by clicking

Turn on Edit in the App tab and click anything in your app: a heading, a button, a card. Change its text, text colour, background, size, weight, alignment, padding or corners, and you see the change at once. Nothing is saved yet.

Review change finds where it comes from in your code. When there is exactly one safe place (the text is written once, or the style comes from one CSS rule), it shows the diff, and Apply change writes exactly that; your app reloads with it. When there is not (the text is built from data, it appears in several places, or it is styled with utility classes), AlbertCode says why, and Ask Albert makes the change as a normal task, with the plan and diff for you to approve.

Pictures and videos too: click one, or a section with a background picture, then Replace picture… or Replace video…, or drop a file on the panel. The app shows it at once, and Review change names the file it adds and the one line of code that changes. Click anything else, and Add a picture or video… puts your file in the project and asks Albert to place it. Files are checked by what they are (pictures up to 20 MB, videos up to 95 MB) and wait outside your project until Apply change. See Pictures and videos.

Note

Direct edits work for React with TypeScript, Next.js, Vite with React, and plain HTML, CSS and JavaScript. For other stacks, Albert makes every change. Apply only writes if the files are unchanged since you reviewed them, and each change is recorded in the evidence ledger.

Task board

Tasks…, in the Evidence menu (or /tasks), shows every task on a board, in columns for where each one stands: Planned, Active, Blocked, Verifying and Completed. Each card shows how far it has come, what it is waiting for ("Plan waiting for you", "Diff waiting for you"), its checks and files, and why it failed if it did. Open a card to pick the task up where it is. List shows the same tasks as a searchable list.

Browser tests

The inspector's Tests tab (Browser tests in the Project menu, or /test) checks your app the way a person uses it: pages, forms, saved data and sign-in. The tests are Playwright files in your repository's e2e/ folder, so you can read them, change them, run them yourself with npx playwright test, and commit them.

1. Write browser tests asks Albert for them as a normal task: you approve the plan and the diff.
2. Install adds the test runner with your project's package manager.
3. Run tests starts the app if needed, runs every test in a browser, and shows what passed and what failed. A failure comes with its error, the line in the test, a screenshot and a trace, and Fix with Albert starts a task with all of that in it.

Note

AlbertCode uses a Chrome, Edge or Chromium that is already on your computer. Only if there is none does it offer to download Playwright's Chromium (about 150 MB), and only when you ask. Results come from Playwright's own report: a run that leaves no report is shown as not having run, never as a pass.

Requirements

Requirements…, in the Evidence menu (or /requirements), turns your specification into a checklist and shows where each item stands. Paste the specification and your model drafts one requirement per behaviour; edit the list and save it. It is kept in your repository as .albertcode/requirements.json, numbered R1, R2 and so on, beside the code it describes.

Each requirement's status is worked out from evidence, never guessed:

Status	When
Complete	It has browser tests, and all of them passed in the latest run
Partial	Some of its tests passed, or it was built but no test checks it yet
Failed	One of its tests failed, or the task that built it failed
Missing	Nothing has built it, and no test has passed for it

Each row says why, lists the browser tests behind it with how each one ended, and offers the next step: Build it, Prove it or Fix it, which put the request in the message box for you to send. What Albert makes links back by itself: a browser test titled [R3] … checks R3.

Architecture

Architecture…, in the Project menu (or /architecture), shows what your app is made of and how the parts connect, from its own files, in three columns: what people use (frontends and web pages), what runs (API servers and background jobs), and what it relies on (databases, caches, sign-in, queues, file storage and outside services such as payments or email).

Nothing is guessed. Every box comes from a file that declares it (package.json, pyproject.toml, requirements.txt, go.mod, docker-compose.yml, or the names in .env.example), and a connection is listed only where a file shows it. Each part says what it is built with, where it lives, and how many routes, pages and data models it has; How it was found opens to the files behind it, How they connect lists each connection and what shows it, and Read it again reads the repository afresh.

Models

Provider	Connect with
Major hosted model providers, and Kimi	An API key
OpenRouter	An API key: many vendors' models through one account
Hugging Face	A token, for open-weight models
Any compatible API service	Its address, and a key if it needs one
Your own machine	Ollama, LM Studio, vLLM or another local model server

AlbertCode checks a key or address works before saving it. The model must support tool calling; /test checks one in a single request. More in Models.

Troubleshooting

Installing  ·  command not found, macOS and Windows warnings, Linux, networks

Problem	Fix
albertcode: command not found right after installing	Open a new terminal. The installer added the command to your PATH, and only new terminals see it
macOS: "could not be executed because you do not have appropriate access privileges"	The browser saved the installer without permission to run. Download the .zip for your Mac instead, or run bash ~/Downloads/Install-AlbertCode-<version>-macos-arm64.command in Terminal (x86_64 on Intel)
macOS: "Apple could not verify…" or "unidentified developer"	Open System Settings → Privacy & Security, click Open Anyway, and open the installer again. Or use the one-line command
Windows: "Windows protected your PC"	Choose More info → Run anyway
Windows: PowerShell refuses to run the command	Your organisation may block scripts. Download the .cmd installer from the release and double-click it instead
Windows: "failed to remove directory …\Scripts: Access is denied (os error 5)"	AlbertCode was still open somewhere, and Windows does not let a running program's files be replaced. Installers from 1.42.2 close it for you after asking. With an older one, close every terminal and VS Code window using AlbertCode (or run albertcode stop), then run the installer again
Linux: the installer refuses to run under sudo	Run it as yourself. It installs for your user, and asks for sudo only if Git is missing
Linux: "the release has no installer for Linux on … processors"	Only x86-64 is supported for now, not ARM
Linux: the install fails on Alpine or another musl-based system	Not supported: AlbertCode needs a glibc-based distribution such as Ubuntu, Debian or Fedora
pypi.org can't be reached	Check your connection. Behind a proxy, set HTTPS_PROXY and run the command again
invalid peer certificate or UnknownIssuer	Your network inspects encrypted traffic. Current installers retry with your computer's certificates; if that fails, set UV_NATIVE_TLS=1 and run again
"the package inside it is damaged"	The download was cut short or altered. Download it again

Every installer run writes a log: ~/.local/share/albertcode-installer/install.log on macOS and Linux, %LOCALAPPDATA%\AlbertCode\install.log on Windows.

Running  ·  model connection, tests, browser sign-in, VS Code, stuck tasks

Problem	Fix
"No model is connected"	Run /connect, or choose Connect a provider in the browser or VS Code
After updating, your model is no longer connected	Saved keys are cleared when a new version first starts. Run /connect again
A model connects but tasks stall or fail early	The model may not handle tool calling well. Run albertcode models test, and see Models
Tests don't run, or use the wrong tool	Run albertcode doctor to see which build tools AlbertCode finds, then install or add the missing one to your PATH
The browser page says to open AlbertCode from your terminal	Run albertcode web. It signs your browser in
macOS: "New folder" says the folder is read-only	You are at the top of the disk ("This computer") or in a system folder. Choose Home or Documents in the picker and make the folder there
VS Code can't reach AlbertCode	Run albertcode once in a terminal to start the service, then reload the VS Code window
The preview says "localhost refused to connect" but the app opens in its own tab	Update to 1.42.1 or later: apps that forbid being shown inside another page now show in the preview too
The app starts on a different port than usual	Its usual port was busy, so AlbertCode gave it a free one. The status line shows where it is; nothing else using the usual port is touched
Accepting a change is refused	You edited a file the change also touches. Look at your edits, then run the task again
Everything seems stuck	Run albertcode stop, then albertcode again

Tip

Still stuck? Open an issue with what you ran, what you expected and what happened, plus albertcode --version and your operating system. More fixes are in Troubleshooting.

Caution

Never include keys, tokens or private code in an issue.

Privacy and security

Your code goes only to the model provider you choose. With a local model, it never leaves your machine. No telemetry and no account.

Saved keys are kept by your system's own protection (the macOS Keychain, Windows data protection or your Linux keyring), and are never given to the commands AlbertCode runs. Only AlbertCode itself can use the service it runs on your computer.

See the security model and PRIVACY.md. To report a vulnerability, follow SECURITY.md.

Benchmarks

39 / 51 resolved  ·  76%

SWE-bench Pro HARD-51 Model: a frontier hosted model One attempt per task, up to 50 minutes each, no human help Held out from all development: 14 of 22 resolved

SWE-bench Pro is Scale AI's benchmark of real software-engineering work: issues and features in professional open-source projects, judged by each project's own hidden tests. HARD-51 is its hardest part, the tasks that at least two of five frontier model families failed.

Note

Self-reported. We ran and graded this ourselves; it hasn't been independently verified. The report gives the method, every task's outcome and the limitations.

Documentation

The full guide covers every command, page and button, with examples. It is also inside AlbertCode, offline: Help → Search the guide… in the browser, or /docs in the terminal.

Guide	What's in it
Getting started	Install, connect a model, and complete a first task
How AlbertCode works	The service, the modes, a change's two approvals, tasks, sessions and evidence
Chatting with Albert	Asking, changing, approving, sessions, chats grouped by topic, attachments
Using AlbertCode	The short version of everything, with links
Terminal	The full-screen interface and the classic terminal: every option, slash command and subcommand, scripting, environment variables
Browser interface	The workspace, its menus and inspector, the command palette, every shortcut, Files and Terminal
VS Code	The extension, its panel, every command and setting
Models	Providers, local models, and what a model needs
Architecture	What a repository is made of, read from its own files
Requirements	What the app must do, as a checklist backed by evidence
Preview and browser tests	Run the app beside the chat, edit it by clicking, test it in a real browser
Tasks and evidence	The task board, a task's evidence, the evidence ledger and compliance exports
The contract	What AlbertCode may do in a repository
Extending	Custom commands, custom agents, saved tools and skills
MCP servers	Connectors, adding servers, sign-in, prompts and resources
Plugins	Installing, updating and making plugins
Installation	Options, updating, uninstalling and requirements
Security model	How your keys, code and data are protected
Troubleshooting	Fixes for common problems
FAQ	Short answers
Glossary	Every term, in one place

FAQ

How is AlbertCode different from other coding agents?

Many agents edit your working tree as they go, and leave you to work out whether the result is right. AlbertCode builds the change in an isolated copy. It runs your own tests, reviews the change, and brings you a diff with the evidence, and you decide whether it lands. When you want speed instead, direct mode skips the ceremony.

Is AlbertCode open source?

No. AlbertCode SWE Agent is a proprietary product. This repository is open: its documentation, installer, examples and benchmark methodology welcome contributions. See the FAQ.

Does it cost anything?

You use your own model provider account, or a free local model. AlbertCode doesn't charge for model usage.

Community

Questions and ideas	Discussions
Bugs and feature requests	Issues
What's coming	The roadmap and the changelog
Contributing	Docs, examples, the installer and integrations. See CONTRIBUTING.md

If AlbertCode saves you time, a ⭐ helps other developers find it.

License

AlbertCode SWE Agent is proprietary software, and it isn't covered by the licences in this repository. Code in this repository is Apache-2.0, and its documentation is CC BY 4.0. See LICENSING.md.