Claude Code-TaskWarrior Integration

A comprehensive integration system that bridges Claude Code's TodoWrite tool with TaskWarrior, providing persistent task management across sessions.

Features

• Persistent Tasks: Tasks survive Claude Code session restarts
• Bidirectional Sync: Import from TaskWarrior, export to TaskWarrior
• Session Management: Organized project-based sessions
• Automatic Backups: Every sync creates timestamped backups
• Priority Mapping: Claude Code priorities (high/medium/low) ↔ TaskWarrior (H/M/L)
• Status Tracking: pending, in_progress, completed status sync
• Multi-Project Support: Organize tasks by project
• Data Validation: Ensures data integrity during sync
• Rich CLI: Full-featured command-line interface
• Global Access: Works from any directory with any Claude Code session

Platform Compatibility

• Tested on: Ubuntu-based Linux systems (Ubuntu, Debian, Pop!_OS, Linux Mint)
• Should work on: Most Linux distributions with bash shell
• Not tested on:
  • macOS (may work with modifications to paths and commands)
  • Windows WSL (untested but likely compatible)
  • Native Windows (requires significant modifications)

Note: The installation instructions use apt package manager. For other systems:

• macOS: Use brew install task node jq
• Fedora/RHEL: Use dnf install task nodejs jq
• Arch: Use pacman -S task nodejs jq

Quick Start

1. Installation

# Install dependencies
sudo apt install taskwarrior nodejs jq

# Global installation (recommended)
mkdir -p ~/bin
cp -r claude-taskwarrior ~/bin/
chmod +x ~/bin/claude-taskwarrior/claude-tw
chmod +x ~/bin/claude-taskwarrior/sync.js

# Add to PATH
echo 'export PATH="$PATH:$HOME/bin/claude-taskwarrior"' >> ~/.bashrc
source ~/.bashrc

2. Initialize TaskWarrior (First time only)

# Initialize TaskWarrior
task add "test task"
task 1 delete

3. Start a Session

# Start with default project (works from any directory)
claude-tw start

# Or start with custom project
claude-tw start my-project-name

4. Sync with Claude Code

When Claude Code updates todos, sync them to TaskWarrior:

# Example: sync current todos
claude-tw sync '[{"id":"1","content":"Task 1","status":"pending","priority":"high"}]'

5. Export for Claude Code

Import existing TaskWarrior tasks into Claude Code:

# Export tasks for Claude Code import
claude-tw export

Usage

Session Management

# Start new session
claude-tw start [project-name]

# Check session status
claude-tw status

# End current session
claude-tw end

Task Synchronization

# Sync Claude Code todos to TaskWarrior
claude-tw sync '<claude-todos-json>'

# Export TaskWarrior tasks for Claude Code
claude-tw export

# Create manual backup
claude-tw backup

TaskWarrior Commands

View your tasks in TaskWarrior:

# List all project tasks
task project:claude-session list

# Show only pending tasks
task project:claude-session status:pending

# Show task summary
task project:claude-session summary

# Mark task complete
task <id> done

# Start working on task
task <id> start

Data Format

Claude Code Todo Format

[
  {
    "id": "unique-id",
    "content": "Task description",
    "status": "pending|in_progress|completed",
    "priority": "high|medium|low",
    "due": "2024-01-15",
    "tags": ["tag1", "tag2"]
  }
]

TaskWarrior Export Format

[
  {
    "id": "tw-12345678",
    "content": "Task description", 
    "status": "pending",
    "priority": "high",
    "created": "2024-01-01T10:00:00Z",
    "modified": "2024-01-01T10:00:00Z",
    "due": "2024-01-15",
    "tags": ["tag1", "tag2"]
  }
]

Configuration

Configuration file: ~/.claude-taskwarrior.conf

# Default project name
PROJECT=claude-session

# Enable automatic sync
AUTO_SYNC=true

# Backup directory
BACKUP_DIR=/home/user/.claude-taskwarrior-backups

# Creation timestamp
CREATED=2024-01-01T10:00:00Z

Directory Structure

claude-taskwarrior/
├── claude-tw              # Main CLI script
├── sync.js                # Core sync engine
├── README.md              # This file
└── examples/              # Usage examples
    ├── basic-workflow.md
    └── advanced-usage.md

Backup System

• Automatic: Backups created before each sync operation
• Location: ~/.claude-taskwarrior-backups/
• Format: backup-project-timestamp-operation.json
• Manual: claude-tw backup creates manual backup

Example backup filename:

backup-claude-session-2024-01-01T10-00-00Z-pre-import.json

Error Handling

The system includes comprehensive error handling:

• Validation: Ensures todo structure integrity
• Graceful Degradation: Continues processing if some tasks fail
• Detailed Logging: Clear error messages with context
• Rollback: Backups enable easy recovery

Integration with Claude Code

Automatic Workflow

1. Session Start: claude-tw start
2. Import Existing: Shows existing TaskWarrior tasks for Claude Code import
3. Work in Claude Code: Use TodoWrite as normal
4. Sync Changes: claude-tw sync "$(claude-todos-json)"
5. Persistent Storage: Tasks persist in TaskWarrior
6. Session End: claude-tw end for summary

Manual Workflow

1. Export TaskWarrior tasks: claude-tw export
2. Copy output to Claude Code: TodoWrite <exported-json>
3. Work with todos in Claude Code
4. Sync back to TaskWarrior: claude-tw sync '<claude-json>'

Global Installation

The integration works from any directory and with any Claude Code session:

# Install globally
mkdir -p ~/bin
cp -r claude-taskwarrior ~/bin/
echo 'export PATH="$PATH:$HOME/bin/claude-taskwarrior"' >> ~/.bashrc
source ~/.bashrc

# Now works from anywhere
cd /any/directory
claude-tw start my-project

Development

Testing

# Test basic functionality
node sync.js import test-project '[{"id":"test","content":"Test task","status":"pending","priority":"medium"}]'
node sync.js export test-project
node sync.js summary test-project

# Test CLI
./claude-tw start test-session
./claude-tw status
./claude-tw end

Extension

The sync engine is modular and extensible:

const ClaudeTaskWarriorSync = require('./sync.js');
const sync = new ClaudeTaskWarriorSync();

// Custom usage
const todos = sync.exportTodos('my-project');
sync.importTodos('my-project', customTodos);

Troubleshooting

Common Issues

1. TaskWarrior not initialized

   task add "init task"
   task 1 delete

2. Permission denied

   chmod +x ~/bin/claude-taskwarrior/claude-tw

3. Node.js not found

   sudo apt install nodejs npm

4. jq not found

   sudo apt install jq

Debug Mode

Enable verbose output:

export CLAUDE_TW_DEBUG=1
claude-tw status

Log Files

Session logs: /tmp/claude-tw-session.json Error logs: Check terminal output during sync operations

Contributing

This project is open source. Contributions welcome:

1. Fork the repository
2. Create feature branch
3. Add tests for new functionality
4. Submit pull request

License

MIT License - see LICENSE file for details.

Credits

Built for integration with:

• Claude Code - Anthropic's AI coding assistant
• TaskWarrior - Command-line task management

---