@gonzui/claude-task-manager/README.md

Task management extension for Claude Code with archiving and history

# Claude Task Manager

[![npm version](https://badge.fury.io/js/@gonzui%2Fclaude-task-manager.svg)](https://badge.fury.io/js/@gonzui%2Fclaude-task-manager)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

日本語版: インストール後、`node_modules/@gonzui/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

## Installation

### Global Installation (Recommended)
```bash
npm install -g @gonzui/claude-task-manager
```

### Local Installation
```bash
npm install @gonzui/claude-task-manager
```

## Usage

### Initialize Project
```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 .`

### Create New Task
```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

### Check Current Task Status
```bash
claude-task status
```

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

### Execute Current Task
```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.

### View Task History
```bash
claude-task history --limit 10
```

### Archive Current Task
```bash
claude-task archive
```

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

### Direct Claude Code Execution
```bash
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
```markdown
# Task Title

**Created:** 2024-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

```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": "2024-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:

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

This will be automatically converted to:
```markdown
## Prerequisites
<!-- Add prerequisites here -->
- Required environment
- Required permissions
- Pre-setup steps
```

### Language Settings

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 >= 16.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

### 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