I Got Tired of Re-Explaining My Codebase to AI Every Single Session
Source: Dev.to
The Problem — Why AI Coding Tools Feel Frustrating
Every developer who uses AI‑assisted coding knows the same pain point:
- Open a long‑standing project.
- Ask a reasonable question – e.g., “How does our auth flow connect to the user service?”
- The AI:
- Makes something up,
- Asks you to paste files, or
- Says it has no access to the codebase.
You end up pasting files, explaining the structure, getting a partial answer, closing the laptop, and then repeating the whole process the next time you need help.
That loop is what drove me to build Atlarix – not another chat UI, but a solution to the real problem: the AI has no persistent, structural understanding of your project.
Why “Dumping Files into Context” Is the Wrong Approach
Your codebase isn’t a flat list of files; it’s a graph:
- Functions call other functions.
- API routes hit services.
- Services write to databases.
- Webhooks trigger workers.
- Classes inherit from bases that other classes also inherit from.
A senior engineer who’s been on a project for a year answers questions by querying a mental graph, not by re‑reading every file.
What if the AI had that graph too?
What Atlarix Actually Does
1. Parse & Build a Blueprint
| Step | What Happens |
|---|---|
| Parse | Runs a parser (currently TypeScript & Python) across the whole codebase. |
| Extract Nodes | Finds every meaningful node: API endpoints, functions, classes, DB operations, webhooks, scheduled jobs, third‑party calls. |
| Tag & Type | Each node gets a type and tags. |
| Graph Construction | Builds a graph of nodes and their relationships. |
| Cache | Stores the graph as a Blueprint in ~/.atlarix/blueprints/{projectHash}/. |
| Speed | Full parse on most projects: under 30 seconds. |
A file watcher updates affected nodes on every save, keeping the graph current automatically.
2. Query‑Based AI Interaction
When you ask a question:
- Query the graph for relevant nodes.
- Inject only those nodes into the AI context (≈ 5 K tokens).
Before – AI scans everything → ~100 K tokens → slow, expensive, confused.
After – AI queries graph → ~5 K tokens → fast, accurate.
This is the core of RTE + RAG:
- RTE (Round‑Trip Engineering) builds the graph.
- RAG (Retrieval‑Augmented Generation) queries it.
Remembering Decisions – Project Memory
Two markdown files live in ~/.atlarix/:
| File | Purpose |
|---|---|
| memory.md | Auto‑written during context compaction (when a conversation gets long). The AI reads it first on a new session. You can edit, version‑control, or delete it. |
| spec.md | Model‑generated task breakdown for complex features (inspired by Claude Code). |
These give the AI a persistent “project memory” beyond the immediate query.
Blueprint Mode – Visual Architecture Designer
- React Flow canvas shows your system as a diagram.
- Drag containers (e.g., Auth API, Worker Service, DB Layer).
- Add beacons (specific routes, functions, handlers).
- Draw edges to represent relationships.
The visual graph is both a design surface and the source of truth for the AI.
Workflow for New Features
- Design the architecture in Blueprint.
- Click “Generate Plan” → AI compares Blueprint (desired) vs. Live (actual) and creates
ATLARIX_PLAN.md. - AI implements one task per message, waits for your review before proceeding.
- Approve → iterate → ship.
Architecture‑first development: design first, let the AI implement exactly what you designed.
Modes & Permissions – Decoupled Controls
| Mode | What It Controls |
|---|---|
| Direct | You and the model only – no agents. |
| Guided | Orchestrator delegates to specialists (Research, Architect, Builder, Reviewer). |
| Autonomous | Agents can spawn sub‑agents for complex, multi‑step work. |
| Permission | What It Controls |
|---|---|
| Ask | Read‑only tools only. |
| Build | Can write files and run commands. |
These are independent. Example combos:
- Autonomous + Ask – agents can plan/research but can’t write.
- Direct + Build – you have full write access, no delegation.
The separation ensures, for instance, that a Reviewer never writes code and a Research agent never executes commands.
v3.0 – The “Reliability” Release
- Workspace storage & path resolution reworked – now just work.
.atlarix/folder system solidified –memory.md&spec.mdreliably persist across sessions.- Relative paths in
create_directoryand file tools resolve correctly to the workspace root.
Sometimes the most important release is the one that makes the existing stuff reliable.
Lessons Learned (What I’d Do Differently)
-
Start with SQLite sooner.
- Blueprint is currently JSON‑cached. Full ANTLR4 parsing with SQLite persistence (PIVOT) is on the roadmap; I should have committed to that architecture earlier.
-
Fewer providers at launch.
- Supporting 8 cloud providers + AWS Bedrock + Ollama + LM Studio sounded impressive, but it added massive surface area. I’d have launched with 3 and expanded later.
-
Permission UI took longer than expected.
- Getting the approve/reject flow right—AI proposes every file change, you see a diff before anything runs—was worth it, but I underestimated the effort.
Get Started
- Website:
- If you’ve hit the same wall with AI coding tools—re‑explaining your codebase over and over—give Atlarix a try.
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, I’m genuinely curious how you approached it. Drop it in the comments.