AIMO — Pooled AI for VS Code
An in-editor coding agent on your organisation's Bosphorus platform. AIMO chats
with the models you are permitted, reads and edits your workspace, runs commands,
reaches the platform's tool servers, and keeps your secrets in your own vault —
asking before it changes anything, and handing your secrets to commands and tools
rather than to the model.
Every request is yours: it is signed in as you, counted against your quota and
rate limits, checked by your organisation's policies, and listed on the platform's
activity and usage pages under your name.
AIMO is made for a Bosphorus installation. Without one it can still run on your
own provider API key — see Use your own API key — but
then nothing the platform adds applies. Installation guide and downloads:
https://bosphorus.morten.com.tr/workspaces/aimo-for-vs-code/
Before you start
- VS Code 1.85 or later.
- Your organisation's gateway address, for example
https://ai.corp.example.
Your administrator gives it to you.
- Your corporate account on the identity provider the platform uses.
- A network path to the gateway. On many installations it answers only on the
company network or over VPN.
Or, with no Bosphorus installation: an API key from OpenRouter, Hugging Face, Evren,
Novita or Cerebras, or the address of an OpenAI-compatible endpoint.
Connect to your gateway
Run AIMO: Set Gateway URL from the Command Palette and enter the address your
administrator gave you. Nothing else works until this is set. The address is kept
in your own user settings; a repository's settings cannot change it. The first
step of the walkthrough and the Tool Servers view offer the same, and also
Use your own API key.
Sign in
AIMO signs you in with the identity provider the platform itself uses — Microsoft
Entra ID on some installations, an OpenID Connect provider such as Keycloak on
others. It learns which from the gateway, so there is nothing more to configure.
- Run AIMO: Sign in. A short code is copied to your clipboard and the sign-in
page opens.
- Paste the code and finish the sign-in in the browser.
- AIMO exchanges that sign-in for your own platform key and keeps it in VS Code's
secret storage.
Signing in on a second machine rotates the key; the first machine gets a new one by
itself on its next request. AIMO keeps one key per gateway, so windows on two
different gateways each keep their own. AIMO: Sign out removes this gateway's key
from this machine.
Use your own API key
With no Bosphorus installation, AIMO runs on your own provider API key instead —
direct mode. Run AIMO: Use Your Own Provider API Key… and choose where your
chats go:
| Provider |
Notes |
| OpenRouter |
Many providers behind one key; reports what each request cost |
| Hugging Face |
The inference router, one entry per serving provider |
| Evren |
Serves from Türkiye; keys start with evren_llm_, and you accept its terms of use yourself |
| Novita |
Keys start with sk_ |
| Cerebras |
Keys start with csk- |
| Custom endpoint |
Your own: any OpenAI-compatible API, such as https://llm.example/v1, or a model server on this machine at http://127.0.0.1:1234/v1 (no key needed there). For LM Studio, AIMO reads each model's context window from LM Studio's own model list |
- Before anything is sent, AIMO shows once on this machine what changes: your
messages, attached files and tool output go straight to that provider, and the
platform's policy checks and guardrails, quotas, audit trail, curated models,
tool servers and vault do not apply.
- Direct mode is per window (see Each window has its own
settings): it signs nobody out, and your
windows on the platform keep their sign-in. While a platform key is on this
machine, your own tool servers do not run in a direct-mode window, because the
platform decides about them while it governs you. Use them in a window on the
platform, or sign out of the platform first.
- The key is checked with the provider without spending a token, kept in VS
Code's secret storage on this machine, shown only as its last four characters,
and sent only to that provider. AIMO: Set the Provider API Key… replaces it,
AIMO: Remove the Provider API Key… deletes it.
- The model is the one you pick with AIMO: Select Model (or type an id):
in direct mode AIMO never picks one for you. Each chat keeps its own; new chats
start on
aimo.direct.model, the one picked last.
- Evren asks you to accept its terms of use. AIMO never accepts them for you:
Read the terms, then I accept version N (AIMO: Evren Terms of Use…).
- Home shows the provider, the key's last four characters, the model, and
today's requests and tokens, with the cost as the provider reports it.
- A chat asks before it moves. Continuing a chat somewhere else — from the
platform to a provider, back, or to another provider — asks first and names
where its whole history would go; New chat starts afresh instead.
- What a repository cannot do: switch the connection, pick the provider, the
endpoint or the model, or raise what a turn may spend. In direct mode
aimo.maxAgentSteps, aimo.maxOutputTokens, aimo.contextTokens and
aimo.mcp.directToolBudgetPercent come from your own settings only.
AIMO: Switch Connection (Platform or Your Own Key)… takes this window back to the
platform, with the sign-in this machine still holds for it, or a new one.
Each window has its own settings
Every VS Code window keeps its own connection (the platform or direct mode), its
provider and model, and its platform addresses (aimo.gatewayUrl,
aimo.vault.*, the sign-in overrides). One window can use direct mode while another
is on the platform, or two windows can use two different gateways. Every other
setting is shared by all windows, as before.
- The first time a new window uses AIMO (Home, a chat, or a command that changes
one of those settings), AIMO asks: copy another window's settings here, or
start fresh with AIMO's defaults. Windows AIMO already ran in keep what they
had; the very first window takes what your settings hold.
- AIMO: Settings of This Window… (also in Home's ⋯ menu) shows this window's
settings, copies another window's, or starts fresh.
- What AIMO changes (Switch Connection, Select Model, Set Gateway URL, the vault
address) changes this window only. It is also written to your settings, so the
Settings editor shows it. A change you make in the Settings editor or
settings.json applies to the window you make it in; the other windows keep
theirs.
- Keys and sign-ins belong to a gateway or a provider, not to a window: a window
that copies another's gateway uses the sign-in this machine already holds for it.
Home
The AIMO icon in the activity bar opens Home: who you are, what you have used,
and every chat of this workspace. Chats open as editor tabs — side by side, each on
its own folder — and come back after a window reload.
- Sessions come first (see below); Account & usage follows: your account, team and profiles; the model, tool servers and
vault; the last minute's requests and tokens on your key, against the limits the
gateway reports for it (unlimited when it sets none); and today's tokens, requests and cost when your
platform offers them.
- Sessions: + New chat (⋯ for another folder). Open chats come first, the
ones that need you at the top — needs approval, finished while you were
elsewhere, answering… — then pinned chats, then the rest by folder. All /
Active / Pinned filter the list; the search box looks through titles and through
what was said. Hover over a chat to open it beside, pin, rename or delete it, open
its requests on the platform, or stop an answer.
- A chat waiting for you is also counted on the AIMO icon and in the status bar, and
announced when you are looking at something else (
aimo.notifyInBackground).
Chat
| You want to |
Do this |
| Ask about the code you are looking at |
Just ask. The open file's path and your selection travel with the message as chips above the message box; click a chip to leave it out |
| Attach more files |
+ File, or right-click a file in the Explorer ▸ Add File to AIMO Chat |
| Show it a screenshot |
Paste it into the message box (Cmd+V / Ctrl+V), Shift-drag an image onto the chat, pick a PNG/JPEG/GIF/WebP with + File, or on macOS Screenshot (AIMO: Attach Screenshot). See Images |
| Copy a whole answer |
The copy button in the answer's header (point at the answer). It copies the Markdown as the model wrote it |
| Copy a command from an answer |
The copy button on a code block. From a shell block that shows prompts and output it copies only the commands; the terminal button pastes them into the terminal without running them. See Code in answers |
| Explain or fix a piece of code |
Select it, right-click ▸ AIMO ▸ Explain This / Fix This |
| See what an edit would change |
The approval card shows the diff; Open diff opens it in the diff editor |
| Allow everything for one turn |
Allow all on an approval card. A command that receives vault values is still asked about, every time |
| Take a turn's edits back |
Undo on the notice that follows the turn, or /undo |
| Continue yesterday's chat |
Click it in Home, or AIMO: Chat History / /history |
| Start another chat without losing this one |
+ New chat in Home, New Chat in a chat tab's title bar, or /new |
| See every open chat and switch |
Home, AIMO: Switch Chat…, or /chats |
| Run a chat on a different folder |
⋯ next to + New chat, AIMO: New Chat on Another Folder…, or /tab |
| Point at a file, some lines, or the editor's problems |
Type @: @src/app.ts, @src/app.ts#L10-40, a symbol, @problems, @selection |
| Only ask, or plan before anything changes |
The mode button under the message box, Shift+Tab, or /mode. See Modes |
| Send the next message while it is still answering |
Just send it: it waits above the box and goes next (× takes it back) |
| Go back to an earlier message |
Hover over it ▸ Rewind: the chat returns to before it, the message goes back into the box, and AIMO offers to put back the files it changed since |
| Try another direction without losing this one |
Hover over a message ▸ Fork, or /fork for the whole chat |
| Name a chat |
/rename, or rename it in Home |
| Use the repository's AGENTS.md / CLAUDE.md |
Accept it when AIMO offers; /instructions changes your answer. See Project instructions |
| Free up context |
/compact |
Modes
| Mode |
What AIMO may do |
| Ask |
Answer and read the workspace; nothing that changes anything is offered or run |
| Plan |
Read, then write a plan; Implement the plan switches to Agent and carries it out |
| Agent |
Do the work, asking before every change (the default, aimo.defaultMode) |
| Auto-edit |
Edit files in the workspace without asking. Commands and tool-server changes still ask, and commands get no values from your vault |
In every mode a command that is about to receive vault values is asked about every
time, and in a folder outside Workspace Trust every action is asked about. Switching
to Ask during an answer stops the next change.
Project instructions
A repository may carry instructions for AI agents — AGENTS.md, CLAUDE.md,
.github/copilot-instructions.md or .aimo/instructions.md. Whoever wrote the
repository wrote them, so AIMO asks first (Use them, Show them, Not for this
folder) and asks again when they change. Accepted, they go with every request on
that folder, below AIMO's own rules; the box names them (📄). Never in Restricted
Mode; aimo.projectInstructions turns this off.
Code in answers
Code blocks are coloured by their language. Each has two buttons:
- Copy copies the block. From a shell block that shows a session — a prompt such
as
$ or (venv) ➜ dir git:(main) followed by output — it copies only the
commands, without the prompt and without the output.
- Insert puts the block at the cursor in the editor. On a shell block it is the
terminal button instead: the commands are pasted into the active terminal (or a
new one) and wait for you to press Enter. Several lines arrive as one paste, so none
runs on its own.
Images
Up to five images go with one message, each shown as a thumbnail above the message
box; an image on its own is a message. Each is scaled to at most 1568 px on its long
edge before it is sent, so a full-screen screenshot costs about 1,700 tokens of the
model's window.
- The model has to be able to see. Select Model marks the models the gateway
confirms as
vision. Sent to a model that is not confirmed, the image goes anyway
with a one-time notice; if the model refuses it, the image is attached again so
you can pick another model and send.
- Dropping onto the chat needs Shift held while you drop. Files from the
Explorer get the same checks as + File.
- Screenshot (macOS) runs the system capture tool: drag a region, Space for a
window, Esc to cancel. macOS may ask you to allow VS Code under System
Settings ▸ Privacy & Security ▸ Screen Recording. Elsewhere, paste a screenshot.
- Images are not kept with a stored chat — only thumbnails.
- A chat is stored as it goes: every few seconds while an answer runs, when its tab
closes and when the window closes. Stored chats belong to the window's folder or
workspace, not to the folder a chat works on: a folder you open in a window of its
own (a git worktree, say) has a list of its own.
- A turn your organisation's policy blocks stays in the chat for you to read, and
is taken out of what the model sees; the model is told which files it changed.
Type / in the message box for the commands: /new, /mode, /model, /tools,
/vault, /compact, /undo, /rename, /fork, /instructions, /history, /tab,
/chats, /clear, /status, /help.
Shortcuts: Ctrl+Alt+A (macOS Ctrl+Cmd+A) goes to the chat you used last (or a
new one), Ctrl+Alt+Shift+A (macOS Ctrl+Cmd+Shift+A) starts a new chat,
Ctrl+Alt+L (macOS Ctrl+Cmd+L) adds the selection to the chat. In the message
box, Enter sends, Shift+Enter starts a new line, Shift+Tab changes the
mode, @ points at a file, ↑ recalls your last message and Esc stops an
answer.
What the agent can do
| Tool |
What it does |
Asks first |
read_file |
read a file, optionally a line range |
only for files that usually hold credentials |
list_directory |
list a folder |
no |
find_files |
find files by name or glob |
no |
search_text |
search file contents |
no |
get_diagnostics |
the problems the editor reports |
no |
write_file |
create or overwrite a file |
yes, with the diff |
str_replace |
replace one exact passage |
yes, with the diff |
run_command |
run a shell command in the workspace |
yes |
mcp_list_servers, mcp_search_tools |
find a tool on the platform's tool servers, or on this machine's |
no |
mcp_call_tool |
run one |
yes, unless the server marks the tool read-only; always for a server on this machine that holds secrets |
Every file path is contained to the workspace folder, judged by where it points: a
link inside the workspace that leads out of it is outside. Stopping a turn, or a
command's timeout, ends the command and everything it started.
Files that usually hold credentials — .env, private keys, cluster
credentials, *.tfvars, secrets.yaml and the like — are read only after you
agree, and a search that matches inside one says so without showing the line.
Models and the context window
Leave aimo.model empty and AIMO uses the model the platform recommends for you.
AIMO: Select Model lists every model you may use with what it is confirmed to
do and the size of its context window.
Each chat keeps its own model. Pick a chat's model with its model button or
/model: that chat's next message goes to it, and no other open chat changes. The
pick also becomes aimo.model, the model new chats start on. Select Model from
Home or the Command Palette sets only the model for new chats, and changing
aimo.model in the settings moves no open chat either. A chat you reopen from
the history comes back on its own model.
AIMO sizes every request to the model's window before sending it. When a
conversation outgrows the window, older tool output is shortened first, then whole
older turns are dropped; a notice tells you when that happened, and the gauge under
the message box shows how full the window is.
The platform's MCP tool servers reach you through the gateway's governed relay.
AIMO never learns a server's address or credentials.
- On demand is how every server works unless you decide otherwise. The model is
given three small tools — list the servers, search for a tool, call a tool — and
looks up what it needs. The size of the registry costs nothing.
- Pinned servers load their tools into every request. Pin the one or two you
use all day with AIMO: Choose Tool Servers, which shows what each costs.
Some tools have to run where you work: a browser AIMO drives, or a tool server of
your own. Switch aimo.mcp.local.enabled on (it is off by default) and they are
listed in Tool Servers beside the platform's:
- Recipes your organisation registers — Chrome DevTools and Playwright,
each at a version fixed in AIMO itself. Options are yours
(
aimo.mcp.local.recipeOptions: headless, isolated, and browserUrl or
browser). The first start on each machine (and on each remote host or
container) downloads the package first, with up to 5 minutes for that, while
Tool Servers shows it as downloading; later starts run from npm's cache.
- CodeGraph, when your organisation registers it, answers questions about the code
in the chat's folder from CodeGraph's own index of that folder. AIMO runs exactly
CodeGraph 1.5.0, installed with CodeGraph's own installer (AIMO never installs it;
macOS and Linux for now), in its own process with CodeGraph's telemetry and update
checks off. Indexing is your decision, folder by folder: AIMO asks before it
indexes one, or run AIMO: Index This Repository with CodeGraph; until then it
offers no tools there. Files outside the folder and credential files are removed
from its answers, and another repository on your machine cannot be asked.
- Your own servers, in
aimo.mcp.local.servers — a command, or an https://
address (http:// only on this machine). The model sees each as own_<name>:
{
"aimo.mcp.local.enabled": true,
"aimo.mcp.local.servers": {
"notes": { "type": "stdio", "command": "node", "args": ["/opt/tools/notes-mcp.js"] },
"search": {
"type": "http",
"url": "https://mcp.corp.example/mcp",
"headers": { "Authorization": "Bearer ${secret:search-token}" }
}
}
}
- Each server asks before it first runs here, showing exactly what it starts —
the command it found, its arguments, its folder, the name of every secret or
vault value it receives (never the secret itself), and any plain setting as
written — and asks again whenever that changes, or on another machine (an SSH
host, a container). Unless you give it a
cwd, it runs in a private folder of
its own, not in your workspace.
- Secrets are never written into settings.
${secret:<id>} names a value
stored with AIMO: Set Local Server Secret; ${vault:me/<path>#<key>} one in
your vault. A plain value for a name like Authorization or API_TOKEN is
refused. A secret a server echoes reaches the model as [secret:<id>].
- The approval card shows every argument of the call. A server that receives
secrets is asked about every time, even after Allow all. It gets none of
them with
aimo.autoApproveTools on, on a folder outside Workspace Trust, or in
Auto-edit when it runs on the chat's folder (${workspaceFolder}).
- While you are signed in, the platform checks and records every call before it
runs. If the platform refuses it, nobody is asked and it does not run; if the
platform cannot be reached, local tools do not run. Your organisation may also
switch your own servers off.
- Nothing local runs in Restricted Mode. In direct mode your own servers work
too, without the platform's check.
- AIMO: Restart Local Tool Server and AIMO: Forget Local Tool Server
Consent are on each server in Tool Servers.
The MCP traffic log
If you switch aimo.trafficLog.enabled on (it is off by default, and AIMO: Turn the MCP
Traffic Log On or Off asks first), AIMO keeps an encrypted log of what passes between it
and the tool servers on this machine, in this VS Code profile's storage. Values AIMO knows
to be secret are masked before anything is written, and so are credential-shaped headers,
cookies, tokens and the values in URLs; a secret a tool server shows that AIMO does not know
— a website's own cookies and tokens, what a page contains — is recorded as the server sent
it.
- It stays on this machine unless you upload a segment yourself, from MCP traffic
log in Tool Servers. AIMO names what goes where and asks first; an upload goes only
to your organisation's gateway, where you and its administrators can read it and the
calls the platform checked are matched against its own records. AIMO: Show My Uploaded
MCP Traffic Logs withdraws one.
- Switched on on another machine and carried here by Settings Sync, it records nothing
until you say yes on this machine. In direct mode the log never leaves this machine.
Vault
Where your installation keeps people's keys in OpenBao, AIMO works with your own
vault there. It hands values to your tools, terminals and commands, and never puts
one in a chat, a log or a stored conversation.
- AIMO Vault: Sign in to the Vault opens your browser at the identity provider
and comes back to
http://localhost:8250.
- Tool-server variables: a tool server that needs something of yours — an API
key, a token — reads it from your vault on every call you make to it.
- Workspace vault variables (
aimo.vault.env) map environment variables to
places in the vault. The mapping holds references, not values, so it can be
committed and every developer gets their own value. The model is told the names;
a value a command prints as it is reaches the model as [vault:NAME].
The vault address is derived from the gateway address. Set aimo.vault.address if
yours is elsewhere.
Settings
Settings marked window are kept per window (Each window has its own
settings). Settings marked user can be set in
your own settings only. A repository's
.vscode/settings.json cannot set them, so opening a project cannot redirect your
sign-in, your key or your secrets, or switch the approvals off.
| Setting |
Default |
Notes |
aimo.gatewayUrl |
(empty) |
Your organisation's gateway. user, window |
aimo.connection |
platform |
platform, or direct for your own API key. user, window |
aimo.direct.provider |
(empty) |
openrouter, huggingface, evren, novita, cerebras or custom. user, window |
aimo.direct.baseUrl |
(empty) |
For custom: the API root, https://… or http://127.0.0.1:…/v1. user, window |
aimo.direct.model |
(empty) |
The model your key pays for that new chats start on; never picked for you. user, window |
aimo.direct.allowInsecureTls |
false |
Accept a self-signed certificate on the custom endpoint only. user, window |
aimo.model |
(empty) |
The model new chats start on (each chat keeps its own). Empty = the platform's default for you. window |
aimo.autoApproveTools |
false |
Skip approvals. Ignored in Restricted Mode. user |
aimo.defaultMode |
agent |
The mode a new chat starts in: ask, plan, agent, edits. user |
aimo.maxAgentSteps |
25 |
Tool rounds per turn (in direct mode, your own setting only) |
aimo.maxStoredChats |
100 |
Chats kept per workspace; 0 keeps every chat; a pinned chat is never deleted |
aimo.notifyInBackground |
true |
Say so when a chat you are not looking at waits for you or finishes |
aimo.projectInstructions |
ask |
ask before using a repository's AGENTS.md and the like, or off |
aimo.includeEditorContext |
true |
Send the open file's path and your selection |
aimo.protectSensitiveFiles |
true |
Ask before reading credential files. user |
aimo.mcpEnabled |
true |
Use tool servers at all |
aimo.mcp.pinnedServers |
[] |
Servers whose tools load directly |
aimo.mcp.local.enabled |
false |
Run tool servers on this machine. user |
aimo.mcp.local.servers |
{} |
Your own tool servers. user |
aimo.mcp.local.recipeOptions |
{} |
Options of the recipes your organisation registers. user |
aimo.mcp.local.env |
{} |
Vault references for those recipes, by registry name. user |
aimo.trafficLog.enabled |
false |
Keep an encrypted log of the traffic of the tool servers on this machine (asks first, on each machine). user |
aimo.trafficLog.retentionDays |
30 |
How long your segments are kept (maxSegments, maxTotalMB cap how many). user |
aimo.vault.address |
(empty) |
Empty = derived from the gateway address. user, window |
aimo.vault.env |
{} |
The workspace's vault variables |
aimo.allowInsecureTls |
false |
Accept a self-signed gateway or vault certificate. user |
Troubleshooting
| What you see |
What to do |
| No AIMO icon after installing |
VS Code installs extensions per profile, and in a remote window (SSH, WSL, a container) the extension runs on the remote side. Install it again from that window with Install from VSIX…, or pass --profile "Your Profile" to code --install-extension |
could not reach …/api/identity/config |
The gateway address is not set, is wrong, or cannot be reached from here. Run AIMO: Set Gateway URL and check you are on the right network |
invalid token: … failed to find key with key ID … |
The sign-in this window holds was made with another gateway's identity provider, typically after the gateway address changed. From 1.4.7 aimo asks the new gateway at once; with an earlier version, reload the window, then sign in |
port 8250 is busy when signing in to the vault |
Another vault sign-in is waiting on that port. Finish or cancel it |
| The vault sign-in page opens but nothing happens afterwards |
You are in a remote window (SSH, container): forward port 8250 to your machine, or sign in from a local window |
| A tool server is missing |
You have not been granted it, or your team may not use it. Ask your administrator |
npx could not fetch … or npx did not finish fetching … |
The first start of Chrome DevTools or Playwright downloads its package with npx, and that failed. The message quotes npm's own error: check your network and the registry npm uses (npm config get registry), then try again |
… rejected your API key (direct mode) |
The key was revoked, mistyped or cut short when it was pasted. AIMO: Set the Provider API Key… checks a new one with the provider before keeping it |
Evren requires you to accept its terms of use |
AIMO never accepts them for you: Read the terms, then I accept version N |
not run: the platform could not record this call |
A tool server on this machine runs only once the platform has recorded the call. Check your network path to the gateway |
not run: this platform does not support local tools yet |
Your organisation's installation does not offer tool servers on this machine yet. Ask your administrator |
| Anything else |
AIMO: Show Log |
| |