What can I do with GitCafe?#

This page is a map for coding agents and other tools: how to read GitCafe without an account, how to authenticate, and where each workflow is documented. Replace <owner>, <repo> and numbers with real values.

Read public repositories without signing in#

Start at https://git.cafe/<owner>/<repo>/llms.txt. It summarizes the repository and links to its code, history, issues and pull requests as Markdown. Any repository page can be read as Markdown by adding ?format=markdown:

See Read GitCafe as Markdown for the address patterns and limits; follow the links in each document rather than guessing addresses. Documents are bounded summaries, not exports: use git clone for the full repository.

The MCP server at https://git.cafe/mcp also serves public repositories without signing in; see connect an MCP app.

Use GitCafe from a browser agent#

In a browser that supports WebMCP, GitCafe pages offer the MCP server's tools to the browser's agent. They act with the session of whoever is signed in to that tab, with that person's full access, not a narrower grant. Signed out, a page offers only the read tools (repositories, code, issues, pull requests and CI) over public repositories. Signed in, it also offers the tools that create, edit, comment on, review and merge, each marked as consequential so that agents honouring the mark ask you first. A page embedded in another site offers no tools.

Choose how to authenticate#

Each method issues credentials that work only for its own purpose: an MCP token does not work for the REST API, and a REST token does not work for MCP.

MCP, API OAuth and auth.md cover only the repositories approved when connecting; connect again to add one. Grant the least access the task needs.

Work from the terminal#

Install the CLI and sign in:

A person approves the sign-in in a browser. In automation, set CAFE_TOKEN to a personal access token instead, created from the Agent / CLI template: pushing code alone does not allow cafe pr create. Read commands work outside a clone when you name the repository:

Commands that change things, such as cafe issue create or cafe pr merge, need the matching role and token permission. Run them only when the user has asked for that effect. Add --json for structured output.

cafe skills install installs ready-made skills that teach coding agents how to use cafe.

Repositories that also live on GitHub#

Using GitHub is optional, but a repository imported from GitHub keeps syncing with it. With two-way sync, what you write in GitCafe (pushes, merges, comments, reviews, labels) also reaches GitHub, so treat it as visible there. References like #5 are written to GitHub as full GitCafe links; use full URLs to refer to a GitHub issue. See what syncs.

Retry without duplicating work#

Some operations (merges, stack landing, branch deletion, mirror syncs) are accepted first and finish later. If a response is lost, check the operation's state before retrying, and retry with the same request ID: see retry safely. Multi-step commands such as cafe stack submit can stop part-way; read what they report before running them again.

Find the right guide#

• Stacks: stacked pull requests, and preview with cafe stack submit --dry-run.
• CI results: read CI results and logs and cafe ci list.
• GitHub: import and sync from GitHub.
• Anything else: the CLI reference and the REST API.

Discover the services#

Clients that look for services before connecting can read the MCP server's description from /server.json, /mcp/server-card or /.well-known/ai-catalog.json. /.well-known/api-catalog lists the REST API and the MCP server.