Set up the Mac app

Requirements: a Mac with Apple silicon running macOS 13 or later. To track GitHub issues you also need the GitHub CLI. To have an agent report progress you need Codex or Claude Code installed.

1. Install the preview

1. Download the Mac preview and unzip it.
2. Move TrackerTrapper.app to your Applications folder, then open it.
3. Look for the checklist icon in your menu bar. Click it, or press ⌘⇧T, to show or hide the panel.

The app bundle includes its command-line tool, the local MCP server and the tracker skill, so you don't need to build anything from source.

2. Walk through Settings → Setup

Click the gear in the panel header to open Settings, then choose Setup. It is a short checklist:

1. Find Tracker Trapper. Keep the app running while agents work. It has no Dock icon.
2. Check notifications. Allow notifications and send a test. Focus modes and macOS banner settings can still hide what appears.
3. Connect your agent. Pick Codex or Claude Code and choose Install / repair connection and skill. If you'd rather do it yourself, use Copy connection command and run it in Terminal. Then restart or reconnect your agent.
4. Track your work. Copy the tracking command into your agent's conversation.

Check that reporting works

Seeing the MCP executable doesn't prove your agent can reach it. Choose Create reporting test, copy the test instruction into your agent, and wait for the test to show a report. You can also copy the full agent reporting instruction and give it to your agent at the start of a task.

3. Track a local checklist

Local plans need no repository or GitHub account. In your agent's conversation, type:

/tracker on      # Claude Code
$tracker on      # Codex

on creates or resumes a checklist for the current task. off pauses reporting for this conversation without deleting anything, and status shows what's being tracked.

4. Track a GitHub issue

Sign in to the GitHub CLI once with gh auth login. Tracker Trapper uses that login and never stores your GitHub credentials itself. Then paste an issue URL into Settings → GitHub to review and import its checklist.

Only checklist lines with a bold stable ID and an em dash become tasks:

- [ ] **TT-01 — Implement the change.** Check: the requested behavior works.
- [ ] **TT-02 — Verify the result.** Check: relevant checks pass with evidence.

Keep the IDs stable when you edit descriptions. Checked items import as completed. Writing progress back to GitHub is an explicit sync step. Preview it first; a pending-sync count alone doesn't prove GitHub was updated.

5. Using the panel

• Refresh re-reads watched sessions and checks GitHub right away.
• Each card shows the plan's progress, the task in hand, what's next, and which agents are working.
• A card's … menu can delete a list. A copy is saved first, and a GitHub issue is never touched.
• Settings → Notifications lets you choose completion and needs-attention alerts, sounds and celebration popups.
• Settings → General sets the keyboard shortcut and Launch at login. Install the app in Applications first.

Update, back up or uninstall

Update: quit Tracker Trapper, replace the app in Applications with the new download, and open it again. Then restart or reconnect your agents so they load the new MCP helper.

Back up: with the app and agents stopped, copy ~/Library/Application Support/TrackerTrapper. That folder holds all plans, runs and evidence.

Uninstall: quit the app, remove it from Login Items if you added it, disconnect its MCP server from your agents, and delete the app. Your data folder stays unless you remove it. Uninstalling never deletes GitHub issues.

Stuck? See FAQ & troubleshooting. The developer guide on GitHub covers building from source, the CLI and subagents.