Skip to content

README.md

Latest commit

 

History

History
548 lines (395 loc) · 12.4 KB

README.md

File metadata and controls

548 lines (395 loc) · 12.4 KB
image

📋 TaskFlow - Smart CLI Todo & Project Manager

Simple. Fast. Git-friendly.

A lightweight task management system that lives in your project directory. Perfect for developers who want todo lists without leaving the terminal.

🎯 Why TaskFlow?

Problem: Most task managers are either:

  • 🐌 Heavy GUI applications (Trello, Asana, Jira)
  • ☁️ Cloud-based (requires account, internet, privacy concerns)
  • 💰 Expensive subscriptions
  • 🔀 Not integrated with development workflow

Solution: TaskFlow gives you:

  • ✅ CLI-first - Fast, keyboard-driven workflow
  • ✅ Per-project - Tasks live in .taskflow.json in project root
  • ✅ Git-friendly - JSON format, easy to track and merge
  • ✅ Zero dependencies - Pure Python, no external packages
  • ✅ Cross-platform - Works on Windows, macOS, Linux
  • ✅ Markdown export - Share tasks in TASKS.md
  • ✅ Priority & tags - Organize however you want
  • ✅ Lightweight - < 500 lines of code

🚀 Quick Start

Installation

# Clone or download
cd TaskFlow

# Make executable (Unix/Linux/Mac)
chmod +x taskflow.py

# Run directly
python taskflow.py init

First Time Setup

# Navigate to your project
cd ~/my-project

# Initialize TaskFlow
python path/to/taskflow.py init

# ✅ TaskFlow initialized!
#    Task file: .taskflow.json

📖 Usage Guide

Add Tasks

# Simple add
python taskflow.py add "Implement user authentication"

# With priority
python taskflow.py add "Fix critical bug" --priority high

# With tags
python taskflow.py add "Write tests" --tags testing,important

# With due date
python taskflow.py add "Deploy v2.0" --due 2026-01-15

# Everything
python taskflow.py add "Refactor database" --priority medium --tags backend,refactor --due 2026-01-20

List Tasks

# List all tasks
python taskflow.py list

# Output:
# 📋 TaskFlow - 5 task(s)
#
# 🔄 🔴 [1] Fix critical bug
# ⬜ 🟡 [2] Implement user authentication
# ⬜ 🟡 [3] Refactor database
# ⬜ 🟢 [4] Write tests
# ✅ 🟡 [5] Deploy v2.0

# Filter by status
python taskflow.py list --status todo
python taskflow.py list --status in_progress
python taskflow.py list --status done

# Filter by priority
python taskflow.py list --priority high

# Filter by tag
python taskflow.py list --tag urgent

# Show details
python taskflow.py list --details

Update Task Status

# Mark as in progress
python taskflow.py start 1
# 🔄 Task started: [1] Fix critical bug

# Mark as done
python taskflow.py done 1
# ✅ Task completed: [1] Fix critical bug

# Mark as blocked
python taskflow.py block 3
# 🚫 Task blocked: [3] Refactor database

Edit Tasks

# Change title
python taskflow.py edit 2 --title "Implement OAuth authentication"

# Change priority
python taskflow.py edit 2 --priority high

# Update tags
python taskflow.py edit 2 --tags auth,security,urgent

# Update due date
python taskflow.py edit 2 --due 2026-01-12

# Multiple updates
python taskflow.py edit 2 --title "New title" --priority high --tags new,tags

Delete Tasks

# Delete task
python taskflow.py delete 4
# 🗑️  Task deleted: [4] Write tests

Export to Markdown

# Export all tasks
python taskflow.py export

# Custom output file
python taskflow.py export --output TODO.md

# Creates formatted TASKS.md with all tasks organized by status

View Statistics

# Show task stats
python taskflow.py stats

# Output:
# 📊 TaskFlow Statistics
#
# Total Tasks: 10
#
# By Status:
#   ⬜ Todo: 5 (50.0%)
#   🔄 In Progress: 2 (20.0%)
#   🚫 Blocked: 1 (10.0%)
#   ✅ Done: 2 (20.0%)
#
# By Priority:
#   🔴 High: 3 (30.0%)
#   🟡 Medium: 5 (50.0%)
#   🟢 Low: 2 (20.0%)

💡 Examples

Example 1: Starting a New Project

# Initialize TaskFlow
$ cd ~/new-project
$ python taskflow.py init
✅ TaskFlow initialized!

# Add initial tasks
$ python taskflow.py add "Setup project structure" --priority high
$ python taskflow.py add "Write README" --priority medium
$ python taskflow.py add "Configure CI/CD" --priority low --tags devops

# View all tasks
$ python taskflow.py list

📋 TaskFlow - 3 task(s)

⬜ 🔴 [1] Setup project structure
⬜ 🟡 [2] Write README
⬜ 🟢 [3] Configure CI/CD

📊 Summary:
   ⬜ Todo: 3

# Start working
$ python taskflow.py start 1
🔄 Task started: [1] Setup project structure

Example 2: Bug Tracking

# Add bugs with tags
$ python taskflow.py add "Login fails on mobile" --priority high --tags bug,mobile,urgent
$ python taskflow.py add "Memory leak in dashboard" --priority high --tags bug,performance
$ python taskflow.py add "Typo in footer" --priority low --tags bug,ui

# List all bugs
$ python taskflow.py list --tag bug

# Mark bug fixed
$ python taskflow.py done 1

Example 3: Sprint Planning

# Add sprint tasks
$ python taskflow.py add "User stories for auth" --priority high --tags sprint-1,planning
$ python taskflow.py add "API endpoint design" --priority high --tags sprint-1,backend
$ python taskflow.py add "UI mockups" --priority medium --tags sprint-1,frontend

# View sprint tasks
$ python taskflow.py list --tag sprint-1

# Export for team
$ python taskflow.py export --output SPRINT_1.md

Example 4: Daily Workflow

# Morning: Check what's in progress
$ python taskflow.py list --status in_progress

# Start new task
$ python taskflow.py start 5

# Complete a task
$ python taskflow.py done 3

# Add new urgent task
$ python taskflow.py add "Hotfix: API rate limiting" --priority high --tags hotfix,urgent

# Evening: Check stats
$ python taskflow.py stats

🔧 Advanced Usage

Git Integration

TaskFlow stores tasks in .taskflow.json - a Git-friendly JSON file.

# Track tasks in Git
git add .taskflow.json
git commit -m "Update project tasks"

# Share with team
git push

# Team members pull and see your tasks
git pull
python taskflow.py list

Pro tip: Add .taskflow.json to .gitignore if you want personal-only tasks, or commit it for team visibility.

Alias Setup

Make TaskFlow even faster:

# Bash/Zsh (~/.bashrc or ~/.zshrc)
alias tf='python /path/to/taskflow.py'

# Now use:
tf add "Quick task"
tf list
tf done 3
# PowerShell ($PROFILE)
function tf { python C:\path\to\taskflow.py $args }

# Now use:
tf add "Quick task"
tf list
tf done 3

Multiple Projects

Each project gets its own .taskflow.json:

# Project A
cd ~/project-a
python taskflow.py list  # Shows Project A tasks

# Project B
cd ~/project-b
python taskflow.py list  # Shows Project B tasks

Export Workflow

# Export tasks every Friday
python taskflow.py export --output WEEKLY_TASKS.md

# Commit to Git
git add WEEKLY_TASKS.md
git commit -m "Weekly task update"

📊 Task File Format

TaskFlow stores tasks in .taskflow.json:

{
  "tasks": [
    {
      "id": 1,
      "title": "Implement feature X",
      "priority": "high",
      "status": "in_progress",
      "tags": ["feature", "urgent"],
      "due_date": "2026-01-15",
      "created": "2026-01-09T08:00:00",
      "updated": "2026-01-09T10:30:00"
    }
  ],
  "last_updated": "2026-01-09T10:30:00"
}

Fields:

  • id - Unique task identifier (auto-generated)
  • title - Task description
  • priority - high, medium, or low
  • status - todo, in_progress, done, or blocked
  • tags - Array of strings for categorization
  • due_date - ISO format date (optional)
  • created - ISO timestamp
  • updated - ISO timestamp

🎨 Icons & Colors

TaskFlow uses visual indicators for quick scanning:

Status Icons:

  • ⬜ todo - Not started
  • 🔄 in_progress - Currently working
  • ✅ done - Completed
  • 🚫 blocked - Waiting on something

Priority Colors:

  • 🔴 high - Urgent, do first
  • 🟡 medium - Normal priority
  • 🟢 low - Do when time permits

Special Indicators:

  • ⚠️ - Task is overdue

📋 Commands Reference

Command Description Example
init Initialize TaskFlow in current directory taskflow init
add Add new task taskflow add "Task title" --priority high
list List all tasks taskflow list --status todo
start Mark task as in progress taskflow start 3
done Mark task as done taskflow done 5
block Mark task as blocked taskflow block 2
edit Edit task properties taskflow edit 4 --priority high
delete Delete task taskflow delete 7
export Export to Markdown taskflow export --output TASKS.md
stats Show task statistics taskflow stats

🔍 Use Cases

For Developers

  • Track bugs and features per project
  • Sprint planning and management
  • Daily task lists synced with Git
  • Personal TODO alongside codebase

For Teams

  • Commit .taskflow.json for shared visibility
  • Export to Markdown for status updates
  • Tag-based organization (sprints, epics)
  • Lightweight alternative to Jira

For Students

  • Track assignments per course
  • Organize study tasks by priority
  • Export for study group sharing
  • Due date reminders

For Freelancers

  • Per-client task tracking
  • Priority management across projects
  • Quick status updates for clients
  • No subscription costs

❓ FAQ

Q: How is this different from other todo apps?

A:

  • ✅ CLI-first - No GUI overhead, keyboard-driven
  • ✅ Per-project - Tasks live with your code
  • ✅ Git-friendly - JSON format, easy to track
  • ✅ Zero cost - No subscriptions, no accounts
  • ✅ Lightweight - One Python file, no dependencies

Q: Can I use this with a team?

A: Yes! Commit .taskflow.json to Git and your team sees the same tasks. Each person can run taskflow list to see current status.

Q: What about conflicts when multiple people edit?

A: Git handles JSON merges well. For heavy concurrent editing, consider using GitHub Issues or a dedicated tool instead.

Q: Can I have personal tasks AND shared tasks?

A: Yes! Keep .taskflow.json in .gitignore for personal tasks, or create a second file (.taskflow.personal.json) and run TaskFlow with a custom path.

Q: Does this work without Git?

A: Absolutely! TaskFlow doesn't require Git. It just stores tasks in a local JSON file. Git integration is optional.

Q: Can I import from other todo apps?

A: Not built-in yet, but the JSON format is simple. You could write a script to import from CSV, Trello export, etc.

Q: Is there a GUI version?

A: No. TaskFlow is CLI-only by design. For GUI, consider tools like Todoist, Trello, or Things.

Q: How do I back up my tasks?

A: The .taskflow.json file is your backup. Copy it, commit to Git, or sync with cloud storage (Dropbox, OneDrive, etc.).

image

🤝 Contributing

Found a bug? Have a feature idea? Contributions welcome!

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/AmazingFeature)
  3. Commit changes (git commit -m 'Add AmazingFeature')
  4. Push to branch (git push origin feature/AmazingFeature)
  5. Open Pull Request

📄 License

MIT License - see LICENSE file for details.

TL;DR: Free to use, modify, and distribute. No warranty provided.

🙏 Credits

Created by Randell Logan Smith and Team Brain at Metaphy LLC

Part of the HMSS (Heavenly Morning Star System) ecosystem.

Technology:

  • Python 3.6+
  • JSON for storage
  • argparse for CLI
  • Zero external dependencies

🚀 Quick Reference

# Initialize
taskflow init

# Add task
taskflow add "Task title" [--priority high|medium|low] [--tags tag1,tag2] [--due YYYY-MM-DD]

# List tasks
taskflow list [--status todo|in_progress|done|blocked] [--priority high|medium|low] [--tag TAG] [--details]

# Update status
taskflow start ID      # Mark as in progress
taskflow done ID       # Mark as done
taskflow block ID      # Mark as blocked

# Edit task
taskflow edit ID [--title "New title"] [--priority high|medium|low] [--tags tag1,tag2] [--due YYYY-MM-DD]

# Delete task
taskflow delete ID

# Export & stats
taskflow export [--output FILENAME]
taskflow stats

📋 Stay organized. Stay productive. Stay in the terminal.