AI Task Tracking

AI Task Tracking is a local issue tracker for working with AI agents on a Mac. It runs as a menu-bar app with a window of Home, lists, boards and projects, and agents reach it through an MCP server named ai-task-tracking: Claude Code, Codex CLI, Cursor, VS Code, Windsurf, Gemini CLI and Claude Desktop. Agents file issues, plan epics with steps, comment as they work and hand decisions back to you; Home shows what needs you and a live feed of every change, tagged with the repo and branch it came from. Everything is plain Markdown and YAML files in a folder on your Mac (a git repo), optionally backed up to a private GitHub repo.

Requirements

Related MCP server: Ticket MCP Server

Install

curl -fsSL https://raw.githubusercontent.com/altoption/ai-task-tracking/HEAD/install.sh | bash

The installer checks this Mac, shows what it will do and asks once. It installs the latest notarized release into ~/Applications (it checks the download's .sha256, the signature and the notarization first, and builds from source if any check fails or there is no release), links ~/.local/bin/aitt, runs aitt setup and opens the app. The new app is prepared next to the old one and swapped in only when it is complete, so a failed download or build leaves the installed app as it was. From a clone, run ./install.sh.

Options go after bash -s -- when the script is piped, e.g. … | bash -s -- --yes:

Environment: AITT_HOME=<dir> sets the data folder. AITT_APP_DIR=<dir> installs somewhere other than ~/Applications; any folder other than ~/Applications or /Applications is a scratch install: it isn't registered with macOS, writes no app settings, and gets no Claude Code entry, no aitt link and no other agent tools unless --connect names them.

First run

The installer runs aitt setup for you; run it again any time to change something (it is safe to re-run). It walks through:

1. Data folder: default ~/AITaskTracking. An existing folder is kept as it is.

2. First project, e.g. your team's name.

3. Backup to a new private GitHub repo (optional).

4. aitt on your PATH (~/.local/bin/aitt). If ~/.local/bin isn't on your PATH, setup prints the line to add to ~/.zshrc.

5. Claude Code: registers the ai-task-tracking MCP server at user scope (every repo gets it).

6. Other agent tools it finds: see Use with other agent tools.

7. Agent skill in ~/.claude/skills/ai-task-tracking, and optionally one line in ~/.claude/CLAUDE.md.

Every step has a flag (aitt setup --help): --home <dir>, --project <name>, --backup <owner/name> / --no-backup, --no-link, --no-mcp, --no-skill, --connect codex,cursor / --no-connect, --claude-md / --no-claude-md, --binary <path>, --yes. All flags: the CLI reference.

Daily use

• Menu bar. The AI Task Tracking icon: Open AI Task Tracking, New Issue, Quick Capture…, the engine and backup status, Back Up Now, Settings… (⌘,), Help, Launch at Login, Quit. It also lists the issues that need you (Settings can hide them).

• Dock. The app also shows in the Dock and the app switcher (Settings ▸ Show in the Dock, on by default). Clicking the Dock icon with no window open opens the window.

• Shortcuts (system-wide). ⌥⌘I opens the window (or ⌃⌥⌘I, ⌥⌘T); ⌥⌘N opens Quick Capture (or ⌃⌥⌘N, ⌥⇧⌘N). Pick one or turn them off in Settings.

• In the window. Home shows Needs you (issues waiting for your decision or review, and work that has stalled: idle in In Progress for a day, or reopened again and again; tune it under stalled: in config.yml; and work whose linked PR's checks fail), In progress, Ready next, Blocked and a live feed of agent activity. All issues, projects and saved views are in the sidebar, as lists or boards. Keys: c new issue, / or ⌘K search, g h Home, g i all issues, ⌘[ / ⌘] back and forward (also the ← → buttons at the top of the sidebar, beside ⌂ Home), ⌘\ collapses the sidebar to icons and back.

• CI status. Issues that link a GitHub PR show its state and checks (fetched in the background with your gh): a badge on the issue page, a dot on rows, and failing checks in Needs you. Without gh nothing shows.

• Attempts and handoff. The issue page counts the agent sessions that worked on an issue ("3 attempts · 2 tools"); when an agent opens In Progress work, get_issue leads with where the last session stopped.

• Settings (⌘,): launch at login; show in the Dock; show Needs-you issues in the menu; show stalled work in Needs you (the menu-bar number, menu and notifications); show CI status; notify me about agent activity, and for which events: an agent needs you, finishes an issue, or creates one (off by default); the two shortcuts; back up to GitHub before quitting. Every setting and its default: the Settings reference.

• Docs. The app serves these docs at http://127.0.0.1:7477/docs/: Docs in the sidebar, Help in the menus (⌘?), or aitt docs from a terminal.

• Links. Agents print issues as [ATT-1 Title](http://127.0.0.1:7477/#/issue/ATT-1) · aitt://issue/ATT-1. The aitt:// link opens the app; from a terminal, aitt open ATT-1 (or a project slug, or either link) does the same, falling back to the browser when the app isn't installed.

Using with Claude Code

Setup gives Claude Code three things:

• the MCP server ai-task-tracking (tools mcp__ai-task-tracking__save_issue, whats_next, get_tree, …), registered at user scope; claude mcp get ai-task-tracking shows it;

• the ai-task-tracking skill, which teaches the workflow (orient, search before creating, epics with steps, hand back, finish with a comment);

• the rules: the data folder's AGENTS.md, which the MCP server sends as its instructions when a session starts. Edit it to change what every agent is told (labels, projects, conventions).

Restart Claude Code sessions after setup (exit and run claude again): a session only loads MCP servers when it starts. Then ask, for example, "what's next?" or "plan this as an epic with steps". More detail: docs/setup/agent-usage.md.

Use with other agent tools

AI Task Tracking is an MCP server, so any MCP-capable agent tool on the Mac can use it. aitt setup finds the tools you have and offers to connect them; aitt setup --connect codex,cursor does it without questions (tool names: codex, chatgpt, cursor, vscode, windsurf, gemini, claude-desktop). Every tool gets the same server, named ai-task-tracking, running <app>/Contents/Resources/aitt mcp with AITT_HOME set to your data folder.

Setup edits each config file carefully: other servers and settings stay as they are, the file is backed up first (<file>.bak-aitt-<timestamp>), running setup again changes nothing, and an ai-task-tracking entry that isn't this app is left alone. Updating an existing entry of this app's sets only command, args (and type where the tool requires it) and env.AITT_HOME; any other key or env var you added (enabled, cwd, …) stays where it is. Uninstalling removes only what setup added (our whole entry).

ChatGPT desktop runs MCP servers only through its bundled Codex agent (ChatGPT.app/Contents/Resources/codex-cli/…/codex), and its writes are recorded as client codex. Regular ChatGPT chats don't get these tools (ChatGPT says "tools aren't exposed in this session"): switch ChatGPT to Work and use the tracker there, not in a plain chat. That agent reads ~/.codex/config.toml, always that path, because the app doesn't see a shell's $CODEX_HOME. Setup detects the app (/Applications/ChatGPT.app or ~/Library/Application Support/com.openai.chat) and writes that file once, together with Codex when they share it; with $CODEX_HOME set elsewhere, --connect codex,chatgpt writes both files. To add it by hand instead: Settings → Plugins → MCPs → Add, STDIO, with command <app>/Contents/Resources/aitt, args mcp, env AITT_HOME set to your data folder, and optionally a working directory, which sets the default project.

Restart a tool after connecting it. Known limits: only Claude Code is known to show the server's MCP instructions to the model, which is why setup also writes the guidance where a tool has a global instructions file; config files with comments (JSONC) are left alone (add the entry by hand). Details, official docs links, how the repo of each write is worked out, and the other limits: docs/setup/other-agent-tools.md.

Backup

The data folder is a git repo. The app commits every change a couple of seconds after it happens. With a backup repo (setup step 3, or aitt setup --backup <owner/name>), it also pushes five minutes after the last change, on Back Up Now, and before quitting (Settings ▸ Back up to GitHub before quitting). The menu shows the backup status (backed up, changes waiting, or a problem).

To restore on another Mac: clone the backup repo, then install with the clone as the data folder: git clone <backup repo> ~/AITaskTracking, then run the installer with AITT_HOME=~/AITaskTracking.

Bringing issues over from another tool

There is no built-in importer. Instead, your own AI agent moves the issues: export them from the old tool (CSV, JSON, an API, or that tool's MCP server) and ask the agent to bring them over. The Data model and importing guide tells it everything it needs: the folder layout, the issue file format, config.yml, and the safe way to import (save_issues in batches while the app runs, or writing the files directly with the app stopped). Point the agent at that page, or at the repo's AGENTS.md, which links it.

Upgrade

Run the install command again. It quits the app, replaces it and runs setup; your data folder and settings stay. --version <tag> installs a specific release. Restart agent sessions afterwards.

Uninstall

curl -fsSL https://raw.githubusercontent.com/altoption/ai-task-tracking/HEAD/uninstall.sh | bash

Add bash -s -- --yes instead of bash to skip the question; from a clone, ./uninstall.sh [--yes]; or run aitt uninstall [--yes] directly. It quits the app, then removes the app, its login item, and the MCP entries (Claude Code and the other agent tools) and ~/.local/bin/aitt link that run this app. The agent skill and the CLAUDE.md line go too, unless another install of AI Task Tracking stays registered. AITT_APP_DIR=<dir> picks an app installed elsewhere. Your data folder is kept; the output says where it is so you can delete it yourself.

Troubleshooting

Where your data lives

• Data folder (default ~/AITaskTracking): config.yml (port, statuses, which statuses and labels count as Needs you under needsYou:, when work counts as stalled under stalled:, repo → project mapping under workspaces:), labels.yml, AGENTS.md (the rules agents get), projects/<slug>/project.md and projects/<slug>/issues/*.md, views/. Plain text, a git repo; you can read and edit it with any editor, and the app picks up changes. The file format: Data model and importing.

• App: ~/Applications/AI Task Tracking.app; the CLI is ~/.local/bin/aitt, a link into it.

• App settings: defaults read io.github.altoption.ai-task-tracking.

• Agent configs: the files in the table above, plus ~/.claude/skills/ai-task-tracking.

Contributing

See CONTRIBUTING.md and docs/setup/development.md.

License

MIT © 2026 Nick Tulip