I Built a Tool That Updates Your Docs Every Time You Commit Code

#ai #opensource #productivity #documentation

I recently built Codebase Cortex for the Notion MCP Challenge — an AI pipeline that watches your git commits and updates your Notion docs automatically. Five agents, semantic search, section-level merging. It worked.

But it bothered me that the first thing you needed was a Notion workspace. I wanted automated documentation without any platform dependency — just markdown files in my repo, version-controlled and diffable.

So I rebuilt the whole thing. Version 0.2 is local-first — your docs are plain markdown files in docs/. No cloud accounts, no API keys for a docs platform, no internet connection needed.

What It Does

You commit code. Cortex analyzes the diff, finds related documentation via semantic search, and updates only the sections that changed. Unchanged sections stay byte-for-byte identical.

Git Commit → CodeAnalyzer → SemanticFinder → SectionRouter → DocWriter
→ DocValidator → TOCGenerator → TaskCreator → SprintReporter → docs/

Nine agents. Each one does one thing. The pipeline runs in the background after every commit if you install the git hook.

Show Me

pip install codebase-cortex

cd your-project
cortex init          # Pick your LLM, configure
cortex run --once    # Docs appear in docs/

First run scans the whole codebase. After that, only diffs.

What you get

docs/
├── architecture-overview.md    # Auto-generated, section-level updates
├── api-reference.md            # Tracks your actual code, not last month's code
├── INDEX.md                    # Auto-generated table of contents
└── .cortex-meta.json           # Tracks which sections you edited by hand

Features That Matter

Any LLM. Cortex uses LiteLLM — 100+ providers. Cloud or local:

# Cloud
LLM_MODEL=gemini/gemini-2.5-flash-lite
LLM_MODEL=anthropic/claude-sonnet-4-20250514

# Local (no API key needed)
LLM_MODEL=ollama/llama3
LLM_MODEL=hosted_vllm/my-model

Your edits are protected. Manually edit a section and Cortex will never overwrite it. It tracks section hashes and skips anything you've touched.

Review workflow. New docs get a draft banner. Use cortex accept after reviewing. Or switch to propose mode — changes stage for review before landing.

cortex config set DOC_OUTPUT_MODE propose
cortex run --once     # Stages to .cortex/proposed/
cortex diff           # Review
cortex apply          # Ship it

CI/CD. Run in GitHub Actions or GitLab CI:

# In your CI pipeline
- run: cortex ci --on-pr              # PR impact analysis (JSON output)
- run: cortex ci --on-merge --auto-apply  # Auto-update on merge

Semantic search, not filename matching. When you change auth/login.py, Cortex finds related docs in your API reference, architecture overview, and getting started guide — via FAISS embeddings, not string matching.

Natural language control. For when you want to direct updates yourself:

cortex prompt "Add error handling examples to the API docs"
cortex prompt "Expand the authentication section" -p "Architecture"

The Full Command Set

Command	What it does
`cortex init`	Setup wizard
`cortex run --once [--full]`	Run the pipeline
`cortex accept`	Clear draft banners
`cortex prompt "..."`	Natural language doc updates
`cortex check`	Find stale docs
`cortex diff / apply / discard`	Review workflow
`cortex sync --target notion`	Push to Notion
`cortex ci --on-pr`	CI/CD mode
`cortex embed`	Rebuild search index
`cortex map`	Visualize codebase clusters
`cortex config show`	View/update settings

Want to Contribute?

The repo is open source (MIT), and there are several ways to get involved:

Try it on your project and open an issue with what breaks or what's missing
Add a new pipeline node — the LangGraph architecture makes it straightforward to add agents
Improve chunking — TreeSitter support for more languages
Build a new backend — the DocBackend protocol is pluggable (Confluence? GitHub Wiki?)

The contributing guide has the full setup.