markdown-task-butler 0.2.9

A task management tool that helps prioritize and recommend actions - your digital butler for tasks

Task Butler

日本語 | 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)

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

This installs task-butler and tb commands globally.

From GitHub

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

Upgrade

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

Quick Try with uvx

uvx markdown-task-butler

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

From Source

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

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:

# 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

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

# 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

# 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

# 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

# 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

# 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

task-butler show abc123

Changing Task Status

# 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

# 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

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

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

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

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

See config.sample.toml for all available options.

Custom Storage Location

Set via environment variable:

export TASK_BUTLER_DIR=/path/to/tasks

Or via command-line option:

task-butler --storage-dir /path/to/tasks list

Development

Setup

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:

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

uv run pytest
# or
make test

Running Tests with Coverage

uv run pytest --cov=task_butler

Roadmap

• Phase 1: Core functionality (MVP)

  • Task CRUD operations
  • Hierarchical tasks
  • Dependencies
  • Recurring tasks
  • CLI interface

• Phase 2: AI Features

  • Task analysis and prioritization
  • Smart suggestions
  • Daily planning assistance
  • Local LLM support (llama-cpp-python)
  • Japanese language model support

• 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

• 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 vaults and supports a format compatible with the Obsidian Tasks plugin.

See the Obsidian Integration Guide for details.

Quick Start

# 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

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.

Quick Start

# 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

# 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

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

# ~/.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:

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

License

MIT

Author

dobachi