Claude Task Manager

日本語版: README.ja.md をご覧ください。

A powerful task management extension for Claude Code that automates task tracking and execution.

Features

• 📝 Markdown-based Task Management: Tasks are stored in task.md files that can be directly read by Claude Code
• 🚀 Seamless Claude Code Integration: Execute tasks directly through Claude Code with full context
• 🗂️ Automatic Archiving: Completed tasks are automatically archived with timestamps
• 🏷️ Priority and Tags: Organize tasks with priority levels (high/medium/low) and custom tags
• 📊 Task History: View and track all completed tasks
• 🎯 Custom Commands: Automatically creates /task custom command for Claude Code
• 📈 Progress Tracking: Visual progress bar for subtask completion
• 🤖 AI Task Splitting: Automatically break down tasks into subtasks using Claude

Installation

Global Installation (Recommended)

npm install -g @gonzui/claude-task-manager

Local Installation

npm install @gonzui/claude-task-manager

Usage

Initialize Project

claude-task init

This command:

• Creates necessary directories (archive/, .claude-tasks/)
• Generates initial configuration
• Creates a starter task.md file
• If .claude/commands/ exists, creates /task custom command
• Updates .gitignore to exclude task-related files

Git-like Directory Behavior:

• When you run any command, Claude Task Manager searches upward for a .claude-tasks directory (similar to how Git finds .git)
• If found, all operations use that project root, regardless of your current directory
• Example: If you init in /project and then cd src/components && claude-task new, the task will be created in /project/, NOT in /project/src/components/
• This ensures centralized task management across your entire project
• To create a separate task management in a subdirectory, explicitly specify the directory: claude-task init .

Create New Task

claude-task new "Implement user authentication" --priority high --tags auth,backend

Options:

• --priority: Set task priority (high/medium/low, default: medium)
• --tags: Add comma-separated tags

Check Current Task Status

claude-task status

Displays:

• Current task name
• Number of archived tasks
• Last execution time
• Total execution count

Execute Current Task

claude-task run

Executes the current task using Claude Code with task.md content as context.

Options:

• -v, --verbose: Show verbose output
• -d, --debug: Show debug information (command, file path, prompt)
• --no-edit-permission: Disable file edit permissions for Claude (default: edit permissions enabled)

Note: By default, Claude is executed with file edit permissions (--dangerously-skip-permissions flag) to allow complete task execution. Use --no-edit-permission if you want Claude to run in read-only mode.

View Task History

claude-task history --limit 10

Archive Current Task

claude-task archive

Moves the current task to the archive folder with a timestamp.

Track Progress

claude-task progress

Displays a visual progress bar showing subtask completion status:

📊 Task Progress
================
Progress: [████████░░░░░░░░░░░░] 40%
Completed: 2/5 tasks

Split Task into Subtasks

claude-task split
claude-task split --count 5

Uses Claude AI to automatically break down your current task into actionable subtasks. The generated subtasks are added to your task.md file.

Options:

• --count: Specify the number of subtasks to generate (default: 3-7)

Direct Claude Code Execution

claude-task claude "Review and optimize the database schema"

Claude Code Integration

Custom Command

After running claude-task init in a project with .claude/commands/ directory, a custom /task command is automatically created. This allows you to use the following commands directly within Claude Code:

Available Commands

• /task new "Task name" [--priority high|medium|low] [--tags tag1,tag2] - Create a new task
• /task status - Check current task status
• /task run - Execute current task (displays task.md content for Claude Code to process)
• /task history [--limit n] - View task history
• /task archive - Archive completed task

Examples within Claude Code

/task new "Implement user authentication" --priority high --tags auth,backend

/task status

/task run

The custom command file is automatically generated in the language configured in your project settings (English or Japanese).

task.md Format

# Task Title

**Created:** 2025-01-15 10:30:00  
**Priority:** high  
**Tags:** feature, backend

## Description
Detailed task description

## Tasks
- [ ] Subtask 1
- [ ] Subtask 2
- [ ] Subtask 3

## Context
<!-- Additional context for Claude Code -->

## Notes
<!-- Your notes here -->

---
*Generated by Claude Task Manager*

Programmatic Usage

import { TaskManager } from '@gonzui/claude-task-manager';

const taskManager = new TaskManager('/path/to/project');

// Initialize
await taskManager.init();

// Create new task
await taskManager.createNewTask({
  title: 'New Feature',
  description: 'Implement new feature',
  priority: 'high',
  tags: ['feature', 'urgent']
});

// Get status
const status = await taskManager.getStatus();

// Execute task
const result = await taskManager.runTask();

Configuration

Configuration is stored in .claude-tasks/config.json:

{
  "created": "2025-01-15T10:00:00.000Z",
  "taskTemplate": "...",
  "claudeCommand": "claude",
  "defaultTaskTitle": "New Task",
  "archiveDir": "archive",
  "language": "en",
  "defaultPrerequisites": [
    "<!-- Add prerequisites here -->"
  ],
  "defaultRules": [
    "<!-- Add rules here -->"
  ],
  "defaultTasks": [
    "Task 1",
    "Task 2",
    "Task 3"
  ]
}

Array Configuration

Since v1.0.6, defaultPrerequisites, defaultRules, and defaultTasks support array format for easier editing:

{
  "defaultPrerequisites": [
    "<!-- Add prerequisites here -->",
    "Required environment",
    "Required permissions",
    "Pre-setup steps"
  ]
}

This will be automatically converted to:

## Prerequisites
<!-- Add prerequisites here -->
- Required environment
- Required permissions
- Pre-setup steps

Language Settings

Claude Task Manager supports multiple languages (English and Japanese):

# Check current language
claude-task lang

# Change language to Japanese
claude-task lang ja

# Change language to English  
claude-task lang en

The language setting affects:

• CLI command outputs
• Task templates
• Custom command templates
• Error messages

Requirements

• Node.js >= 18.0.0
• Claude Code CLI installed and configured

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development mode
npm run dev -- [command]

License

MIT

Contributing

Contributions are welcome!

Changelog

v1.1.0 (2026-01-24)

• Feature: Add progress command for visual subtask completion tracking
• Feature: Add split command to auto-generate subtasks using Claude AI
• Refactor: Split TaskManager.ts into focused modules for better maintainability
• Improved: Node.js requirement updated to >= 18.0.0
• Improved: Better type safety with proper TypeScript types
• Fix: Split command timeout handling for Claude CLI

v1.0.8 (2025-08-04)

• Feature: Add archive command to manually archive current task
• Improved: Custom command file now generated in English for better Claude Code compatibility
• Improved: Custom command instructions to explicitly use Bash tool
• Improved: /task run command simplified to use @task.md reference
• Fix: /task new command now properly creates new tasks through actual CLI execution

v1.0.7 (2025-07-25)

• Fix: Documentation dates corrected from 2024 to 2025

v1.0.6 (2025-07-25)

• Feature: Add Prerequisites and Rules sections to task templates
• Feature: Support array format in config.json for easier editing
• Feature: Enable file edit permissions by default with --dangerously-skip-permissions
• Feature: Add --no-edit-permission option to disable file edits
• Improved: Language detection from environment variables
• Improved: Archive filename format with milliseconds
• Fix: Template variable replacement for both languages
• Fix: Remove checkboxes from default task items

v1.0.5 (2025-07-24)

• Feature: Fix claude-task run command to properly execute tasks
• Feature: Add --debug flag to show detailed execution information
• Feature: Change from absolute to relative path in Claude prompts
• Fix: Update default claude command from 'claude code' to 'claude'
• Improved: Use --print flag for non-interactive Claude execution

v1.0.2 (2025-07-23)

• Fix: Dynamic version reading from package.json for accurate version display

v1.0.1 (2025-07-23)

• Fix: Create .claude/commands directory when .claude exists during init
• Improved: Claude Code custom command generation

v1.0.0 (2025-07-23)

• Initial release
• Task management with archiving and history
• Multi-language support (English/Japanese)
• Git-like directory behavior for finding project root
• Claude Code integration with custom commands
• Automatic .gitignore updates