Chatting with Albert

Albert is AlbertCode's agent. You talk to it the same way in the terminal, the browser and VS Code: ask a question, or say what you want changed. This guide covers the conversation itself: what to type, the approvals, sessions, attachments and shortcuts.

• New to AlbertCode? Read How AlbertCode works first.
• Looking for one command? See the terminal reference or the browser reference.

Where you type

Asking a question

Ask anything about the repository. Albert reads the code to answer, and changes nothing.

› What does this project do, and where are the tests?
› Where is the session cookie set, and how long does it last?
› Why would /api/orders return 403 for an admin?
› Which of our dependencies are more than two major versions behind?

Good questions name what you are looking at: a file, a function, an endpoint or an error message. Paste the error itself rather than describing it.

Asking for a change

Say what you want, and how you will know it is done:

› The /login endpoint returns 500 when the password is empty. Make it return 400 with
  "Password is required", and add a test.

› Add a "Remember me" checkbox to the sign-in form. When ticked, the session lasts 30 days
  instead of one. Keep the existing tests passing.

› Rename the `cust` table's `nm` column to `name`, with a migration, and update every query.

What happens next depends on the mode:

• Governed (the default): Albert writes a plan and waits for your approval. See Approvals.
• Direct: Albert works in your files straight away, asking before each write (or not, with auto-approve).
• Ask only: Albert offers the change and waits. In the browser, Start a governed change? shows the request it would send: Yes, plan it, Do it directly, or keep talking. In the terminal: p plan it, d do it directly, e edit the words, n keep talking.

Choosing for one request: /plan and /do

Start a message with /plan or /do to choose for that request, whatever the mode:

› /plan Split billing/invoice.py into invoice_model.py and invoice_pdf.py
› /do Fix the typo in the README's install section

/plan always starts a governed change; /do always starts a direct one. In the terminal, /direct <request> is /do, and /direct auto <request> applies each write without asking.

Changing the mode

The browser's command palette (Ctrl K) also has every mode.

Approvals

A governed change stops twice for you.

1. The plan

The plan says what will change and why: the goal, the files and how each changes, the steps, the test plan, security points, how to roll it back, and the assumptions it made.

Rejecting discards the task. Nothing has been written at this point.

2. The result

When the change is built, tested and reviewed in its isolated copy, you see the outcome: the files changed, the checks that ran and their results, the reviews' findings, and the steps it took.

If a review blocked the change, accepting is not offered. Say how to address the findings and Albert works on it again (Ask for changes in VS Code, revise in the terminal), or discard it. In the terminal you may also keep the isolated copy to inspect it yourself, or delete it.

Accepting is refused if you changed a file the change also touches since the task started. Look at your edit, then run the request again.

Direct writes

In Direct with Ask each write, each write and each command waits for you:

With Auto-approve (/mode auto, or /direct auto for one request) writes apply as they come. Either way, Git is your undo: git diff shows what changed and git restore puts it back.

While Albert works

• Steps. Each step appears as it happens: what Albert read, searched, ran and changed. Open a step to see its output or diff. In the terminal, /tasks and then a task's steps open the same detail.

• The gate track. In the browser, while a session has a governed task, a track under the session's title shows where the task stands, from the plan to your files:

  Copy

  ✓ Plan ─ ◆ Your approval ─ ○ Build in a copy ─ ○ Checks ─ ○ Reviews ─ ◇ Your acceptance ─ ○ In your files

  The work is circles and your two decisions are diamonds. Done is green with a tick, the step under way is lit, a step waiting for you is amber, and where a task stopped is red. Above, the plan is waiting for your approval. Click the track to go to the task's card. Direct and Ask only have no gates, so no track.

• Stop. The Stop button (browser and VS Code) ends the run. A governed change's isolated copy is kept until you discard it. In the browser you can stop a run from the sidebar too, without opening its session: see Sessions.

• It keeps going. A run belongs to the service. Start a new session, switch to another, or close the window, and it carries on. Its session in the sidebar shows a moving lamp while it works and an amber one when it is waiting for you.

Follow-ups

Keep talking in the same session to build on what was just done:

› Now add the same validation to /register.
› Why did you change the session middleware?
› Undo the change to config.py but keep the rest.

A follow-up to a change starts a new task that continues the previous one: Albert is told what the previous task changed and why, so you don't repeat yourself.

Sessions

A session is one conversation. Nothing said in one session reaches another, and each has its own run: start or open another session while one is working, and the first carries on (see While Albert works).

In the browser, the sidebar lists every session under the folder it works in, the folder you used most recently first:

SESSIONS                     Projects | Days
▾ S shop                                  3
    ● Show prices with VAT on the…            the session open now
    ● Add a WELCOME10 discount…          1h   waiting for you (amber)
    ○ Add discount codes in shop/…       3h
▾ N notes                                 2
    ○ What does the notes app store?     2h   pinned, so first in its folder
    ● Why does saving a long note…       1d   stopped with an error (red)
▸ PA payments-api                         3   folded

• The lamp before each title moves while its run works, is amber while it waits for you (a plan or a diff to approve, a write to allow), and is red when its run stopped with an error while you were elsewhere, until you open it. A ring means nothing is going on.
• When it was last used is on the right. Hover a row and its ⋯ takes that place.
• A folder's row folds and unfolds its sessions, and AlbertCode remembers. A folded folder still shows the session open now, and its row lights when one of its sessions needs you. Its + starts a new session in that folder. Its ⋯ has New session here, Copy its path and Delete its sessions… (the session open now is kept, and the folder and its files are never touched).
• Days, above the list, lists the sessions by day instead: Pinned, Today, Yesterday, Previous 7 days, Previous 30 days and Older. Projects goes back. AlbertCode remembers which you chose.

Each session's ⋯:

Example. You ask in shop for "Add a WELCOME10 discount code, with tests", then open notes and ask "Why does saving a long note fail?" while the first is still working. Under shop its lamp keeps moving; when the plan is ready it turns amber, wherever you are. Its ■ stops it without leaving notes.

Opening a session picks it up where it was: its words, its run (still working, or waiting for an approval you can give now), and the folder it was about. The top of the conversation shows the session's title, its folder and branch, and its mode.

On the classic page, Clear this chat, in the ⋮ menu, empties the session open now.

Chats about one thing

When you start a chat from a button on one of AlbertCode's pages, the chat is filed under the thing that button is about. When a thing has more than one chat, the sidebar shows it as one row that opens to its chats, with a count, under its folder (or its day):

▾ N notes                            4
    ▾ Add a note and see it listed     2
        Add a browser test for R1 …
        Build R1: add a note …
    ▸ notes.spec.ts: add a note        2
    ○ What does this repository do?

So the work on one requirement, or on one test, stays together.

No second chat for the same work. While a chat about a thing is still working, or waiting for you, a page's button about the same thing opens that chat rather than starting another: pressing Fix with Albert twice, or going to the chat and back and pressing it again, leaves one chat and one task. A new chat about it starts only once that work is over (accepted, rejected, cancelled or failed). Chats you start by typing are not filed under anything. A topic belongs to its folder: the same test in two different repositories is two topics.

Click a topic's row to open or close it; AlbertCode remembers your choice. A topic opens by itself when it holds the chat you are in. Searching finds chats inside topics and opens their topic.

Attachments

Give Albert screenshots, logs, documents and other files with your message.

Files up to 500 MB are accepted. What you attach goes with your next message only. Pictures reach the model as pictures when the model accepts images; when it doesn't, AlbertCode tells you rather than letting the model guess.

Models

See Models.

Commands, agents and MCP prompts in the chat

• Custom commands. /review src/cart.py sends the text your review command holds. A plugin's command is also reachable as /plugin:command. See Extending.
• Custom agents. /agent reader works as the reader agent from now on; /agent default goes back. In the browser, the agent chip beside the mode does the same.
• MCP prompts. /server:prompt arguments uses a prompt an MCP server offers, such as /github:review-pr 128. See MCP servers.

Shortcuts

The browser reference lists every shortcut, including the Files panel, the terminal and the folder picker.

Writing good requests

• Say what done looks like. "Return 400 with a message", "the existing tests still pass", "add a test that fails before the fix".
• Name the place when you know it. A file, a function, an endpoint or a page.
• One change at a time. Two unrelated changes are two requests; each gets its own plan, diff and evidence.
• Paste the evidence. The full error, the failing test's output, a screenshot.
• Let the plan be your review. If the plan is wrong, say what to change before approving it: it is cheaper than reviewing a wrong diff.