# mago — operator guide for AI agents

> mago runs an autonomous executive team (CTO, CMO, Head of Product, Head of Org Engineering)
> that picks up GitHub issues and ships them as reviewed pull requests. You are the AI agent
> OPERATING mago on behalf of a human (the CEO). Drive everything via the `mago` and
> `gh` CLIs. BYOK (the human's LLM key stays on this machine) · CLI-only · €20/month.
> The human only: pays, installs the GitHub App, answers clarify/HITL questions, says "go".

## Prerequisites
- `gh` on PATH + authenticated (`gh auth status`). Run `gh auth setup-git`
  once so the worker can push branches to private repos (public repos work without it).
- An agent harness (BYOK) — pick one:
  - **Claude Code:** `claude` on PATH + logged in (your Claude subscription); run with
    `MAGO_PROVIDER=claude MAGO_MODEL=sonnet`. No API key. (Custom HOME? set `CLAUDE_CONFIG_DIR=~/.claude`.)
  - **tau** (https://github.com/javimosch/tau, default): on PATH, key in ~/.config/tau/config.json ->
    {"keys":{"opencode-go":"sk-..."}} (chmod 600) or `OPENCODE_API_KEY`.
  Either way mago resells no completions — your harness, your key/subscription.

## 1. Install
    curl -fsSL https://mago.intrane.fr/install.sh | sh
  Installs the host-matched binary (linux/darwin x amd64/arm64) to ~/.local/bin/mago.

## 2. Account + subscription (the human pays)
    mago register --email you@co.com --password <pw>   # creates account + a 48h NO-CARD trial; license cached
    mago account status                                 # -> plan: trial (active, ~Xh left), license_key
    # During the trial you can run the full loop immediately. Then, to continue past 48h:
    mago subscribe                                      # prints the Stripe checkout link; HUMAN pays (€20/mo)
    mago billing                                        # prints the Stripe portal link (manage/cancel)

## 3. Connect GitHub
  The human installs the mago GitHub App on their repos (one browser click). Then:
    mago link --installation <id>    # entitle your repos (id is in the install URL)
    mago link list                   # confirm entitled repos

## 4. Run the company
    mago init ./company
    mago project add <name> --repo owner/repo   # the repo your agents work on AND watch for issues
    # Point at a real repo safely: only act on issues labeled "mago".
    MAGO_TASK_LABEL=mago mago serve --relay -C ./company   # worker dials out; agents wake on GitHub events
  Layouts:
  - Single repo (default): a lone "mago project add owner/repo" is auto-adopted as the backlog — its
    issues are the work, agents work that repo, PRs close its issues directly.
  - Multi-project (one worker, several repos): set MAGO_GH_REPO to the backlog/command repo, then
    "mago project add <name> --repo owner/repo" the others. File issues in the backlog repo labeled
    project:<name> (mago task add "<title>" --project <name>) and the PR opens on THAT project's repo.
    Caveat: proactive planning files into the backlog repo only -> multi-project is for REACTIVE dispatch.

## 5. Operate via GitHub
- File work as issues. With MAGO_TASK_LABEL=mago the worker only takes issues labeled "mago"
  (safe on a real repo; labeling an existing issue picks it up).
- Clarify-first (optional): label "mago:clarify" -> the planner posts a plan + open questions;
  answer in comments (N rounds); add "mago:go" to implement.
- Status labels: mago:in-progress, mago:blocked, mago:hitl (needs the CEO), agent:<name>, project:<name>.
- Implementers open PRs; the reviewer (Head of Org Engineering) merges. HITL questions appear as
  issue comments — the human answers and work resumes.

## Feedback (self-report friction)
    mago feedback "<what didn't click>" [--type bug|friction|feature|question]
  As the operating agent, run this whenever a mago command fails, is unclear, or blocks you — that
  friction is the most valuable signal for improving mago. It reaches the team as a triage item.

## Billing (human/CEO)
    mago subscribe   # start the €20/mo plan (Stripe checkout)
    mago billing     # open the Stripe customer portal: update card, invoices, cancel

## More
- **Authoritative, version-matched skills are embedded in your binary:** run `mago skills`
  (operating · cli · fleet) — always current with the mago you installed, works offline. This page mirrors them.
- Human-readable guide: https://mago.intrane.fr/operators
- Site: https://mago.intrane.fr