How Tracker Trapper works
How coding agents report progress to Tracker Trapper on your Mac, and how it reaches GitHub and your iPhone.
Tracker Trapper doesn't watch your screen or guess at progress. Your agent tells it what happened, through a small local connection on your Mac, and Tracker Trapper keeps that record and shows it back to you.
Plans and tasks
A plan is one checklist. It can be a local plan, which needs no repository or account, or a GitHub issue whose checklist you import. Each task has a stable ID (like TT-02) so progress still lines up when the wording changes.
| Status | Meaning |
|---|---|
| Pending | Not started yet. |
| In progress | An agent has started it. |
| Blocked | An agent can't continue and has said why. |
| Completed | Its acceptance check passed, and the agent attached evidence. |
| Skipped | Closed without being done. It counts as closed, never as done. |
A plan can also mark its next task, so you can see what comes after the work in hand.
Runs and agents
Each agent session that works on a plan gets its own run. A run is active, waiting for you, paused, finished, interrupted, or failed. Two agents can work on one plan without taking over each other's run. Subagents are grouped under the run that started them.
Finishing a run never completes its tasks. Tasks are completed one by one, with evidence, when their check passes.
What “Active” means
The menu bar focuses on work in hand. A plan is Active while an agent has a task in progress and has reported within the last 15 minutes. Finished tasks stay visible for a few minutes so you can see what just landed. Nothing is marked done because it went quiet: silence is shown as staleness, never as completion.
How agents report
Tracker Trapper includes a local MCP server that runs on your Mac with no server URL or port. It also includes a command-line tool. Agents use them to start runs and tasks, report activity, mark blockers, and complete tasks with evidence. The tracker skill (/tracker on in Claude Code, $tracker on in Codex) turns tracking on for the current conversation.
Connecting the MCP server makes the tools available. It doesn't make an agent use them automatically, so give your agent the reporting instruction from Settings → Setup.
GitHub checklists
Local progress updates the menu bar immediately. Writing that progress back to a GitHub issue is a separate, explicit sync step that uses your GitHub CLI (gh) login. Local plans never touch GitHub.
The iPhone companion
When you turn on Mobile sync, your Mac publishes a small summary of its Active plans to Tracker Trapper's relay. Your paired iPhone reads from the relay. The phone is read-only: it shows progress, and it never edits tasks or approves agent actions. Plans that finished recently stay for a while so their completion can be announced, and a plan waiting on your answer stays until you reply.
The phone shows three separate facts: when your Mac last shared, when the phone last checked, and whether it's online. If your Mac is asleep, the phone keeps showing the last thing it heard. Set up the companion.