Runesmith is a Python CLI tool for automated, high-quality codebase documentation generation and management using Large Language Models (LLMs) such as OpenAI, Azure OpenAI, Anthropic, Gemini, and Ollama. It supports both interactive and configuration-driven workflows, and is designed for extensibility, reproducibility, and safe, minimal updates to existing documentation.
- Overview
- Key Features
- Installation
- Quickstart
- Usage
- Configuration
- Supported Providers & Models
- Environment Variables
- Internal Workflow
- Architecture & Project Structure
- Dependency Management
- Extensibility
- Planned Enhancements
- Contributing
- License
- Changelog
- Acknowledgements
Runesmith automates the generation and updating of documentation for codebases, including READMEs, API docs, tutorials, quickstarts, and more. It leverages LLMs to summarize, synthesize, and polish documentation, while respecting your codebase’s structure, .gitignore, and existing documentation. Runesmith is also extensible for infrastructure-as-code (IaC) blueprints and prompt management.
- Automatic Documentation: Generate or update documentation for your codebase with a single command.
- Multi-Provider LLM Support: OpenAI, Azure OpenAI, Anthropic, Gemini, and Ollama (local).
- Context Awareness: Honors
.gitignore, blacklists, and existing docs; makes only minimal, safe changes. - Interactive & Config Modes: Use an interactive wizard or a YAML config file.
- Customization: Select doc types, blacklist file extensions, and add custom LLM instructions.
- Token Safety: Warns if your codebase exceeds the LLM’s context window.
- IaC Blueprints: Modular, composable infrastructure blueprints for cloud-agnostic deployments (YAML/JSON).
- Extensibility: Plugin-based architecture for providers and workflows.
- Prompt Management: YAML-based prompt definitions, chaining, and versioning.
- Testing & Validation: Tools for prompt and documentation validation.
pip install runesmith-
Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh -
Clone the Repository and Install Dependencies:
git clone https://github.com/yail259/runesmith.git cd runesmith uv syncThis creates a
.venvand installs all dependencies as specified inpyproject.tomlanduv.lock. -
Activate the Virtual Environment:
source .venv/bin/activate
-
Generate Documentation (Interactive Wizard):
runesmith generate
- You will be guided through provider/model selection, code path, output directory, doc types, and custom instructions.
- Optionally, save your settings to
config.yamlfor future runs.
-
Generate Documentation from Config:
runesmith generate --config config.yaml
-
Interactive Mode:
runesmith generate
-
Config-Driven Mode:
runesmith generate --config config.yaml
provider: OpenAI
model: gpt-4o
code_path: ./src
output_dir: ./docs
blacklist: [".env", ".pyc"]
doc_types:
- Readme
- API documentation
- Quickstart guide
custom_instructions: |
Please focus on developer experience and include usage examples.- Interactive Wizard: Prompts for all options (provider, model, code path, output dir, blacklist, doc types, custom instructions).
- YAML Config: All options can be specified in a YAML file for reproducible runs.
- Environment Variables: API keys and secrets can be set via environment variables or a
.envfile.
- OpenAI: gpt-4o, gpt-4-turbo, gpt-4.5, etc.
- Azure OpenAI: gpt-4o, gpt-4-turbo, etc.
- Anthropic: claude-3.5-haiku, claude-3-opus, etc.
- Gemini: gemini-1.5-pro, gemini-2.5-pro, etc.
- Ollama: Any local model available via Ollama.
Note: Only OpenAI and Ollama are tested by default. For other providers, ensure you have the correct API keys and environment variables set.
Set the following environment variables as needed for your provider (can be placed in a .env file):
- OpenAI:
OPENAI_API_KEY - Azure OpenAI:
AZURE_OPENAI_KEY,AZURE_OPENAI_ENDPOINT,AZURE_OPENAI_API_VERSION - Anthropic:
ANTHROPIC_API_KEY - Gemini:
GEMINI_API_KEY - Ollama: (runs locally, no key needed)
- Crawling: Scans your codebase, respecting
.gitignoreand skipping blacklisted extensions. - Token Counting: Warns if your codebase exceeds the model's context window.
- Per-Chunk Summarization: Each file is summarized via the selected LLM.
- Merging & Smoothing: Summaries are merged and polished into final documentation per doc type.
- Safe Updates: If documentation already exists, Runesmith will only make minimal, safe changes.
- Output: Final documentation is written to the specified output directory.
- CLI: Built with Typer.
- Modular/Plugin Design: Extensible for providers and workflows.
- Declarative IaC: YAML/JSON blueprints for infrastructure.
- Provider SDK/CLI Integration: For cloud operations.
- State/Version Tracking: For blueprints and deployments.
Project Layout:
src/runesmith/
__init__.py
__main__.py
cli.py
crawler.py
llm.py
pyproject.toml
uv.lock
.python-version
.gitignore
README.md
LICENSE
- Lockfile:
uv.lockwith SHA256 hashes for reproducible installs. - Editable Install: For development.
- Key Packages:
ollama,openai,tiktoken,typer,questionary,rich,pydantic,httpx,requests,python-dotenv,pyyaml,pathspec. - Python Version: 3.10 (enforced via
.python-version).
- Custom Providers: Add new LLM providers via plugin interface.
- Hooks: Pre/post-deployment for IaC.
- Blueprints: Authored in
/blueprints(YAML/JSON). - Prompt Management: YAML-based prompt definitions, chaining, and versioning.
- Testing & Validation: Built-in tools for prompt and documentation validation.
- Add generated docs to LLM context for updates.
- Retrieval-Augmented Generation (RAG) for context window issues.
- Standalone binary packaging.
- Multilanguage support.
- Iterative prompting/looping.
Contributions are welcome! Please open issues or pull requests on GitHub. See CONTRIBUTING.md for guidelines.
MIT License © 2025 yail259
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- Initial public release.
- Multi-provider LLM support (OpenAI, Azure OpenAI, Anthropic, Gemini, Ollama).
- Interactive and config-driven documentation generation.
- Context-aware codebase crawling with
.gitignoreand blacklist support. - Per-chunk summarization and final doc synthesis.
- Minimal, safe updates to existing documentation.
- IaC blueprint support (YAML/JSON).
- Plugin-based extensibility for providers and workflows.
- Token counting and context window warnings.
- PyPI package published (
pip install runesmith).
- uv for fast Python dependency management.
- Typer, Rich, Questionary, and all other open-source dependencies.
- Excludes Python bytecode, build/dist artifacts, venvs, env files, batch/config files, web directory, test scripts, and cache files.
- Purpose: Prevents version control of generated, environment-specific, and temporary files to maintain repository cleanliness.
Happy documenting! 🧙♂️
This README was generated and updated by runesmith itself!