AstraCode

A coding agent for VS Code. Its models come from your AstraWork account, and every model call goes through the AstraWork gateway.

Install

code --install-extension astracode.vsix

Then open the AstraCode icon in the activity bar. The chat stays locked until you sign in.

Sign in

Click Sign in to AstraWork. Your browser opens the AstraWork sign-in page. After you sign in, copy the address of the page you land on (it contains a sign-in code), or the access token (JWT) that AstraWork shows, and switch back to VS Code. AstraCode reads the clipboard for a short time after you click the button, and ignores anything that is not a sign-in credential.

The token is kept in VS Code SecretStorage, never in settings.json. When the session expires, sign in again.

Layout

AstraCode has one activity bar icon. It holds two views: the chat, and Session changes.

To put AstraCode in the secondary side bar, next to Claude Code, right-click the view title and choose Move View, or drag the view there. VS Code remembers the position across restarts. An extension cannot place its own view, so this step is yours.

Toggle the sides with AstraCode: Toggle the primary side bar and AstraCode: Toggle the secondary side bar in the Command Palette.

The chat title bar has two buttons: + starts a new chat, and the history icon opens the chat history. Settings is the gear button next to the attach button in the input box. AstraCode: Show logs is in the Command Palette.

Chat

Each turn starts with an AstraCode header and the time. While a turn runs, the send button becomes Stop.

Every step the agent takes is a row showing the tool, its arguments, the result and how long it took.

• Consecutive reads and searches are grouped under Explore. The group is collapsed by default and opens itself when a step fails.
• A file edit shows how many lines it added and removed, for example +32 −18.
• When the agent keeps a checklist, it appears as Agent plan with a progress bar. Collapse it to see only the current step.

Giving the agent context

• Type @ and part of a file name to attach a file. The agent reads the file when it needs it, so its content is not pasted into your message.
• Attach images with the attach button, with Ctrl+V, or by dragging them into the input box. Up to 4 images per message: PNG, JPEG, GIF or WebP, about 4 MB each. The planning model reads images.
• Select code in the editor and choose AstraCode: Add to Chat, or use the pin hint that appears above the input box. Pins go with the next message only. A pinned file longer than 5,000 lines is cut to its first part.
• Up arrow in an empty input box walks back through the prompts you sent, from this panel and from the astracode CLI.

Projects and tasks

Above the input box are two pickers, Project and Task. Both lists come from your AstraWork account. The Task list shows only your open tasks in the coding stage.

When you choose a task, the tokens and cost of each turn are recorded against it on the AstraWork productivity board. With No task, work is not measured. The task's plan dates appear under the pickers, for example 3 days left, or 2 days overdue in amber.

Report Done appears when a task is selected. It opens a form with the task's plan dates, actual dates, tokens and cost in USD. The tokens and cost are the usage already recorded against the task; edit any field you know better. AstraWork stamps the actual dates itself. If it keeps its own dates, only a reviewer can change them.

Permissions

The permission mode decides what the agent may do. Switch it from the picker under the input box, with Shift+Tab, or with AstraCode: Change permission mode.

The approval box shows what the agent wants to do, with the diff or command and any warnings. Three rules hold in every mode:

• Shell, Python and package-install tools always ask, and so does every MCP tool. No mode approves them automatically.
• An action that reaches outside the workspace always asks, with the reason listed in the box. Writing Git metadata (.git) is refused.
• "Always allow" is not offered for shell tools or for actions that carry a warning. Otherwise it is remembered until the session ends, and only for the folder that holds the file. Approving an edit to src/api/user.ts does not cover .github/workflows.

Trust-based downgrade. If the agent reads content that looks like injected instructions, or brings in content from an outside source, the session drops to Ask first even when Auto-edit was on, and every "always allow" is cleared. Only you can lift it, by choosing Auto-edit again.

Tracking changes

Every file the agent edits or creates is recorded in the session change log, visible in three places:

The diff is against the content from before the agent first touched the file, not against what is on disk, so it stays correct after several edits.

Edits go through VS Code's workspace edit API. That means Ctrl+Z undoes them, and unsaved changes in an open editor are not overwritten. Commands run by the agent are not part of this log, so /undo cannot restore files that a command wrote.

Running commands

The agent's shell and Python tools run commands as astra.sandbox says:

If host is set but your organization's policy does not allow it, the command tools are switched off and the chat says why. Use docker in that case. Until the policy has loaded, the default policy applies, which gives the same result.

AstraCode never falls back from docker to host on its own.

With docker, Windows paths such as C:\Work\repo are translated to /workspace in the commands sent in, and back in the output.

MCP servers

MCP servers run someone else's code next to yours, so they are off by default (astra.mcp). When you turn them on, the servers come from the catalog in the repo's sandbox/mcp/servers.json. Every MCP tool call asks for approval, and no server starts in an untrusted workspace.

Memory and long conversations

ASTRA.md holds project notes that are loaded into the prompt on every turn. Type /memory <rule> in the chat to append a rule, /memory on its own to open the file, or use AstraCode: Edit the project ASTRA.md. For notes that apply to every repo, keep a file at ~/.astra/ASTRA.md.

A rule you only say in the chat lives in that conversation. A new chat, /clear, or a compaction that drops it, and the agent no longer knows it. /memory is what makes a rule survive.

Keep it short. Every line costs context on every later question. Each memory file is capped at 12,000 characters, and each is scanned for prompt-injection signals. A file that reads like commands is flagged in the chat, because it goes straight into the system prompt.

Context. The context gauge appears at 70% of the model's context window. At about 80% (earlier when the window is small), the conversation is compacted before the next turn: the most recent turns stay word for word, and the older part becomes a summary with four sections: goal, what was learned, what changed, and what is left. Turn this off with astra.autoCompact, and run /compact yourself instead.

/compact takes a note: /compact keep the details on PermissionManager tells the summary what to write out in full. The four sections are always written, so a note never drops the rest.

/undo returns files to their state before the last turn, not before the whole session. The snapshots live in ~/.astra/file-history/, so they survive restarts. After you reopen a conversation, /undo asks for confirmation first, because the files on disk may have changed since. Snapshots older than 30 days are removed. /undo cannot restore files that a bash command wrote.

Sessions are saved after each turn, outside the repo. The title bar has two buttons for them:

The same actions are in the Command Palette as AstraCode: New chat, AstraCode: Chat history and AstraCode: Reopen a past session, and /sessions lists them too. The list shows only sessions from the folder you have open, and a conversation is saved after its first answer.

Slash commands

Type / in the input box to pick one.

Your own commands go in ~/.astra/commands/<name>.md:

---
name: review
description: Review the current diff
---
Read the diff on this branch and point out real bugs, skipping style questions.
Focus on $ARGUMENTS.

$ARGUMENTS receives everything typed after the command name. $1 to $9 receive individual words. With no placeholder at all, the arguments are appended at the end.

Commands from the repo (.astra/commands/) run only in a trusted workspace. They carry a from repo label in the suggestion list, because someone else wrote them.

Verifying after an edit

astra.verifyCommand runs after every agent turn that changed files. It needs astra.sandbox enabled.

// USER settings.json, not the workspace one
"astra.verifyCommand": "pnpm test"

When the command fails, its output goes back into the conversation so the agent can keep fixing. When it passes, nothing is added to the context.

A value set in the repo's .vscode/settings.json is ignored, and the chat says so. That command comes from anyone who can open a PR against the repo, so running it automatically would hand execution rights to a folder just because you opened it.

Configuration

Everything below is in the settings popup inside the chat panel. Open it with the gear button, or with AstraCode: Open settings. It opens over the conversation rather than replacing it, so changing a model does not cost you the question you were in the middle of. Close it with Esc, the ✕ button, or a click outside. There is one settings surface, so there are never two panels that disagree.

The popup opens on a list of five sections. Each row shows a short summary, so you can check your account or the active models without opening anything. Click a row for its details, and use ‹ to go back. A red dot on a row means something there needs attention.

If sign-in is missing or the model list failed to load, the popup opens straight on that section.

Context & Usage

The percentage chip next to the mode button in the input box shows how much of the model's context window this conversation uses. Click it to open Context & Usage:

• the context window used, split by source: system prompt, system tools, MCP tools, memory, skills and the conversation itself;
• AstraCode's cache hits from the last turn, and the room still available;
• your account's turns and spend and, when AstraWork reports a limit, the balance and the share of the limit used. These are the same numbers your AstraWork profile shows;
• when the numbers were last read, with a refresh button.

Chat is blocked until you sign in. AstraCode's models come from your AstraWork account and from no other source.

Models

• Coding model is used for edits, commands, titles and summaries.
• Planning model is used for images and for everything while plan mode is on.

Both are saved to settings.json. The model list, what each model may be used for, and the quotas all come from your account. A model your account cannot use is shown, but disabled.

The Model button next to the mode button in the input box chooses a model for this conversation only. Its menu has Make this the default, which saves the choice as astra.model for every conversation.

Server addresses need no setup. The AstraWork gateway and web addresses are built into the extension, and there is no setting for them. AstraCode: Test connection checks that the build reaches the gateway and that your account's models come back.

Capability profile

The model table shows tool calling, context window and injection resistance. The gateway does not report these three. They come from models.json, which astracode measure writes. The CLI and the extension share ~/.astra, so a model measured in the terminal is known in the IDE.

You do not need to measure anything to start. A model missing from models.json is assumed to support native tool calling and image input, to have a 32,768-token context window unless the gateway states its own, and to have an injection resistance of unknown. If an assumption is wrong, the first turn fails. AstraCode then switches that model to the XML tool path, remembers it, and says so in one line.

Injection resistance cannot be probed at runtime. A model measured as low is kept out of work that has write access. An unmeasured model reads unknown, which is not excluded.

Where AstraCode keeps things: ~/.astra

Shared with the astracode CLI. Nothing here belongs to a single repo. Project configuration lives in .astra/ inside the repo itself.

Set ASTRA_HOME to move the whole directory somewhere else.

Settings in settings.json

Your organization's policy can tighten some of these, for example the permission mode and sandbox networking. AstraCode shows a notice when it does.

Logs: AstraCode: Show logs in the Command Palette. Every line goes through the secret redactor before it is written.