Guides
Task-oriented pages for connecting a forge and driving madtea from the CLI or an MCP client.
| Doc | What it covers |
|---|---|
| install.md | Take a Seat: the download channels, what madtea install does, and wiring your agent. |
| setup.md | Connecting a forge: token path, SSH-first path (https/ssh/ssh-only), storage backends, credential precedence. |
| clients.md | Wiring the MCP server into Claude Code, Codex, Antigravity, Cursor, Zed, and other clients. |
| troubleshooting.md | Common errors and how to fix them. |
| secret-exec.md | Run a command with your token injected into its environment — never on disk, in argv, or in history. |
| raw-api.md | Drop to the raw forge API with built-in jq, Go-template, and pagination — the escape hatch for endpoints with no first-class command. |
| tour-finish.md | Ship a branch: commit, push, PR, merge, and back to main in one resumable command. |
| tour-orchestrate.md | Land a whole batch: merge a set of PRs, test the union, find and revert the one that breaks it. |
| tour-worktrees.md | One repo, many hands: per-task isolated worktrees so parallel agents never fight over the same index. |
| tour-issue-rank.md | Ask the backlog: wire issue dependencies, rank keystones and free leaves, track epics. |
Part of the madtea documentation tree.
- Configuration & first run How to point madtea at your forge, where it stores credentials, and how the override precedence resolves.
- Editor & MCP client setup The same madtea binary serves an MCP endpoint over stdio (madtea serve).
- Raw API passthrough madtea api makes a raw call against the forge’s REST API and prints the response.
- secret-exec — run a command with your token, never on disk madtea secret-exec runs a child command with your stored Forgejo/Gitea token injected into its environment.
- Take a Seat Install madtea on Linux, macOS, or Windows - one self-contained binary, one prerequisite: git.
- Tour: ask the backlog with the issue dependency graph Issues depend on other issues - that structure is real, but it usually lives in someone’s head. madtea lets you write it down and then sorts the backlog by what unblocks the most.
- Tour: land a whole batch with orchestrate madtea orchestrate merges a batch of green PRs and then proves the union works. Each PR may have passed CI in isolation; orchestrate tests whether they still pass together.
- Tour: one repo, many hands with worktrees A single checkout serves one pair of hands. Add an agent or several and they fight over the same index, HEAD, and working tree. madtea worktree makes isolated per-task trees the paved road.
- Tour: ship a branch with finish madtea finish covers the whole branch-to-merge cycle in one resumable command. This is the most common workflow: you have a feature branch with committed work and you want it on main.
- Troubleshooting Guide This guide covers common errors in madtea, their causes, and how to fix them. Error messages are taken directly from the codebase.