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

$3

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

$3

`bash
npm install @gonzui/claude-task-manager
`

Usage

$3

`bash
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 .

$3


`bash
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

$3


`bash
claude-task status
`

Displays:
- Current task name
- Number of archived tasks
- Last execution time
- Total execution count

$3

`bash
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.

$3


`bash
claude-task history --limit 10
`

$3

`bash
claude-task archive
`

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

$3

`bash
claude-task progress
`

Displays a visual progress bar showing subtask completion status:
`
📊 Task Progress
================
Progress: [████████░░░░░░░░░░░░] 40%
Completed: 2/5 tasks
`

$3


`bash
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)

$3


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

Claude Code Integration

$3

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).

$3


`markdown

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

Notes

---
Generated by Claude Task Manager
`

Programmatic Usage

`typescript
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:

`json
{
"created": "2025-01-15T10:00:00.000Z",
"taskTemplate": "...",
"claudeCommand": "claude",
"defaultTaskTitle": "New Task",
"archiveDir": "archive",
"language": "en",
"defaultPrerequisites": [
""
],
"defaultRules": [
""
],
"defaultTasks": [
"Task 1",
"Task 2",
"Task 3"
]
}
`

$3

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

`json
{
"defaultPrerequisites": [
"",
"Required environment",
"Required permissions",
"Pre-setup steps"
]
}
`

This will be automatically converted to:
`markdown


Prerequisites



- Required environment
- Required permissions
- Pre-setup steps
`

$3

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

`bash


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

`bash


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

$3

- 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

$3

- 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

$3

- Fix: Documentation dates corrected from 2024 to 2025

$3

- 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

$3

- 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

$3

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

$3

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

$3

- 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