Arch

Arch reconstructs the state of forgotten software projects, hence what was done, what remains, what was deferred, and what to do next, using evidence from the repository.

Comment

Inspiration

Arch came from a problem I repeatedly experienced while developing software with AI.

I would work on a project across many coding sessions. During development, features were completed, others were postponed, decisions were made, TODOs appeared, bugs were discovered, Git commits accumulated, and documentation was updated — sometimes.

Then I would return to the project days or weeks later and face a surprisingly difficult question:

Where were we?

I often asked an AI assistant to create a handover document before ending a session because otherwise important context could disappear. But that was fragile. You have to remember to create the handover, and even then it can become outdated as development continues.

I realized that most of the information needed to reconstruct the project was already there — scattered across source code, documentation, TODOs, decisions, tests, notes, and Git history.

That became Arch.

Instead of requiring a perfect handover, Arch tries to reconstruct what actually happened from the evidence the project left behind.

What it does

Arch analyzes an existing software repository and reconstructs its current project state.

It collects evidence from documentation, source files, TODO/FIXME markers, architectural decisions, development notes, and Git history. An LLM then analyzes that evidence and produces a structured Project Memory containing:

  • Current state
  • Completed work
  • Open / unfinished work
  • Deferred work
  • Important decisions
  • Contradictions
  • Unknown or uncertain information

Arch then recommends what the developer should work on next.

The important difference is that Arch does not simply ask an AI, "What is happening in this repository?" Every important conclusion remains connected to the evidence that produced it.

For example, a README might claim that a feature is complete while a FIXME, failing test, or newer development note says otherwise. Arch can surface that contradiction instead of blindly trusting one document.

Arch can be used from the command line or through a local web UI. It supports DeepSeek as a hosted model and Ollama for completely local model inference.

It also caches Project Memory. If the repository has not changed, Arch can reopen the previous analysis with zero additional LLM calls.

How we built it

Arch is written in Python and was developed in milestones.

We deliberately built the first layer without AI. The repository scanner deterministically collects evidence and records where every piece came from.

The reconstruction layer then sends bounded groups of evidence to an LLM. Because real repositories can exceed a model's practical context size, Arch analyzes evidence in batches and hierarchically consolidates the partial Project Memories into a final result.

During development we added an evidence-authority system so the model can distinguish between things such as current project documentation, production source code, test fixtures, specification examples, and historical debugging information.

Arch supports two model providers:

  • DeepSeek API for fast hosted analysis
  • Ollama for local/offline analysis, tested with Qwen

The CLI and web UI both use exactly the same underlying orchestration pipeline.

For repeated analysis, Arch creates a fingerprint of the repository evidence and persists Project Memory under .arch/. If the evidence has not changed, the cached memory is reused. If something changes — or the user explicitly requests Refresh/Reanalyze — Arch reconstructs the project again.

For the UI we intentionally kept the technology simple: Flask with plain HTML, CSS, and JavaScript, running locally on the user's computer.

Challenges we ran into

The hardest problem turned out not to be calling an LLM. It was deciding:

What actually counts as evidence about the current state of a software project?

Our early real-world tests exposed several interesting failures.

A TODO written inside a test fixture could be mistaken for genuine unfinished work. An illustrative example inside a specification could become an apparent project fact. Historical debugging documentation describing an old bug could make Arch believe the bug still existed. Temporary backup files could contaminate the reconstruction.

Solving these problems led us to introduce evidence context and authority rather than treating every piece of text equally.

Context size was another challenge. Large repositories cannot simply be inserted into one model prompt, so Arch needed bounded batching and hierarchical consolidation while preserving evidence references throughout the process.

Local inference created a different challenge. Qwen through Ollama worked, but complex consolidation calls could take several minutes on consumer hardware. We added progress reporting and provider-specific timeout handling rather than making a long-running local analysis look like a frozen application.

Finally, real reconstruction can consume many model calls and tokens. That made change detection and caching important: there is no reason to reconstruct an unchanged repository every time a developer opens it.

Accomplishments that we're proud of

The part we are most proud of is that Arch was tested against the exact kind of messy evidence it is supposed to understand, rather than only against clean synthetic inputs.

We created a deliberately messy demo repository containing completed work, genuinely deferred work, an architectural decision, outdated documentation, a FIXME, and a failing test.

Arch correctly reconstructed that:

  • normal project persistence had been implemented,
  • restart persistence was still broken,
  • the README overstated the state of persistence,
  • the storyboard workspace had been deliberately deferred,
  • the deferral was an architectural decision rather than forgotten work,
  • and fixing restart persistence was the appropriate next step.

We also tested Arch against its own repository. It found genuine inconsistencies in our documentation during development — including requirements that had become stale after architectural decisions changed.

Another important accomplishment is that Arch works with both DeepSeek and a completely local Ollama/Qwen setup.

And after an analysis has been completed, reopening an unchanged repository successfully reuses its persisted Project Memory with zero LLM calls.

What we learned

The biggest lesson was that project memory is not the same thing as project documentation.

A README is evidence, but it is not necessarily truth.

The real state of a software project can be distributed across documentation, source code, Git history, tests, TODOs, ADRs, handover notes, and decisions made at different points in time.

That changed the question Arch tries to answer.

Instead of asking:

"What does the documentation say?"

Arch effectively asks:

"Given the available evidence, what is the most defensible picture of this project's current state?"

We also learned that adding an LLM is often the easy part. Making its conclusions traceable, controlling context size, distinguishing historical information from current facts, handling conflicting evidence, and avoiding unnecessary model calls were much harder — and ultimately became some of the most important parts of Arch.

What's next for Arch

The next step is to test Arch against additional real-world repositories of varying sizes, ages, languages, and levels of documentation quality.

That testing will tell us which capabilities should come next rather than adding features based only on assumptions.

One natural direction is deeper IDE integration. A future VS Code extension could let a developer reopen an old repository and immediately see Arch's Project Memory, contradictions, deferred work, and recommended next step directly inside the development environment.

Other future improvements could include better handling of very large individual documents, more efficient consolidation to reduce token usage, richer evidence navigation, and incremental reconstruction so only changed areas of a repository need to be reconsidered.

The long-term idea remains very simple:

Open a project you haven't touched for months and ask: Where was I, what happened here, and what should I do next?

Arch should be able to answer.

Built With

Share this project:

Updates