Hi everyone, this is my first post on dev.to and I wanted to share a project I've been building.
I built Archie to fix this. One command:
npx archie init
It reads your codebase and git history, uses Gemini to generate a structured ARCHITECTURE.md
, and keeps that doc updated automatically via a git post-commit hook. No manual upkeep required.
The doc captures:
End result is that every developer and every AI tool that opens the project gets the same context the original developer had. The AI stops re-suggesting things you already ruled out.
Context window
I went with Gemini specifically for the huge context window
Incremental updates
Archie builds a dependency graph from static import analysis. When files change, it finds their direct imports and importers (basically their neighbors), and only sends those to Gemini — not the whole codebase. Keeps updates fast and cheap per commit.
State management
.git/archie/state.json
tracks lastProcessedCommit
. The hook grabs ALL commits between the last processed one and HEAD, not just the latest — so it catches changes even if you've made a bunch of commits offline.
Surgical update prompting
There's a Generate mode (first run) and an Update mode (every run after). The update prompt explicitly tells Gemini to only touch the sections affected by the changed files, so anything you've manually written stays untouched.
Significance detection
This is what stops Archie from burning API calls on every tiny commit. It only fires on things like package.json changes, schema/migration files, new directories, or commits touching 5+ files. Smaller commits still move the state pointer forward, just without triggering a regeneration.
It's still early — about 250 npm downloads since launch a few days ago — so I'm still figuring out what's actually useful to people.
npm i archie-ai
I'd genuinely like to hear what you think, whether it's the core premise, the architecture doc format, or any of the technical decisions above. Happy to discuss any of it in the comments.