Minitasks
A lightweight, file-system based task manager for VSCode
Minitasks is a simple yet powerful task management extension that stores tasks directly in your project's filesystem. No databases, no external services—just Markdown files organized in folders.
Table of Contents
Features
- 📁 File-based: Tasks stored as Markdown files in your project's
.minitasks folder
- 🗂️ Category Management: Organize tasks into customizable categories (Backlog, In Progress, Review, Done, etc.)
- 👤 Git Integration: Automatically captures task author from git config
- 📝 Markdown Support: Write rich task descriptions with full Markdown support
- 🤖 AI Assistant: Chat participant to manage tasks with natural language
- 🏷️ Tagging System: Add tags to categorize and filter tasks
- 📦 Archive Support: Archive completed tasks to keep your workspace clean
- 🎨 Customizable: Configure category colors, order, and default settings
- 🔄 No Lock-in: All data stored in human-readable files under version control
Installation
From VSIX Package
- Download the latest
.vsix file from the releases page
- Open VSCode
- Press
Ctrl+Shift+P (or Cmd+Shift+P on Mac)
- Type "Extensions: Install from VSIX"
- Select the downloaded
.vsix file
From Source
- Clone this repository
- Run
npm install or bun install
- Run
npm run package or bun run package
- Install the generated
.vsix file
Getting Started
Initialize Minitasks
- Open a workspace or folder in VSCode
- Click the Minitasks icon in the Activity Bar (left sidebar)
- Click "Initialize Minitasks" button
- The
.minitasks folder will be created with default categories
Create Your First Task
- Click the
+ button in the Minitasks view
- Enter a task title
- Optionally add tags (comma-separated)
- The task file will open for you to add details
Usage
Creating Tasks
Via UI
- Click the
+ button in the Minitasks view
- Enter task title and tags
- Edit the
task.md file to add detailed description
Via Chat
Type in the Copilot Chat:
@minitasks create a task to fix login bug
The AI will create the task and populate it with context.
Managing Tasks
Change Task Status
- Right-click a task → "Set Status" → Choose new category
- Or drag and drop tasks between categories
Edit Tasks
- Click on a task to open its
task.md file
- Edit the Markdown content directly
- Changes are reflected immediately in the task view
Delete Tasks
- Right-click a task → "Delete task"
- Or manually delete the task folder from
.minitasks
Clone Tasks
- Right-click a task → "Clone task"
- Creates a duplicate with a new timestamp
Categories
Default Categories
- Backlog: New tasks waiting to be started
- In Progress: Tasks currently being worked on
- Review: Tasks waiting for review
- Done: Completed tasks
Create Custom Categories
- Click the folder
+ icon in the Minitasks view
- Enter the category name
- Tasks can now be moved to this category
Rename/Delete Categories
- Right-click a category → "Rename category" or "Delete category"
- Category colors can be configured in
.minitasks/_config.json
Archiving Tasks
Archive completed tasks to keep your workspace clean:
- Right-click a task → "Set Status" → Select any category
- Move the task to "Done" or another category
- Right-click the task → "Archive" (if available)
- Or manually move the task folder to
.minitasks/_archive/
View archived tasks:
- Click the archive icon in the Minitasks view
- Or browse
.minitasks/_archive/ directory
AI Chat Integration
Minitasks includes a chat participant (@minitasks) for AI-powered task management:
Available Commands
@minitasks create a task to implement authentication
@minitasks list all tasks in backlog
@minitasks move task "fix bug" to in progress
@minitasks show me tasks tagged with "bug"
@minitasks archive completed tasks
The AI assistant understands natural language and can:
- Create tasks with intelligent context
- List and filter tasks
- Move tasks between categories
- Suggest task breakdowns for complex work
Project Structure
.minitasks/
├── _config.json # Global configuration
├── _archive/ # Archived tasks
├── Backlog/ # Default category
│ └── 260201-fix-auth/ # Task folder (YYMMDD-name format)
│ └── task.md # Task definition
├── In Progress/
├── Review/
└── Done/
Each task is a Markdown file with YAML frontmatter:
------
title: Fix authentication bug
created-at: 01/02/2026, 14:30:00
author: YourName
tags: bug, security
------
# Fix authentication bug
## Description
Users are experiencing session timeouts...
## Steps to Reproduce
1. Login to the app
2. Wait 5 minutes
3. Try to access protected route
## Expected Behavior
Session should remain active for 30 minutes.
Configuration File
.minitasks/_config.json:
{
"defaultCategory": "Backlog",
"categories": {
"Backlog": { "color": "#3498db", "order": 0 },
"In Progress": { "color": "#f39c12", "order": 1 },
"Review": { "color": "#9b59b6", "order": 2 },
"Done": { "color": "#2ecc71", "order": 3 }
}
}
Configuration
Category Colors
Edit .minitasks/_config.json to customize category colors:
{
"categories": {
"Backlog": { "color": "#3498db" }
}
}
Default Category
Set which category new tasks are created in:
{
"defaultCategory": "Backlog"
}
Commands
All commands are accessible via Command Palette (Ctrl+Shift+P or Cmd+Shift+P):
| Command |
Description |
minitasks.initialize |
Initialize Minitasks in current workspace |
minitasks.createTask |
Create a new task |
minitasks.openTask |
Open a task file |
minitasks.setCategory |
Move task to different category |
minitasks.createCategory |
Create a new category |
minitasks.renameCategory |
Rename an existing category |
minitasks.deleteCategory |
Delete a category |
minitasks.cloneTask |
Duplicate a task |
minitasks.deleteTask |
Delete a task |
minitasks.viewArchive |
View archived tasks |
minitasks.refresh |
Refresh the task view |
Troubleshooting
Tasks not appearing
- Ensure
.minitasks folder exists in your workspace root
- Click the refresh button in the Minitasks view
- Check that task folders follow the
YYMMDD-name format
Cannot create tasks
- Verify you have write permissions in the workspace folder
- Ensure the workspace is initialized (
minitasks.initialize)
- Check VSCode output panel for error messages
Git author not detected
- Ensure git is installed and configured
- Run
git config --global user.name "Your Name"
- Restart VSCode after configuring git
Categories not showing
- Check
.minitasks/_config.json for valid JSON syntax
- Ensure category folders exist in
.minitasks/
- Refresh the Minitasks view
License
This project is licensed under the MIT License. See the LICENSE file for details.
