Everything you need to run Gitset

01 What is Gitset

Gitset is an open-source toolkit for everything around your code on GitHub: commit messages, issues, pull requests, release notes, READMEs, labels, and repository upkeep. Every tool drafts from your repository's real context, and you refine the draft in plain language until it ships. Nothing is published without your explicit confirmation.

Gitset is BYOAI — bring your own AI key. Anthropic, OpenAI, Gemini, OpenRouter, or any OpenAI-compatible endpoint. There are no subscriptions, no seats, and no token metering: you pay your provider directly, at their price, and Gitset adds nothing on top.

02 Ecosystem

Gitset runs in two places, sharing the same drafting engine and the same templates:

The web app

Sign in with GitHub, connect a repository, and every tool publishes what you approve in one click. Keeps a version history per draft.

The CLI

Runs entirely on your machine. No account, no login. Your code and your key go directly to your AI provider — never to a Gitset server.

A private API handles generation and storage for the web app — the provider abstraction and prompt layer are shared with the CLI's source, so both stay behaviorally identical. The web app and the CLI are open source (MPL-2.0); that internal API is not.

03 Installation

04 Authentication

The web app uses GitHub OAuth — one sign-in, three scopes (user:email, repo, read:org), each used only for what it says. Revoke it anytime from GitHub's own settings.

The CLI has no login at all. There's no account to create and no session to expire — you configure a provider key once (see below) and every command runs locally from there.

05 Configuration

Everything lives locally in ~/.gitset. Start with the interactive setup — it's the same entry point whether you're configuring your first provider or your fifth:

It walks you through picking a provider, pasting a key (masked as you type), and choosing a model — the recommended one is pre-selected. Run it again later to add a provider, change the default, or switch color themes for a light or dark terminal. Prefer flags for scripts or CI?

Templates work the same way on both surfaces: define your commit style, issue structure, PR format, README skeleton, or release-notes layout once, and every draft follows it. On the CLI, gitset init scaffolds editable files in ~/.gitset/templates, and gitset template edit <tool> opens one in your editor. On the web, each tool has a template manager with a curated library you can try without ever overwriting your own saved template.

Label Pack follows the same pattern for GitHub labels: define a reusable set once (locally via gitset labelspack, or on the web from Issue Crafter or PR Maker) and apply it to any repository, replacing GitHub's defaults.

06 CLI commands

Common flags on drafting commands: --provider, --model, --yes, --json, --print. Run gitset help <command> for the full list on any command.

07 Tools

Every tool exists on the web; most exist as a CLI command too (see above). Same drafting logic, same templates, either surface.

08 Knowledge Mapper

Knowledge Mapper builds and maintains docs/gitset-knowledge/ — a structured, always-current map of your codebase (architecture, module boundaries, commands, dependency graph) that both developers and AI coding agents read before touching your code. It's generated from your source code, manifests, and CI configuration — never from your existing prose docs, so it can't inherit their drift.

It runs entirely in the CLI as a six-stage local pipeline (Discover → Map → Summarize → Plan → Write → Validate): the first two stages walk your repository and build an import graph with zero AI calls, only Summarize and Write touch your configured provider, and a deterministic Validate pass checks every generated link, command, and script before anything is written to disk.

On accuracy: Knowledge Mapper has proven reliable in practice, including with fast, cost-efficient models. Its biggest source of inaccuracy usually isn't the AI step — it's the repository's own history. Deprecated files, dead code, and stale references left in a codebase can lead a model to describe an architecture that used to be true. That's expected behavior for any tool that reads real code rather than curated documentation, and it tends to improve as legacy code is cleaned up. For the highest accuracy on a large or long-lived codebase, a higher-capability model will generally separate current architecture from historical leftovers better than a faster, more cost-efficient one.

Full command reference and CI setup: CLI README.

09 Examples

A refinement instruction is just a plain-language sentence — no special syntax:

Scripting or CI can skip the interactive loop entirely:

10 Typical workflow

1. Make changes, stage them, and run gitset commit to draft the message.
2. Push the branch, then gitset pr --create to draft and open the pull request.
3. Reviewers ask for changes on the web app, where you can see version history side by side.
4. Merged and ready to ship? gitset release drafts the notes from the commit range since your last tag.

11 Best practices

• Run gitset init once per machine and adjust the scaffolded templates — the defaults are a reasonable starting point, not a house style.
• Prefer gitset config's wizard over hand-typing keys; it validates the model choice for you.
• Use --print to preview a draft without writing or publishing anything, especially the first few times with a new template.
• Rotate provider keys the same way you'd rotate any API key — gitset config lets you replace one without touching anything else.
• In CI, always pass --yes (or read --json output) — interactive prompts will otherwise hang a non-interactive shell.

12 Troubleshooting

Something else? Check the FAQ, reach out, or read the source — Gitset is open source end to end (except the private API).