DEV Community

Teruo Kunihiro
Teruo Kunihiro

Posted on

ai-docs managing AI generated context files

#ai #aiagent #coding #go

Why I Built ai-docs: Managing the Growing Chaos of AI Context Files

When developing alongside AI agents, one of the first headaches that arises is how to manage the flood of context files they generate.

The Problem

Here are a few specific challenges I kept facing:

  • As your AI coding assistant evolves, you naturally want to externalize and back up its memory files.
  • These files are not deterministic and will inevitably differ across local environments and each developer's.
  • Git merges often lead to nasty conflicts.
  • During code review, these files just get in the way.
  • Yet simply ignoring them with .gitignore is risky to disappear. You still want to back them up remotely.

That’s when I realized: maybe these files don't belong in the main branch at all. And that's how ai-docs was born.

GitHub - trknhr/ai-docs

The Spark

The idea hit me during a casual meeting. What if we isolate AI-related files on a separate Git branch and mount them as a worktree? That way, we could keep them versioned and visible, without polluting the main development flow.

Two days and one impulsive coding spree later, I had a working prototype. Like any proper AI-era project, I co-built it with ChatGPT and Claude.

How I Built It

  • I brainstormed the ideal workflow with ChatGPT.
  • When the conversation alone didn’t give me clarity, I prototyped locally using Git worktrees.
  • I summarized everything into a spec file and let Claude Code scaffold the CLI.
  • Then I tested, tweaked, and patched wherever things didn’t behave as expected.

What ai-docs Does

ai-docs is a CLI tool that helps you manage AI assistant context files by separating them into an isolated Git branch.

Key Features:

  • Creates an isolated branch named @ai-docs/{username}, {username} is determined by your name on config file, git user.name or hostname.
  • Mounts this branch locally at .ai-docs/ via Git worktree
  • Moves files like memory-bank/ and CLAUDE.md to this branch
  • Automatically updates .gitignore in main to prevent tracking those files
  • Provides pull and push commands to sync changes

Challenges I Faced

1. Claude Code and the Danger of rm -rf

The initial versions made liberal use of rm -rf, which ended up deleting my .git folder. A brutal reminder that you should never blindly run AI-generated code.

I later restricted file deletions to cases where the --force flag is used, and leaned more heavily on safe git commands.

2. GitHub Actions: Trial and (Mostly) Error

I wanted to set up automatic releases using GoReleaser + GitHub Actions. But it was a frustrating loop of misconfigurations, outdated AI suggestions, and documentation-diving. I learned a lot, but definitely want to improve my speed here next time.

Usage (macOS Recommended) 

brew tap trknhr/homebrew-tap
brew install ai-docs

# First-time setup (may need to run twice to initialize config)
ai-docs init -v

# Push local AI context files to remote
aI-docs push -v

# Pull updates from remote
aI-docs pull -v
Enter fullscreen mode Exit fullscreen mode

Options like --dry-run and --force are supported and useful during testing.

Summary: A Clean Home for Your AI Files

ai-docs helps you:

  • Keep your working branches clean: AI context files live elsewhere
  • Access files easily: via .ai-docs/ worktree
  • Sync with ease: using simple push and pull

It’s still a rough-around-the-edges tool, but it works well enough to use daily.

If you're building with AI and want to keep things organized, give ai-docs a try. Feedback on GitHub or X (Twitter) would be amazing!

GitHub - trknhr/ai-docs

Happy vibe coding!

Top comments (0)