Adhdev Project Tracker

For developers with ADHD who juggle multiple projects. Your editor remembers what you forget.

Automatically detects your git projects, saves your exact place in each one (cursor, files, scroll position), categorizes them by activity, and tracks your monthly progress. Everything stays on your machine. No telemetry. No auth. Just focus.

---

Features

1. Project Auto-Detection — Scans your workspace for git repos up to 3 levels deep. No setup required.

2. Smart Categorization — Groups projects as Active (≤28 days), Idle (29–60 days), Abandoned (61–119 days), Dead (≥120 days untouched), or Completed (100% task completion). Quick visual scan of what's current.

3. Context Capture & Recovery — Remembers your exact position: open files, cursor line/column, scroll position, git branch. Switches projects and everything's exactly where you left it.

4. Duplicate Detection — Warns if you're about to track the same repo twice under different paths (e.g., moved folder, symlink).

5. Session Timer — Shows how long you've been in the current VS Code session (bottom right status bar). No history, just current awareness.

6. Motivation Stats — Tracks monthly and all-time project completions. See your finish rate at a glance: This Month: 2/5 (40%) | All Time: 12/30 (40%).

7. Graveyard Archival — Projects untouched for 120+ days are offered to move to a "Dead" section, keeping your sidebar clean without losing history.

8. Feature Requests — Suggest improvements directly from the editor. Stored locally, never sent anywhere.

9. Motivational Notifications — Small encouraging messages when you switch between projects (toggleable).

10. Configurable Settings — Adjust thresholds, scan depth, and toggle features to match your workflow.

11. Command Palette Access — Core features accessible via commands: Open Project, Suggest a Feature, Clear All Extension Data.

12. Task File Tracking — Creates .workspace-meta/tasks.md per project. Automatically scans source code for TODO/FIXME comments and pre-populates a backlog with file locations and line numbers. Editing the file updates the sidebar progress bar in real time.

---

Installation

From VS Code Marketplace (Recommended)

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X on macOS, Ctrl+Shift+X on Windows/Linux)
3. Search for: "Adhdev Project Tracker"
4. Click Install
5. Open a folder containing git repositories
6. Look for My Projects panel in the Explorer sidebar (left panel)

That's it. The extension activates automatically and starts scanning.

Manual Installation from Source

For developers who want to build from source:

1. Clone the repository:

   git clone https://github.com/Gabjure/adhdev-tracker-tool.git
   cd adhdev-tracker-tool
   

2. Install dependencies:

   npm install
   

3. Compile TypeScript:

   npm run compile
   

4. Package the extension:

   npm run package
   

5. Install the .vsix file in VS Code:

   • Press Cmd+Shift+P (or Ctrl+Shift+P on Windows/Linux)
   • Type: "Extensions: Install from VSIX"
   • Select adhdev-tracker-tool-1.2.3.vsix
   • Reload VS Code when prompted

---

Quick Start

1. Open a folder with git repos

   • VS Code → File → Open Folder
   • Choose a folder containing 2+ git repositories

2. Check the sidebar

   • Left panel → My Projects panel
   • See all detected repos grouped by activity level (Active, Idle, Abandoned, Dead)
   • Each project shows branch, last commit time, and completion %

3. Open a project

   • Click any project in the list
   • Folder opens (or switches), and your context restores automatically
   • Files reopen, cursor positions and scroll positions are restored

4. Track your stats

   • Check sidebar header for motivation stats: This Month: X/Y (Z%) | All Time: A/B (C%)
   • Completion is tracked automatically based on project activity

5. Customize (optional)

   • Press Cmd+, (or Ctrl+,) → search "adhdev"
   • Adjust thresholds, toggle features, set scan depth
   • Reload extension when changing settings (Cmd+Shift+P → "Developer: Reload Window")

---

Configuration

Open VS Code Settings (Cmd+, or Code → Preferences → Settings) and search "adhdev" to customize.

Available Settings

Setting	Default	Description	Example
adhdev.folderDepth	3	How many folder levels to scan for git repos (1–5). Higher = slower scan but finds nested projects; lower = faster but may miss deep repos.	Set to 1 for single-level folders; 5 for deeply nested projects
adhdev.activeThresholdDays	28	Days since last commit to mark project as Active. Adjust for your sprint cycle (e.g., 7 for weekly, 60 for quarterly).	7 = weekly sprints; 60 = long cycles
adhdev.idleThresholdDays	60	Days since last commit to mark project as Idle. Beyond this = Abandoned.	30 = tighter feedback; 90 = looser
adhdev.enableTimer	true	Show session timer in status bar (bottom right). Turn off if you prefer minimal UI.	false = no timer
adhdev.enableNotifications	true	Show motivational messages on project switch. Turn off if you find them distracting.	false = silent mode
adhdev.enableDuplicateDetection	true	Warn about duplicate projects (70% path similarity threshold). Turn off if you have many similarly-named repos.	false = no warnings
adhdev.enableIdleDetection	true	Pause the project timer when there's no editor activity. Prevents idle/sleep time from counting as work.	false = timer keeps running
adhdev.idleTimeoutMinutes	15	Minutes of inactivity (no edits, cursor movement, or editor switches) before the timer pauses. Range: 1–120.	5 = aggressive pausing; 30 = more lenient

Configuration Examples

Sprint-focused workflow (tighter thresholds):

{
  "adhdev.activeThresholdDays": 7,
  "adhdev.idleThresholdDays": 14
}

Projects are marked Active for 7 days, Idle for 14 days, then Abandoned. Good for weekly sprints.

Deeply nested projects:

{
  "adhdev.folderDepth": 5
}

Scan 5 levels deep (slower scan, but finds projects nested deeply).

Minimal mode (disable notifications & timer):

{
  "adhdev.enableTimer": false,
  "adhdev.enableNotifications": false
}

Clean UI, no distractions. Extension still auto-detects projects and recovers context.

---

How It Works

Context Capture

Every 30 seconds (or when files are saved/focused), the extension saves:

• List of open files — Which files you have tabs open for
• Cursor position — Exact line and column in each file
• Scroll position — Where you've scrolled in each file
• Git branch — Current branch name
• Commit hash — Short form (for reference)

Storage location:

• macOS/Linux: ~/.adhdev-tracker-tool/contexts/{projectId}.json
• Windows: %APPDATA%/Code/User/globalStorage/Gabjure.adhdev-tracker-tool/contexts/

Rolling window: Only the 5 most recent snapshots per project are kept (oldest auto-deleted).

Context Recovery

When you click a project to open it:

1. Folder opens in VS Code (or switches focus if already open)
2. On reload/switch, extension checks for pending recovery data
3. Restores each file to its exact cursor and scroll position
4. Attempts to check out the saved git branch (unless you have uncommitted changes)
5. If a file was deleted, it's skipped gracefully (no errors)

Smart safeguards:

• If you have uncommitted changes, branch checkout is skipped (you'll see a warning)
• Missing files don't cause errors; they're simply not reopened
• Slow git operations timeout at 5 seconds

Storage & Privacy

All data lives locally on your machine. Nothing is ever sent to a server.

Storage locations:

• macOS/Linux: ~/.adhdev-tracker-tool/
• Windows: %APPDATA%/Code/User/globalStorage/Gabjure.adhdev-tracker-tool/

Files stored:

• projects.json — List of tracked projects + metadata
• motivation-stats.json — Monthly/all-time completion stats
• contexts/{projectId}.json — Context snapshots (5 per project)
• feature-requests.json — Your suggestions

Data you control:

• Delete data anytime via Command Palette → "Clear All Extension Data" (cannot be undone)
• All files are readable JSON (you can inspect or edit manually if needed)

---

Commands

Access via Command Palette (Cmd+Shift+P or Ctrl+Shift+P):

Command	Description
Adhdev: Open Project	Switch to a project (shows list). Same as clicking in sidebar.
Adhdev: Suggest a Feature	Submit feedback/ideas. Stored locally in feature-requests.json.
Adhdev: Clear All Extension Data	Nuclear option. Deletes all projects, stats, and context. Cannot be undone.

---

Troubleshooting

My Projects panel is empty

Problem: No projects show in the sidebar, even though you have git repos in your folder.

Causes & fixes:

• Make sure you've opened a folder (File → Open Folder). The extension needs a workspace root.
• Check that your projects are actual git repos (they should have a .git folder).
• Increase adhdev.folderDepth in settings if projects are nested deep (more than 3 folders down).
• Try reloading the extension: Cmd+Shift+P → "Developer: Reload Window"
• Check the VS Code output log: View → Output → "Adhdev Project Tracker" for errors

Projects aren't updating or showing stale data

Problem: Project list shows old info or doesn't reflect recent commits.

Causes & fixes:

• The extension tracks last commit time, not file edits. Make a commit to update.
• Changes appear when you reload VS Code or after ~30 seconds.
• Verify project folder is a real git repo: cd /path/to/project && git log --oneline | head -1
• If you moved a project folder, it may show as a new project (old one still in the list). Use "Clear All Extension Data" to reset.

Context isn't restoring correctly

Problem: When you switch back to a project, files don't reopen or cursor isn't restored.

Causes & fixes:

• Files don't reopen: They may have been deleted or moved. Extension skips missing files gracefully.
  • Check ~/.adhdev-tracker-tool/contexts/{projectId}.json to verify the file path is saved.
  • If the file still exists, try reopening it manually and switching projects again.
• Branch doesn't checkout: You likely have uncommitted changes. Git won't switch branches with uncommitted work.
  • Fix: Commit or stash your changes, then switch projects again.
  • Warning message appears in output log if this happens.
• Scroll/cursor slightly off: Context captures every 30 seconds. If you switched projects quickly, the latest state might not be saved.
  • Wait 30 seconds after positioning cursor, then switch projects.

Duplicate warnings are too aggressive

Problem: You get duplicate warnings for projects that aren't actually duplicates.

Causes & fixes:

• Threshold is currently 70% path similarity. Two similarly-named projects trigger a warning.
• Options:
  • Click "Continue Anyway" to add the project anyway
  • Set adhdev.enableDuplicateDetection to false in settings (disables all warnings)
  • Keep both projects if they're actually separate (the warning is just caution)

Session timer seems wrong or resets

Problem: Timer shows incorrect elapsed time or resets unexpectedly.

Causes & fixes:

• Timer shows elapsed time since VS Code window opened in this session. It resets when you close the window.
• It doesn't accumulate across days or measure actual "focus time" (just wall clock).
• If timer disappeared: check adhdev.enableTimer is set to true. Reload extension if changed.

Performance is slow with many repos

Problem: Scanning takes a long time or VS Code feels sluggish.

Causes & fixes:

• Reduce adhdev.folderDepth to 1 or 2 (scanning deep folders is slow)
• Exclude large folders from VS Code workspace (e.g., node_modules, .venv)
• Check if a repo has a very large commit history (git operations timeout at 5s as a safeguard)
• If you have 100+ repos, consider organizing into separate workspaces

Can't read the git branch

Problem: Projects show "unknown" for branch or branch info is missing.

Causes & fixes:

• Some repos have slow git operations (large history, network repos). Extension times out after 5 seconds and shows fallback "unknown".
• The project is still tracked; you just won't see the branch name.
• Try running git status in that repo manually to check if git is responsive.
• If the repo is corrupted, running git fsck might help.

---

Edge Cases Handled

The extension robustly handles these situations:

• Permission denied reading directory → Skips folder, continues scanning other directories
• Nested repos (repo inside repo) → Both parent and child repos are detected (no issues)
• Symlinks → Avoids infinite loops; follows symlinks carefully
• Missing files on recovery → Skips gracefully, opens other files without errors
• Uncommitted changes on branch checkout → Shows warning, skips checkout (safe)
• Deleted project folder → Project displayed but can't open (skipped gracefully)
• Large repos with slow git → Git operations timeout at 5 seconds, fallback info used
• Workspace with 100+ projects → No hard limit, but UI may scroll; consider multiple workspaces
• Very long file paths (255+ chars) → Handled safely on all platforms
• Files moved between projects → Old snapshot skipped, extension continues

---

Development & Contributing

Prerequisites

• Node.js 18+
• TypeScript 5.3+
• VS Code 1.85+
• npm or yarn

Setup

git clone https://github.com/Gabjure/adhdev-tracker-tool.git
cd adhdev-tracker-tool
npm install
npm run compile

Run Tests

npm test

Expected: ~30 tests pass (unit tests for project detection, context capture, duplicate detection, etc.)

Debug in VS Code

1. Open the project in VS Code
2. Press F5 → Select "Run Extension"
3. A new VS Code window opens with the extension loaded
4. Set breakpoints in src/ files
5. Interact with the extension to trigger breakpoints
6. Inspect variables, step through code

Useful debug tips:

• Set breakpoint in src/extension.ts to debug startup
• Output panel shows all logs: View → Output → "Adhdev Project Tracker"
• Use console.log() in source; appears in output panel

Build for Release

npm run compile
npm run package

Produces: adhdev-tracker-tool-1.2.2.vsix (installable via "Install from VSIX")

Directory Structure

adhdev-tracker-tool/
├── src/
│   ├── extension.ts           # Main entry point, command & listener registration
│   ├── projectDetection.ts    # Git repo scanning
│   ├── contextCapture.ts      # Auto-saves editor state every 30s
│   ├── contextRecovery.ts     # Restores editor state on project switch
│   ├── motivationTracking.ts  # Stats, categories, graveyard
│   ├── duplicateDetection.ts  # Path-similarity checking
│   ├── sidebar.ts             # Tree view provider
│   ├── storage.ts             # JSON persistence (platform-specific paths)
│   ├── git.ts                 # Git operations with 5s timeout
│   ├── constants.ts           # DEFAULT_THRESHOLDS (single source of truth)
│   └── types.ts               # Cross-module type contracts
├── test/
│   ├── projectDetection.test.ts     (5 tests)
│   ├── duplicateDetection.test.ts   (11 tests)
│   └── motivationTracking.test.ts   (14 tests)
├── docs/
│   ├── ARCHITECTURE.md              # Module map, data flow, settings
│   └── CONVENTIONS.md               # Naming, async/error patterns
├── package.json
├── tsconfig.json
├── CLAUDE.md
└── README.md

---

Known Limitations

Be aware of these limitations (by design or technical constraints):

1. No cloud sync — Projects and data don't sync across devices (intentional for privacy). You'll have separate project lists on each machine.

2. No time tracking — Only tracks last-modified date (by git commit), not actual time spent per project.

3. No git remote tracking — Doesn't know if you've pushed, if branch is behind upstream, or if there are unpushed commits.

4. No auto-completion detection — You manually set completion % (0–100). No automatic detection of "done" states.

5. Single workspace only — VS Code multi-root workspaces (.code-workspace files) are scanned but treated as one folder list. Projects from different workspace roots may not categorize correctly.

6. No project templates/scaffolding — No quick-start helpers or generators to create new projects from templates.

7. No manual completion override — You can't manually mark a project as 100% complete; completion is derived from activity. A dedicated set-completion command was removed in an earlier version.

---

Future Ideas

Some ideas for future versions (no commitment, depends on community feedback):

• Project tags/labels — Custom grouping beyond Active/Idle/Abandoned (e.g., "frontend", "research", "learning")
• Habit streaks — Track consecutive days touching a project ("On fire! 7 days in a row")
• Time tracking per project — Optional session timer per project (not just current window)
• Git integration — Detect unpushed commits, branch age, upstream status
• Export/import backup — Save/restore all projects and data
• Web dashboard — If sync is added later, a web view of projects and stats
• Activity heatmap — Visualization of project activity over time
• Smart prioritization — AI-assisted suggestions of which project to work on next (based on deadlines, streaks, etc.)

---

License

MIT — See LICENSE file

---

Author

Built by Gabriela Pardo de Andrade Aljure (@Gabjure)

For ADHD developers, by an ADHD developer. Built in public, feedback welcome.

---

Support & Feedback

Have a question, found a bug, or want to suggest a feature?

• Report a bug or request a feature: GitHub Issues
• Suggest a feature from the editor: Cmd+Shift+P → "Suggest a Feature"
• Ask a question: GitHub Discussions
• Contact the author: @Gabjure on GitHub

---

Thanks for using Adhdev Project Tracker. 🎯 You've got this.