madtea

Introducing madtea

Fri, 17 Jul 2026 00:00:00 +0000

Git tooling was designed when the only developer in your terminal was you. Add an AI agent to that terminal, and familiar commands start failing in new ways: git remote -v leaks a token into the agent’s context, a well-meaning issue edit pastes over your bug repro steps, git reset --hard erases uncommitted work.

madtea is a Forgejo/Gitea client built for that shared terminal: one binary, two ways in. A gh-style CLI for you. An MCP server for your agent. Every command is safe to hand to an agent, and every guardrail explains itself to a human.

ActivityPub

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea activitypub actor`

Get instance ActivityPub actor

`madtea activitypub repo`

Get repository ActivityPub actor

`madtea activitypub user`

Get user ActivityPub actor

MCP Tools

`madt_activitypub`

ActivityPub federation endpoints (requires madt_enable(domains=[“activitypub”])): instance, user, and repository actors.

Output schema: declared

One tool, action-dispatched. Set action to one of:

`action="actor"`

Get the instance ActivityPub actor.

`action="repo"`

Get a repository’s ActivityPub actor by numeric repository ID.

Required: repo_id

`action="user"`

Get a user’s ActivityPub actor by numeric user ID.

Admin

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea admin cron list`

List cron tasks

`madtea admin cron run`

Run a cron task

`madtea admin emails list`

List all emails

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)

`madtea admin emails search`

Search emails

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)
`--q`	string		Search query (required)

`madtea admin hooks create`

Create a system hook

API Compatibility

Mon, 01 Jan 0001 00:00:00 +0000

What this answers: “will this madtea feature work against my server?” — madtea features × the Gitea and Forgejo REST APIs — plus the maintainer view: tracking drift between the two platforms. The client-vs-client question (“which CLI covers what”) is a different axis and lives in COMPARISON.md.

madtea targets Gitea API v1 as its single API surface (ADR 0017); Forgejo is supported through the Gitea-compatible API it maintains. Where Forgejo diverges, madtea detects the platform and surfaces the gap as a typed, explained error — see How madtea handles divergence.

Branches & Tags

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea branches-remote create`

Create branch via API

Flag	Type	Default	Description
`--from`	string		Branch or ref to create from

`madtea branches-remote delete`

Delete remote branch

`madtea branches-remote get`

Get branch details

`madtea branches-remote list`

List remote branches

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)

`madtea branches-remote protect`

Get branch protection rules

CI/CD & Actions

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea actions artifacts delete`

Delete an artifact

`madtea actions artifacts download`

Download an artifact zip

Flag	Type	Default	Description
`--output`	string		Output file path (default: stdout)

`madtea actions artifacts get`

Get artifact details

`madtea actions artifacts list`

List repository artifacts

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)

`madtea actions dispatch`

Trigger a workflow dispatch

CLI Comparison

Mon, 01 Jan 0001 00:00:00 +0000

What this answers: which client covers what, for someone — human or agent — picking a forge CLI. It compares madtea against the four relevant clients, feature by feature:

gh — the GitHub CLI, the Microsoft-backed benchmark everyone knows. gh cannot talk to a Forgejo/Gitea server at all; its column reads “gh offers this on its own forge” — the capability bar to clear, not an alternative client. gh is also madtea’s naming yardstick: ADR 0016 makes gh-then-tea vocabulary a recorded, test-enforced rule (internal/parity/), so gh muscle-memory lands on the right verb.
glab — GitLab’s official CLI. Like gh, it cannot talk to a Forgejo/Gitea server; its column reads “glab offers this on its own forge (GitLab)”. GitLab concepts are mapped to their forge equivalents (MR ≈ PR, pipeline ≈ Actions run, group ≈ org).
tea — Gitea’s official CLI. Same backend as madtea.
fj — forgejo-cli, the Forgejo-native community CLI. Same backend as madtea.

Server-side compatibility is a different question. “Will this feature work against my Forgejo/Gitea server?” lives in COMPAT.md, which owns the platform axis. A row below carries at most a terse pointer there.

Commits

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea commits compare`

Compare two refs

`madtea commits diff`

Get commit as unified diff

`madtea commits get`

Get full commit details

`madtea commits list`

List commits

Flag	Type	Default	Description
`--files`	bool	false	Include file change list per commit
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--not`	string		Exclude commits reachable from this ref
`--page`	int	0	Page number for pagination (0 = first page)
`--path`	string		Filter to commits affecting this file path
`--sha`	string		Branch, tag, or commit SHA to start from
`--since`	string		Commits since timestamp (YYYY-MM-DD or RFC3339)
`--stat`	bool	false	Include diff statistics
`--until`	string		Commits until timestamp (YYYY-MM-DD or RFC3339)
`--verification`	bool	false	Include GPG signature verification info

`madtea commits pr-for-commit`

Get PR for a commit

Configuration & first run

Mon, 01 Jan 0001 00:00:00 +0000

How to point madtea at your forge, where it stores credentials, and how the override precedence resolves. This guide assumes the madtea binary is already installed - see install.md if not. For what scopes to enable on the token, see PERMISSIONS.md. For how madtea stores the token and the credential-safety guarantees, see credential-safety.md.

First run

madtea auth login walks you through entering your forge URL and pasting an API token, then stores the token securely in your OS keychain (or pass, or systemd-creds on a headless server, when no keychain is available). Run it once globally and every repo on that forge is covered:

ADR 0015 — One MCP tool per resource noun, action-dispatched

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: legacy tracker 1693 (OperationSpec registry), legacy tracker 1695 (action enum), legacy tracker 1646 (call-time git-repo check)

Context

madtea’s MCP server must expose the full Forgejo/Gitea API surface to an agent. Naively mapped, this is upwards of 200 discrete operations across a dozen resource domains. Two competing pressures shape the design:

An agent’s tool-picker is a search space. Every additional tool the model must discriminate among adds latency and increases mis-selection probability. A 200-tool surface is impractical.
A single opaque “call anything” tool loses discoverability. Without structure, an agent cannot learn what operations are available without reading extensive prose; it cannot self-correct from a bad choice; and the schema cannot carry per-operation constraints.

The existing madt_api_call passthrough tool fills the second role when needed, but it carries no first-class operation semantics — it is the escape hatch, not the primary surface.

Credential Safety

Mon, 01 Jan 0001 00:00:00 +0000

How madtea stores your Forgejo/Gitea token locally and what the “credential-safe git wrappers” claim actually guarantees. For what scopes to enable on the token itself, see PERMISSIONS.md. For how to report a credential-related vulnerability, see SECURITY.md.

Storage backends

By default madtea auth login stores your token in a secure backend — the OS keychain when one is available, otherwise pass, otherwise systemd-creds on a headless server with systemd. The URL and username always go to git config (they are not secret). When no secure backend is available, madtea refuses to store the token with an error naming the fix — plaintext git config is never an automatic fallback; it happens only with the explicit --insecure-storage flag, which also forces the plaintext path when a keychain is present. The backend is not user-selectable beyond that: auto-detection always tries the OS keychain first, then pass, then systemd-creds.

ADR 0013 — Credential storage: secure-backend-preferred, scope-consistent, never on argv

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: legacy tracker 1726, legacy tracker 1753, legacy tracker 1765; legacy tracker 1718 / ADR 0009

Context

madtea authenticates to a forge with a token; where and how it is stored sets the blast radius of a leak. Several incidents shaped the model: plaintext tokens written even under a secure backend (legacy tracker 1726), a token exposed by git config --get-regexp (legacy tracker 1753 / legacy tracker 1718), and a token read from the wrong git-config scope so the wrong ciphertext was decrypted (legacy tracker 1765).

ADR 0011 — linux/macOS/windows are first-class; OS behavior behind build-tag splits

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: legacy tracker 1759, legacy tracker 1731 (Linux-assumption regressions); release/install overhaul epic

Context

madtea ships binaries for linux, macOS, and windows (GoReleaser builds linux_{amd64,arm64}, darwin_{amd64,arm64}, windows_amd64). Yet the code carried Unix-only assumptions that surfaced only as Windows bugs:

internal/safeio fsynced the parent directory after a rename — legal on POSIX, unsupported on Windows (FlushFileBuffers on a directory handle errors), so every credentialed write failed on Windows (legacy tracker 1759).
internal/selfreplace relied on os.Rename overwriting an existing destination — POSIX-atomic, but Windows refuses, and a locked running .old image blocked the self-update (legacy tracker 1731).
madtea install hardcoded /usr/local/bin + sudo cp/chmod — meaningless on Windows.

Each was caught late (by a user on Windows, or by a manual GOOS=windows build during review) because CI only builds and tests on linux (golang:1.26-alpine). The implicit default was “Unix,” and nothing structurally enforced otherwise.

ADR 0024 — Declared-files staging: a commit's file set must be named, never swept

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-10
Tracking: legacy tracker 1981 (records the legacy tracker 1964 / PR legacy tracker 1977 contract as a first-class decision)

Context

madt_commit and madt_finish (and madt_add) once offered a blanket-staging mode — all=true on the MCP surface, -A/--all on the CLI — that ran the equivalent of git add -A before committing: stage every modified, deleted, and untracked path in the worktree, then commit the lot. It sat beside the declared form (files=[...] on MCP, --files on CLI), which stages and commits only the named paths.

Destructive

Mon, 01 Jan 0001 00:00:00 +0000

Model of record: ADR 0029 (strict omission). A madtea surface never carries an operation that can destroy unrecoverable work or data; destruction is offered only when madtea can machine-prove nothing is lost (content-verified prune, force-with-lease push, merged-only branch delete). The irreversible forge-data deletes (repository, issue, release, tag, wiki page) are omitted from both the MCP tools and the CLI: each delete subcommand remains discoverable but refuses, naming the forge web UI. Use the forge web UI (or raw git) for a genuine hard delete.

ADR 0018 — internal/diag is the sole diagnostics emitter

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: legacy tracker 1528 (diagnostics visibility epic), legacy tracker 1549 (migration), legacy tracker 1550, legacy tracker 1548

Context

madtea ships as both a CLI binary and an MCP server (ADR 0014). The two surfaces have different output channels:

CLI: user-facing warnings, notices, and errors go to os.Stderr. ANSI color is appropriate when a TTY is detected.
MCP tool call: there is no stderr the agent can see. Diagnostics must be captured and delivered inside the tool result — a severity-prefixed block that the agent reads as part of the response.

Before legacy tracker 1528, every warning or notice in the codebase was written as a raw fmt.Fprintf(os.Stderr, "Warning: ...") call. This worked on the CLI surface but was invisible on the MCP surface: an agent calling madt_issues that triggered a credential-fallback warning or a pagination-truncation notice would get the main response with no indication anything was unusual, because the warning had gone to the server’s stderr log and not into the tool result.

Editor & MCP client setup

Mon, 01 Jan 0001 00:00:00 +0000

The same madtea binary serves an MCP endpoint over stdio (madtea serve). The consolidated MCP tools (one per resource noun, action-dispatched — issues, prs, repos, branches, releases, actions, …) are identical across every client; only the config file’s location and format differ.

Every client launches the server the same way — running the madtea binary with the single argument serve and talking to it over stdio. The blocks below differ only in how each client spells that out.

Files & Content

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea dir list`

List directory contents

Flag	Type	Default	Description
`--ref`	string		Branch, tag, or SHA

`madtea dir list-root`

List root directory contents

Flag	Type	Default	Description
`--ref`	string		Branch, tag, or SHA

`madtea file batch`

Batch file operations

`madtea file contents`

Get file contents via file-contents endpoint

`madtea file create`

Create a new file

Flag	Type	Description
`--author-email`	string	Custom commit author email
`--author-name`	string	Custom commit author name
`--branch`	string	Branch to create file on
`--committer-email`	string	Custom committer email
`--committer-name`	string	Custom committer name
`--date-author`	string	Custom author date (ISO 8601)
`--date-committer`	string	Custom committer date (ISO 8601)
`--message`	string	Commit message (required)
`--new-branch`	string	Create file on a new branch with this name

`madtea file delete`

Delete a file

ADR 0006 — `finish` always refuses to run from the default branch

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Amended: 2026-07-17 by ADR 0031 — commit joins finish in refusing the default branch (per-call --allow-default-branch override), closing the branch-commit-finish loop at both ends.
Date: 2026-06-24
Tracking: legacy tracker 1621 (formalizes a rule locked on legacy tracker 1601).

Context

madtea finish completes a feature branch: it commits, pushes, opens a PR, merges it, and returns to the default branch. Running it from the default branch is a category error — there is no feature branch to merge, and the only coherent interpretations (open a PR from the default onto itself; push the default with no review) are exactly the unguarded paths finish exists to avoid.

ADR 0019 — Foreign-repo primary checkouts are immutable to madtea

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-03
Tracking: legacy tracker 1912

Context

ADR 0007 (structural fail-closed, multi-repo) introduced dir= targeting: a madtea agent can name any other on-disk git repository as the target of a mutating local-git tool (madt_branch_create, madt_commit, madt_push, …). ADR 0009 (non-overridable guards) established that the agent-facing safety hooks are structurally enforced with no opt-out.

Issue legacy tracker 1862 (cross-repo intent contract) extended dir= to any repository on disk — not just siblings sharing a workspace root — and built the worktree flow as the sanctioned mechanism for agents contributing to a foreign repo:

ADR 0016 — Names match gh/tea verbatim; no invented vocabulary

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: legacy tracker 1225 (batch rename to parity), legacy tracker 1572 (stale CLAUDE.md vs deliberate bareword), legacy tracker 1593 (no-negative-steers), legacy tracker 1604, legacy tracker 1605 (param-name ergonomics)

Context

madtea exposes two surfaces — the Cobra CLI (madtea …) and the MCP server (madt_<noun> tools) — and every operation appears on both. Without a deliberate naming rule, each surface accumulates its own vocabulary as contributors pick names that feel natural or internally consistent. Over time this creates two problems:

Git

Mon, 01 Jan 0001 00:00:00 +0000

Foreign-checkout immutability model (madt_fetch, madt_pull, madt_worktrees): ADR 0019. Credential injection model (GIT_ASKPASS, never token-in-URL): ADR 0013.

CLI Commands

`madtea add`

Stage files for commit

`madtea branch`

Create, list, or delete local branches

Flag	Type	Default	Description
`--base`	string		Start-point ref/sha to branch from (with -b; default: current HEAD)
`--create`	bool	false	Create and checkout a new branch
`--delete`	bool	false	Delete a merged branch (safe; madtea never force-deletes)
`--issue`	int	0	Link branch to Forgejo/Gitea issue number
`--list`	bool	false	List branches

`madtea checkout`

Switch branches

ADR 0030 — git-mirrored CLI commands anchor their argument shape to git's signature

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-17
Tracking: #171

Context

ADR 0016 pins CLI subcommand, flag, and MCP action names to gh then tea verbatim, and docs/contributing/naming-conventions.md records the one refinement it already needs: madtea’s thin wrappers over local git commands (branch, tag, checkout, stash, worktree, …) match git’s vocabulary, not gh/tea’s, because they are git — an agent or human reaching for them arrives with git’s muscle memory.

Names are not the only muscle memory a git-mirrored command inherits. The argument shape — which operands are positionals versus flags, and what a positional means — is just as load-bearing, and ADR 0016 does not speak to it. madtea worktree add diverged here: it took the branch as a positional (add <path> [branch]) and had the service layer silently decide the meaning — an existing branch was checked out, a missing one was created (git worktree add -b). Raw git’s signature is git worktree add <path> [<commit-ish>]: the positional after the path is a commit-ish to check out (an existing ref, never a silent create), and creating a new branch is the explicit -b <branch>. madtea’s worktree add had no -b at all.

Git Objects

Mon, 01 Jan 0001 00:00:00 +0000

MCP Tools

`madt_git_objects`

Low-level git object operations (current repo by default; requires madt_enable(domains=[“git-objects”])): refs, trees, blobs, annotated tags, notes, and diff/patch apply.

Output schema: declared

One tool, action-dispatched. Set action to one of:

`action="apply_diff"`

Apply a diff or patch to the repository, creating a new commit. The target branch must already exist (create one via madt_branches_remote action=create); applying to a protected default branch is rejected.

Required: content

Optional: branch, message, author

ADR 0022 — Hermetic test guard: `go test` cannot resolve real credentials or mutate the real checkout

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-07
Tracking: legacy tracker 2034

Context

A handler test called issuesDevelop without sandboxing. Because serviceissue.Develop operates on the process working directory’s git repo and resolves credentials from the ambient environment, the test — run from the real madtea checkout — resolved real issue legacy tracker 42 through the live forge API, created and checked out a branch, and pushed it to origin. It did this silently, through a full green gate, twice (origin gained issue-42-phase-3-git-commands-migration).

ADR 0020 — Identifier arity is a hard boundary: a singular parameter never becomes a batch

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-07
Tracking: legacy tracker 2029 (PR legacy tracker 2035). Builds on ADR 0005 and the FlexIDs lineage (legacy tracker 881, legacy tracker 884, legacy tracker 1327).

Context

The FlexIDs lineage made identifier value shapes liberal: numbers accepts 441, "441", [441], ["441"], and "441, 442", all normalized to []string. ADR 0005 codified the complementary rule for names: parameter names are strict (gh/tea/API-anchored), with only a bounded did-you-mean. legacy tracker 2029 extended shape liberality across operation arity in one direction: every single-target action accepts a single-element numbers=[N] as equivalent to number=N (resolveOneNumber), because that input’s meaning is unambiguous.

Issues

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea issue all-comments`

List all comments in the repository

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)
`--since`	string		Filter comments updated since this date (YYYY-MM-DD or RFC3339)

`madtea issue attachments`

List attachments on an issue

`madtea issue attachments add`

Upload an attachment to an issue

`madtea issue attachments delete`

Delete an attachment from an issue

Labels

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea labels add`

Add labels to an issue (keeps existing labels)

`madtea labels clone`

Clone labels from a source repository

Flag	Type	Default	Description
`--force`	bool	false	on create: update an existing same-named label; on clone: update existing instead of skipping

`madtea labels create`

Create a label

Flag	Type	Default	Description
`--color`	string	cccccc	hex color, without leading #
`--description`	string		Optional label description — a short note explaining what the label means (e.g. ‘Something is not working’).
`--exclusive`	bool	false	mark exclusive (only one label per group)
`--force`	bool	false	on create: update an existing same-named label; on clone: update existing instead of skipping
`--is-archived`	bool	false	archive the label (hidden from selectors)
`--name`	string		Label name (alternative to positional argument)

`madtea labels delete`

Delete a label

ADR 0027 — Launch scope is the credential boundary; `dir=` is never a token selector

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted (owner ruling 2026-07-15; enforcement tracked in #90, issue-filing carve-out implementation in #59)
Date: 2026-07-15
Tracking: #90
Amended 2026-07-17 (#155): a third enumerated read-only carve-out — the whoami-scoped local-resolution report (see “Carve-out 3” below).
Amended 2026-07-19 (#263): the residual-risk paragraph in Consequences restated honestly - the boundary is host-scoped by credential, not clone-scoped (the on-disk clone is fabricable friction, not authorization).
Amended 2026-07-19 (#264): carve-out 2’s repo-prefix is now enforced structurally client-side - the dir= report client is confined by gitea.WithRepoScope, which refuses any request outside the target repo’s own subtree, not just by convention of which methods the carve-out handlers call.

Context

dir= began as a repo selector for local-git tools (ADR 0007) and was extended to any git repo on disk (legacy tracker 1862), with ADR 0019 clamping foreign primaries to the worktree→finish contribution flow. Separately, ADR 0025 made credential resolution host-keyed and per-checkout: a clone of a Codeberg repo can carry working Codeberg credentials while the session’s launch checkout is authed to a different forge — or to nothing at all.

ADR 0014 — CLI and MCP are thin surfaces over one service layer

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: legacy tracker 1492 (SoC audit), legacy tracker 1493 (client-construction dedup), legacy tracker 1495 (assignee set-merge dedup)

Context

madtea ships two distinct user-facing surfaces: the Cobra CLI (internal/cmd) and the MCP server (internal/mcp). Before the SoC audit (epic legacy tracker 1492), both surfaces contained business logic, API client construction calls, and result-assembly code that was either duplicated or subtly divergent. Concrete examples found in the audit:

MCP Prompts

Mon, 01 Jan 0001 00:00:00 +0000

madtea registers its golden-path workflows as MCP prompts. A client that supports prompts (such as Claude Code) surfaces each one as a slash command — invoke it as /mcp__madtea__<name> followed by the prompt’s arguments.

Prompt	Invocation	Title	Arguments
`file-issue`	`/mcp__madtea__file-issue`	File a well-formed issue	`title` (required): concise issue title; `body` (optional): issue body: context, expected vs actual, repro steps (optional)
`finish-branch`	`/mcp__madtea__finish-branch`	Finish the current branch	`summary` (required): what changed and why (PR body); `closes` (optional): comma-separated issue numbers to close on merge (optional; e.g. 42,57)
`reconcile`	`/mcp__madtea__reconcile`	Reconcile a conflicted pull request	`number` (required): the pull request number to reconcile (e.g. 42)
`release`	`/mcp__madtea__release`	Check release cadence and cut a release	—
`review`	`/mcp__madtea__review`	Review a pull request	`number` (required): the pull request number to review (e.g. 42)
`standup`	`/mcp__madtea__standup`	Recent activity summary	`days` (optional): how many days back to summarize (optional; default 7)
`start-feature`	`/mcp__madtea__start-feature`	Start a feature branch	`name` (required): branch/feature name (e.g. fix-login or issue-42-rate-limit)
`triage`	`/mcp__madtea__triage`	Triage the open backlog	`target` (optional): what to rank: omit for the current repo, or pass owner/repo, or a bare owner to aggregate a whole org

ADR 0001 — The MCP layer is the universal source of truth for agent conventions

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-02
Tracking: legacy tracker 1316 (agent self-sufficiency). This ADR closes the “decide first” sub-issue legacy tracker 1317.
Amended: 2026-07-02 — the Tier taxonomy below is forked by ADR 0008 (legacy tracker 1693); see “ADR 0008 update” at the end of this document for what changed and what didn’t.

Context

madtea ships as both a CLI binary and a Model Context Protocol (MCP) server, and as a Claude Code plugin that bundles skills and PreToolUse hooks around that same binary. The plugin manifest advertises support for “Claude Code, OpenAI Codex CLI, and Google Gemini CLI”, and the README documents install paths for those plus Cursor, Windsurf, Cline, Zed, and “any MCP client”.

Milestones

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea milestone close`

Close one or more milestones

`madtea milestone create`

Create a new milestone

Flag	Type	Default	Description
`--description`	string		Milestone description
`--due`	string		Due date (YYYY-MM-DD)

`madtea milestone delete`

Delete a milestone

`madtea milestone get`

Get milestone details

`madtea milestone list`

List milestones

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)
`--state`	string	open	Filter by state: open, closed, all

`madtea milestone reopen`

Reopen one or more milestones

Miscellaneous

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea render markdown`

Render markdown to HTML

Flag	Type	Default	Description
`--repo`	string		Repository context (owner/repo)

`madtea render markup`

Render markup to HTML

Flag	Type	Default	Description
`--mode`	string	gfm	Markup mode (gfm, comment, wiki)
`--repo`	string		Repository context (owner/repo)

`madtea server-info`

Show detected server platform and version

`madtea settings api`

API settings

`madtea settings attachment`

Attachment settings

`madtea settings repository`

Repository settings

`madtea settings ui`

UI settings

ADR 0009 — Agent-facing guards are non-overridable; no agent-reachable opt-out

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Amended: 2026-07-07 by ADR 0021 — pure-read local-git steering demoted to non-blocking advisory; blocking guards (mutation, credential-exposure, shared-state) are unchanged.
Date: 2026-06-28
Tracking: legacy tracker 1721

Context

madtea’s Claude Code plugin ships four PreToolUse Bash hooks (check-git-{commit,local,cli,remote}.sh). They intercept the agent’s Bash tool and either steer raw git / madtea CLI calls to the credential-safe madt_* tools, or hard-block the raw remote ops that would leak a credential token embedded in a remote URL.

Notifications

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea notifications list`

List notifications

Flag	Type	Default	Description
`--all`	bool	false	Include read notifications
`--before`	string		Only show notifications updated before this time (YYYY-MM-DD or RFC3339)
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)
`--since`	string		Only show notifications updated after this time (YYYY-MM-DD or RFC3339)
`--status-types`	stringSlice	[]	Filter by status: read, unread, pinned
`--subject-type`	stringSlice	[]	Filter by subject: issue, pull, commit, repository

`madtea notifications new`

Get count of unread notifications

ADR 0008 — The OperationSpec registry is the single source of record for all operation help and metadata

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-28
Tracking: legacy tracker 1693

Context

madtea ships as both a CLI binary and an MCP server, and today maintains two independently-authored help corpora:

CLI help — Cobra Short/Long/flag-usage strings, hand-written per command in internal/cmd.
MCP help — ActionSpec.Summary and jsonschema param tags, authored in internal/mcp.

The parity test (internal/parity) keeps names aligned across surfaces but never description text, so the two corpora drift freely. Concrete divergences today: pr merge exposes four boolean flags (--squash, --rebase, --rebase-merge, --ff-only) on the CLI versus a single strategy enum on MCP; the CLI flag --admin appears as force_merge in MCP; issues create is described as “Create a new issue.” on the CLI and “Create an issue.” in MCP. MCP summaries are also deliberately richer — a drift guard mandates that footgun keywords appear inline — but that policy runs against MCP alone and cannot protect the CLI description.

Organizations

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea org activity`

Get organization activity feed

`madtea org avatar delete`

Delete an organization’s avatar

`madtea org avatar upload`

Upload an organization avatar

`madtea org blocks add`

Block a user

`madtea org blocks check`

Check if a user is blocked

`madtea org blocks list`

List blocked users

`madtea org blocks remove`

Unblock a user

`madtea org create`

Create a new organization

Flag	Type	Default	Description
`--description`	string		Organization description
`--full-name`	string		Organization full/display name
`--location`	string		Organization location
`--repo-admin-change-team-access`	bool	false	Allow repo admins to change team access
`--visibility`	string	public	Organization visibility: public, limited, or private
`--website`	string		Organization website URL

`madtea org edit`

Edit organization settings

ADR 0025 — Origin-first forge resolution and host-keyed credentials

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-12
Tracking: epic #30
Amends: 0013 (credential keying), 0007 (extends the structural workspace detection to forge selection)

Context

madtea resolves a repository’s path (owner/name) from its origin remote, but resolves the API server from the single madtea.url config value. The two can disagree, and when they do madtea silently queries the wrong forge.

Observed failure (2026-07-12): a workspace holds clones from two forges — a self-hosted Gitea (the configured madtea.url) and Codeberg. In a clone whose origin is codeberg.org/<org>/<repo>:

Packages

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea packages delete`

Delete a package version

`madtea packages files`

List package files

`madtea packages get`

Get package version details

`madtea packages latest`

Get latest package version

`madtea packages link`

Link package to a repository

`madtea packages list`

List packages for an owner

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)
`--type`	string		Filter by package type (go, npm, container, etc.)

`madtea packages unlink`

Unlink package from repository

ADR 0005 — Parameter-name ergonomics: proactive schema clarity, not reactive matching

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-24
Tracking: legacy tracker 1604, legacy tracker 1605. Builds on legacy tracker 1577 (the bounded did-you-mean) and legacy tracker 1593 (no negative steers).

Context

Agents reach for a “natural” argument name that is not the tool’s canonical parameter, the JSON unmarshaler silently drops it, and a wasted round-trip follows. Recurring, real instances:

madt_finish is keyed by title; an agent passed commit_message (and message) — “the commit message” is the reflex word for a commit subject.
madt_search is keyed by q; an agent passed query.

Each time one of these surfaces, the reflex is to reach for the reactive side — extend the unknown-argument did-you-mean (legacy tracker 1577) with another synonym, a compound/_-token splitter, or a broad alias table — until “no guess ever fails.” That instinct keeps getting re-explored from scratch, and it pulls toward exactly the failure mode we want to avoid: a never-fail matcher that is confidently wrong (user_message → body?, review_id → id). This ADR records the decision so a future “wrong parameter name” bug resolves by reference.

Pull Requests

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea pr body append`

Append content to the end of a pull-request body

Flag	Type	Default	Description
`--file`	string		Read content from file (use - for stdin)

`madtea pr body patch`

Apply anchored (old -> new) replacements to a pull-request body

Flag	Type	Default	Description
`--file`	string		Read replacements JSON from file (use - for stdin)
`--new`	stringArray	[]	Replacement text (repeatable; pairs with –old)
`--old`	stringArray	[]	Anchor text to find (repeatable; pairs with –new)
`--replace-all`	boolSlice	[]	Replace every occurrence for the corresponding –old/–new pair (repeatable, in order)

`madtea pr body section-replace`

Replace the content of a named marked section in a pull-request body

Raw API passthrough

Mon, 01 Jan 0001 00:00:00 +0000

madtea api makes a raw call against the forge’s REST API and prints the response. It is the last-resort escape hatch: prefer a first-class command (issue list, pr create, labels set, …) every time, because those carry the safety, confirmation, and output handling that a raw call does not. Reach for api only when no built-in command covers the endpoint you need — and when that happens, it’s worth filing an issue so the gap gets a real command.

ADR 0021 — Pure-read local-git steering is non-blocking advisory, not a hard deny

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-07
Tracking: legacy tracker 2044, legacy tracker 2047

Context

madtea’s Claude Code plugin ships a local-git steering hook (hooks/scripts/check-git-local.sh) that intercepts the agent’s Bash tool and redirects raw git forms to the madt_* MCP tool that does the same job. Since legacy tracker 1610/legacy tracker 1612 it did this by hard deny — permissionDecision: "deny", no agent-reachable opt-out (ADR 0009).

Over time the hard-deny set grew to cover a large read surface: git status, git branch read/list, git rev-parse HEAD, git log (every read form), git worktree list, git ls-tree, git show <ref>:<path>, git grep <pattern> <ref>, git tag -l, git diff <ref>, git ls-files --deleted, and git sparse-checkout list. The legacy tracker 2044 audit classified every hard-blocked git form and found twelve pure reads blocked purely for MCP-tool steering — they cannot mutate the object DB, refs, working tree, index, config, or stashes, and never contact a remote. Their block carried no mutation, credential, or shared-state rationale; the only reason was economics (steer the agent onto the one-call structured madt_* tool).

ADR 0031 - Recoverable-guard tier: refuse wrong-workflow acts by default, override per call

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-17
Tracking: #222

Context

ADR 0029 pinned the rule for unrecoverable acts: they are omitted from every madtea surface. It deliberately said nothing about a second class this repo keeps meeting: acts that destroy nothing but are almost always workflow wreckage. The motivating incident (2026-07-17): a process with a confused working directory committed a feature snapshot directly onto the local default branch. Nothing was lost - the commit was branched off and the ref reset by the user - but the damage cost real recovery work: a diverged local main, a broken local build, and untangling by hand. Remote branch protection never entered the picture; the commit was never pushed, and protection fires at push time anyway, after work has stacked on the wrong base. Not every repo configures protection at all.

ADR 0010 — A release is a git tag; one blessed cross-platform install

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: legacy tracker 1711 (release-mess report); release/install overhaul epic filed on acceptance

Context

Every release left a trail on the default branch: a docs(changelog): backfill [Unreleased] PR, a chore: prepare release PR, and their merge commits (legacy tracker 1711). Two coupled causes:

The changelog was hand-maintained. CHANGELOG.md’s [Unreleased] section was updated per-PR by hand, so the discipline lapsed and a backfill scramble preceded every cut (and release.sh refuses on an empty [Unreleased]).
release.sh committed to a protected branch. It bumped .claude-plugin/plugin.json, promoted [Unreleased] → [version], and regenerated docs — all commits, so on a branch-protected main they went through their own release PR.

But the commit-to-main step is unnecessary:

ADR 0012 — Release signing and trust-on-first-use update verification

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: legacy tracker 1266 (release signing key); release/install overhaul epic (ADR 0010)

Context

madtea update downloads a release and replaces the running binary. Without integrity verification, a tampered release or a man-in-the-middle on the download runs arbitrary code as the user. madtea depends on no third-party update service and publishes to a self-hosted forge, so the trust model must be self-contained in the binary plus the release artifacts.

Releases

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea release assets edit`

Rename or edit a release asset

Flag	Type	Default	Description
`--name`	string		New name for the asset

`madtea release assets get`

Get a specific release asset

`madtea release assets list`

List assets on a release

`madtea release by-tag`

Get a release by tag name

`madtea release create`

Create a release from a tag

Flag	Type	Default	Description
`--asset`	stringSlice	[]	Files to attach (can be repeated, supports globs)
`--draft`	bool	false	Create as draft release
`--hide-archive-links`	bool	false	Hide auto-generated archive download links
`--notes`	string		Release notes (inline text)
`--notes-file`	string		Read release notes from file (use - for stdin)
`--prerelease`	bool	false	Mark as pre-release
`--target`	string		Target commit or branch for the tag
`--title`	string		Release title (defaults to tag name)

`madtea release delete`

Delete a release (refused — use the forge web UI)

Repository

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea project disable`

Disable projects for the current repository

`madtea project enable`

Enable projects for the current repository

Flag	Type	Default	Description
`--mode`	string		Projects mode: repo, owner, or all

`madtea project status`

Show project settings for the current repository

`madtea repo activity`

Get activity feed

`madtea repo archive`

Download a repository archive

Flag	Type	Default	Description
`--format`	string	tar.gz	Archive format: tar.gz or zip
`--output`	string		Output file path (defaults to -.)

`madtea repo assignees`

List available assignees

Safe body edits

Mon, 01 Jan 0001 00:00:00 +0000

madtea has no command that overwrites an issue body or pull-request body wholesale. Every edit is surgical and anchored: you change a specific span, line, or named region, and the write is rejected if the text you anchored to has drifted or the body changed underneath you. That makes silent clobbering — by an AI agent working from a stale read, or by two writers racing — structurally impossible rather than merely discouraged. (Comments are the one surface Gitea gives no version token: there comment-edit does a full-body replace guarded by an --expected-body check — required on the MCP/agent surface, optional on the CLI. See Comments.)

ADR 0002 — Safe inline body updates: anchored capture-then-update with optimistic-lock write-back

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-03
Tracking: legacy tracker 1349 (RFC / brainstorm). Supersedes and subsumes legacy tracker 1348 (reconcile CLI --body with the MCP body-edit block; add a trample-safe checklist toggle). Unblocks the stale tracking-issue bodies on legacy tracker 1272, legacy tracker 934, legacy tracker 1282.

Context

madtea lets an agent or a human edit issue bodies, pull-request bodies, and comment bodies. The motivating failure is clobbering: an agent regenerates a tracking issue’s body from a stale read and silently discards everything that was there — closed sub-issue checkboxes, hand-written notes, a progress counter. The blunt fix that shipped earlier blocks issue-body edits on the MCP (agent) surface entirely and tells the agent to use a comment instead. That stopped the clobbering, but it also forbade every legitimate inline update (tick a box, fix a typo, append a section, sync a checklist), so tracking-issue bodies rot while the truth lives in comments — exactly the live state on legacy tracker 1272, legacy tracker 934, and legacy tracker 1282.

Safety hooks

Mon, 01 Jan 0001 00:00:00 +0000

Claude Code only. These bash hooks are Claude-Code-specific. They ship with the Claude Code plugin — installing the plugin is the way to get them. Agents on other MCP clients (Codex, Antigravity, Cursor, Zed, …) get the same credential-safe MCP tools but not these hooks — and don’t need them, because the MCP tools never put a token in argv, history, or errors in the first place.

The Claude Code plugin installs seven PreToolUse hooks that intercept tool calls before they run — they don’t change git itself, only what the agent is permitted to run. The plugin is the single delivery channel: a binary-only madtea (Homebrew, Scoop, release tarball) does not materialize these hooks — install the plugin to add them. An MCP-only user who installs neither still keeps the credential-safe MCP tools, which never leak credentials in the first place.

Search

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea search issues`

Search issues across the instance

Flag	Type	Default	Description
`--label`	stringSlice	[]	Label names (comma-separated or repeated)
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--owner`	string		Filter by repository owner
`--page`	int	0	Page number for pagination (0 = first page)
`--state`	string		Filter by state: open, closed, all

`madtea search prs`

Search pull requests across the instance

secret-exec — run a command with your token, never on disk

Mon, 01 Jan 0001 00:00:00 +0000

madtea secret-exec runs a child command with your stored Forgejo/Gitea token injected into its environment. The token is fetched from wherever madtea already keeps it — your OS keychain, pass, the MADTEA_TOKEN environment variable, or git config — and placed into the child process’s environment under the variable name(s) you choose. It is never printed, logged, written to a file, or passed as a command-line argument.

The use case: a deploy script, goreleaser, curl, or some other tool needs the same token madtea uses, but you don’t want to copy it into a shell variable, an .env file, or your shell history to get it there.

ADR 0028 — Semver tiers within 0.x; no launch-gated version freeze

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted (owner ruling 2026-07-17); Amended 2026-07-17 (#244)
Date: 2026-07-17
Tracking:

Amendment (2026-07-17, #244)

Two changes to the original decision:

0.x MINOR tier narrowed to breaking-only. The original text said “breaking or feat bumps MINOR”. The amended rule is: only a breaking change (type!: / BREAKING CHANGE) bumps MINOR within 0.x; feat: and every other releasable type (fix/ux/perf) bump PATCH. Post-1.0 mapping is unchanged. The cadence score weights are NOT affected - a feat still scores 3 pts while releasing as a patch.

Setup

Mon, 01 Jan 0001 00:00:00 +0000

Credential storage model (OS keychain, never token-in-URL): ADR 0013. Install location policy (one blessed binary per OS): ADR 0010. Launch-scope credential boundary (one token per session, no cross-clone shopping): ADR 0027.

CLI Commands

`madtea auth login`

Set up Forgejo/Gitea credentials

Flag	Type	Default	Description
`--force`	bool	false	Skip confirmations (for non-interactive use)
`--insecure-storage`	bool	false	Store the token in plaintext git config instead of a secure backend (OS keychain, pass, or systemd-creds).
`--token`	string		API token
`--url`	string		Forgejo/Gitea server URL
`--web`	bool	false	Open a browser to authenticate

`madtea auth logout`

Clear madtea-stored credentials for a scope

ADR 0023 — Shipped strings are self-contained: no internal references in steering, error, or refusal text

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-10
Tracking: legacy tracker 2130

Context

madtea ships strings to users in three compiled-in forms: hook steering text (the plugin’s PreToolUse scripts), error/refusal returns from the CLI and the madt_* tools, and MCP tool/parameter descriptions. The house habit — natural while the project was internal-only — has been to justify a rule by citing the governance artifact behind it: “ADR 0009”, "the removed all=true, #1964", "see #1862". Those citations resolve only inside the org: they point at ADR files in this repo and issues on an internal forge.

ADR 0003 — Side-effect confirmation is a structural, enforced convention

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-03
Tracking: legacy tracker 1370 (epic). This ADR is sub-issue legacy tracker 1371; the convention is implemented across legacy tracker 1372–legacy tracker 1381.

Context

A command that performs a side-effect must tell the caller what it did — otherwise the caller re-runs work that already happened. The concrete failure that prompted this: madtea finish ends by running git checkout <default> && git pull (returnToDefaultBranch), but its output says only “Returned to <default>” — never that it pulled, or to which commit. A caller can’t tell the pull happened and re-runs madtea pull (an observed redundancy).

ADR 0017 — Target the standard Gitea API v1; surface Forgejo gaps transparently

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-01
Tracking: legacy tracker 1011 (Forgejo actions probe), docs/contributing/forgejo-15-actions-probe.md

Context

madtea is described in the project CLAUDE.md as follows: “Forgejo compatibility: Uses standard API v1 endpoints that Forgejo maintains for Gitea compatibility. Works with both platforms without modification.” In practice, the two platforms are close but not identical. Forgejo is a soft fork of Gitea that maintains compatibility with the Gitea API v1 for the vast majority of endpoints but has not implemented some Actions-family endpoints that Gitea ships (verified empirically in docs/contributing/forgejo-15-actions-probe.md against Forgejo 15).

Stats

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea stats`

Repository or organization statistics

`madtea stats contributors`

Contributor stats for a repository

`madtea stats issues`

Issue analytics for a repository

`madtea stats org`

Get organization statistics

`madtea stats repo`

Get repository statistics

`madtea stats usage`

Local command usage statistics

Flag	Type	Default	Description
`--html`	string		Write a self-contained HTML report to this path and print the path
`--limit`	int	20	Maximum rows to show (0 = all)
`--since`	string		Filter events since date (YYYY-MM-DD) or Go duration (e.g. 720h)

MCP Tools

`madt_stats`

Repository, organization, contributor, and issue statistics.

ADR 0029 - Strict omission: no madtea surface carries a work-destroying override

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-17
Tracking: #206 (epic), #207

Context

madtea’s destructive-operation surfaces grew case by case, and by mid-2026 three different safety models coexisted with no ADR pinning any of them:

Omission - force-delete of a local branch exists on NO madtea surface. The MCP madt_branch_delete tool has no force parameter, and the CLI madtea branch -d refuses -D/--force-delete, redirecting to raw git branch -D in the user’s own shell (internal/cmd/git/branch.go). The plugin hooks then steer agents off raw git. Two independent layers, neither depending on the other behaving.
Machine-proof destruction - madtea prune deletes a ref only after content-verifying it is contained in the default branch, and madtea push --force rides --force-with-lease. Refs die; work provably does not.
Consent-gated presence - madt_worktrees remove force= (#168) and the madt_delete tool (repo/issue/release/tag/wiki page) DO exist on the agent surface, guarded by an elicitation dialog.

Model 3 leaked twice, and both leaks are structural, not incidental:

ADR 0007 — Structural fail-closed for mutating local-git tools in a multi-repo workspace

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-25
Tracking: legacy tracker 1631 (resolves the deferred legacy tracker 1313 no-signal dead-zone).

Context

The legacy tracker 1313 wrong-repo guard (internal/mcp/repoguard.go, commit 352df60) fails closed only when it has a caller-repo signal that differs from the repo the server resolved from its launch-fixed cwd. In our actual deployment that signal effectively never exists, so the block path has — outside tests — never fired:

MADTEA_CALLER_REPO (the env hint) has zero non-test writers. It is read in detectCallerRepoFromEnv but nothing sets it; its block branch was only ever exercised by a synthetic t.Setenv.
The roots path (callerRepoFromRoots) fires only when the client advertises exactly one root that is a git repo differing from the cwd repo. In the common umbrella-workspace setup the single advertised root is the cwd repo, so there is no mismatch; and Codex CLI / Gemini CLI advertise no roots at all, so the roots path can never fire for them.

docs/safety/wrong-repo-protection.md flagged this as a known coverage gap and called fail-closed-on-unknown “a deferred design question, not current behavior.” We were about to recommend MADTEA_CALLER_REPO as the cross-repo protection for roots-less harnesses — a safety path we had never dogfooded. This ADR resolves the deferred question and closes the dogfooding gap.

Take a Seat

Mon, 01 Jan 0001 00:00:00 +0000

Install madtea on Linux, macOS, or Windows - one self-contained binary, one prerequisite: git.

Linux

# amd64 shown; arm64: swap the arch
curl -fsSL https://codeberg.org/sixfold_space/madtea/releases/download/latest/madtea_linux_amd64.tar.gz | tar -xz
./madtea_linux_amd64/madtea install # installs to /usr/local/bin; delete the extracted dir after

macOS

brew tap sixfold_space/tap https://codeberg.org/sixfold_space/homebrew-tap.git && brew install --cask madtea

Windows

scoop bucket add madtea https://codeberg.org/sixfold_space/scoop-bucket && scoop install madtea

Any OS, from source

# needs Go
go install codeberg.org/sixfold_space/madtea/cmd/madtea@latest

Building from a clone instead is covered in Build madtea from source.

ADR 0004 — A positive terminal-closure signal on completed results

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-06-23
Tracking: legacy tracker 1597.

Context

A side-effecting command already confirms what it did (ADR-0003): finish names its merge and pull, a close says “Closed issue #42”. That cured the caller re-running a step the tool had already performed — but it did not cure a second, subtler redundancy: after a result that ends a unit of work, an agent re-verifies the outcome. The concrete failure that prompted this: madt_finish reported a clean merge, and the agent then ran go build to re-confirm the merged tree compiled — work the finish had already validated and landed. The same instinct fires after a release publish (re-fetch the release), an issue close (re-get the issue), a branch delete (re-list branches).

ADR 0026 — Guard texts are terminal or forwarding: no guard cycles, no dead ends

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-07-14
Tracking: #15

Context

madtea steers agents away from raw, credential-unsafe or shared-state-unsafe git through two families of guards: the Claude Code plugin’s PreToolUse hooks (they deny/advise on the Bash tool) and the madt_* tool refusals (they reject an unsafe call and teach the safe one). Each guard was written well on its own. The failure mode is at the seams between them.

A live case study (an agent in a foreign-repo worktree, mid-merge-conflict):

Token Permissions

Mon, 01 Jan 0001 00:00:00 +0000

What scopes to enable on your Forgejo/Gitea personal-access token. For how madtea stores that token and the credential-safety guarantees, see credential-safety.md. For how to report a security issue, see ../SECURITY.md.

What to enable

madtea works against three rough token tiers. Pick the smallest one that covers what you’ll do.

Read-only (browse, list, search):

read:repository
read:issue
read:user

Standard (typical day-to-day: create PRs/issues, merge, comment, mark notifications read):

read:repository + write:repository
read:issue + write:issue
read:notification + write:notification
read:user

Full (org administration, packages, webhooks, branch protection, admin domains):

Troubleshooting Guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers common errors in madtea, their causes, and how to fix them. Error messages are taken directly from the codebase.

1. Configuration Errors

`not configured - run 'madtea auth login' first`

Cause: No Forgejo/Gitea URL or token found in environment variables or git config.

Recovery:

madtea auth login # Interactive setup for this repo
madtea auth login --global # Store credentials globally
# Or set environment variables:
export MADTEA_URL=https://forgejo.example.com
export MADTEA_TOKEN=your-token

`not configured - run 'madtea auth login' or set MADTEA_URL and MADTEA_TOKEN`

Cause: GetConfig() found neither env vars nor git config entries. Same fix as above.

Users

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea gpg-key add`

Add a GPG key

`madtea gpg-key delete`

Delete a GPG key

`madtea gpg-key list`

List GPG keys

`madtea user activity`

Get user activity feed

`madtea user avatar delete`

Delete avatar

`madtea user avatar upload`

Upload avatar image

`madtea user blocks add`

Block a user

`madtea user blocks check`

Check if a user is blocked

`madtea user blocks list`

List blocked users

`madtea user blocks remove`

Unblock a user

Why madtea

Mon, 01 Jan 0001 00:00:00 +0000

Other forge CLIs wrap the API. madtea wraps the workflow — and it is built on the assumption that an AI agent with shell access may be driving it.

This is the punch list: what madtea does that gh, tea, and raw API calls don’t. Every claim below is verified against the source tree; where a comparison against gh or tea is asserted, it is backed by the CLI comparison.

1. It has an issue graph. Nobody else does.

gh and tea have zero dependency commands — this whole category is a capability gap, not an ergonomics win.

Wiki

Mon, 01 Jan 0001 00:00:00 +0000

CLI Commands

`madtea wiki create`

Create wiki page

Flag	Type	Default	Description
`--file`	string		Read content from file (use - for stdin)
`--message`	string		Commit message (required)

`madtea wiki delete`

Delete a wiki page (refused — use the forge web UI)

`madtea wiki get`

Get wiki page content

`madtea wiki list`

List wiki pages

Flag	Type	Default	Description
`--limit`	int	0	Maximum number of items to return (0 = server default)
`--page`	int	0	Page number for pagination (0 = first page)

`madtea wiki revisions`

List wiki page revisions

Workflows

Mon, 01 Jan 0001 00:00:00 +0000

Destruction model for prune (content-verified, never force-delete) and branch delete: ADR 0029.

CLI Commands

`madtea adr check`

Verify ADR numbering, index bijection, and links (exit 1 on drift)

`madtea adr new`

Create the next ADR record and index row (number from origin)

Flag	Type	Default	Description
`--offline`	bool	false	Number from the local tree instead of the origin default branch
`--title`	string		Record title (defaults to a title derived from the slug)
`--tracking`	string		Tracking reference recorded in the header (e.g. an issue or epic)

`madtea finish`

Commit, push, create PR, merge, and return to default branch

Wrong-repo fail-closed guard

Mon, 01 Jan 0001 00:00:00 +0000

A repo-scoped MCP tool called without an explicit owner_repo resolves its target repo from the MCP server process’s working directory — not from any cd the agent did. The server is a single long-lived process whose OS working directory is fixed at launch, and concurrent tool calls share it, so the server cannot follow an agent into a sibling repo. In a multi-repo workspace that fixed cwd may be the wrong repo, which has caused real wrong-repo writes — a finish merged the wrong branch to the wrong repo, and an issue create filed on the wrong repo (hazard legacy tracker 1313). To keep that from happening silently, madtea applies a fail-closed guard before any repo-scoped handler runs.