ai-context-gen

Generate IMPLEMENTATION_NOTES.md context files for AI coding assistants — Claude Code, Cursor, GitHub Copilot Chat, and ChatGPT.

Inspired by antirez (Redis creator) who used this pattern to build agar (FLUX.2 inference in pure C) with Claude Code — maintaining a context file that helped Claude understand multi-day projects.

Also writing prompts by hand for your AI assistant? → Prompt Starter Pack Premium ($9) — 40 battle-tested templates for code review, debugging, architecture decisions, and AI-agent design.

Why?

AI coding assistants work better when they understand your project's structure, conventions, and architecture. Instead of re-explaining your codebase every session, generate a comprehensive context file that:

• Maps your file structure
• Shows recent git history
• Lists dependencies
• Extracts key function signatures and docstrings
• Includes README and config files

Features

• 🌳 File tree generation with smart filtering
• 🔍 Language detection (Python, Rust, JS/TS, C/C++, Go)
• 📦 Dependency extraction from package files
• 🔧 Code analysis — extracts classes, functions, docstrings
• 📝 Git integration — branch, recent commits, remotes
• 🚫 Smart ignores — node_modules, pycache, build dirs, etc.

Installation

No dependencies required for basic usage! Just Python 3.10+.

# Clone and use directly
git clone https://github.com/joepoznanski/ai-context-gen.git
cd ai-context-gen
python ai_context_gen.py /path/to/your/project

# Or copy the single file to your project
cp ai_context_gen.py /path/to/your/project/

Optional: Install with pip (for development)

pip install click gitpython  # Optional dependencies

Usage

# Analyze current directory
python ai_context_gen.py

# Analyze a specific project
python ai_context_gen.py /path/to/project

# Custom output filename
python ai_context_gen.py -o CONTEXT.md

# Limit file tree depth
python ai_context_gen.py --depth 3

# Include test directories
python ai_context_gen.py --include-tests

# Include larger files (up to 200KB)
python ai_context_gen.py --max-file-size 200

# Print to stdout instead of file
python ai_context_gen.py --stdout

Example Output

Running on this project itself:

$ python ai_context_gen.py
Analyzing C:\Users\joepo\projects\ai-context-gen...
Generated C:\Users\joepo\projects\ai-context-gen\IMPLEMENTATION_NOTES.md
  - 2 files analyzed
  - 892 lines of code
  - Languages: Python

The generated IMPLEMENTATION_NOTES.md will include:

• Project overview (files, lines, languages)
• Git branch and recent commits
• Complete file tree
• Dependencies from package files
• README content
• Code summary with function signatures

CLI Options

usage: ai-context-gen [-h] [-o OUTPUT] [-d DEPTH] [--include-tests]
                      [--max-file-size KB] [--stdout] [-v]
                      [directory]

Generate IMPLEMENTATION_NOTES.md files for AI coding assistants.

positional arguments:
  directory             Project directory to analyze (default: current directory)

options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Output filename (default: IMPLEMENTATION_NOTES.md)
  -d DEPTH, --depth DEPTH
                        Maximum depth for file tree (default: 4)
  --include-tests       Include test directories in analysis
  --max-file-size KB    Maximum file size to include in KB (default: 100)
  --stdout              Print to stdout instead of writing file
  -v, --version         show program's version number and exit

How to Use with AI Assistants

1. Generate the context file:

   python ai_context_gen.py

2. At the start of an AI coding session, reference the file:

   Please read IMPLEMENTATION_NOTES.md to understand this project's structure.
   

3. Regenerate when the project structure changes significantly:

   python ai_context_gen.py  # Overwrites existing file

Keep the handoff focused

For a large repository, start with a shallow, source-only handoff and add test directories only when the assistant needs to inspect test conventions. This keeps the first context file readable and avoids spending the session on generated output.

# A compact first-pass handoff for a large repository
python ai_context_gen.py /path/to/project --depth 2 -o IMPLEMENTATION_NOTES.md

# Add tests when validating a change or investigating a regression
python ai_context_gen.py /path/to/project --depth 3 --include-tests

Regenerate the file after changing architecture, dependencies, or public interfaces; a stale handoff can be more misleading than no handoff at all.

Review a change with a fresh context file

Before asking an assistant to review a non-trivial change, regenerate the context file and give it both the diff and the current handoff. This keeps the review grounded in the repository's conventions instead of only the changed lines.

python ai_context_gen.py /path/to/project --depth 3 -o IMPLEMENTATION_NOTES.md
git -C /path/to/project diff -- path/to/changed-file

Ask the assistant to identify risks, missing tests, and convention mismatches against those two inputs. Regenerate again after a merge rather than carrying a review-era handoff into the next task.

Check a context file before sharing it

IMPLEMENTATION_NOTES.md can include README and configuration content from the repository you analyze. Before attaching it to a hosted assistant, inspect the generated file for credentials, internal URLs, customer data, and other repository-specific material. Keep the generated file local when that review isn't practical.

# Generate locally, then review the handoff before sharing it elsewhere
python ai_context_gen.py /path/to/project -o IMPLEMENTATION_NOTES.md
rg -n -i 'api[_-]?key|secret|password|token|private[_-]?key' IMPLEMENTATION_NOTES.md

This tool does not guarantee secret redaction; the repository owner remains responsible for deciding whether a generated context file is safe to share.

What Gets Ignored

By default, these directories are excluded:

• node_modules, __pycache__, .git, .svn
• venv, .venv, env, .env
• build, dist, target, out
• IDE folders: .idea, .vscode, .vs
• Test directories (unless --include-tests)

And these file patterns:

• Compiled files: *.pyc, *.so, *.dll, *.exe
• Lock files: package-lock.json, yarn.lock
• Generated files: *.min.js, *.map

Supported Languages

Language	File Analysis	Dependency Extraction
Python	✅ Full AST parsing	✅ requirements.txt, pyproject.toml
Rust	✅ Regex extraction	✅ Cargo.toml
JavaScript/TypeScript	✅ Regex extraction	✅ package.json
C/C++	✅ Regex extraction	✅ CMakeLists.txt (detection)
Go	🔜 Planned	✅ go.mod

Contributing

This is a simple, single-file tool. Feel free to fork and modify for your needs.

License

MIT

Acknowledgments

• antirez for the inspiration and proving this pattern works for serious projects
• Claude Code for being a great pair programming partner

---

More free tools by HumanKaylee

• Prompt Starter Pack — 20 free battle-tested prompt templates for code review, debugging, and architecture decisions, plus a 40-template Premium Pack ($9).
• cron-doctor — AI-powered cron expression generator + silent cron-job failure detector.
• developer-context-compressor-kit — turns a repo into a project map, LLM handoff brief, and change-risk packet for AI pair-programming.