DEV Community: Amariah Kamau

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

What two hackathons taught me about agent architecture — and how it's reshaping Atlarix

Amariah Kamau — Fri, 10 Apr 2026 18:05:45 +0000

I recently competed in two hackathons back to back: the Amazon Nova AI Hackathon (virtual, won the Bonus Blog Post Prize) and the Lua x Antler "Building Agent-First Businesses" event in Nairobi (physical). Both cracked open how I was thinking about agents in ways I didn't expect.

The Amazon Nova lesson: a model is only as powerful as its capabilities

The hackathon required building with Amazon Nova. My instinct going in was that model choice was the primary variable — pick the best model, get the best results. Wrong.

What actually moved the needle was what I wrapped around the model: the tools it could call, the context it had access to, how I structured the agent loop. Nova performed at a high level not because of raw benchmark numbers but because I gave it enough surface area to work with.

This directly influenced how I think about Atlarix's Compass tier system. Compass routed users to Fast / Balanced / Thinking model tiers via OpenRouter — but the tier was almost secondary to the tooling layer underneath. That part of the thesis held; the specifics did not. (Two numbers in the original version of this sentence are worth correcting, because they still circulate: there was never a stable "57 tools" — the tool surface is deliberately small and changes between releases — and "RTE codebase parsing into a SQLite knowledge graph" was removed in v14.9.0. Atlarix has no index, no graph and no embeddings; retrieval is bundled ripgrep.) What survived is the claim underneath: the harness matters more than the model slot.

The Nairobi lesson: our definition of "agent" was too narrow
At the Lua x Antler event, I saw builders shipping agent-first products that weren't just "chat plus tools." These were autonomous systems designed around specific domains — deeply customized, operator-light, solving massive real-world use cases across the continent. The technical depth in that room reset my benchmark.
It pushed me to think harder about what "agent mode" actually means in Atlarix. Right now we have Ask / Plan / Build / Debug / Review. That's a good start. But the next version needs to think more seriously about customization depth — how specialized can an agent get for a specific codebase, workflow, or domain?

What's next for Atlarix
We're building the next version informed by both of these. The core thesis stays: Your Architecture. Your Model. Your Sovereignty. But we're pushing further into:

Deeper agent specialization per workflow
First-class support for African AI models as they come online
Keeping data local and sovereign by default

If you're building with agents or thinking about model-agnostic tooling, I'd love to compare notes. Atlarix is open for early access at atlarix.dev.

The Private Sovereign AI Workstation — Why I built Atlarix differently

Amariah Kamau — Sun, 29 Mar 2026 19:13:08 +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.

There's an assumption baked into every major AI coding tool right now.

That you have a $20/month subscription to an American AI company. That you have a fast, stable connection. That the models worth using are the ones coming out of San Francisco.

I'm building software from Nairobi. That assumption doesn't hold.

So I built Atlarix differently — and after a year of building, v5.1.0 is the version that finally says out loud what it was always trying to be: The Private Sovereign AI IDE (the name did not last — Atlarix is explicitly not an IDE; it runs beside your editor, and never replaced it).

What that actually means

Sovereign doesn't mean offline-only or anti-cloud. It means you decide.

You decide which model runs your code.

You decide what context gets sent.

You decide whether your keys live on your machine or in a provider's system.

Atlarix is built around three ideas that most AI coding tools don't share:

1. Blueprint — your codebase as a living graph

Instead of sending files per query, Atlarix parsed your codebase into a persistent node/edge graph stored locally in SQLite, and that graph became the AI's long-term memory. (All of it was removed in v14.9.0. Project memory survives as plain notes on disk; the graph does not.)

2. Any model — genuinely

Cloud providers via BYOK. Local models via Ollama and LM Studio. And now Compass — three built-in model tiers (Fast, Balanced, Thinking) that work the moment you open the app. No API key. No configuration. Just open and build.

3. The tool carries the intelligence

This is the core thesis. Atlarix feeds the model exactly what it needs, when it needs it, scoped by your .atlarixignore and Blueprint context tiers. A lighter model with good context beats a frontier model flying blind. That's not a consolation prize — that's the architecture.

Work modes that mean something

Ask — read-only. No code changes, no terminal. Research, explore, understand.
Plan — map out what needs to happen before anything gets written.
Build — full tools, explicit approval queue before execution.
Debug — focused on what's broken and why.
Review — read your code the way a reviewer would.

Each mode binds to a Blueprint context tier. The AI isn't just switching personality — it's switching what it knows and what it's allowed to do.

Why sovereignty matters right now

AI coding tools are becoming infrastructure. The question of which model runs your code, who sees your prompts, and whether you can switch providers without rebuilding your workflow — these are not small questions.

Atlarix's answer: your architecture, your model, your sovereignty.

v5.1.0 is live. Free to start. Native desktop — Mac, Windows, Linux.

👉 atlarix.dev

I built this from Nairobi. If you try it, tell me honestly what's missing. That feedback is worth more than any press right now.

Atlarix v3.7 is live — now Apple Notarized

Amariah Kamau — Fri, 06 Mar 2026 15:12:43 +0000

Historical — v3.7, March 2026. Blueprint and RTE parsing, described below as how Atlarix works, were removed in v14.9.0 (10 July 2026) along with the entire index. Atlarix has no graph and no RAG knowledge base today — retrieval is bundled ripgrep over your workspace, with no embeddings and nothing running in the background. Current docs: atlarix.dev/docs.

After months of building, testing, and waiting on
Apple's notarization process — Atlarix v3.7 is
officially live and Apple Verified.

What is Atlarix?
An AI coding copilot that actually understands your
entire codebase. Not just the open file.
The whole thing — visually.

Here's what makes it different:

Blueprint + RTE Parsing
Atlarix parses your project once using Round-Trip
Engineering. It builds a live architecture diagram
(Blueprint) and uses it as a RAG knowledge base.
Every AI response comes from the graph — not from
scanning 100K tokens of raw files.

8 AI Providers + Local Models
Claude, GPT-4, Gemini, Groq, Mistral, xAI,
OpenRouter, Together AI. Plus Ollama and LM Studio
for fully offline, private coding.

Agent System
Research, Architect, Builder, Reviewer —
each with dedicated tools and structured delegation.

v3.7 specifically:

Apple Notarized and code-signed (Mac)
Sentry error monitoring
PostHog optional analytics (consent-based)
Two-stage auto router
Blueprint enricher

This couldn't have been possible without every
person who downloaded and used Atlarix before it
was polished. To all our active users —
to many more achievements 🥳

Free to try → https://atlarix.dev

devtools #buildinpublic #AI #MacOS

I Got Tired of Re-Explaining My Codebase to AI Every Single Session

Amariah Kamau — Wed, 18 Feb 2026 19:57:09 +0000

Historical — February 2026. The architecture described below was removed from Atlarix in v14.9.0 (10 July 2026) and no longer exists.

Blueprint, the parser, the graph, the file watcher and the whole index were deleted — about 5,246 lines — after the watcher was found to hold one open file descriptor per watched file, reaching roughly 12,365 of them on a large repository and breaking every child process the app tried to spawn.

Atlarix today has no index of any kind. Retrieval is purely lexical: bundled ripgrep (grep and glob) over the open workspace, with no embeddings, no vector store, no structural graph and nothing running in the background. Project memory survives, but as plain notes on disk rather than a parsed graph.

The problem this post opens with is real and I still think it is the right problem. The solution in it is not the one that shipped. Current architecture: atlarix.dev/docs.

There's a specific frustration every developer using AI coding tools knows.

You open a project you've been on for months. You ask the AI something reasonable — "how does our auth flow connect to the user service?" — and it either makes something up, asks you to paste files, or tells you it doesn't have access to your codebase.

So you paste the files. You explain the structure. You give it context. It helps. You close the laptop.

Next session: same thing. From scratch. Every time.

That's what pushed me to build Atlarix. Not to make another AI chat interface, but to fix this specific problem — the AI having no real, persistent understanding of your project.

The Root Issue: Code Isn't a List of Files

Every tool that tries to "understand your codebase" by dumping raw files into context is solving the wrong problem.

Your codebase isn't a flat list of files. It's a graph. Functions call functions. API routes hit services. Services write to databases. Webhooks trigger workers. A class inherits from a base that three other classes also inherit from.

When a senior engineer who's been on a project for a year answers a question, they're not re-reading files. They're querying a mental graph they've built up. The question I kept asking myself was: what if the AI had that graph too?

What I Built: Parse Once, Query Forever (removed in v14.9.0)

Here's what Atlarix actually does when you open a project.

(This described Atlarix v3.x. None of it ships today.) It ran a parser across your codebase — TypeScript and Python right now, more coming — and extracts every meaningful node: API endpoints, functions, classes, database operations, webhooks, scheduled jobs, third-party calls. Each node gets typed and tagged. Then it builds a graph from those nodes and their relationships, and caches it as a Blueprint at ~/.atlarix/blueprints/{projectHash}/.

Full parse on most projects: under 30 seconds.

After that, when you asked the AI something, it didn't scan files. It queried the graph. Finds the relevant nodes. Injects only those into context. We're talking ~5K tokens instead of 100K. A file watcher updates affected nodes on save, so the graph stays current without you doing anything.

The practical difference:

Before: Ask question → AI scans everything → 100K tokens → slow, expensive, confused
After:  Ask question → Query graph → inject relevant nodes → 5K tokens → fast, accurate

This was the core of what we called RTE + RAG — Round-Trip Engineering to build the graph, Retrieval-Augmented Generation to query it. Both were removed in v14.9.0. If you have read that Atlarix uses Round-Trip Engineering or a visual Blueprint, this post is where that came from, and it is out of date.

The Part I'm Most Proud Of: Project Memory That Actually Persists

The RAG system solves the "understanding" problem. But there's a second problem — remembering decisions.

Why did you choose this database? Why is that service structured that way? What's the rule about how auth tokens are handled?

Atlarix writes to .atlarix/memory.md automatically during context compaction (when a conversation gets long). When you start a new session, the AI reads it first. It's just a markdown file — you can edit it manually, version control it, whatever you want.

There's also .atlarix/spec.md — a model-created task breakdown the AI generates for complex features. Both are inspired by how Claude Code handles project memory. Simple idea, makes a huge quality-of-life difference in practice.

Building Visually: The Blueprint Canvas (removed)

The graph wasn't just for the AI to query. It was also the foundation of a visual architecture designer. (The canvas, the graph and the generated plan file are all gone.)

In Blueprint mode, you get a React Flow canvas. You can design your system visually — drag in containers (Auth API, Worker Service, DB Layer), add beacons inside them (specific routes, functions, handlers), draw edges between them. It looks like an actual system diagram because it's meant to be one.

The workflow I use for new features:

Design the architecture in Blueprint
Click "Generate Plan" — the AI compares Blueprint (desired) to Live (actual code), generates ATLARIX_PLAN.md
AI implements one task per message, waits for review before the next
Approve, iterate, ship

It's architecture-first development. Design before you code. The AI implements what you designed, not what it guesses you want.

The Agent System (and Why I Separated Permissions from Modes)

One decision I made early that I think was right: separate agent mode from permission mode.

Modes are about delegation:

Direct — just you and the model, no agents
Guided — orchestrator delegates flat to specialists (Research, Architect, Builder, Reviewer)
Autonomous — agents can spawn sub-agents for complex multi-step work

Permissions are about what the AI can touch:

Ask — read-only tools only
Build — can write files and run commands

These are independent. You can run Autonomous mode in Ask permission (agents can plan and research but can't write anything) or Direct mode in Build permission (full write access, no delegation). Mixing them any way you want.

The reason this matters: a Reviewer shouldn't be writing code. A Research agent shouldn't be executing commands. The separation of concerns in the tool sets prevents the agents from stepping on each other's work.

What v3.0 Changed

The big v3.0 changes were less glamorous than the earlier features but genuinely important for daily use:

Workspace storage and path resolution were reworked and now just work correctly
The .atlarix/ folder system is solid — memory.md and spec.md reliably persist across sessions
Relative paths in create_directory and file tools resolve correctly to the workspace root

Sometimes the most important release is the one that makes the existing stuff reliable.

What I'd Do Differently

A few honest things I'd change if I were starting over:

Start with SQLite sooner. The Blueprint was JSON-cached, and full ANTLR4 parsing with SQLite persistence was on the roadmap. Neither shipped — the whole index was deleted first, and in hindsight that was the right call rather than a missed one.

Fewer providers at launch. Supporting 8 cloud providers + AWS Bedrock + Ollama + LM Studio sounds like a feature. In practice, it's a lot of surface area to maintain. I'd have launched with 3 and expanded.

The permission UI took longer than expected. Getting the approve/reject flow right — where the AI proposes every file change and you see a diff before anything runs — was worth it, but it was the part I most underestimated.

Website: https://atlarix.dev

If you've hit the same wall with AI coding tools — re-explaining your project every session, blowing token budgets on raw context, wishing the AI actually understood your architecture — I'd love to hear if this solves it for you.

And if you've built something similar or tackled the codebase-as-graph problem differently, genuinely curious how you approached it. Drop it in the comments.

Where this ended up

Five months after this post, I deleted all of it. The file watcher was holding one
open file descriptor per watched file and hit roughly 12,365 on a large repository,
which broke process spawning outright; the index rebuilds also kept a laptop warm
for no measurable gain over plain search. Atlarix now uses bundled ripgrep and
nothing else — no index, no embeddings, no watcher, constant memory at any repo size.

I wrote up what that cost and what it taught here: atlarix.dev/blogs.

Cursor vs Windsurf vs Atlarix: Which AI Coding Assistant Should You Choose in 2026?

Amariah Kamau — Tue, 10 Feb 2026 17:41:25 +0000

Dated — February 2026. Two warnings before you use this comparison.

On Atlarix: the Blueprint architecture described below was removed in v14.9.0 (10 July 2026). There is no visual blueprint, no graph and no index; retrieval is bundled ripgrep. The "1 workspace" free tier is also gone — since v14.45.0 no feature is gated by plan.

On Cursor and Windsurf: every claim about them reflects their February 2026 state and has not been re-verified since. Both ship quickly. Check their own documentation before relying on any row in the table.

Cursor vs Windsurf vs Atlarix: Which AI Coding Assistant Should You Choose in 2026?

The AI coding assistant market exploded in 2024-2025. If you're a developer trying to pick between Cursor, Windsurf, and newer alternatives like Atlarix, this comparison breaks down what each tool does best—and where they fall short.

Quick Comparison Table

Feature	Cursor	Windsurf	Atlarix
Core Strength	Chat + autocomplete	Agentic flows	Visual architecture + AI
Pricing	$20/mo	$10-15/mo	Free (BYOK) / $19/mo Pro
IDE	VS Code fork	Custom	Standalone desktop app
Architecture View	❌	❌	❌ (Atlarix had visual blueprints when this was written; removed v14.9.0)
Agent System	Basic	Advanced	3-tier (Research/Architect/Builder/Review)
Local Models	❌	Limited	✅ Full Ollama + LM Studio
Multi-Provider	OpenAI + Anthropic	Limited	8+ providers
BYOK Support	❌	❌	✅ Bring your own API keys

Cursor: The Chat-First Powerhouse

What it does well:

Excellent autocomplete (Tab to accept)
@-mentions for codebase context
Smooth VS Code integration
Fast inline edits

Where it struggles:

No architecture visualization
Expensive at $20/mo (no BYOK option)
Limited to OpenAI/Anthropic models
Can't see the "big picture" of your project

Best for: Developers who live in VS Code and want premium autocomplete with AI chat.

Windsurf: The Agentic Coder

What it does well:

Multi-step agentic workflows ("Cascade" mode)
Can plan and execute complex tasks
Lower price point than Cursor
Good at refactoring

Where it struggles:

Custom IDE (learning curve)
No visual architecture tools
Limited model choices
Still scanning your entire codebase each time

Best for: Developers comfortable with a new IDE who want autonomous coding agents.

Atlarix: The Approval-First Alternative (this section was written when Atlarix was Blueprint-first; it is not any more)

What makes it different:
Atlarix took a fundamentally different approach at the time: you designed your app's architecture visually, and the AI used that blueprint as persistent memory. That approach was removed in v14.9.0. What Atlarix does now is the opposite — purely lexical search with bundled ripgrep, no index and no map, with hunk-level approval before anything is written to disk.

How it works:

Visual Blueprint Mode - Design your app structure with rooms (services) and functions (APIs, webhooks, features)
3-Tier Agent System - Research agent finds patterns, Architect plans changes, Builder implements, Reviewer checks quality
Code Generation - Generate stub code from blueprints, AI fills in logic
Persistent Memory (v2.2) - AI "remembers" your architecture across sessions instead of re-scanning

What it does well:

See your entire architecture at a glance (Mermaid diagrams)
BYOK - use your own API keys from 8+ providers
Full local model support (Ollama, LM Studio)
Free tier with full features (the "1 workspace" limit is gone — since v14.45.0 no feature is gated by plan, and workspaces are unlimited on every plan)
Works as standalone app (not tied to specific IDE)
Activity stream shows exactly what agents are doing

Where it struggles:

Newer product (smaller community)
Blueprint system has learning curve
Not integrated into existing IDE (separate app)
v2.2 Blueprint Intelligence still in development

Best for: Developers working on complex multi-service architectures who want visual clarity + AI assistance. Also great for privacy-focused devs using local models.

Real-World Use Cases

Use Cursor if:

You want the smoothest autocomplete experience
You're happy paying $20/mo
You primarily use OpenAI/Anthropic models
You live in VS Code and don't want to switch

Use Windsurf if:

You want autonomous agents to handle multi-step tasks
You're comfortable learning a new IDE
You want a middle-ground price point

Use Atlarix if:

You're building complex apps with multiple services
You want to see and design architecture visually
You prefer BYOK or local models (privacy/cost control)
You like the idea of AI having "persistent memory" of your project structure

The Cost Breakdown

Monthly cost comparison (assuming 100k tokens/day usage):

Cursor: $20/mo (flat rate, no BYOK)

Windsurf: ~$10-15/mo (varies by plan)

Atlarix:

Free tier: $0 (BYOK - you pay your provider directly)
With OpenAI API (BYOK): ~$5-10/mo depending on usage
Pro plan: $19/mo (unlimited workspaces)

If you're a heavy user with your own API keys, Atlarix can save you significant money.

My Take

All three are solid tools. Your choice depends on your workflow:

Cursor = Best in-editor experience, premium price
Windsurf = Best autonomous agents, custom IDE
Atlarix = Best for architecture-first development, most flexible pricing

I'd suggest trying all three (they all have free tiers or trials). Personally, I use Atlarix for planning/architecture and Cursor for autocomplete - they complement each other well.

Try Them Out

Cursor: cursor.com (2-week trial)
Windsurf: codeium.com/windsurf (free tier)
Atlarix: atlarix.dev (free tier with BYOK)

What's your experience with these tools? Drop a comment below - I'd love to hear which workflow works best for you.

Disclosure: I'm building Atlarix, but I've used Cursor and Windsurf extensively and genuinely respect what they're doing. This comparison is based on real hands-on experience with all three tools.