I've been building ARCLUX — a repository intelligence tool (CLI + web dashboard) that maps your codebase into a dependency graph, traces impact ("what breaks if I touch this file?"), and runs 18 structural detectors (circular deps, dead code, orphan files, layer violations, etc).
Verified at meaningful scale — microsoft/vscode, facebook/react, and vitejs/vite all analyze successfully, not just small toy fixtures.
Language support:
- TypeScript, JavaScript, Python — full support
- Go, Java — parsing works, but same-package calls with no import statement (common in both languages) aren't resolved as edges yet
Honest state (this is v0.1.0-alpha):
- Very large/unusual repos (10k+ files, heavy monorepos) can currently time out or fail without a clear error — no size guard or progress streaming yet, that's next
- Some packages (search, persistent caching) are still stubs
I'm not trying to compete with enterprise tooling — this started as a personal project to actually understand codebases I work in, and it grew from there.
Would love feedback, bug reports, or PRs if any of this is useful to you.
Top comments (9)
Impact analysis is one of the trickiest things to get right at scale — worth flagging one failure mode I hit building something adjacent (MCP codebase-intelligence server): symbol lookups can silently resolve to a shadow/duplicate definition elsewhere in the repo (test fixtures, examples/ folders, etc.) and the wrong answer looks exactly as confident as a correct one. No error, just quietly wrong. Might be worth a detector for that specifically, alongside your circular-deps/dead-code/orphan-files set — a "same name, multiple definitions, which one resolved" check.
Respect for shipping the honest state section instead of polishing over the alpha gaps. Curious how you're handling incremental re-analysis on large repos once the size-guard work lands — full re-walk on every change, or something closer to file-scoped invalidation?
Starred it — will try it against a repo I maintain.
Really appreciate this — exactly the kind of feedback I was hoping for.
The shadow-definition detection idea is great, and it's a real gap right now — nothing in ARCLUX catches that today (a symbol resolving to a duplicate/shadow definition in a test fixture or examples/ folder, silently). Adding it to the backlog as a proper detector, alongside the circular-deps/dead-code/orphan-files set.
On incremental re-analysis: honest answer, not solved yet. Every analyzeRepository() call does a full re-scan currently. There's a content-hash cache layer (packages/cache) and a separate dependency-tracking foundation (packages/incremental, loosely inspired by salsa-rs) already built, but neither is wired into the main pipeline yet. Scope-based invalidation is the direction, not full re-scan forever — but it's genuinely not there today.
Given what you're building with mscodebase-intelligence, you clearly know this space well. If you're interested, I'd genuinely welcome you as a collaborator on ARCLUX — happy to find a well-scoped first issue, and the shadow-definition detector you mentioned could even be it, if you want to take a swing at it.
Thanks again for starring the repo, and for the sharp feedback.
Thanks for the detailed answer — that makes sense.
The shadow-definition detector is actually the part I’m most interested in experimenting with. Dependency graphs are useful for showing what depends on what, but detecting a definition that silently shadows or changes the meaning of another symbol feels like a different and potentially very valuable layer of codebase intelligence.
I also noticed the structured engineering history in
progres/— progress, bugs, decisions, and gotchas kept as part of the project rather than scattered across commits and issues. That caught my attention because I’ve been experimenting with a similar idea in my own work, although my structure is quite different.What I’m particularly curious about is whether that history can become useful context for AI agents themselves — not just documentation for humans. For example, could an agent use previous decisions and known gotchas as part of its reasoning when analysing a change?
I’m going to experiment with a few of these ideas rather than trying to reproduce the whole structure. Thanks for sharing the project.
Great question, and honestly the answer is: it started as documentation for the AI, and became documentation for humans as a side effect.
The original problem: every new AI session starts with zero memory of past sessions. Without something to read first, it would re-investigate things that were already figured out, redo work that was already done, or worse, assume something was broken when it was actually an intentional decision. The progres/ system exists so a new session can
cata handful of files and immediately know: what's done, what's a stub on purpose, what design decisions were made and why, and what environment gotchas to avoid repeating.That said, it's turned out to be just as useful for the human (me) going back weeks later and going "wait, why did I do it this way" — the decisions.md file especially. So in practice it's dual-purpose now, but the AI-legibility need is what shaped the format: dated headers, one category per concern (status vs bugs vs decisions vs gotchas), and recently a status field (Not Started/In Progress/Done) so an old "planned" entry doesn't get mistaken for still-pending work once it's actually done.
Curious what you land on for your own version — given yours already has 1000+ tests and a much heavier core, I'd guess the failure mode you're solving for might be different from mine.
That makes a lot of sense. And in my case, the diary actually started for a very practical reason, long before I was thinking about it as an engineering practice.
I’m not a professional programmer. I started experimenting with Telegram bots, then moved to Cursor, and during long sessions I noticed a very frustrating pattern: once the context became large enough, the AI would start going in circles. It would rediscover the same bug, propose essentially the same fix under a different name, or undo a decision we had already made earlier in the session.
At some point I got tired of losing that history, so I started keeping a diary — I think around my second version of the bot.
Since then it has evolved quite a bit. My current project has several different kinds of history/diaries rather than one single log. They track not just what was done, but bugs, decisions, failed approaches, and things that shouldn't be repeated.
So your description of
progres/immediately caught my attention. I arrived at a similar idea from the opposite direction: not “how do I document the project for an AI?”, but “how do I stop the AI from forgetting what we already learned?”And I think that's an interesting distinction. The history isn't just context for the agent — it can become a kind of external memory of why the current code looks the way it does.
That's actually what I'd like to experiment with in my own project: whether an AI can use that history not just to understand the current codebase, but to avoid repeating previously disproven approaches.
😭✍️That reframe — "how do I stop the AI from forgetting" vs "how do I document for the AI" — is sharper than how I'd been thinking about it, and it matches something that's actually happened to me directly.
A while back, a session mistook an intentional decision (a section I'd deliberately removed from the README) for accidental damage, based purely on a generic commit message, and "fixed" it by restoring what I'd removed on purpose. Caught it, reverted, and logged the decision explicitly so it wouldn't happen a second time — which is exactly the failure mode you're describing. Not the AI forgetting facts, but forgetting the reasoning behind a choice, and then confidently undoing it.
That's actually why the decisions.md file ended up being the one I care about most, more than the plain status log. Status is "what got built." Decisions is "what we tried, what we ruled out, and why" — and that second part is the one that actually prevents the circling you're describing, since a bad approach doesn't just disappear, it gets marked as tried-and-rejected so it can't quietly resurface with a different name three sessions later.
Genuinely curious how the multiple-diary-types setup works for you in practice — splitting by type (bugs vs decisions vs rejected approaches) sounds like the same instinct, just arrived at from your direction instead of mine.
That’s actually a good question, because the multiple-history approach wasn’t designed up front.
It evolved as I kept running into different kinds of “memory loss”.
AGENT_DIARYis more about the agent/session history — what happened, what was checked, what changed.DEV_DIARYis closer to the development process itself.EXPERIMENTS_LOGis important for another reason: it records things we tried, including approaches that didn't work. I don't want a future session to see an old idea and confidently “rediscover” it as if it were new.Then there are things like known issues and accumulated project knowledge, which are useful at a different level.
So I don't really think of these as several diaries anymore. They are becoming different layers of external memory.
The interesting part for me is that they don't all need to be loaded into the context. An agent should be able to retrieve the relevant kind of history depending on what it is doing.
For example, when debugging, previous failed approaches may be more valuable than the current status. When changing architecture, the decisions and their reasons matter more. When starting a new session, a compact current-state view is enough.
That's probably the direction I want to explore further: not just giving an agent “memory”, but giving it a way to distinguish what happened, what was decided, what failed, and what we learned from it.
The "layers, not diaries" framing is a real upgrade over how I'd been thinking about this — and the selective-retrieval point is something I've actually felt the cost of without having named it yet.
Right now my setup is closer to "load everything, every session" — a fresh session cats all the progres/ files at once, regardless of what it's about to do. It works, but it's wasteful: debugging a CI failure doesn't need the same context as designing a new detector, and I'm paying the full context cost either way. Your point about failed approaches mattering more during debugging, decisions mattering more during architecture changes, and a compact current-state view being enough at session start — that's a much sharper way to think about it than "one flat history, read all of it."
What I don't have yet is any mechanism for an agent to know it needs a specific layer before asking for it — it's still me manually deciding to grep a particular file, not the agent recognizing "this is a debugging task, pull failed-approaches first." That selective-retrieval-by-task-type piece sounds like the actual hard part, versus just splitting files by category, which is the easy 80% I've already done.
If you end up building that retrieval layer, I'd genuinely be curious to see how you approach the "agent recognizes what kind of task this is" part — that feels like the piece that turns categorized files into something closer to actual structured memory.
Yeah, that's basically the direction I'm moving toward.
My current setup is already split into different memory layers rather than one flat diary:
AGENT_DIARY.md— incidents, root causes and decisionsKNOWN_ISSUES.md— known problems and their current stateEXPERIMENTS_LOG.md— experiments, measurements and failed approachesAGENTS.md— agent behavior/protocols rather than project historydocs/adr/— architectural decisions and why they were made.agent_task_state.md— the current task state, verification and next actionOn top of that, I have
mscodebase-intelligencefor retrieving the actual code/context from the repository instead of loading the whole codebase.So the part I don't have fully solved yet is pretty much the same part you're pointing at: the agent doesn't yet have a proper task-aware retrieval layer that automatically decides which memory layers are relevant.
The interesting next step would be to classify the incoming task first — debugging, research, architecture, experiment, implementation, etc. — and use that classification to select the relevant memory sources.
For example, a debugging task should pull failed approaches and recent incidents first, while an architecture task should prioritize ADRs, current state and historical decisions.
So I think we're actually looking at the same problem from two sides: I've already built the memory layers and retrieval infrastructure, but the missing piece is the intelligent routing between the task type and those layers.