Gitoutput

Turn any Git repository or local directory into a prompt-friendly text digest for LLMs — no install required, straight from npx.

Quick start

npx gitoutput /path/to/directory

npx gitoutput https://github.com/AnEntrypoint/gitoutput

That's it — gitoutput writes a chunked digest (summary + mcp-thorns report in chunk 1, directory tree and file contents split across the rest) to <gitprojectname>-1.txt, -2.txt, etc. in the current directory. npx fetches the latest published version each time, so there's nothing to install or keep up to date.

# Print a single digest to stdout instead of writing files
npx gitoutput . --output -
npx gitoutput . --output - | pbcopy

# Point it at a subdirectory or branch
npx gitoutput https://github.com/AnEntrypoint/gitoutput/tree/main/src
npx gitoutput . --branch develop

Requirements

• Node.js 18+ (ships with npx)
• git installed and on your PATH — used as a fallback for private repos, non-GitHub hosts, and anything a plain zip download can't express. Public github.com repos are fetched directly as a zipball instead, with no git subprocess involved.
• For private repositories: a GitHub Personal Access Token (PAT). Generate one here.

Private repositories

npx gitoutput https://github.com/username/private-repo --token github_pat_...

# or via environment variable
export GITHUB_TOKEN=github_pat_...
npx gitoutput https://github.com/username/private-repo

Filtering what's included

By default, everything not matched by .gitignore/.gitingestignore or gitoutput's own built-in ignore list is included — the goal is a digest with exactly what an agent needs to plan changes, nothing more. The built-in list unconditionally excludes:

• All hidden files and directories (anything starting with . — .github/, .eslintrc, .env.example, editor/IDE config, AI-agent tooling state, VCS internals, etc.)
• Build/output directories that mirror or duplicate source (build/, dist/, out/, output/, builds/, artifacts/, generated/, public/, static/, etc.)
• Binaries and compiled artifacts across every major language/platform (executables, object files, ML model weights, 3D/game-engine assets, archives, media, fonts, office documents)
• Lockfiles, caches, and secrets (node_modules, *.lock, *.key/*.pem/credentials.json, etc.)

npx gitoutput . --exclude-pattern "*.test.js"
npx gitoutput . --include-pattern "src/**"
npx gitoutput . --include-gitignored   # also include .gitignore'd files

Output

By default, gitoutput writes chunked files instead of printing to stdout: <gitprojectname>-1.txt, <gitprojectname>-2.txt, etc., each at most 80,000 characters. Chunk 1 contains the summary and an mcp-thorns codebase report; later chunks contain the directory tree and file contents.

npx gitoutput .                       # writes gitoutput-1.txt, gitoutput-2.txt, ...
npx gitoutput . --output digest.txt   # writes digest-1.txt, digest-2.txt, ...
npx gitoutput . --output -            # print a single digest to stdout instead

Image output

--images renders the entire digest (summary, tree, file contents) as dense PNG pages using mdpix's bitmap-atlas renderer — the same rendering engine and per-model geometry as pxpipe — instead of writing .txt chunks. This packs the whole codebase into the minimum number of images for the target vision model.

npx gitoutput . --images                        # writes gitoutput/page-001.png, page-002.png, ...
npx gitoutput . --images --image-profile gpt     # render at GPT's page geometry instead of Claude's
npx gitoutput https://github.com/user/repo --images --output digest

Writes page-NNN.png (dense text pages), factsheet.txt (exact-value strings — hashes, UUIDs, URLs, numeric IDs — pulled out so vision misreads don't corrupt them), and manifest.json (page count, profile, truncation flag, minified flag) into an output directory. --images is incompatible with --output -; PNG bytes have no stdout mode.

The digest is whitespace-minified before rendering by default (collapsed excess blank lines, trimmed trailing/internal whitespace runs — leading indentation and all content are always left untouched, never obfuscated) so more real content fits per page; pass --no-minify to render the raw digest verbatim instead. The gain is real but modest on already-tidy, lint-enforced codebases (low single-digit percent) and larger on codebases with looser whitespace conventions.

Machine-readable output (--json)

Pass --json to print a single JSON object with the written output paths to stdout instead of the human-readable success message — the way a script or one of the skills captures file paths from a subprocess call, without guessing the output naming convention. Works with or without --images:

npx gitoutput . --images --json

{
  "outDir": "/abs/path/to/gitoutput",
  "pageFiles": ["/abs/path/to/gitoutput/page-001.png", "/abs/path/to/gitoutput/page-002.png"],
  "factsheetFile": "/abs/path/to/gitoutput/factsheet.txt",
  "manifestFile": "/abs/path/to/gitoutput/manifest.json",
  "pageCount": 2,
  "truncated": false
}

npx gitoutput . --json

{
  "outDir": "/abs/path/to",
  "chunkFiles": ["/abs/path/to/gitoutput-1.txt", "/abs/path/to/gitoutput-2.txt"],
  "chunkCount": 2
}

All paths are absolute. factsheetFile is null when no exact-value strings were found. On error, {"error": "<message>"} is printed instead and the process exits non-zero. --json has no effect with --output - (stdout mode has no file paths to report).

All options

| Flag | Short | Description | | ------------------------ | ----- | ----------------------------------------------------------------------------| | --max-size <bytes> | -s | Maximum file size to process, in bytes (default: 10 MB) | | --exclude-pattern <p> | -e | Shell-style glob pattern to exclude (repeatable) | | --include-pattern <p> | -i | Shell-style glob pattern to include (repeatable) | | --branch <name> | -b | Branch to clone and ingest | | --include-gitignored | | Include files matched by .gitignore / .gitingestignore | | --exclude-submodules | | Exclude Git submodules (recursively included by default) | | --token <token> | -t | GitHub PAT for private repositories (falls back to GITHUB_TOKEN env var) | | --output <path> | -o | Output file base name for chunked files. Defaults to <gitprojectname>.txt. Pass - for stdout | | --images | | Render the digest as PNG pages instead of .txt chunks (see Image output) | | --image-profile <name> | | Page geometry/font for --images: claude (default), gpt, gemini, grok | | --json | | Print a machine-readable JSON result instead of the success message (see Machine-readable output) | | --no-minify | | Disable whitespace minification of --images pages (on by default) |

npx gitoutput --help

Supported Git hosts

Bare user/repo slugs and scheme-less URLs are resolved against known hosts: github.com, gitlab.com, bitbucket.org, gitea.com, codeberg.org, and gist.github.com. Self-hosted instances are also recognized heuristically when the hostname starts with git., gitlab., or github. (e.g. GitHub Enterprise).

Using it as a library

If you're building a Node.js tool on top of gitoutput rather than shelling out to the CLI:

npm install gitoutput

import { ingestAsync } from "gitoutput";

const [summary, tree, content] = await ingestAsync("https://github.com/AnEntrypoint/gitoutput");

console.log(summary);

A 4th return value carries the written output's absolute paths (unless output: "-", which returns null since stdout mode has no file paths to report):

const [summary, tree, content, imageResult] = await ingestAsync(".", {
  images: true,
  output: "./out",
});

console.log(imageResult); // { outDir, pageFiles, factsheetFile, manifestFile, pageCount, truncated }

const [, , , textResult] = await ingestAsync(".", { output: "./out.txt" });

console.log(textResult); // { outDir, chunkFiles, chunkCount }

Skills

codebase-vision-report

Renders a codebase into dense images via --images, reads every page, and writes a report answering a prompt — install with the skills CLI:

npx skills add AnEntrypoint/gitoutput@codebase-vision-report

Then invoke it inside Claude Code (or another skills-compatible agent) with a target and a prompt, e.g. /codebase-vision-report . :: find security issues. See skills/codebase-vision-report/SKILL.md for the full workflow. Always uses gitoutput's densest defaults (claude profile, minification on) so the codebase packs into as few pages as possible.

codebase-text-report

The non-image counterpart: ingests the codebase as plain-text chunks via gitoutput's default mode instead of rendering pages, reads every chunk, and writes the same prompt-driven report shape.

npx skills add AnEntrypoint/gitoutput@codebase-text-report

/codebase-text-report . :: find security issues. See skills/codebase-text-report/SKILL.md.

Docker

docker build -t gitoutput .
docker run --rm gitoutput https://github.com/AnEntrypoint/gitoutput

Contributing

Issues and pull requests welcome — see CONTRIBUTING.md.

Stack

• commander — CLI framework
• ignore — .gitignore-style pattern matching
• js-tiktoken — token estimation
• mdpix — dense bitmap-atlas PNG rendering for --images