gitmanual

gitmanual

Found it on GitHub? Get it running.

Paste any GitHub repo and get its setup manual: will it work on your device, what you need, and the exact steps for macOS, Windows or Linux.

Website · Self-hosting · Contributing · How it works

The trick

Swap hub for manual in any GitHub link:

github.com/ollama/ollama   →   gitmanual.com/ollama/ollama

That's it. You get a manual for the repo, written from its own files.

Why

Plenty of people find a great project on GitHub and don't know how to run it. READMEs assume you already know which runtime, package manager, database and system it needs. gitmanual reads the repo for you and turns it into a manual a newcomer can follow.

What's in every manual

• Start here: the best way in for your system. The options are a ready-made download, the maintainers' own setup guide (shown inline), the project's website and docs, a setup script, or GitHub Codespaces when the repo ships a dev container.
• Will it work on my device?: a yes, maybe or no for your system and chip, with reasons. It's based on the release files, install commands, Windows/WSL needs, separate devices (phones, TVs), Docker and library setups, and what the README itself says about supported systems.
• Parts list: runtimes and versions, tools, package managers, databases and .env settings.
• Assembly steps: copy-paste commands for macOS (zsh), Windows (PowerShell) or Linux (bash), with fixes for the errors people hit most.
• Setup script: the same steps as one setup.sh or setup.ps1 (/owner/repo/setup/mac.sh, linux.sh, windows.ps1). It stops at the first error, skips what's already installed and is safe to run again. It never starts servers or runs commands that still need your own values; it lists those at the end.
• Install it: the right download for your system and CPU, plus Homebrew, winget, apt, Docker and other commands taken from the README.
• Did you get it running?: per-system votes, so the next person knows what to expect.
• Still stuck?: "Ask Claude" and "Ask ChatGPT" open a chat with the repo, your system and the manual's steps already filled in, using your own account. With an ANTHROPIC_API_KEY, the site writes the guide itself instead (once per repo and system, then cached).

Maintainers: add a badge to your README so newcomers find the steps. Swap in your owner/repo:

[![Setup manual](https://gitmanual.com/ollama/ollama/badge.svg)](https://gitmanual.com/ollama/ollama)

For AI assistants: an MCP server at https://gitmanual.com/mcp, listed in the MCP Registry as io.github.zainudinnoori/gitmanual. Its tools are get_setup_manual and get_setup_script; no login needed.

• Claude Code: claude mcp add --transport http gitmanual https://gitmanual.com/mcp
• Claude (desktop or web): Settings → Connectors → Add custom connector → https://gitmanual.com/mcp
• Cursor (~/.cursor/mcp.json) and other clients: { "mcpServers": { "gitmanual": { "url": "https://gitmanual.com/mcp" } } }

The same facts are available as JSON at /api/v1/manual?repo=owner/repo (&os=, &arch=, &format=md), and /llms.txt describes it all.

Browser extension: a Setup manual button on every GitHub repo, next to Star and Fork. Add it to Chrome (works in Edge and Brave too); the code is in extension/.

Plus the shelf (/shelf): every repo people have looked up, with search and filters for stars, language and difficulty. Every repo also gets a share image and a 1080×1080 poster.

How it works

gitmanual never clones a repo or runs its code.

1. Read. Three GitHub API calls (repo details, file list, latest release), then only the setup files from raw.githubusercontent.com: the README and setup guides, package manifests, version pins, Docker and CI files, and .env examples.
2. Work out. Rules detect the stack (Node, Python, Go, Rust, Ruby, PHP, Java/Kotlin, .NET, Swift, Elixir, Clojure, Flutter, C/C++), versions, package managers, services and settings. README commands are kept only when they install *this* project.
3. Check. Your browser works out your system and chip on your side, and the page compares them with what the repo supports.
4. Write. The maintainers' own ways in come first, then steps for your system.

Analyses are cached for 12 hours, and every manual is server-rendered, so search engines can read the steps. How it works explains the verdicts and the limits in plain words.

Quick start

Requires Node.js 20.9+. Or follow gitmanual's own manual, with steps and a setup script for your system.

git clone https://github.com/zainudinnoori/gitmanual.git

cd gitmanual npm install cp .env.example .env.local # optional: add a GITHUB_TOKEN (recommended) npm run dev

Open http://localhost:3000 and paste a repo. Without any settings it works out of the box: history is kept in a local SQLite file (data/gitmanual.db), and GitHub allows about 20 new repos an hour. A GitHub token raises that to thousands.

Configuration

All settings are environment variables, and every one is optional for local use. See .env.example and the self-hosting guide.

Deploy

The quickest route is Vercel + Turso (both have free tiers): create a Turso database, add the variables above, and deploy. The step-by-step version is in docs/self-hosting.md.

Project structure

app/                    Pages and API routes (Next.js App Router)

[owner]/[repo]/ The manual, its share image and poster shelf/ finds/ how-it-works/ api/ analyze, guide (Claude), vote, finds, cron/facebook lib/ pipeline.ts cache → GitHub → analysis → save github.ts GitHub API and raw file downloads detect.ts Stack, versions, services and per-OS steps install.ts Release downloads and README install commands readme.ts guides.ts README sections, setup guides, scripts, docs links fit.ts platforms.ts "Will it work on my device?" os.ts Per-OS installers and PowerShell rewrites db.ts Turso / SQLite og.tsx Share images and posters facebook.ts picks.ts Optional Finds (Facebook Page sync)

The visual language (an assembly manual: ink outlines, a wrench-orange box, sticker verdicts) is described in DESIGN.md.

Roadmap

These are the known gaps. Help is welcome:

• Apps inside subfolders of big repos (monorepos) are listed but not fully set up.
• System support that a README doesn't mention can't be detected (vLLM on Windows, for example).
• Install guides that live only on a project's website are linked, not turned into steps.

Contributing

Wrong steps for a repo? That's the most useful bug report there is. Open an issue with the repo link, or improve a rule yourself. See CONTRIBUTING.md. Please follow the Code of Conduct, and report security issues privately (SECURITY.md).

License

MIT. The repos gitmanual describes keep their own licenses; it only reads their public files.