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
• 🔌 MCP Server: Exposes task management to Claude Code as schema-bound MCP tools via .mcp.json
• 📟 Statusline & Hooks: Shows the current task in Claude Code's status line and injects it at session start (opt-in via init --hooks)
• 🔄 Todo Reconciliation: task.md stays the persistent source of truth; Claude Code's in-session todo list mirrors it one way
• 📦 Plugin Packaging: One-step install of the command + skill + hook + MCP server as a Claude Code plugin
• 📈 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

Options:

• --hooks: Also wire the current task into Claude Code's status line and session start (see Statusline & SessionStart Hook)

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

Options:

• --short: One-line output for statusline embedding, e.g. Implement auth ▸ 60% (title only when the task has no subtasks, No task when there is none)

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.

Work on Several Tasks

claude-task new "API rework" --name api   # create alongside the current task
claude-task list                          # list every task with its progress
claude-task switch api                    # make another task the active one
claude-task switch spike --create         # create it on the spot

One task is active at a time — it lives in task.md, exactly as before — but several named tasks can coexist under .claude-tasks/tasks/<name>.md:

• new --name <name> creates a task without archiving the current one and switches to it. Plain new keeps its classic behavior (archive and replace).
• switch <name> saves the active task first, so nothing in progress is lost.
• list marks the active task with * and shows done/total per task.
• status --short (the statusline) becomes [<name>] <title> ▸ <pct>%.
• Nothing changes until you use one of these commands: existing single-task projects are migrated transparently the first time you create or switch to a named task.

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

Complete Subtasks

claude-task done 1 3      # mark subtasks 1 and 3 as done
claude-task done --undo 1 # uncheck subtask 1

Marks subtasks complete (or, with --undo, incomplete) by their number. The numbers match the order shown by claude-task progress, and the updated progress bar is printed afterwards.

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 (deprecated)

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

Deprecated: claude only prints the task content. Use claude-task run to actually execute the current task with Claude Code.

Claude Code Integration

Plugin Installation (one step)

The repository doubles as a Claude Code plugin marketplace. Inside Claude Code:

/plugin marketplace add devgonzui-ai/claude-task-manager
/plugin install claude-task@gonzui-tools

The plugin bundles the /task slash command, the task skill, a SessionStart hook (injects the current task into every new session), and the MCP server (launched via npx, so no global npm install is required for it).

Two things still need a local step:

• The claude-task CLI itself (used by the command, skill, and hook) comes from npm: npm install -g @gonzui/claude-task-manager, then run claude-task init once per project to create task.md / archive/.
• Claude Code does not let plugins set the status line, so for the statusline either run claude-task init --hooks or add the statusLine entry from the Statusline & SessionStart Hook section to your settings yourself.

The plugin package lives in plugin/ and is regenerated from the same sources as init (npm run generate:plugin), so both install paths always ship identical content — a test fails if they drift.

Custom Command, Skill & MCP Server (via init)

If you prefer not to use the plugin, claude-task init wires up the same integrations per-project. After running it in a project that has a .claude/ directory, three integrations are generated automatically:

• A /task slash command at .claude/commands/task.md
• A Skill at .claude/skills/task/SKILL.md, so newer Claude Code versions can discover task management on their own.
• An MCP server registration in .mcp.json, exposing task management as schema-bound tools (see MCP Server below).

The /task command lets you use the following 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).

MCP Server

The package ships a claude-task-mcp binary — a stdio MCP server that lets Claude Code manage tasks through typed, schema-validated tools instead of assembling CLI commands:

| Tool | Description | | --- | --- | | task_new | Create a new task (archives the current one first) | | task_status | Show current task and execution stats | | task_progress | Show subtask checkbox progress | | task_done | Mark subtasks done by number (supports undo) | | task_split | Split the task into subtasks using AI | | task_history | List archived tasks | | task_archive | Archive the current task |

claude-task init registers the server in your project's .mcp.json (safe to commit — Claude Code asks for approval before using project-scoped servers):

{
  "mcpServers": {
    "claude-task": {
      "command": "claude-task-mcp",
      "args": []
    }
  }
}

If a claude-task entry already exists in .mcp.json, init leaves it untouched. All tools route through the same TaskManager core as the CLI, so both front-ends stay consistent.

Statusline & SessionStart Hook

Run claude-task init --hooks to make the current task ambient in Claude Code. It merges the following into .claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "claude-task status --short",
    "padding": 1
  },
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "claude-task status"
      }
    ]
  }
}

• Statusline: Claude Code's status bar shows the current task and progress, e.g. Implement auth ▸ 60%, refreshed as you work.
• SessionStart hook: the hook's stdout is injected as context, so every new session starts already knowing the current task — no need to ask.

Existing settings are preserved: a statusLine you already configured is left untouched, your own SessionStart hooks are kept, and re-running init --hooks never duplicates entries. Nothing is written unless you pass the flag, and no hook performs destructive actions (archiving stays manual).

task.md vs Claude Code's Todo List

Claude Code keeps its own in-session todo list. The two layers have distinct roles and are kept in sync one way:

| Layer | Role | | --- | --- | | task.md (claude-task) | Persistent, file-based, cross-session source of truth | | Claude Code todo list | Ephemeral in-session working mirror |

The generated skill, slash command, MCP tool descriptions, and the claude-task run prompt all instruct Claude to:

1. Seed its in-session todo list from the unchecked subtasks in task.md (via claude-task progress) when starting work.
2. Persist each finished subtask with claude-task done <n> before checking off the mirrored todo.
3. Treat task.md as authoritative on any disagreement — re-seed the todo list from claude-task progress, never the other way around.

This removes double management: subtasks live in task.md and survive across sessions, while the in-session list is just a live view of them.

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

See CHANGELOG.md for the full release history.