DEV Community: Amariah Kamau

Add a Coding Agent to Zed and JetBrains IDEs With the Agent Client Protocol

Amariah Kamau — Sat, 10 Oct 2026 14:21:41 +0000

Zed and JetBrains IDEs both speak the Agent Client Protocol (ACP): an open protocol between an editor and a coding agent, so the editor provides the chat, the diffs and the approvals, and any agent that implements the protocol can sit behind them. No plugin is involved. Atlarix implements it with one command, atlarix acp. Here is how to add it to each editor.

Install the Atlarix CLI

ACP editors start the agent as a program, so first install the CLI: npm i -g atlarix, brew install amariahak/atlarix/atlarix, or the one-line installers on the CLI page. Check it with atlarix --version.

Zed

Open Zed's settings (~/.config/zed/settings.json) and add Atlarix as an agent server: "agent_servers": { "Atlarix": { "type": "custom", "command": "atlarix", "args": ["acp"] } }. Then open the Agent Panel, start a new thread and choose Atlarix. Sign in when it asks; it opens your browser once.

JetBrains IDEs

In IntelliJ IDEA, PyCharm, WebStorm, GoLand or any other JetBrains IDE with AI Assistant, open the chat's agent menu and choose More Agents → Add Custom Agent. That opens ~/.jetbrains/acp.json; add "agent_servers": { "Atlarix": { "command": "/path/to/atlarix", "args": ["acp"] } } with the full path from which atlarix (macOS, Linux) or where atlarix (Windows). You do not need a JetBrains AI subscription to use an ACP agent.

What you get in the editor

Atlarix's modes — Build, Explore, Plan, Debug, Review — and its models appear in the editor's own mode and model pickers. Edits and commands come to you as the editor's permission prompts before anything changes. In Plan mode the plan shows as the editor's plan list, and building it switches the mode picker to Build. File references in replies open at the line. Past chats load from the editor's history.

Signing in

Atlarix offers two sign-in methods to an ACP editor: a browser sign-in the editor can start for you, and atlarix login in a terminal. Either signs in the CLI on that computer, and the editor's chats then use your account, your models and your own keys.

The same agent everywhere

A chat started in Zed or a JetBrains IDE is an Atlarix session like any other, so it shows up in the Atlarix app and CLI, and other Atlarix sessions can message it. The editor is just one more place to type.

We have also submitted Atlarix to the ACP registry, which Zed and JetBrains read to offer agents with one click; until that is merged, the settings above are the way in. For VS Code, Cursor, Kiro and Windsurf, which do not speak ACP, Atlarix has its own extension — see the editors guide.

Originally published at atlarix.dev.

How to Use Your Own API Key With an AI Coding Agent in VS Code

Amariah Kamau — Sat, 10 Oct 2026 14:20:51 +0000

A coding agent on your own API key means three things: you choose the model, you pay the provider's price with no markup, and your requests go to the provider you picked. This is how to set that up in VS Code — or Cursor, Kiro or Windsurf — with the Atlarix extension, start to finish.

1. Install the extension

In your editor's Extensions view, search for Atlarix and install it — it comes from the Visual Studio Marketplace in VS Code and from Open VSX in Cursor, Kiro and Windsurf. It brings its own copy of the agent, so there is no CLI or runtime to install separately.

2. Sign in once

Open the Atlarix view (the ant in the activity bar, or ⌘⌥A / Ctrl+Alt+A) and sign in. An Atlarix account is free; it is what keeps your chats, settings and keys the same across the editor, the desktop app and the CLI.

3. Connect your provider

Open the ⋯ menu at the top of the chat and choose Account, usage and billing. Under Your own keys, press Connect a provider…, pick the provider — OpenAI, Anthropic, Google, DeepSeek, OpenRouter, or another from the list — and paste the key. The prompt links to the page where that provider issues keys. The key is stored by Atlarix on your computer, and the Atlarix app and CLI on the same computer use it too.

4. Pick the model

The model picker sits just under the message box. Your key's models now appear in it alongside Atlarix Auto and the Atlarix Core models; choose one and it applies to this chat. Different chats can use different models — a fast cheap one for questions, a stronger one for a refactor.

5. Work as normal

Every mode works on your own key: Build, Explore, Plan, Debug and Review. Edits open in the editor's diff for your Yes or No, commands wait for approval, and plans tick off as they are built. The account panel shows what this chat has cost on your key so far.

What it costs, and where requests go

Atlarix adds nothing to your own key's usage: you pay the provider exactly what they charge. Requests on your key go from your computer to the provider, not through Atlarix. If the provider rejects the key — revoked, mistyped or out of credit — the chat says so, so you know to fix the key rather than retry.

Which model to start with

There is no single answer, and the honest advice is to try two. Frontier models from OpenAI, Anthropic and Google are the strongest at long multi-step changes; DeepSeek and GLM are far cheaper per token and very capable for most everyday work; OpenRouter gives you one key for many providers. Because the picker is per chat, comparing them on your own code costs one extra chat.

The same key works in Zed and JetBrains IDEs, which run Atlarix over the Agent Client Protocol — see the editors guide. And if you would rather not manage keys at all, Atlarix Auto in the same picker chooses a model for each step for you.

Originally published at atlarix.dev.

Atlarix in VS Code, Cursor, Kiro and Windsurf: An AI Coding Agent That Uses Any Model

Amariah Kamau — Sat, 10 Oct 2026 14:19:52 +0000

Until this release, using Atlarix meant a window beside your editor: the desktop app, or since 15.0 the CLI in a terminal. With 15.4.0 the agent moves into the editor itself. One extension for VS Code and the editors built on it — Cursor, Kiro, Windsurf, VSCodium — carries the same agent as the app and the CLI, and Zed and JetBrains IDEs run it through the Agent Client Protocol. This post is what you get and how to start.

Install it

Search for Atlarix in your editor's Extensions view, or install it from the Visual Studio Marketplace (VS Code) or Open VSX (Cursor, Kiro, Windsurf, VSCodium). There are builds for macOS, Windows and Linux on Intel and ARM, and the extension carries its own copy of the Atlarix CLI, so there is nothing else to install. Open the Atlarix view (the ant in the activity bar, or ⌘⌥A / Ctrl+Alt+A) and sign in the first time.

Every mode, any model

The message box has the mode: Build changes code and runs commands, Explore reads and answers without changing anything, Plan writes a plan you can read before anything happens, Debug chases a failure to its cause, Review reads a change and reports what is wrong with it. Just under it is the model: Atlarix Auto, which picks a model for each step, the Atlarix Core models, or any model from your own API key — OpenAI, Anthropic, Google, DeepSeek, OpenRouter and the rest. The picker is the same list the app and CLI show.

Edits you approve in the editor's own diff

When the agent wants to change a file, the editor opens its own side-by-side diff with the proposed version before anything is written. Yes applies it, No leaves the file alone, and Always stops asking for that kind of change in this workspace. Commands wait for you the same way. You are reading the change in the tool you already trust for reading changes.

Plans you can watch being built

In Plan mode the plan appears in its own panel with a checklist of steps. Build it switches to Build and carries it out, and the panel stays on screen while it works: each step goes from ☐ to ◐ to ☑, the header counts them off, and it says Built at the end. You can see where the work is without reading the transcript.

Context without copy-paste

Select code and press ⌘⌥L (Ctrl+Alt+L) to add it to the chat with its file and lines; type @ to attach a file; the + button attaches images. The model's thinking streams into a fold above its answer, so you can watch it reason and close it when the answer starts.

Your Chrome, your other sessions

With the Atlarix Chrome extension installed, the agent in your editor can open pages in your own Chrome — signed in as you — to test what it just built. Every Atlarix session can message every other one: the app, the CLI, Chrome or another editor can hand your editor a task, and it arrives as a card and is answered there. /editor in the CLI moves a terminal chat into your editor; the ⋯ menu in the editor moves it back to the app or a terminal.

Your account in the panel

⋯ → Account, usage and billing shows your plan, credit and this chat's usage, with Get Pro, Add credit and Sign out; your own provider keys; and the MCP servers in this folder, which you can test, switch off or add. Come back after a few minutes away and one line recaps where the chat stands; turn that off in the same menu.

Zed and JetBrains IDEs

Zed and JetBrains IDEs speak the Agent Client Protocol natively, so they run Atlarix's CLI as their agent with no plugin: atlarix acp. Building a plan switches the editor's mode picker, the plan shows as the editor's own plan list, and file links open at the line. The editors guide has the settings for both.

What it costs

Installing the extension is free. Your own API keys cost nothing through Atlarix — you pay your provider directly. Atlarix Core models are paid from Pro or pay-as-you-go credit, the same balance as the app and CLI.

Chats you start in the editor show up in the app and the CLI, and the other way round: it is one agent with one history, wherever you happen to be typing. Install it from the Marketplace or Open VSX, and see the editors guide for everything else.

Originally published at atlarix.dev.

Atlarix CLI 15.0.1: Sub-Agents in the Terminal, Coloured Code and a Plan You Can Read

Amariah Kamau — Mon, 05 Oct 2026 16:06:10 +0000

Originally published at atlarix.dev.

The Atlarix CLI shipped in 15.0.0 as the same agent as the desktop app, in a terminal. We then used it for real work: an actual pull request to a well-known open-source project, start to finish, from the terminal. That surfaced the bugs and rough edges a demo never does. Atlarix 15.0.1 is what came out of it, and this post walks through what changed and why.

Sub-agents work, and they sit under the prompt box

Sub-agents are how an agent explores in parallel: one reads the tests while another traces a function. In 15.0.0 every sub-agent the CLI started failed before it ran and then showed as running forever. Two separate bugs were behind it, and a third turned up while fixing them: outside Atlarix's own repository the CLI could not find the prompts it ships with, so every turn quietly ran without its mode's instructions and every sub-agent failed to start. All three are fixed, with tests that run the CLI from a folder that is not ours.

While Atlarix works, the space under the prompt box now lists what is running: the main agent and what it is doing, then one row per sub-agent with its current step, how long it has run and its tokens. Finished ones drop off, and background commands share one row. Press ↓ and enter on a sub-agent to watch it live, its tool calls and what it is writing; ← and → step between sub-agents and esc backs out.

Code is coloured, for the languages you actually read

Answers and edit diffs are now syntax highlighted, and inline code stands out in lavender rather than a dim grey chip. The interesting part is how languages are handled. Atlarix does not ship a list of grammars. The first time a language shows up, its grammar is found by name: one already on your machine from another terminal app built on the same toolkit is reused, otherwise the language's own grammar project is fetched once. Only the languages you read ever land on disk, and offline the code simply stays plain.

A plan you can read while you decide

Plan mode used to end with a popup that asked you to approve a plan you could not see. Now the plan stays pinned above the prompt box while it waits to be built. You read it, type what to change underneath, and watch it redraw as Atlarix revises it. Build it, or /build, starts the work; esc hides the plan and /plan brings it back.

Sending is instant

The first message of a session used to freeze the terminal for about a second before it appeared. The cause was token counting, which rebuilt its tokenizer every time it counted, dozens of times on a first turn. It is built once now. The desktop app got faster from the same fix.

The small things that add up

The context meter shows how full the context is as a share and as tokens of the model's window, instead of a running total that could pass the window and look like a contradiction.
A message you send while Atlarix works is drawn where the agent read it, not under the whole reply.
/compact typed mid-answer waits for the answer to finish, and messages typed after it still go first.
Pasting the same text again expands the pasted-text chip so you can edit it.
The approval dialog's diff is coloured like the transcript's.
The terminal tab pulses while Atlarix works, so a busy session is visible from another tab.
Long session names are shortened, the prompt box sits a step above the page, and checklists read on one line.

How to get it

If you already have the CLI it updates itself. Otherwise: npm install -g atlarix, brew install amariahak/atlarix/atlarix, or the one-line installer on atlarix.dev/cli. The CLI shares the desktop app's sessions, models, keys and MCP servers, and runs on your own API keys, local models or Atlarix Core.

Most of 15.0.1 came from using the CLI on a real task and fixing what got in the way. It also gave us the next one: Atlarix in Slack, which works on your repositories from a message and is coming soon. The full list of changes is in the Atlarix changelog.

Atlarix Auto: A Free AI Coding Agent That Picks the Model for Each Step

Amariah Kamau — Wed, 23 Sep 2026 20:57:54 +0000

Most AI coding tools ask you to make two decisions before you write a line: which model, and whose API key. Atlarix Auto removes both. It is one option in the model picker — the one new installs start on — and instead of running your whole session on a single model, it chooses a model for each step of the work. On an account with no credit, Auto in the Atlarix desktop app is free. On Atlarix Pro or credit, it is paid and private.

What Atlarix Auto is

Atlarix is a desktop coding agent: it plans, edits your code, runs commands in a per-OS sandbox, and runs your tests before it calls anything done, with every change waiting for your approval. Auto is the model setting that decides which language model does each piece of that work. You pick Auto and give it a task.

How Auto picks a model, step by step

A coding session is not one kind of work. Reading a codebase, writing a change, planning a refactor and reviewing a diff need very different amounts of reasoning. Auto routes on what each request is:

What the step is	What Auto uses
Exploring and building	A fast, affordable model that is strong at code
Planning and code review	A stronger reasoning model
Deep thinking switched on	Every step moves up one level
A step with a screenshot, image or PDF	A model that can actually read it
Sub-agents, session titles, summaries	The cheapest capable model
A model is rate-limited	The same level from another provider

Routing happens per request, not per session: a long task that suddenly needs to look at a screenshot gets a vision-capable model for that one step, then returns to the cheaper one. If a step fails, Atlarix retries it; a "Try with a stronger model" button reruns a hard turn one level up.

Free Auto, and the trade that makes it free

On an account with no credit, Auto in the desktop app costs nothing. It runs on OpenAI models through OpenAI's data-sharing program: OpenAI provides free daily capacity for traffic it may use to improve its models. That is the whole reason it is free. Before your first free message, Atlarix shows a one-time notice explaining this, and you choose whether to go ahead. Free Auto is available in the desktop app (and to Atlarix Reviewer for public repositories only); the Chrome extension runs on paid Auto.

How the free daily allowance works

Each account gets a fair daily share, sized from what is left and how many people are using it, with a floor so everyone gets real work done and a ceiling so no single account drains it. When your share runs out, Auto falls back to a free model rather than cutting you off; only past that does it pause until the daily reset — shown on your own clock.

What stays private

With Atlarix Pro or credit, Auto is paid and private: nothing it handles is shared or used to train models. Your own API keys work as before. Local models through Ollama or LM Studio never leave your machine. Atlarix itself never trains on your code, in any mode.

What it costs when you pay

The app is free — every feature, no gating. Paid inference is Atlarix Pro ($19/month, including Core usage across the desktop app, the Chrome extension and Atlarix Reviewer) or pay-as-you-go credit, with the cost of every reply shown.

Try it

Download Atlarix from atlarix.dev. New installs start on Auto; if you picked a model before, switch to Auto in the model picker, then give it a real task on your own code.

Originally published at atlarix.dev.

The harness, not the model: how to make a weak or local model reliable enough to ship

Amariah Kamau — Fri, 11 Sep 2026 19:41:05 +0000

If you've tried to point a local model — Qwen, a quantized Llama, whatever fits on your GPU — at a real task in a real repo, you already know the feeling. It starts confidently. It edits three files. It announces it's done. And then you run the tests and half of them are red, one of the files it "edited" is byte-for-byte unchanged, and the function it swore it added isn't there.

The usual conclusion is: the model is too weak. Get a bigger model, or rent a frontier API, and the problem goes away.

That conclusion is mostly wrong, and it's expensive. A large share of what looks like model weakness is actually the absence of a system around the model — the scaffolding that a frontier model partially compensates for on its own and a weak model does not. If you build that system, a much weaker model becomes usable for work you'd have assumed it couldn't touch. The industry has a name for that system: the harness.

I've spent the last several months building one — a coding harness called Atlarix that's designed to run any model, including small local ones, and get real work out of them. Along the way it's produced code that got merged into projects like Remix, Caddy, Traefik, and Valkey (more on that, honestly, at the end). This post isn't a pitch for it. It's the set of principles I learned building it, written so you can apply them to your own agent, whatever it's built on. Atlarix is just the reference implementation I'll point at to prove I actually did each thing rather than just theorizing.

Here's the core claim, stated plainly:

A weak model doesn't need a bigger prompt. It needs a system that catches its mistakes instead of trusting them.

Four mechanisms do most of the work. None of them require a better model.

1. Verify edits against reality, not against the model's word

The single most common failure mode of a weak model in a coding loop is the confident false completion: it reports success for work it didn't actually do. The edit didn't apply. The file didn't change. The function it described isn't on disk.

A frontier model does this too — it just does it less often, so you get away with trusting it. With a weak model you cannot trust the report at all. So don't. The fix is a principle I'd now build into any agent from day one:

Never let the model be the judge of whether its own change succeeded. Check the world.

Concretely, after every edit, the harness re-reads the file from disk and confirms the change is actually present. If the edit didn't land, that fact goes back to the model as a tool result — "the file is unchanged" — instead of forward to the user as "done." The model gets a chance to notice and retry, in the same turn, before anything reaches you.

The same principle extends to commands. When the agent runs the project's own checks — tsc, eslint, ruff, mypy, pytest, whatever the repo uses — a non-zero exit code is not something the agent gets to narrate its way past. In Atlarix the turn is held open: a command that exits non-zero, or an edit that didn't verify on disk, is routed back to the agent rather than surfaced as a finished result. The agent literally cannot declare a task done while the project's own tests are failing.

That one rule — the agent can't mark work complete while the repo's checks are red — eliminates the most damaging class of weak-model errors, because the most damaging errors aren't wrong code. They're wrong code reported as correct. Wrong-but-flagged is recoverable. Wrong-but-confident is what ships bugs.

You can implement this in any loop. Run the checks. Read the exit code. If it's non-zero, feed the failure back as the next observation instead of returning to the caller. It's not clever. It's just refusing to take the model's word for anything you can verify yourself.

2. Enforce control in the harness, not in the prompt

There's a strong temptation to solve agent misbehavior with more instructions. "Always wait for the command to finish before continuing. Never claim completion prematurely. Always ask before running destructive commands." You write a longer and longer system prompt, and a frontier model mostly follows it, and a weak model mostly doesn't — because following a paragraph of procedural instructions is itself a capability that weak models lack.

So stop asking the model to behave and make the behavior structural.

If a rule matters, the harness should enforce it mechanically, so a model that "forgets" the rule physically can't break it.

Tool approvals, background command handling, wait-states, sub-agent orchestration — in a prompt-driven agent these are all things you ask the model to handle correctly. In a harness-driven agent they're enforced by the system around the model. A weak model can't emit a premature "task complete" if completion is gated on verification it doesn't control (see #1). It can't skip an approval if the approval is a queue the execution path must pass through, not a politeness the model chooses to observe.

The practical test: for every "always/never" line in your system prompt, ask "what happens if the model ignores this?" If the answer is "something bad happens," that rule doesn't belong in the prompt — it belongs in the harness, as a gate the model routes through whether it wants to or not. The prompt is for guidance. The harness is for guarantees. Weak models need guarantees.

3. Give it a sandbox, so a mistake is contained instead of catastrophic

A weak model will try to run something it shouldn't — a command scoped too broadly, a write outside the project, a destructive operation it didn't reason through. If your safety story is "the model is careful," you don't have a safety story.

Contain execution at the OS level, so the blast radius of a bad call is bounded by the system, not by the model's judgment.

Atlarix confines command execution per-OS — Landlock on Linux, AppContainer on Windows, Seatbelt on macOS — so the agent physically cannot write outside the project you opened. There's an approval queue with hunk-level accept/reject on every diff, and a danger gate on destructive operations. The point isn't the specific primitives; it's the principle: the model's mistakes are caught by the system, not trusted on faith. When containment is structural, you can let a weaker, less-trustworthy model act, because the cost of it being wrong is bounded.

This is also what makes local-first viable at all. If the model runs on your machine and the execution is sandboxed to your project, "the AI touched my system" stops being a leap of faith. The containment is what earns the autonomy.

4. Feed it structure on demand, not the whole repo

Weak models have smaller effective context and degrade faster as you fill it. The instinct is to stuff the repo into the prompt so the model "has everything." This is exactly backwards — you drown the small model in tokens and it performs worse.

Retrieve narrowly and on demand. Let the model pull what it needs when it needs it, instead of pre-loading everything it might need.

Atlarix searches the repo on demand — bundled ripgrep for grep/glob, no index to build, no background watcher — and keeps durable notes on what it learns about the codebase so it doesn't re-derive the same structure every turn. The model asks for what it needs; it isn't forced to hold the whole tree in its head.

The general principle for any agent: on-demand, tool-driven retrieval beats context-stuffing, and it beats it more the weaker your model is. A frontier model can afford to waste context. A local model can't. Give it a way to look things up, and a way to remember what it found, and you've freed its limited context for actual reasoning.

Why this matters beyond saving on API bills

The obvious payoff is cost — run a local model, pay nothing per token, keep your code on your own machine. That's real. But the deeper payoff is trust. Every one of these mechanisms replaces a place where you were trusting the model with a place where the system checks. Verified edits replace trusting the completion report. Harness-enforced control replaces trusting the model to follow rules. The sandbox replaces trusting it not to do damage. On-demand retrieval replaces trusting it to juggle the whole repo.

Stack them and something surprising happens: the model's reliability stops being the ceiling. The system's guarantees become the floor, and a weaker model operating above a solid floor beats a stronger model operating on trust. That's the whole thesis. The harness, not the model.

The honest part

I said I'd be straight about the merges, so here it is.

Atlarix, running on open-weight and local models, has produced code that maintainers merged into real projects — Remix (merged by its co-creator), Caddy, Traefik, Valkey, and others. Every one is a public, verifiable pull request; the links are on atlarix.dev if you want to check them, and you should.

But I want to be precise about what that does and doesn't mean, because a technical audience deserves it and will figure it out anyway. These were human-directed. I drove the agent — chose the target, steered the work, reviewed the diff before it went out — and the agent appears as a co-author on the commits, not the sole author. A maintainer of Remix or Caddy reviewed the change and merged it after dealing with me as the human behind it. What the harness did was get an open-weight model's output to the point where it could clear that bar: correct, verified against the project's own checks, and clean enough to survive a real maintainer's review.

That's the claim, and it's a narrower and more honest one than "AI merged code into Remix." It's: a well-built harness plus a modest model, driven by a human who knows what they want, can produce work that passes the same gate a human contributor's work passes. That's not magic. It's the four mechanisms above, doing their job.

If you're building your own agent, take the principles and leave the tool. If you want to see the reference implementation, it's Atlarix — a private AI workstation that runs any model, local or hosted, with your code staying on your machine. Either way: stop blaming the model. Build the harness.

I'm Amariah Abishai, a self-taught engineer in Nairobi building AI developer tooling at NorahLabs. If you want the deeper version of the retrieval design, there's a published paper on an earlier structural-retrieval approach I tried, measured, and eventually moved away from — which is its own lesson for another post.

I shipped two PRs into Alibaba's qwen-code using only open-weight models. Here's the honest version.

Amariah Kamau — Fri, 03 Jul 2026 16:28:04 +0000

I build Atlarix — a desktop coding harness that runs whatever model you point it at: managed, your own API key, or fully local via Ollama or LM Studio. The whole thesis is that the gap between a weak open-weight model and a frontier one closes when the harness does the heavy lifting. This post is a test of exactly that.

So I decided to test that thesis in the least forgiving place I could think of: contributing real code to a frontier lab's own production repo, using nothing but open-weight models to write it.

Two pull requests are now merged into QwenLM/qwen-code — Alibaba's open-source coding agent. Here's the honest version, including the part that didn't go well and the constraint that shaped how I worked.

The first attempt got closed — correctly

My first swing was ambitious: a full always-on scheduled-task daemon. Tasks that fire on a cron schedule without an interactive session open, system service installation, webhook triggers, the works. Around 5,000 lines across four rollout phases.

A maintainer closed it. And they were right to.

The problem wasn't that the code didn't work — it was that I'd built a second, parallel daemon with its own storage format and lifecycle, when the repo already had a long-running daemon (qwen serve) and a durable scheduler I should have extended instead. On top of that, four phases in one PR is simply too much to review well.

The maintainer's feedback was blunt and generous at the same time: reuse the existing infrastructure, make the change incremental, split it into reviewable pieces. What could have been ~300 lines of extension, I'd written as thousands of lines of duplication.

That stung. But it was the most useful thing that happened in the whole process, because it taught me the lesson every open-source contributor eventually learns: read the existing architecture before you build, and keep your PRs small enough to review.

So I did the right-sized thing instead

Instead of fighting to rebuild the giant feature immediately, I went looking for a small, well-scoped problem — the kind of change that's easy to review, easy to revert, and unlikely to break anything.

I found one in the web-shell's model picker.

PR #6209 — vision model support in the web-shell UI. The CLI could select a vision model; the web-shell daemon UI couldn't. I added it, following the exact pattern the codebase already used for other model modes. Small, mechanical, convention-matching. It merged.

PR #6236 — a real data-loss fix. This one mattered more than its size suggests. When a user selected a vision model from the web-shell picker, they'd see a success toast — but their choice was silently discarded. The picker stored the model ID in one format (modelId(authType), ACP-style) while the core resolver expected another (authType:modelId). The mismatch meant the stored value never resolved, and the system quietly fell back to auto-select. The settings page still showed the value, which masked the failure completely. The user's explicit choice had no effect, and nothing told them.

The fix re-encodes the format before persisting, plus type-safe dispatch to replace some fragile ternary chains, plus the missing English and Chinese i18n keys. It merged too.

The honest part: the models didn't write perfect code

This is the bit I actually care about, because it's where the hype usually lies.

Both PRs went through several rounds of genuine maintainer review. And the maintainers — Alibaba collaborators, plus an automated reviewer running on Qwen's own models — found real bugs. Not style nitpicks. Actual security and lifecycle issues: an HMAC check computed over the wrong input, a timing-attack-vulnerable token comparison, a timer that could fire on a stopped process, an auth config silently stripped from a webhook path.

I fixed and re-verified each one before merge. On #6236, a maintainer even built the PR locally with real browser tests and screenshots to confirm the fix worked end-to-end before approving.

That review loop is the entire point. The claim isn't "open-weight models wrote flawless code." They didn't. The claim is that open-weight models, driven by a good harness, could take architectural feedback and iterate to something a senior maintainer at a frontier lab was willing to merge. That's a much more interesting and much more honest result than "the AI one-shotted it."

The constraint nobody tells you about: cost

Here's a detail I think is worth being transparent about, because it's the reality of building solo.

PR #6209 was built almost entirely on Qwen (3.6 Plus, 3.7 Plus/Max) via OpenRouter. But partway through PR #6236, I started running low on OpenRouter credits. As a solo founder trying to conserve runway for actual users, I switched to using DeepSeek API credits instead. So #6236 ended up roughly a 50/50 mix of Qwen and DeepSeek.

I could have hidden that and claimed "100% Qwen" across the board. But two things: first, it wouldn't be true, and the whole value of a post like this is that it's honest. Second — it actually makes the result broader, not weaker. The thesis was never "Qwen specifically." It was "open-weight models, in a harness built for them, can do real work." Making that work across two different open-weight labs is stronger evidence than making it work with one.

No frontier model wrote either PR. Just open-weight models — Qwen and DeepSeek — running in Atlarix.

Why this matters (to me, at least)

I'm a self-taught developer building in Nairobi. The models I can afford to run at scale are open-weight ones. Atlarix exists because I needed a way to make those models genuinely productive — not "good enough for a demo," but good enough to ship code into a repo maintained by the people who train the models.

Two merged PRs in a Tier-1 lab's production repo, written by open-weight models in the harness, reviewed and merged by the lab's own maintainers, is the clearest proof of that thesis I've been able to produce.

The gap between open-weight and frontier is real. But a lot of it lives in the harness, not the weights. Close that gap, and a model you can run yourself can punch well above its weight.

Atlarix is at atlarix.dev. If you're building with open-weight models or thinking about model-agnostic tooling, I'd genuinely like to compare notes.

Atlarix vs opencode on Terminal-Bench 2.0 — same model, only the harness changes (k=1, receipts included)

Amariah Kamau — Mon, 29 Jun 2026 19:22:30 +0000

Update — treat this as a historical data point, not a current claim. Two things have superseded it. Terminal-Bench has moved to 4.0, which recalibrated task resources, dropped saturated tasks and standardised an 8-hour agent timeout — 2.x scores are not comparable to it. And the headless runner that produced these numbers dispatched reasoning one notch below each model's declared ceiling, while published leaderboard entries run the ceiling. Both are fixed; the run has not been repeated.

The caveat in the post below still stands and matters more than the result: a 3-task gap at k=1 is within noise, and this does not show Atlarix is ahead of opencode. There is also no Atlarix SWE-bench number — if you have seen one attributed to Atlarix, it is invented. Current results and methodology: atlarix.dev/benchmark.

Benchmarks

I build Atlarix, an agent workstation for open-weight models. The core claim behind it is that the harness — retrieval, tool surface, control loop — is what lets an open-weight model perform, not just the model's raw weights. This post is me trying to falsify that claim with a controlled run, and publishing every output file so you can check it.

Short version: on Terminal-Bench 2.0, single attempt, Atlarix resolved 42/89 and opencode resolved 39/89 on the same model. That 3-task gap is within k=1 noise — I'm not claiming a win. What it shows is that the harness isn't bottlenecking the model. Details and caveats below; raw files at the end.

The experiment

The only variable is the harness. Everything else is pinned identical across both agents.

Benchmark: terminal-bench/terminal-bench-2 — all 89 tasks, one isolated container each, automated verifiers.
Model: minimax/minimax-m3, routed through OpenRouter, pinned to a single provider at fp8 — identical for both harnesses.
Infrastructure: Harbor on Modal (-e modal), one container per task.
Attempts: single attempt, -k 1.
Timeout: native, --timeout-multiplier 1 (same for both).
Retries: --max-retries 3 (same for both).
Tool calling: native function-calling forced, no text-tool shim.

Commands

# Atlarix harness
harbor run -d terminal-bench/terminal-bench-2 \
  -m openai/minimax/minimax-m3 \
  -n 24 -k 1 -y --timeout-multiplier 1 --max-retries 3 \
  -e modal --agent-import-path atlarix_tb:AtlarixAgent

# opencode harness (same model + provider + infra)
harbor run -d terminal-bench/terminal-bench-2 \
  -m bench/minimax/minimax-m3 \
  -n 24 -k 1 -y --timeout-multiplier 1 --max-retries 3 \
  -e modal --agent-import-path atlarix_tb.opencode_proxy:BenchOpenCodeAgent

(-n 24 is concurrency — how many containers run in parallel — not a task count. All 89 tasks run.)

Results

Harness	Resolved	Score
Atlarix	42 / 89	47%
opencode	39 / 89	44%

Read this before you read the table

k=1 means one sample per task. The official Terminal-Bench leaderboard requires k=5 specifically to measure run-to-run variance. A 3-task difference at k=1 is inside that noise band. So this is not a leaderboard result and not a claim that Atlarix beats opencode. The honest takeaway: an open-weight model performs about as well under Atlarix as under a strong existing harness — the harness isn't holding it back.

~25% of tasks timed out — for both harnesses. At native timeout (×1), roughly a quarter of tasks hit AgentTimeoutError on each side and count as unresolved. So the sub-50% absolute scores aren't all capability failures; a meaningful share are wall-clock on heavy tasks. The timeout ceiling is identical for both agents, so the comparison stays fair — but that's why neither number is higher.

The one config change (full disclosure)

Atlarix's desktop app asks for human approval before every file write and command — a core safety feature. Benchmarks run unattended, so I grant that approval once via an explicit operator flag (ATLARIX_AUTONOMOUS_DANGER=1). Without it, any task needing an install or privileged command is blocked and fails.

This is not an advantage over opencode — every agent auto-approves to run an automated benchmark; it's inherent to running unattended. Stating it for full transparency. The flag is off by default; the interactive app always asks.

Reproduce it

The exact Atlarix bundle I ran is a public, Electron-free headless build: atlarix-headless-linux-amd64.tar.gz. The benchmark is the open-source Harbor framework. The raw Harbor result files — per-task pass/fail for both harnesses — are published unedited. Nothing is hand-typed.

Everything (raw result.json for both sides, summary.csv, exact bundle, full setup): atlarix.dev/benchmark

What's next

More open-weight models, so no claim rests on one.
The official Terminal-Bench (k=5) submission — on the roadmap.
More benchmarks beyond terminal tasks.

If you spot something wrong in the result files, that's the point — tell me.

Built in Nairobi.

Show dev: I built an AI agent workstation in Nairobi for open-weight and local models

Amariah Kamau — Fri, 19 Jun 2026 09:10:36 +0000

Historical. Blueprint, ctags, ast-grep and SQLite FTS5 were all removed from Atlarix in v14.9.0 (10 July 2026) — the index leaked file descriptors and did not beat plain search. Atlarix has no index of any kind today; retrieval is bundled ripgrep, no embeddings, no graph. Current docs: atlarix.dev/docs.

What I built

Atlarix — a ~400MB AI agent workstation that sits beside your IDE (VS Code, IntelliJ, Vim) instead of replacing it. A native harness that runs whatever model you point it at — managed, your own API key across the live models.dev catalogue, or fully local via Ollama and LM Studio. (This post originally named four open-weight labs as "the point"; that framing no longer holds — the managed lineup is configured remotely and changes, and the harness is deliberately model-agnostic.)

Built solo under NorahLabs, in Nairobi, Kenya.

The problem

I was running open-weight models for actual agentic work — multi-file edits, terminal commands, codebase exploration. Every tool I tried was built around Claude or GPT, with my models bolted on as a BYOK option. Context-window assumptions tuned for a different model. System prompts and tool-calling shaped around closed-model behavior. Retrieval that either dumps the whole repo or leans on a cloud vector DB that doesn't even exist on an offline machine.

The models are frontier-class now. The tooling around them isn't.

The approach

Blueprint — structural retrieval, no embeddings (removed in v14.9.0)

- Universal Ctags symbols + ast-grep edges, backed by SQLite FTS5 *(all removed in v14.9.0 — see the note at the top)*
- grep results reranked by structural relevance
- each result annotated with its enclosing function/class
- no vector DB, constant memory at any repo size

The thesis: for code, lexical + structural retrieval plus the model's own reasoning beats a vector index — which is also why Claude Code and opencode carry no embedding index. On my own large multi-repo workspace, a "find the signup code" query dropped from ~63K to ~26K turn tokens with exact file:line citations. (That's my own workspace, not a published benchmark — a reproducible eval is what I'm building next.)

Verified edit loop

- write → re-read from disk → compare to intended
- zero tokens on the happy path
- blocks "task complete" if an edit didn't actually land

Live model catalog

- managed model IDs fetched from a hosted config at startup
- new drops from the four labs appear automatically
- swapping a model is a config change, not an app rebuild

Per-OS sandboxing

- macOS: Seatbelt
- Linux: bubblewrap
- Windows: AppContainer
- every file write + command approval-gated, per-hunk diff review

Tech stack

Electron + React + TypeScript
SQLite FTS5 for retrieval
Universal Ctags + ast-grep for structural indexing
Rust helper for the Windows sandbox
Node.js 24+

Where it's at, honestly

v13.9.0, shipped and working. I'm one developer, so I'll be straight about the early edges: no published head-to-head benchmark yet, macOS is notarized but Windows builds are currently unsigned (signing's coming), and the retrieval numbers above are from my own use, not a controlled eval. The honest pitch is "the first workstation built around open-weight models instead of just accepting them — here's exactly how," not "this beats everything."

Feedback wanted

If you're running open-weight models for agentic work — what's your current setup, and where does it break? That's the feedback that actually shapes this.

🌐 atlarix.dev

We Tried to Reduce LLM Context Usage in a Multi-Repo Codebase. The AI Used More Tokens, Not Less. Here's Why That's Correct.

Amariah Kamau — Mon, 25 May 2026 17:46:41 +0000

Update — this experiment ended the way the numbers suggested it would. Blueprint was removed from Atlarix in v14.9.0 (10 July 2026), along with the whole index: FTS5, BM25, ctags, the reranker and the file watcher, about 5,246 lines. The 54% result below was part of why. The watcher also turned out to hold one file descriptor per watched file, reaching roughly 12,365 on a large repository.

Retrieval is now purely lexical — bundled ripgrep, no index, no embeddings, nothing in the background. This post is the evidence for that decision, not a description of a shipping feature.

When we set out to build Blueprint — Atlarix's structural codebase retrieval system — the hypothesis was simple: give the AI a map of the codebase upfront, and it will need to read fewer files. Fewer files means less context. Less context means lower cost and faster responses.

We ran a controlled benchmark. The AI with Blueprint used 54% more context than the AI without it.

Here's why that's not a failure.

The problem with how most AI coding tools handle context

If you've used Cursor, Claude Code, or GitHub Copilot on a large codebase, you've hit this wall: the AI either reads too much (dumping raw files into context until you hit the limit) or reads too little (making confident wrong assumptions about files it hasn't seen).

The root cause is navigation. Without a structural map of the codebase, the AI is exploring blind — making guesses about which files matter, following import chains manually, or relying on whatever files happen to be open. In a multi-repository workspace, this gets worse fast. You might have 25 separate projects with thousands of files. The AI has no idea where it is.

The standard solutions are:

Raw file injection — dump everything relevant into context upfront. Expensive and doesn't scale past a few hundred files.
Dense vector search — embed the codebase and retrieve by semantic similarity. Loses structural relationships (call chains, import graphs, HTTP routes).
Agentic search — let the model call search/read tools and figure it out. Works, but slow and token-hungry as the model searches blindly.

We built Blueprint to try a fourth approach: give the model a symbolic structural graph before it starts exploring.

What Blueprint actually is

Blueprint is a four-layer index:

Layer 1 — Universal Ctags (symbol index)
Extracts every function, class, type, and method across 18 languages. Line-accurate positions. Cached to .atlarix/symbols.json.

Layer 2 — ast-grep (structural edges)
AST-level pattern matching for import edges, call edges, and HTTP route edges. Express app.get, Fastify fastify.post, Next.js export async function GET — all become first-class nodes in the graph.

Layer 3 — BM25 (semantic symbol ranking)
Ranks ctags symbols by concept query. "Authentication middleware" finds the right functions without requiring an exact name match.

Layer 4 — ripgrep (text fallback)
Exact string search for when you know precisely what you're looking for.

The output is a compact Markdown slice — rooms (directory-scoped clusters), beacons (individual symbols), and edges (structural relationships). Section-scoped: the agent requests one folder at a time, not the whole workspace.

The benchmark

We ran two arms of the same task on a production multi-repository workspace:

25 sections across the workspace root
3,250 tracked files total
Target section: a TypeScript CLI package, 99 files, ~9,500 lines

Task: Trace an event-driven HTTP-ingress-to-webhook-reply pipeline. Both arms had identical deliverables — narrative of the flow, key file paths, Mermaid sequence diagram.

Arm A (with Blueprint): Prescribed tool order — explore folder → get_blueprint → text search → read_file on 2-3 central files.

Arm B (without Blueprint): Same task, no get_blueprint — only explore folder → text search → read_file.

Model: Kimi K2.6 (268K context window) via OpenRouter. Same model, same provider, both arms.

The results

	With Blueprint	Without Blueprint
Blueprint slice	~6,500 tokens	0
Final billed input	63,541 tokens	41,327 tokens
Output tokens	2,671	2,534
Task completion	✅	✅

Blueprint arm used 54% more total context.

Context growth per turn:

With Blueprint: 8,661 → 13,966 → 24,771 → 25,012 → 31,717 → 54,188 → 63,541

Without Blueprint: 2,253 → 3,567 → 8,629 → 13,934 → 14,175 → 37,876 → 41,327

The Blueprint arm took six tool-call turns. The no-Blueprint arm took five.

Why this is the correct result

Here's what we found in the qualitative output comparison:

The Blueprint arm named 7 specific internal functions by exact identifier — the auth validator, mention detector, memory clamp, post-processor, card builder, and two others. It surfaced a section-specific post-processor module not explicitly requested.

The no-Blueprint arm found a client module in an eval/ subdirectory that Blueprint's section scope hadn't included. It named specific environment variables and API constants the text search found directly.

Both arms completed the task correctly. But the type of knowledge was different.

Blueprint gave the model a symbol-level map before any file was read. With that map, the model knew which files were worth reading and went deeper — more function names, more architectural detail, more thorough coverage. Without the map, the model explored more conservatively: followed fewer paths, read fewer files, stopped sooner.

The no-Blueprint arm used fewer tokens partly because it was less certain about what to look for next.

For a read-only exploration task, "explored less" isn't obviously worse. Both arms got the answer. But for write tasks — bug fixes, refactors, feature implementation — a model that stops exploring because it's navigationally lost is not saving tokens. It's missing dependencies, and those missing dependencies become production bugs.

The real finding: structural understanding and execution context are separable problems

The honest framing isn't "Blueprint reduces total context." It's that these are two different problems:

Structural understanding cost — how many tokens does it take to know where you are in the codebase?

With Blueprint: ~6,500 tokens, regardless of section complexity, in ~3 seconds.
Without Blueprint: amortised across many search/read tool calls over multiple turns.

Execution context — how many tokens accumulate as the model actually does the work?

This is determined by exploration depth — how many files the model reads, how many tool calls it makes. Blueprint increases this by making the model more confident. But it's bounded and manageable.

We address the execution context problem with a separate mechanism: post-turn tool-result summarisation. After each turn, large tool outputs in the persisted transcript are rewritten by a fast compaction model — keeping paths, symbol names, and key values, dropping JSON noise and repetition. In the benchmark runs, individual read_file results compressed from 2,500–3,500 tokens to 60–110 tokens. ~95–98% reduction per qualifying block.

Two mechanisms, two layers, two different problems.

What this means if you're building on top of LLMs

If you're building an AI coding tool, an agentic system, or anything that needs to navigate a large codebase:

Don't chase "total context reduction" as a single metric. It conflates structural overhead (knowable upfront, bounded by your retrieval design) with execution noise (determined by task complexity and model confidence).

Give the model a map before it explores. Not raw files — a structural graph. The model will use more total context because it will explore more thoroughly. That's the right trade for write tasks.

Compress history, not retrieval. Post-turn summarisation on tool outputs is more effective than trying to cram less information into the initial retrieval. The model needs the full file during the turn. Future turns don't.

The full paper

This benchmark is documented in a technical paper published on Zenodo with full methodology, exact prompts, provider-billed token counts, and an honest discussion of limitations:

Blueprint: Section-Scoped Structural Graph Retrieval and Post-Turn Compression for Agentic LLM Coding in Multi-Repository Workspaces

zenodo.org/records/20381860 · DOI: 10.5281/zenodo.20381860

Atlarix is available at atlarix.dev. The MCP server registry is open-source at github.com/AmariahAK/atlarix-mcps.

Built in Nairobi. Questions or thoughts? Drop them in the comments.

Build an AI Agent That Actually Understands Your Codebase (Without Switching Editors)

Amariah Kamau — Mon, 18 May 2026 13:04:51 +0000

Historical. Blueprint, ctags, ast-grep and SQLite FTS5 were all removed from Atlarix in v14.9.0 (10 July 2026) — the index leaked file descriptors and did not beat plain search. Atlarix has no index of any kind today; retrieval is bundled ripgrep, no embeddings, no graph. Current docs: atlarix.dev/docs.

I use Neovim. I'm not switching.

But I also want an agent that can refactor across 50 files, run tests, debug failures, and come back with a working PR — not just suggest the next line.

The problem: every AI coding tool that does serious agentic work wants to be your editor. Cursor, Windsurf, GitHub Copilot Workspace — all VS Code. If you use anything else, you're a second-class citizen.

So I built something different. An agent that has its own workspace beside my editor, not inside it. I stay in Neovim. The agent gets a live map of the codebase, a terminal, file tools, and an approval queue.

This post walks through how it works, how to set it up, and what it actually looks like in practice.

The Core Problem with Raw Code Injection

Before getting into the setup, it's worth understanding why most agents struggle with large codebases.

The standard approach is to dump files into the context window:

Here is your codebase:
[file 1 - 500 lines]
[file 2 - 800 lines]
[file 3 - 1200 lines]
...

This works at small scale. At 20+ files it starts to break down. The model spends most of its reasoning budget reconstructing architecture from raw text instead of actually solving the problem.

The better approach: give the agent a structured map of the codebase and let it query specific parts on demand. Think of it like the difference between handing someone a stack of printed pages vs giving them a searchable database with a good schema.

That's the core idea behind Atlarix's Live Code Map — your repo gets parsed into a node/edge graph that the agent navigates instead of reading raw files linearly.

Setup

1. Download and Install

Grab the installer from atlarix.dev.

macOS: .dmg, notarized, installs to Applications
Linux: .AppImage (auto-updates), .deb, or .rpm
Windows: unsigned .exe (code signing coming)

2. Install the CLI

Open Atlarix → Settings → General → Install CLI.

This drops an atlarix binary into your PATH. After that:

# Open current directory as a workspace
atlarix .

# Open a specific path
atlarix ~/projects/my-api

Same muscle memory as code .. Atlarix opens in the background, your terminal returns immediately.

3. Connect a Model

Go to Settings → AI. You have two options:

BYOK (Bring Your Own Key) — paste in an API key for any of the supported providers:

OpenAI, Anthropic, Google Gemini, Groq, Together AI,
Mistral, xAI, OpenRouter, AWS Bedrock

Local models via Ollama or LM Studio — set the base URL and pick your model. No API key needed. Works on the free Solo tier.

Ollama base URL: http://localhost:11434
Model: qwen2.5-coder:7b

For local models I've had good results with qwen2.5-coder:7b and deepseek-coder-v2:16b on an M2 MacBook. The structured context from the code map means you don't need a massive model to get useful results.

Model Bridge (managed) — Atlarix's own managed tier (Speed/Standard/Deep) if you don't want to manage keys. Speed tier is included in the free Solo plan.

Opening a Workspace

cd ~/projects/my-saas-api
atlarix .

Atlarix opens and loads your workspace. The first thing it does is a lightweight repo scan via git ls-files — fast, respects your .gitignore, and doesn't run any heavy parsing upfront.

The Live Code Map was built on-demand when the agent first called get_blueprint. (The get_blueprint tool, the Blueprint tab and the map itself were all removed in v14.9.0 — see the note at the top.)

For a 500-file TypeScript repo, the initial parse takes 3–5 seconds. After that it's cached and incremental.

Your First Agent Task

Let's say I want to add rate limiting to my auth routes. Here's what that actually looks like.

Step 1: Start in Explore Mode

Pick Explore from the mode selector. This is read-only — the agent can query the code map, read files, and search, but can't write anything. Good for orientation.

Me: Map the auth flow. Where does a login request go from the 
    route handler to the database?

The agent called get_blueprint to pull the architectural graph, then navigated from the auth route to the middleware stack to the database layer. (Today it does this with ripgrep and reasoning over ranked results — no graph involved.) It comes back with a precise answer and which files are involved — without reading every file in the codebase.

Step 2: Switch to Plan Mode

Now switch to Plan mode. The agent can now draft a plan but still can't execute writes.

Me: I want to add rate limiting to the login and registration 
    routes. Use express-rate-limit. Failed attempts should be 
    tracked by IP. After 5 failures in 10 minutes, lock out 
    for 30 minutes.

The agent knows the architecture from the previous explore session. It drafts a step-by-step plan:

Plan: Add rate limiting to auth routes

[ ] Install express-rate-limit
[ ] Create rate limiter config in src/middleware/rateLimiter.ts
[ ] Apply limiter to POST /auth/login in src/routes/auth.ts
[ ] Apply limiter to POST /auth/register in src/routes/auth.ts
[ ] Add error response handler for 429 status
[ ] Update integration tests in tests/auth.test.ts

Review the plan. If it looks right, switch to Build mode.

Step 3: Build — Approval Queue in Action

In Build mode, the agent starts executing. For every file write, you get an approval prompt:

Write: src/middleware/rateLimiter.ts

+ import rateLimit from 'express-rate-limit';
+
+ export const loginRateLimiter = rateLimit({
+   windowMs: 10 * 60 * 1000, // 10 minutes
+   max: 5,
+   message: { error: 'Too many login attempts. Try again later.' },
+   standardHeaders: true,
+   legacyHeaders: false,
+ });
+
+ export const registerRateLimiter = rateLimit({
+   windowMs: 60 * 60 * 1000, // 1 hour
+   max: 3,
+   message: { error: 'Too many registration attempts.' },
+   standardHeaders: true,
+   legacyHeaders: false,
+ });

[Approve] [Reject]

You approve. The file gets written. The agent continues through the plan.

For terminal commands:

Terminal: npm install express-rate-limit

[Approve] [Reject]

You approve. It runs, shows you the output, continues.

This isn't friction — it's the same review cycle as a PR, but live. You're watching the work happen and approving as it goes rather than reviewing after the fact.

Step 4: Review in Your Editor

The agent writes the files. You review them in Neovim, VS Code, IntelliJ, or wherever. The agent doesn't care what you're using to review — it just cares about the approval queue.

# Meanwhile in my terminal
nvim src/middleware/rateLimiter.ts
# Looks good, approve the rest in Atlarix

Step 5: Tests

If the agent runs tests as part of the plan and they fail, it reads the failure output and iterates. Self-correction is built in — up to a configurable number of retry attempts before it stops and asks you what to do.

Test run: npm test
FAIL tests/auth.test.ts
  ● Auth › POST /login › should return 429 after 5 attempts
    Expected: 429
    Received: 200

Diagnosing failure...

It reads the test, traces the failure to a missing @types/express-rate-limit dev dependency, installs it, re-runs. Pass.

Modes Reference

Mode	What the agent can do
Explore	Read files, query code map, search, web search. No writes.
Plan	Everything in Explore + draft plans, create `.atlarix/ATLARIX_PLAN.md`
Build	Full tool access — file writes, terminal, tests, MCP calls
Fix	Focused on diagnosing and fixing specific errors
Review	Read-only analysis, code quality feedback, architectural suggestions

You can switch modes mid-session. The agent's context persists across the switch.

What Works Well With Local Models

If you're running Ollama, here's what I've found works well and what doesn't:

Works great:

Explore mode — querying the code map, finding files, understanding architecture. Even a 7B model does this well when it has the graph.
Simple, scoped Build tasks — "add a field to this schema and update the related API endpoint"
Fix mode — diagnosing TypeScript errors with LSP output injected into context

Works better with larger models:

Multi-step autonomous plans across many files
Complex refactors with non-obvious dependency chains
Tasks that require reasoning about edge cases and side effects

The practical threshold I've found: for anything touching more than 10 files or involving significant architectural decisions, I switch from my local 7B to a Standard tier cloud model. For everything else, local is fast and free.

Tips

Use .atlarix/ATLARIX.md for persistent context. This file gets injected into every session for this workspace. Put your tech stack, conventions, and any context the agent should always know.

# Project Context

Stack: Node.js, Express, TypeScript, PostgreSQL, Prisma
Auth: JWT with refresh tokens, stored in httpOnly cookies
Testing: Jest + Supertest
Conventions: 
- All database queries go through service layer, never directly in routes
- Error handling via custom AppError class in src/lib/errors.ts

Start tasks in Explore mode. Even for tasks you think are simple, a quick explore turn first means the agent navigates correctly from the start rather than making wrong assumptions.

Reject and explain, don't just reject. When you reject an approval queue item, add a reason. The agent uses it to replan. "Reject — use the existing AppError class for error handling, not a raw throw" gets you a better next attempt than a silent reject.

Check the Blueprint canvas on new codebases. (Removed — there is no canvas.) The visual graph in the Blueprint tab is useful for understanding unfamiliar repos. Filter by file type, zoom into a module, and let the graph show you the dependency shape before you start prompting.

Free Tier Summary

Feature	Solo (Free)
Workspaces	1
Local models (Ollama, LM Studio)	✓ Unlimited
Model Bridge Speed tier	✓ Included usage
Core tools (file, terminal, search, blueprint)	✓
MCP marketplace	✗ (1 manual MCP)
Agent Behaviors marketplace	✗

For a solo developer using local models, the free tier is genuinely unlimited. No token caps on Ollama usage.

Getting Started

# 1. Download from atlarix.dev
# 2. Install CLI from Settings → General
# 3. Open your project
atlarix .

# 4. Connect Ollama (or paste an API key)
# 5. Start in Explore mode, describe your codebase
# 6. Switch to Build when you're ready to execute

The learning curve is less steep than it sounds. The hardest part is resisting the urge to jump straight into Build mode — a quick Explore turn first makes everything else go smoother.

atlarix.dev — macOS + Linux, free Solo tier

Open source: atlarix-skills · atlarix-mcps

Questions? Drop them in the comments — happy to go deep on any part of this.

How I reduced AI codebase context from 100K to 5K tokens using a graph-based RAG — and why I deleted it

Amariah Kamau — Thu, 30 Apr 2026 18:43:26 +0000

Historical — the architecture below was removed from Atlarix in v14.9.0 (10 July 2026).

Blueprint, the parser, the SQLite graph, BM25 node scoring and the file watcher were all deleted — roughly 5,246 lines — after the watcher was found to hold one file descriptor per watched file and reach about 12,365 on a large repository.

Atlarix today has no index of any kind. Retrieval is purely lexical: bundled ripgrep (grep and glob), no embeddings, no vector store, no graph, nothing in the background. Current architecture: atlarix.dev/docs.

Most AI coding tools lie to you about context.

They say "I understand your codebase." What they actually do is dump as many files as possible into the context window and hope the model figures it out. That works on a 3-file project. It falls apart on anything real.

Here's the problem I kept hitting: a medium-sized production codebase hits ~100K tokens when you try to feed it to an LLM. That's expensive, slow, and surprisingly lossy — models start hallucinating relationships between files that don't exist, missing the ones that do.
So I built a different approach inside Atlarix. Here's exactly how it works.

Step 1: Parse the codebase into a typed graph (Round-Trip Engineering)

When you open a project in Atlarix, it runs a parser over every file using Tree-sitter AST. Instead of storing raw text, it extracts:

Every function, class, interface, and type
Import/export relationships between files
Call relationships between functions
File-level dependency edges

This got stored as a typed node/edge graph in SQLite — what we called the Blueprint. (Removed in v14.9.0. There is no SQLite graph and no Blueprint today.)

Step 2: Query the graph, not the files

When you asked Atlarix something, it didn't re-read your files — it queried the Blueprint graph. (Today it does re-read files, deliberately: ripgrep over the workspace, no index in between.)
We use BM25 scoring to rank nodes by relevance to the query. Only the top-scoring nodes get passed to the LLM. Everything else stays in SQLite.
Result: instead of ~100K tokens, the average query uses ~5K tokens. That's a 95% reduction.

Step 3: Hierarchical context for complex queries

For simple queries, BM25 node retrieval is enough. For complex ones — multi-file refactors, architecture questions — we use a three-layer hierarchy:

Mermaid diagram — a persistent high-level map of the whole codebase, always in context
BM25-scored Blueprint nodes — targeted retrieval for the specific query
Fast-model compression — if context hits 70% capacity, a fast model compresses the least relevant nodes before passing to the main model

This keeps context tight regardless of project size.

Step 4: Provider-agnostic by design

The Blueprint RAG layer sits beneath every AI provider. Whether you're using GPT-4o, Claude, Gemini, Groq, or a local Ollama model — the same 5K token context gets served. You're not paying for the model to re-read your whole codebase on every message.

Why this matters beyond token cost

The token reduction is the headline number. But the real win is accuracy.
When you give an LLM 100K tokens, it attends to all of it roughly equally. The file you actually care about is competing with 200 other files for attention. With 5K targeted tokens, the model is working with exactly what's relevant. Responses are more precise, edits land in the right place, and hallucinated file paths basically disappear.

What's next

Atlarix v7 added parallel agents named Research, Architect, Builder, Reviewer and Debugger on top of this foundation. Those names are long gone and are a common source of stale descriptions of Atlarix. The work modes today are Explore, Plan, Build, Debug and Review, and the task tool spawns scoped workers whose edits come back as reviewable proposals rather than writes.
We also just shipped Windows support today — so Atlarix now runs on Mac, Windows, and Linux.
If you're building something where AI context management is a bottleneck, I'd love to compare notes. Try it at atlarix.dev or ask me anything in the comments