I’ve released Folderwise, a free, open-source framework for keeping documentation readable, current and reviewable, with help from AI agents (assistants that can read and edit your files). It works on ordinary folders of Markdown files, with Git tracking every change. Get it on GitHub →
The idea is simple: knowledge should stay readable by people, easy to maintain, and useful long after the conversation that created it.
Why I built it
It’s easy to ask an AI agent a question, solve a problem, and then lose the useful answer in a chat history. It’s just as easy to write a guide and forget whether its instructions still work six months later. [Optional: one sentence about a specific time this bit you, e.g. a recovery you had to redo from scratch.]
I wanted one place for the knowledge I keep coming back to: homelab services, server inventories, recovery procedures, purchase decisions and project notes. Agents can help maintain it, and the result stays something I can read comfortably and review with confidence.
What Folderwise helps you do
- Give every topic a home. Each knowledge folder has its own Git repository, so a topic like “home network” can evolve independently of “server inventory.”
- Give agents useful starting context. Shared templates and project instructions help agents follow the same conventions instead of inventing a new structure every session.
- See what needs another look. Review dates distinguish a recent edit from a recent verification, so a restore procedure you haven’t tested in a year gets flagged. The tools flag documentation that may need checking; they don’t magically verify the facts.
- Keep changes reviewable. Git history, change records, and checks for metadata and links make it easy to see what an agent changed and why.
- Keep growing inventories manageable. CSV-backed records can become readable Markdown tables, so a server list stays structured and still reads like documentation.
- Use the editor you like. Your knowledge stays in plain files you can read and edit without a special application or a hosted knowledge platform.
A visual layer with Obsidian
Obsidian is an optional companion that makes these Markdown files pleasant to explore. Search helps you find a detail quickly, backlinks show which notes refer to the one you’re reading, and graph views reveal how your notes connect.
I’m also trying an Obsidian-plus-iCloud setup for reading on Mac and iPhone. Syncing depends on how you configure Obsidian and your files: Folderwise itself doesn’t currently provide an iCloud sync bridge or automatic Git commits.
Start with one useful topic
You don’t need a huge knowledge base to benefit. Pick something you regularly look up: how to restore a service, what runs on each server, or why you chose a particular setup. Write the answer down once, then give yourself and your agents a consistent way to keep it useful.
Folderwise includes the framework, templates, setup guidance and command-line tooling. Git, Python and uv (a fast Python package manager) are the foundations; using an AI agent or Obsidian is optional.
Get Folderwise for free
The repository has the README, installation steps and the latest improvements. It’s free and open source under the MIT license. Try it with one topic, adapt it to the way you work, and open an issue to tell me what would make it more useful.
