Software documentation generator powered by either Claude Code or GitHub Copilot agents. OnPush autonomously explores your codebase, produces and maintains comprehensive Markdown docs.
OnPush is designed to be used in the terminal or as part of a CI pipeline. It uses either the Claude Agent SDK or GitHub Copilot SDK to launch AI agents that autonomously explore your codebase using file reading, code search, git history, and web tools. The tool then produces or updates comprehensive Markdown documentation.
When running locally you can either utilise your Claude or Copilot Subscriptions or use API keys to generate documentation. In CI mode you should use API keys only as anything else is likely against the terms of service for those products.
Use is at own risk and you should ensure you are complying with the terms of service for any products you use with this tool.
- GitHub Copilot CLI or Claude Code - The agent cli you want to use needs to be installed and authenticated.
- node (20+) and npm - OnPush is built with Node.js and distributed via npm.
npm install -g onpush-cligit clone git@github.com:gnk-softworks/onpush-cli.git
cd onpush-cli
npm install
npm run build
npm link# Navigate to your project
cd /path/to/your/project
# Initialize
onpush init
# Generate documentation
onpush generateOnPush creates a .onpush/config.yml in your project and outputs Markdown files to docs/.
OnPush resolves Anthropic authentication in this order:
--anthropic-api-keyflagANTHROPIC_API_KEYenvironment variable- Claude Code session (if logged in)
When using --provider copilot, authentication is resolved in this order:
--github-tokenflagCOPILOT_GITHUB_TOKEN/GH_TOKEN/GITHUB_TOKENenvironment variables- GitHub CLI stored credentials
Options:
--config <path> Path to config file (default: .onpush/config.yml)
--anthropic-api-key <key> Anthropic API key (overrides env var and Claude Code auth)
--github-token <token> GitHub token for Copilot provider (overrides env vars)
--provider <name> AI provider: anthropic or copilot (overrides config)
--quiet Suppress all output except errors
--no-color Disable colored output
--ci Force CI mode (auto-detected via CI=true env var)
Interactive setup wizard. Creates .onpush/config.yml.
- Select mode: Current Repo or Remote Repo(s)
- Configure project name, output directory, document types
- Create custom document types with guided prompts
- Set parallel generation count
Generate or update documentation.
Options:
--full Force full regeneration (ignore incremental)
--type <slug> Generate only a specific document type
--single-file Merge all docs into a single file
--model <model> Override AI model
--parallel <n> Run N generations concurrently (default: from config)
--output <dir> Override output directory
--verbose Show detailed progress
--json Output structured JSON summary
--cost-limit <usd> Abort if cost exceeds threshold
--provider <name> Override AI provider (anthropic or copilot)
--byok-type <type> BYOK provider type: openai, azure, or anthropic (Copilot only)
--byok-base-url <url> BYOK base URL for the LLM API (Copilot only)
--byok-api-key <key> BYOK API key for the LLM provider (Copilot only)
First run performs full generation. Subsequent runs are incremental — the agent analyzes git diffs and only regenerates affected documents.
Interactive TUI for managing document types. Toggle defaults on/off, create custom types, or delete custom types.
Show current documentation state, last generation info, and repo change status.
Show historical cost data from past generations.
Remove all generated docs and state. Preserves config.
Interactive removal of OnPush configuration and/or generated docs.
| Type | Default |
|---|---|
| Product Overview | Enabled |
| Architecture / System Design Document | Enabled |
| API / SDK Reference | Enabled |
| Business Overview | Enabled |
| Security | Enabled |
| Testing | Enabled |
| Data Model | Disabled |
| Deployment and Operations | Disabled |
| Known Issues and Technical Debt | Disabled |
Define custom document types during onpush init or via onpush types. The wizard asks for:
- Name and slug
- Description of what the document covers
- Target audience
- Sections to cover
- Additional guidance for the AI
These are assembled into a structured prompt matching the quality of built-in types.
Documents the repository you're in. Docs are stored alongside your code in docs/ (or on a separate branch).
my-project/
├── src/
├── .onpush/
│ ├── config.yml
│ └── state.json
└── docs/
├── product-overview.md
├── architecture.md
└── ...
Documents one or multiple repositories from a dedicated docs location. Repos can be local paths, Git URLs (any host), or GitHub shorthand.
repositories:
- path: "../api-service"
name: "API Service"
- github: "org/auth-service"
name: "Auth Service"
- url: "https://gitlab.com/org/billing.git"
name: "Billing Service"Remote repos are shallow-cloned and cached in .onpush/cache/.
Config lives at .onpush/config.yml:
version: 1
mode: current
project:
name: "My Project"
description: "REST API for the billing platform"
output:
directory: "docs/"
filename_template: "{slug}.md"
toc: true
generation:
provider: "anthropic" # or "copilot"
model: "claude-sonnet-4-6"
cost_limit: null
timeout: 3600
parallel: 10
# copilot_byok: # Optional, Copilot provider only
# type: "openai"
# base_url: "https://..."
# api_key: "..."
types:
product-overview:
enabled: true
architecture:
enabled: true
prompt: |
Focus on the microservices communication patterns.
# ...
custom_types:
- slug: "testing-guide"
name: "Testing Guide"
description: "Testing strategy and how to write new tests"
prompt: |
Generate a testing strategy document for new developers.
...
exclude:
- "node_modules/**"
- "dist/**"
- ".env*"
- "**/*.key"An example workflow is included at .github/workflows/generate-docs.yml. It installs Node, Claude Code, and OnPush, then runs onpush generate --ci.
To use it in your own repository, copy the workflow file and add ANTHROPIC_API_KEY to your repository secrets.
CI mode is auto-detected via CI=true or --ci flag. Output switches to JSON with plain text progress.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Fatal error |
| 2 | Partial failure (some docs failed) |
| 3 | Cost limit exceeded |
| Variable | Purpose |
|---|---|
ANTHROPIC_API_KEY |
Anthropic API key |
COPILOT_GITHUB_TOKEN |
GitHub token for Copilot provider (highest priority) |
GH_TOKEN |
GitHub token for Copilot provider (fallback) |
GITHUB_TOKEN |
GitHub token for Copilot provider and cloning private repos |
ONPUSH_PROVIDER |
Override AI provider (anthropic or copilot) |
ONPUSH_MODEL |
Override default model |
ONPUSH_OUTPUT_DIR |
Override output directory |
ONPUSH_COST_LIMIT |
Set cost limit (USD) |
ONPUSH_BYOK_TYPE |
BYOK provider type: openai, azure, or anthropic (Copilot only) |
ONPUSH_BYOK_BASE_URL |
BYOK API base URL (Copilot only) |
ONPUSH_BYOK_API_KEY |
BYOK API key (Copilot only) |
CI |
Auto-enables CI mode |
If you have a feature request or have found a bug, please create an issue on the GitHub repository.
We welcome any contributions from the community to improve the library.
- Find an issue in the issues tab you want to work on or create an issue with a description of the problem or feature you would like to add.
- The "next" branch is the development branch for the project. Please use this branch as the base for your changes.
- Make your proposed changes.
- Ensure change is tested. We would like to maintain a high standard of code quality and reliability, so please include tests for any new features or bug fixes you add.
- Create a pull request back into the "next" branch.
- A Maintainer will review your changes and merge them into the "next" branch if approved.
- Bug Fixes: We will endeavour to approve, merge and release any bug fixes quickly.
- Features: Before any new feature is merged it must be approved by maintainers in GitHub Issues. We will review and approve features based on their complexity and alignment with the project goals.
Don't be a jerk. We are all here to learn and improve the project. Please be respectful of others and their contributions.
We welcome contributions that are assisted by AI tools, but please ensure that all code is reviewed and tested by a human before submitting a pull request.