READMEdevelop

🔭 TodoScope

Every codebase has a to-do list. Most of them are a mess. TodoScope is about the gap between what teams say they'll fix and what actually gets done — and what that gap reveals about how software really gets built.

Give your AI assistant a live view of every TODO across all your repos.

Connect Sage.is, Claude.ai, or any assistant that can call an HTTP API, and ask: "What's still TODO in this project?" TodoScope answers instantly. It also gives your team a clean web UI to browse, track, and stay on top of inline TODOs and TODO.md files — without leaving the codebase.

The code is open. The project evolves. Get involved.

The TodoScope board — TODO.md sections and inline TODO/FIXME/BUG comments as one kanban board

Every TODO.md section and every inline TODO / FIXME / BUG comment across your repos, on one board. Edit a file in your editor and the cards morph in — no reload.

The TodoScope dashboard — add a repo by URL or local path, see when each was last scanned

AI & Agent Integration

TodoScope implements the Model Context Protocol, making it a first-class tool for AI assistants.

Sage.is AI and Claude.ai can call TodoScope directly — ask your assistant to list, summarize, or prioritize TODOs across any repo it has access to.
Clients discover TodoScope through its manifest and its OpenAPI spec — plain HTTP, no SDK.
The OpenAPI spec is generated dynamically — the docs always match the live API.

Endpoint	Purpose
`GET /api/mcpo/manifest`	Service discovery manifest
`GET /api/mcpo/openapi.json`	Live OpenAPI 3.0 spec
`POST /api/mcpo/scan_repository`	Scan a repo, return all TODOs as JSON

The todo-scope Skill

TodoScope reads a simple TODO.md convention: sections map to kanban columns, bold checkbox items become cards, indented checkboxes become each card's checklist. The todo-scope Claude Code skill gets any repo's TODO.md into that shape — it bootstraps a missing TODO.md, restructures a messy one, groups stray one-liners into proper cards, and sets up .todoscope-exclude.csv.

The skill ships in this repo at .claude/skills/todo-scope/SKILL.md and loads automatically for Claude Code sessions here. To use it in your own repos, install it globally:

mkdir -p ~/.claude/skills/todo-scope
curl -o ~/.claude/skills/todo-scope/SKILL.md \
  https://raw.githubusercontent.com/Startr/TodoScope/master/.claude/skills/todo-scope/SKILL.md

Then run /todo-scope in any project.

What It Does

TODOs pile up. They hide in comments, sit in TODO.md files, and get forgotten across repos. TodoScope finds them all:

AI-ready API: plain HTTP with an OpenAPI spec — Sage.is, Claude, and other assistants query it directly.
Streaming scan: See TODOs appear in real time as files are scanned.
TODO.md support: Detects and renders standalone TODO files alongside inline code comments.
Live refresh: Watches local repos for changes and updates the view without a full rescan.
Local repo management: Register local paths — paths stay on the server, never exposed to the browser.
.gitignore aware: Skips files and directories your project ignores.

How It Works

Provide a Git URL or register a local repo path.
TodoScope clones (or reads) the repository.
It scans all text files for TODO patterns and finds standalone TODO.md files.
Results stream to the web UI and are available via the API.

Installation

macOS app via Homebrew (recommended)

brew install --cask sage-is/apps/todoscope

A native desktop app: real window, Dock icon, menu-bar icon with Open and Quit. Releases are unsigned until our Apple Developer ID lands; the cask removes the quarantine bit at install so the app opens on first double-click. Data lives in ~/.todoscope/.

macOS .app via DMG

Download TodoScope-<version>.dmg from Releases, drag to Applications. The DMG is unsigned for now — macOS will refuse to open it until you clear quarantine: xattr -dr com.apple.quarantine /Applications/TodoScope.app. Prefer the Homebrew cask, which does this for you.

Standalone binary (no Python required)

Download from GitHub Releases and run:

./todoscope

Opens your browser to http://localhost:5000. Data stored in ~/.todoscope/.

Local development

Requires Python 3.11+ and Git.

git clone https://github.com/Startr/TodoScope.git GIT-TodoScope
cd GIT-TodoScope
pip install pipenv
cd scanner && pipenv install
cd ..
make it_run_dev

Open http://localhost:5000. The security warning on the page walks you through setting your first access key.

Docker

git clone https://github.com/Startr/TodoScope.git GIT-TodoScope
cd GIT-TodoScope
make it_build
make it_run SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")

Cloned repositories and your access_keys.csv are mounted from the host, so they survive container restarts.

CapRover

Deploy from the CapRover dashboard using the included caprover-one-click.yml, or add this repo as a custom one-click source. Set the SECRET_KEY variable during setup. After deployment, visit the app URL and set your first access key via the security panel.

Cloudflare Quick Tunnel

To share a local instance publicly for demos:

make run_tunnel

API Endpoints

The scanner provides a RESTful API. Key endpoints include:

Scan Repository:

curl -X POST http://localhost:5000/api/mcpo/scan_repository \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/username/repository.git"}'

List Local Repositories:

curl -X GET http://localhost:5000/api/mcpo/list_repositories

Pull Repository Updates:

curl -X POST http://localhost:5000/api/mcpo/pull_repository \
  -H "Content-Type: application/json" \
  -d '{"repo_name": "repository_name_from_list"}'

Example API Output (Scan Repository)

{
  "repo_url": "https://github.com/username/repository.git",
  "repo_name": "repository",
  "todo_count": 42,
  "todos": [
    {
      "file_path": "src/main.py",
      "line_num": 24,
      "todo_text": "# TODO: Fix this hack when we have time",
      "next_line": "def temporary_solution():"
    }
    // ... more TODOs
  ],
  "web_url": "http://localhost:5000/scan/https://github.com/username/repository.git"
}

Project TODOs

This project, while dedicated to finding TODOs, has its own list of desired enhancements and features. Contributions are welcome!

In Progress

TODO

Brand & Landing Page — Scope E (First-Run & Onboarding)

First-run onboarding: wizard, demo repo, try-it-live

todo-scope Skill — Publish & Promote

Publish the todo-scope skill: ship with the repo, package, document install
Promote the skill: in-app nudges and outreach

Features

Explore scan results: search, README context, metrics, exports

Tech Debt

Refactor stream_results.html JS: superseded — the hand-built DOM builders are deleted; the server renders partials and the client morphs them (see Phase 2 live board).

Backlog

MCPO: settle the MCP story (rename shipped)
Share-on-Network firewall test: verify the desktop app's tray share toggle across the macOS application firewall — accept the incoming-connections prompt, reach the LAN URL from a second device, sign in with an access key. Local curl-to-own-LAN-IP is filtered on the dev Mac, so this needs a real second device.
Inline TODO completion tracking: Snapshot-and-diff approach to detect when inline TODOs are removed between scans and show them as completed in the Done column. Uses .todoscope-snapshot.json and .todoscope-done.json. Git-history-independent — works on shallow clones.
TODO editor — remaining scope: add-TODO form, edit card text, and drag-between-columns write-back. Checkbox toggling shipped (see Phase 2 live board).
Publish CapRover one-click app source: Add caprover-one-click.yml to the Sage-is one-click repo
Scanner extensibility: smarter parsing, plugins, external integrations
Ralph-loop agent mode: agent loop with TODO.md as the state file

Release Pipeline — Repo Rename

Rename GitHub repo: Startr/WEB-MCPO-Repo_scanner → Startr/TodoScope
Update Docker image: ghcr.io/startr/todoscope
Update all internal references: pyproject.toml, scripts, templates, docs, README, CapRover
Convention: clone to GIT-TodoScope/ locally for dev clarity
Verified: 45 tests passing, all links updated

Release Pipeline — Docker CLI Wrapper + Dev Mode

Create scripts/todoscope: bash CLI wrapper (11 commands, dev mode, tunnels)
Dev mode: smart repo discovery, source mounting, hot reload
Tunnel commands: todoscope tunnel + todoscope tailscale
Verify end-to-end: scripts/todoscope start → open → dev → tunnel (needs Docker image built)

Release Pipeline — PyInstaller Binary Build (macOS + Linux + Windows)

Create todoscope.spec: PyInstaller spec file (two targets: CLI onefile + .app windowed)
Add dev deps to Pipfile: pyinstaller, build, twine
Makefile targets: binary, binary_dir, app, dmg, pypi_build, pypi_publish, clean_dist
Verified: make binary → dist/todoscope (11MB ARM64) → ./dist/todoscope --version → 1.0.0
Cross-platform binaries — build & verify

Release Pipeline — Mac .app + DMG + Menu Bar

Build .app: make app → TodoScope.app wrapper around PyInstaller binary
Create DMG: make dmg → styled DMG via create-dmg with background + Applications link
App icon: real 🔭 Apple Color Emoji via canvas+receiver (scripts/generate_emoji_icon.sh)
Menu bar icon: 🔭 on transparent background via canvas+receiver (scripts/generate_menu_icon.sh)
pystray menu bar app: 🔭 in menu bar with Open Browser, Show Log, Quit
Dock icon toggle: Hide/Show Dock Icon menu item via NSApp.setActivationPolicy ctypes
Duplicate instance prevention: detects running server, opens browser instead
Data persistence: local_repos.yaml, access_keys.csv, repositories all in ~/.todoscope/
Verified: .app launches → Dock icon bounces → 🔭 in menu bar → browser opens → all menu items work

Release Pipeline — Makefile Targets + Local Cross-Platform Builds

Makefile targets: binary, binary_dir, app, dmg, pypi_build, pypi_publish, clean_dist
Icon wired: --icon assets/todoscope.icns in app target
Styled DMG: create-dmg with background, icon positions, Applications drop link
Cross-platform builds (Docker, zero cloud CI):
scripts/release_all.sh: one command builds ALL artifacts + uploads via gh CLI
make release_all target: calls release_all.sh
Code signing: Developer ID credentials — consumed by the Tauri shell's bundler, per the verdict
Verify full release: make release_all → all artifacts built + uploaded

Release Pipeline — Homebrew Tap

Homebrew tap: formula, cask, ecosystem updates

Release Pipeline — Automated Release Flow

One-command release: make patch_release + make release_finish triggers everything
Version single-source-of-truth: scanner/__init__.py drives everything

Release Pipeline — Future Enhancements

Tray & Dock polish: platform icon behavior across macOS, Linux, Windows
Tauri shell (v2.0): built 2026-08-15 — src-tauri/ shell, make tauri_dev/tauri_build/tauri_dmg, cask route; settled points in shell build choices
Branding & Poka-Yoke audit: ensure all user-facing text, errors, and flows are clear and mistake-proof for v1

Bugs

Completed

Changelog

v0.0.1 — First Release (2026-04-16)

Access key authentication with CSV-backed key management and login/logout flow
Live TODO count badge endpoint (/api/badge/todos/:repo)
Streaming scan results in the web UI via SSE
Agent-ready API: manifest, OpenAPI spec, and scan_repository endpoint
Broadened TODO pattern recognition: FIXME, BUG, NOTE alongside TODO
.gitignore-aware scanning; skips scanner/repositories/ in local scans
TodoScope branding: naming, favicon, meta/OG tags, footer ecosystem links
Landing page with hero copy, feature strip, and embedded demo GIF
code.dev deep-link for every registered repository
Robust error handling with custom exceptions, retries, and recovery strategies
Unit and integration test suite with Makefile runner targets
CapRover one-click deployment config (caprover-one-click.yml)

License

Released under the GNU Affero General Public License v3.0 (AGPL-3.0).

Use it. Share it. Make it better. But keep it open. The full license text is available in the LICENSE file.

Contribution

Contributions are highly encouraged! If you have an idea for improvement or a bug fix, please:

Fork the repository.
Create a new branch for your feature or fix.
Make your changes.
Submit a pull request with a clear description of your changes.

Let's work together to make this tool even better and help keep our codebases clean and manageable!

GitHub TODO Scanner