Inspiration

I work with AI coding agents daily, and I kept running into the same frustrating problem: every time I made a significant change to my codebase — adding a new module, refactoring a class, deleting a deprecated function — the markdown files my agents depended on became stale. CLAUDE.md would still reference functions that no longer existed. STRUCTURE.md would be missing entire new modules. The agents would hallucinate based on outdated context, and I'd have to manually hunt down and fix every reference. Documentation debt isn't just annoying — in an AI-driven workflow, it actively makes your coding assistant worse. I built DocJanitor to make this a problem that solves itself.

What it does

DocJanitor is a VS Code extension that watches your filesystem in real-time and keeps your agent context documents perfectly in sync with your code. When you save a file, the Janitor detects what changed, classifies the impact (Minor vs. Major), and uses a CLōD-powered AI model to surgically update your STRUCTURE.md — patching only the relevant section rather than regenerating the whole document. It also maintains agentic interoperability: when it creates or updates a STRUCTURE.md for the first time, it injects a grounding directive into whichever agent rule file you use — CLAUDE.md, GEMINI.md, CURSOR.md, or CODEX.md — so your AI assistant always knows where to find the source of truth. Deletions and function removals are handled too: if you delete a file or remove a function, its entry disappears from the documentation automatically.

How we built it

The system runs as two tightly coupled components. The backend is a Python agent built on watchdog for cross-platform filesystem monitoring. When a file event fires, it uses tree-sitter-style AST heuristics to extract functions and classes, then routes to the CLōD API to select between a fast model (Qwen 2.5-7B) for minor changes and a more powerful model (Qwen 2.5-72B) for architectural shifts. The AI is given the current STRUCTURE.md as context and returns a full surgical patch. The frontend is a VS Code extension written in TypeScript that spawns the Python agent as a child process, communicates over a line-buffered newline-delimited JSON (NDJSON) IPC bridge, and renders live updates in a premium sidebar with a pulsing "Processing" animation.

Challenges we ran into

The trickiest challenge was Python environment portability. The extension needs to spawn a Python process, but every developer's machine is different — some use Miniconda, some use system Python, some use virtual environments. We couldn't hardcode a path, and dynamic detection risked picking up the wrong interpreter (a system Python 3.11 without the required packages). We solved this by migrating to VS Code Workspace Settings, letting each developer specify their own janitor.pythonPath locally without that configuration ever entering the shared codebase. We also hit a gnarly Windows encoding crash: the AI would occasionally generate emojis in its output, and the Windows GBK console codec would raise a UnicodeEncodeError mid-thread, silently killing the watcher. We fixed this by wrapping all console output in a safe_print helper that enforces UTF-8 encoding throughout.

Accomplishments that we're proud of

We shipped a fully working VS Code extension with a real-time documentation agent, AI-powered surgical patching, and cross-agent interoperability — all in a single hackathon session. The complete lifecycle works end-to-end: create a file, watch it appear in STRUCTURE.md; delete a function, watch it disappear from the exports list; delete a file, watch its entire section vanish. The "Agentic Interoperability" feature — where DocJanitor automatically grounds other AI assistants by linking them to the maintained documentation — is something we haven't seen done before.

What we learned

Building for AI agent workflows requires thinking about documentation as a first-class runtime artifact, not an afterthought. We also learned that portability is harder than functionality — getting the agent to run correctly on a single machine took an hour; making it run reliably on any machine required careful thought about environment isolation, encoding, path resolution, and graceful fallbacks. Lastly, the IPC boundary between TypeScript and Python is surprisingly fragile: even a single malformed JSON line can break the entire update pipeline, which pushed us toward a robust line-buffered parser with strict error isolation.

What's next for DocJanitor

The next major feature is Managed Context Blocks — instead of only maintaining STRUCTURE.md, DocJanitor will own a fenced <!-- JANITOR:START -->...<!-- JANITOR:END --> block inside CLAUDE.md and similar files, keeping a live, condensed module inventory that AI assistants can reference directly. Beyond that, we want to add Staleness Detection — surfacing warnings in the VS Code sidebar when an agent rule file references a function or module that no longer exists in the codebase. The longer-term vision is AI-Assisted Rule Suggestions: when a major structural change happens, DocJanitor proposes additions to your agent rule files as a diff you can accept or reject — making documentation not just automatic, but genuinely intelligent.

Built With

• clod
• javascript
• python