markdown-task-butler 0.2.9
A task management tool that helps prioritize and recommend actions - your digital butler for tasks
License: MIT
Requires Python: >=3.11
Keywords: cli, markdown, obsidian, productivity, task, todo

# Task Butler

[日本語](README.ja.md) | English

Your digital butler for task management. A CLI tool that helps you manage tasks, prioritize work, and stay organized.

## Features

- **Simple CLI**: Intuitive commands for managing tasks
- **Markdown Storage**: Tasks stored as human-readable Markdown files with YAML frontmatter
- **Hierarchical Tasks**: Create parent/child relationships between tasks
- **Dependencies**: Define task dependencies to track blocking work
- **Recurring Tasks**: Set up daily, weekly, monthly, or yearly recurring tasks
- **AI Features**: Task analysis, smart suggestions, and daily planning with local LLM
- **Obsidian Integration**: Export/import in Obsidian Tasks plugin compatible format
- **Rich Output**: Beautiful terminal output with colors and formatting
- **Git Friendly**: All data stored in plain text, easy to version control

## Installation

### From PyPI (Recommended)

```bash
pip install markdown-task-butler
# or
uv tool install markdown-task-butler
```

This installs `task-butler` and `tb` commands globally.

### From GitHub

```bash
uv tool install git+https://github.com/dobachi/task-butler.git
```

### Upgrade

```bash
pip install --upgrade markdown-task-butler
# or
uv tool upgrade markdown-task-butler
```

### Quick Try with uvx

```bash
uvx markdown-task-butler
```

Note: `uvx` runs in a temporary environment. Shell completion is not available.

### From Source

```bash
git clone https://github.com/dobachi/task-butler.git
cd task-butler
uv sync
uv run task-butler
```

## Quick Start

### 1. Initial Setup

Run the interactive configuration wizard (recommended):

```bash
task-butler config init
```

This allows you to configure:
- Storage format (frontmatter / hybrid)
- Task storage directory (default: `~/.task-butler/tasks/`)
- Obsidian Vault path (optional)
- Organization method (flat / kanban)

Or set environment variables directly:

```bash
# Change the base directory for all settings (default: ~/.task-butler/)
export TASK_BUTLER_HOME=~/my-task-butler

# Change only the task storage location
export TASK_BUTLER_DIR=~/my-tasks
```

### 2. Basic Operations

```bash
# Add a task
task-butler add "Write documentation"

# Add a high-priority task with due date
task-butler add "Fix critical bug" --priority urgent --due 2025-01-30

# List all tasks
task-butler list

# Start working on a task (use short ID - first 8 chars)
task-butler start abc12345

# Mark a task as done
task-butler done abc12345
```

### 3. Short ID Support

All commands that take a task ID support **short IDs** (first 8 characters of the UUID):

```bash
# These are equivalent:
task-butler show abc12345-1234-5678-9abc-def012345678
task-butler show abc12345

# Even shorter prefixes work if unique:
task-butler done abc1
```

If a short ID matches multiple tasks, you'll see a list of matching tasks to choose from.

## Shell Completion

Task Butler supports shell completion for commands, options, and task IDs.

### Setup

```bash
# Zsh (shows task titles)
task-butler --install-completion zsh

# Fish (shows task titles)
task-butler --install-completion fish

# Bash (shows task titles)
mkdir -p ~/.bash_completions
curl -o ~/.bash_completions/task-butler.sh \
  https://raw.githubusercontent.com/dobachi/task-butler/main/scripts/task-butler-completion.bash
echo 'source ~/.bash_completions/task-butler.sh' >> ~/.bashrc
source ~/.bash_completions/task-butler.sh
```

After installation, restart your shell or source the config file.

> **Note**: For Bash, do NOT use `--install-completion bash` as it installs a basic version without task titles.

### Features

- **Command completion**: Tab to complete command names (`task-butler st<TAB>` -> `start`)
- **Option completion**: Tab to complete option names (`--pri<TAB>` -> `--priority`)
- **Task ID completion**: Tab to see matching task IDs with titles
  - Open commands (`start`, `done`, `cancel`) show only pending/in_progress tasks
  - Other commands (`show`, `delete`, `note`) show all tasks
- **Project name completion**: Available for `--project` option
- **Tag name completion**: Available for `--tag` option

### Example

```bash
# Add some tasks
task-butler add "Task 1"
task-butler add "Task 2"

# Complete task ID
task-butler show <TAB>
# Shows: abc12345 (Task 1)  def67890 (Task 2)

task-butler start <TAB>
# Shows only open tasks with status indicator
```

## Commands

### Adding Tasks

```bash
# Basic task
task-butler add "Task title"

# With options
task-butler add "Task title" \
  --priority high \           # low, medium, high, urgent
  --due 2025-02-01 \         # Due date (YYYY-MM-DD, today, tomorrow)
  --project "my-project" \   # Project name
  --tags "work,important" \  # Comma-separated tags
  --hours 4 \                # Estimated hours
  --desc "Description"       # Task description

# Subtask (child of another task)
task-butler add "Subtask" --parent abc123

# Task with dependencies
task-butler add "Deploy" --depends abc123,def456

# Recurring task
task-butler add "Weekly review" --recur weekly
task-butler add "Biweekly sync" --recur "every 2 weeks"
```

### Listing Tasks

```bash
# List open tasks (default)
task-butler list

# Include completed tasks
task-butler list --all

# Filter by priority
task-butler list --priority high

# Filter by project
task-butler list --project my-project

# Filter by tag
task-butler list --tag important

# Table format
task-butler list --table

# Tree format (shows hierarchy)
task-butler list --tree

# Alias
task-butler ls
```

### Viewing Task Details

```bash
task-butler show abc123
```

### Changing Task Status

```bash
# Start working on a task
task-butler start abc123

# Mark as done
task-butler done abc123

# Mark as done with time logged
task-butler done abc123 --hours 2.5

# Cancel a task
task-butler cancel abc123
```

### Managing Tasks

```bash
# Add a note
task-butler note abc123 "Progress update: API complete"

# Delete a task
task-butler delete abc123

# Force delete (skip confirmation)
task-butler delete abc123 --force
```

### Other Commands

```bash
# Search tasks
task-butler search "bug"

# List all projects
task-butler projects

# List all tags
task-butler tags

# Show version
task-butler version

# Help
task-butler --help
task-butler add --help
```

## Data Storage

Tasks are stored in `~/.task-butler/tasks/` as Markdown files with YAML frontmatter.

**Filename format**: `{short_id}_{title}.md` (e.g., `abc12345_Implement_authentication.md`)

```markdown
---
id: abc12345-1234-5678-9abc-def012345678
title: Implement authentication
status: in_progress
priority: high
created_at: 2025-01-25T10:00:00
updated_at: 2025-01-25T14:30:00
due_date: 2025-02-01T00:00:00
tags:
  - backend
  - security
project: api-v2
estimated_hours: 8
---

Implement JWT-based authentication for the API.

## Notes

- [2025-01-25 10:30] Started research
- [2025-01-25 14:30] JWT library selected
```

### Storage Format

Two storage formats are supported:

- **frontmatter** (default): YAML frontmatter only
- **hybrid**: YAML frontmatter + Obsidian Tasks line (for better Obsidian integration)

Hybrid format example:
```markdown
---
id: abc12345-...
title: Meeting prep
...
---

- [ ] Meeting prep ⏫ 📅 2025-02-01

Description here...
```

### Configuration

Configuration can be set via (in order of precedence):

1. **CLI option**: `--format hybrid`
2. **Environment variable**: `TASK_BUTLER_FORMAT=hybrid`
3. **Config file**: `~/.task-butler/config.toml`

```toml
# ~/.task-butler/config.toml
[storage]
format = "hybrid"  # "frontmatter" or "hybrid"
```

See [`config.sample.toml`](config.sample.toml) for all available options.

### Custom Storage Location

Set via environment variable:
```bash
export TASK_BUTLER_DIR=/path/to/tasks
```

Or via command-line option:
```bash
task-butler --storage-dir /path/to/tasks list
```

## Development

### Setup

```bash
git clone https://github.com/dobachi/task-butler.git
cd task-butler
uv sync --dev
```

### Running Checks (Before Commit)

Always run `make check` before committing to ensure CI will pass:

```bash
make check    # Run lint + format check + tests (same as CI)
```

### Available Make Targets

| Command | Description |
|---------|-------------|
| `make check` | Run all CI checks (lint + format + test) |
| `make lint` | Run ruff linter |
| `make format` | Check code formatting |
| `make test` | Run tests |
| `make fix` | Auto-fix lint and format issues |
| `make ci` | Full CI simulation (includes typecheck) |

### Running Tests

```bash
uv run pytest
# or
make test
```

### Running Tests with Coverage

```bash
uv run pytest --cov=task_butler
```

## Roadmap

- [x] **Phase 1**: Core functionality (MVP)
  - Task CRUD operations
  - Hierarchical tasks
  - Dependencies
  - Recurring tasks
  - CLI interface

- [x] **Phase 2**: AI Features
  - Task analysis and prioritization
  - Smart suggestions
  - Daily planning assistance
  - Local LLM support (llama-cpp-python)
  - Japanese language model support

- [x] **Phase 3**: Obsidian Integration
  - Use Obsidian vault as storage directory
  - Obsidian Tasks plugin compatibility (export/import)
  - Conflict detection and resolution

- [ ] **Phase 4**: Advanced Features
  - File watching (auto-import from Markdown)
  - Export (JSON, CSV)
  - Interactive chat mode

- [x] **Phase 5**: Distribution
  - PyPI publication (`pip install markdown-task-butler`)
  - Shell completion (Bash/Zsh/Fish)
  - Extended documentation

- [ ] **Phase 6**: Windows Support
  - Windows compatibility testing
  - PowerShell completion
  - Windows installer / standalone executable

## Obsidian Integration

Task Butler works with [Obsidian](https://obsidian.md/) vaults and supports a format compatible with the [Obsidian Tasks](https://github.com/obsidian-tasks-group/obsidian-tasks) plugin.

See the [Obsidian Integration Guide](docs/OBSIDIAN.en.md) for details.

### Quick Start

```bash
# Use Obsidian vault as storage
export TASK_BUTLER_DIR=~/Documents/MyVault/Tasks

# Create task with date fields
task-butler add "Meeting prep" --due 2025-02-01 --scheduled 2025-01-25 --priority high

# Export in Obsidian Tasks format
task-butler obsidian export
# → - [ ] Meeting prep ⏫ 📅 2025-02-01 ⏳ 2025-01-25 ➕ 2025-01-25

# Import from Obsidian note
task-butler obsidian import ~/Documents/MyVault/daily/2025-01-25.md
```

### Supported Emojis

| Emoji | Meaning | CLI Option |
|-------|---------|------------|
| 📅 | Due date | `--due` |
| ⏳ | Scheduled date | `--scheduled` |
| 🛫 | Start date | `--start` |
| 🔺⏫🔼🔽⏬ | Priority | `--priority` |
| ✅ | Completed date | Auto-set |
| 🔁 | Recurrence | `--recur` |

### Obsidian Commands

```bash
task-butler obsidian export    # Export in Obsidian format
task-butler obsidian import    # Import from Obsidian file
task-butler obsidian import --link  # Import + replace source lines with links
task-butler obsidian check     # Detect conflicts with frontmatter
task-butler obsidian resolve   # Resolve conflicts
task-butler obsidian format    # Display single task in Obsidian format
```

## AI Features

Task Butler includes AI-powered features for task analysis, smart suggestions, and daily planning.

> **GPU Support**: For high-speed inference with NVIDIA GPU, see the [AI Feature Setup Guide](docs/AI_SETUP.en.md).

### Quick Start

```bash
# Download a model (first time only)
tb ai download tinyllama-1.1b    # English (lightweight, 670MB)
tb ai download elyza-jp-7b       # Japanese (recommended for Japanese, 4GB)

# Enable LLM provider
tb config set ai.provider llama
tb config set ai.llama.model_name elyza-jp-7b  # For Japanese

# Set output language
tb config set ai.language ja     # Japanese
tb config set ai.language en     # English
```

### AI Commands

```bash
# Analyze tasks and get priority scores
tb analyze                # Analyze all open tasks
tb analyze abc123         # Analyze specific task
tb analyze --save         # Save analysis to task notes

# Get smart task suggestions
tb suggest                # Suggest next tasks
tb suggest --hours 2      # Tasks fitting in 2 hours
tb suggest --energy low   # Tasks for low energy
tb suggest --count 5      # Get 5 suggestions

# Generate daily plan
tb plan                   # Today's plan (8 hours)
tb plan --hours 6         # Custom hours
tb plan --date 2025-02-01 # Specific date
```

### Available Models

| Model | Size | Language | Description |
|-------|------|----------|-------------|
| `tinyllama-1.1b` | 670MB | English | Lightweight, fast |
| `phi-2` | 1.6GB | English | Better reasoning |
| `elyza-jp-7b` | 4GB | Japanese | Best for Japanese |

### Model Management

```bash
tb ai status              # Show current AI configuration
tb ai models              # List available models
tb ai download MODEL      # Download a model
tb ai delete MODEL        # Delete a model
```

### Configuration

```toml
# ~/.task-butler/config.toml
[ai]
provider = "llama"        # "llama", "rule_based", or "openai"
language = "ja"           # Output language: "en" or "ja"

[ai.llama]
model_name = "elyza-jp-7b"
n_ctx = 2048              # Context window size
n_gpu_layers = 0          # GPU layers (0 = CPU only)

[ai.analysis]
weight_deadline = 0.3     # Deadline importance
weight_dependencies = 0.25
weight_effort = 0.2
weight_staleness = 0.15
weight_priority = 0.1
```

### Fallback Mode

If no LLM is installed, Task Butler uses a rule-based analyzer that provides:
- Priority scoring based on deadlines, dependencies, and effort
- Task suggestions based on available time
- Basic daily planning

Install the LLM optional dependency for enhanced AI features:

```bash
uv tool install markdown-task-butler[llm]
# or
pip install markdown-task-butler[llm]
```

## License

MIT

## Author

dobachi