OnPush

Software documentation generator powered by either Claude Code or GitHub Copilot agents. OnPush autonomously explores your codebase, produces and maintains comprehensive Markdown docs.

How It Works

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.

Installation

Prerequisites

• 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.

Install via npm

npm install -g onpush

Install from source

git clone [email protected]:gnk-softworks/onpush-cli.git
cd onpush-cli
npm install
npm run build
npm link

Quick Start

# Navigate to your project
cd /path/to/your/project

# Initialize
onpush init

# Generate documentation
onpush generate

OnPush creates a .onpush/config.yml in your project and outputs Markdown files to docs/.

Authentication

Anthropic (default)

OnPush resolves Anthropic authentication in this order:

1. --anthropic-api-key flag
2. ANTHROPIC_API_KEY environment variable
3. Claude Code session (if logged in)

GitHub Copilot

When using --provider copilot, authentication is resolved in this order:

1. --github-token flag
2. COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN environment variables
3. GitHub CLI stored credentials

Global Options

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)

Commands

onpush init

Interactive setup wizard. Creates .onpush/config.yml.

• Select AI provider: Anthropic or GitHub Copilot
• Select AI model (provider-specific presets or custom model name)
• 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

onpush generate

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.

onpush types

Interactive TUI for managing document types. Toggle defaults on/off, create custom types, or delete custom types.

onpush status

Show current documentation state, last generation info, and repo change status.

onpush cost

Show historical cost data from past generations.

onpush clean

Remove all generated docs and state. Preserves config.

onpush deinit

Interactive removal of OnPush configuration and/or generated docs.

Document Types

Default Types

| 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 |

Custom Types

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.

Operating Modes

Current Repo

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
    └── ...

Remote Repo(s)

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/.

Configuration

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-opus-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"

CI/CD

GitHub Actions

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.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Fatal error | | 2 | Partial failure (some docs failed) | | 3 | Cost limit exceeded |

Environment Variables

| 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 |

Community

Join the OnPush Discord server to ask questions, share feedback, and connect with other users and contributors.

Feature requests and bug reports

If you have a feature request or have found a bug, please create an issue on the GitHub repository.

Contributions

We welcome any contributions from the community to improve the library. Join our Discord server to discuss contributions or get help.

How to Contribute

1. 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.
2. The "next" branch is the development branch for the project. Please use this branch as the base for your changes.
3. Make your proposed changes.
4. 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.
5. Create a pull request back into the "next" branch.
6. 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.

Code of Conduct

Don't be a jerk. We are all here to learn and improve the project. Please be respectful of others and their contributions.

AI Policy

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.

License

Elastic License 2.0 (ELv2)