Zap - Local Issue Tracker
A VS Code extension for viewing and managing local issues from .issues/ directories in your projects.
Features
- Project-based issue management: Track issues locally within your project using markdown files in
.issues/ directory
- Multiple project support: Manage issues across multiple workspaces
- Issue states: Organize issues by status - Open, In Progress (WIP), Done, and Closed
- Fresh Done tracking: Recently completed issues are highlighted in a special "Fresh Done" category
- Real-time updates: File watcher automatically refreshes the view when issues change
- Quick access: Click to open issue files directly in the editor
Issue States
| State |
Icon |
Description |
| In Progress |
🔥 |
Currently being worked on |
| Open |
⭕ |
New or pending issues |
| Fresh Done |
✨ |
Recently completed (within configured time window) |
| Done |
✅ |
Completed issues |
| Closed |
🚫 |
Cancelled or won't fix |
Getting Started
Prerequisites
Your project needs a .issues/ directory with issue files in markdown format:
your-project/
└── .issues/
├── 001-feat-user-auth.md
├── 002-fix-login-bug.md
└── 003-refactor-api.md
Each issue file should have YAML frontmatter:
---
number: 1
title: 'Implement user authentication'
state: open
labels:
- feature
- auth
assignees:
- developer
created_at: 2026-01-15T00:00:00Z
updated_at: 2026-01-15T00:00:00Z
---
## Description
Issue description goes here...
Extension Settings
| Setting |
Type |
Default |
Description |
zap.showClosedIssues |
boolean |
true |
Show closed issues in the list |
zap.showDoneIssues |
boolean |
true |
Show done issues in the list |
zap.groupByProject |
boolean |
true |
Group issues by project |
zap.freshDoneMinutes |
number |
10 |
Time window (minutes) for Fresh Done category |
Commands
- Zap: Refresh Issues - Manually refresh the issue list
- Zap: Add Project - Add a project directory to track
- Zap: Remove Project - Remove a project from tracking
- Zap: Open Issue - Open an issue in preview
- Zap: Open Issue File - Open the issue's markdown file
Companion CLI
For full issue management (create, update status, etc.), use the zap CLI:
# Create a new issue
zap new "Feature: Add dark mode"
# Change issue status
zap set wip 1 # Start working
zap set done 1 # Mark complete
License
MIT
| |
