📅 timeblock-agent

AI-powered time blocking and schedule management with natural language understanding

A comprehensive CLI + GUI tool that combines manual task entry, Claude AI integration, calendar sync, and visual time blocking to help researchers, developers, and knowledge workers optimize their schedules.

---

✨ Features

🤖 AI-Powered Intelligence

• Natural Language Parsing: Convert daily briefings into structured tasks
  • "Today: team meeting (90min), code review (1h), write docs (2h)"
• Weekly Goals Extraction: Parse high-level goals with time estimates
• Smart Scheduling: AI suggests optimal time blocks based on task types
• Conflict Detection: Identifies overlapping tasks and overcommitments
• 💬 Chat Interface: Ask questions about your schedule in natural language
  • "What's my busiest day this week?"
  • "Do I have time for a 2-hour task today?"
  • "What should I prioritize tomorrow?"

📊 Multiple Interfaces

• CLI: 12 commands for quick task management
• Streamlit GUI: Visual timeline with drag-and-drop scheduling
• Calendar Sync: Bidirectional sync with Calcurse, Todo.txt, and Outlook

📁 Data Management

• JSON-based state persistence (~/.timeblock/state.json)
• Task categories: meeting, analysis, admin, development, other
• Duration parsing: 90min, 1.5h, 2h30m, etc.
• Weekly goals tracking with progress monitoring

---

🚀 Quick Start

Installation

git clone https://github.com/yourusername/timeblock-agent.git
cd timeblock-agent
pip install -e .

Setup API Key (for AI features)

# Create .env file
cp .env.example .env

# Add your Anthropic API key
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

Basic Usage

# Initialize
timeblock init

# Add tasks manually
timeblock add -t "Team meeting" -d 90min
timeblock add -t "Code review" -d 1h

# OR use natural language
timeblock daily "Today I'm working on: documentation (2h), standup (30min), PR reviews (90min)"

# View your schedule
timeblock today

# Get AI insights
timeblock brief

# Ask questions
timeblock chat "Am I overcommitted today?"

# Launch GUI
streamlit run app.py

---

📖 CLI Commands

Task Management

Command	Description	Example
add	Add a new task	timeblock add -t "Meeting" -d 90min
today	Show today's schedule	timeblock today
week	Show this week's schedule	timeblock week
list	List all tasks with filters	timeblock list --status pending
complete	Mark task as completed	timeblock complete "Meeting"

AI-Powered Commands

Command	Description	Example
daily	Parse daily briefing	timeblock daily "Today: meeting (90min), code review (1h)"
weekly	Parse weekly goals	timeblock weekly "This week: finish pipeline (~8h), write docs (~4h)"
brief	Morning briefing with AI suggestions	timeblock brief
chat	Ask questions about your schedule	timeblock chat "What's my busiest day?"

Calendar Sync

Command	Description	Example
sync	Sync with external calendar	timeblock sync --backend calcurse
sync --pull	Import events from calendar	timeblock sync --pull --backend todotxt
sync --push	Export tasks to calendar	timeblock sync --push --backend outlook

Utilities

Command	Description	Example
init	Initialize or reset state	timeblock init
export	Export state as JSON	timeblock export > backup.json

---

💬 Chat Feature Examples

Ask your schedule anything in natural language:

# Check availability
timeblock chat "Do I have time for a 3-hour task today?"

# Find optimal days
timeblock chat "What's my least busy day this week?"

# Get insights
timeblock chat "How many meetings do I have this week?"

# Workload analysis
timeblock chat "Am I overcommitted?"

# Priorities
timeblock chat "What should I focus on tomorrow?"

# Category breakdown
timeblock chat "How much time am I spending on development vs meetings?"

The AI analyzes your full schedule context including:

• Today's tasks and time blocks
• Weekly tasks and goals
• Recently completed tasks
• Work hours configuration

---

🖥️ Streamlit GUI

Launch the visual interface:

streamlit run app.py
# Access at http://localhost:8501

GUI Features:

• 📅 Today View: Timeline with scheduled and unscheduled tasks
• 📊 Week View: Weekly overview with goals dashboard
• 📋 All Tasks: Filterable task list
• ➕ Add Tasks: Form with auto-categorization
• ⏰ Schedule Tasks: Time picker for unscheduled items
• ✅ Quick Actions: Complete, delete, or reschedule tasks
• 🎨 Color Coding: Tasks color-coded by category

---

📅 Calendar Integration

Calcurse

# Two-way sync with Calcurse
timeblock sync --backend calcurse

# Pull events only
timeblock sync --pull --backend calcurse

# Push tasks only
timeblock sync --push --backend calcurse

Todo.txt

# Sync with todo.txt
timeblock sync --backend todotxt

# Configure path in .env
echo "TODOTXT_PATH=~/todo.txt" >> .env

Microsoft Outlook

# Setup Azure credentials (see docs)
export AZURE_TENANT_ID=...
export AZURE_CLIENT_ID=...
export AZURE_CLIENT_SECRET=...

# Sync with Outlook
timeblock sync --backend outlook

---

🎯 Use Cases

Researchers

# Monday morning
timeblock daily "Today: lab meeting (2h), RNA-seq analysis (4h), read 2 papers (1.5h)"
timeblock brief  # Get AI suggestions for optimal scheduling

# Set weekly goals
timeblock weekly "This week: finish seq pipeline (~12h), write methods section (~8h), review grant (~4h)"

Developers

# Sprint planning
timeblock daily "Today: standup (30min), code review (1h), feature dev (4h), documentation (1h)"
timeblock sync --pull --backend outlook  # Import team meetings

# Check capacity
timeblock chat "Can I take on a 6-hour project this week?"

Knowledge Workers

# Daily workflow
timeblock add -t "Email catch-up" -d 30min
timeblock add -t "Client presentation" -d 90min
timeblock add -t "Report writing" -d 2h

# Get insights
timeblock chat "How much admin time do I have this week?"
timeblock brief  # See conflicts and suggestions

---

📂 Project Structure

timeblock-agent/
├── timeblock/
│   ├── __init__.py           # Package initialization
│   ├── state.py              # JSON state management
│   ├── utils.py              # Helper functions (time parsing, formatting)
│   ├── cli.py                # CLI with 12 commands
│   ├── agent.py              # Claude AI integration (NLP, chat, suggestions)
│   └── calendars/            # Calendar sync backends
│       ├── __init__.py       # Abstract base class
│       ├── calcurse.py       # Calcurse integration
│       ├── todotxt.py        # Todo.txt integration
│       └── outlook.py        # Microsoft Graph API
├── app.py                    # Streamlit GUI
├── docs/                     # Sphinx documentation
├── setup.py                  # Package configuration
├── requirements.txt          # Dependencies
├── .env.example              # Environment template
├── README.md                 # This file
└── ROADMAP.md                # Development roadmap

---

🔧 Configuration

Edit ~/.timeblock/state.json or use environment variables:

# Work hours
WORK_START=09:00
WORK_END=17:00
TIMEZONE=America/New_York

# AI features
ANTHROPIC_API_KEY=sk-ant-...

# Calendar paths
CALCURSE_PATH=~/.local/share/calcurse
TODOTXT_PATH=~/todo.txt

# Outlook (Azure app registration required)
AZURE_TENANT_ID=...
AZURE_CLIENT_ID=...
AZURE_CLIENT_SECRET=...

---

📚 Documentation

Full API documentation available at docs/:

# Build documentation
cd docs
make html

# View in browser
open build/html/index.html

Topics covered:

• Installation & Setup
• CLI Reference (all commands)
• API Reference (Python modules)
• Calendar Sync Guide
• Streamlit GUI Tutorial
• Advanced Usage & Best Practices

---

🤝 Contributing

Contributions welcome! Areas for enhancement:

• Additional calendar integrations (Google Calendar, iCal)
• Mobile app
• Recurring tasks
• Analytics dashboard
• Export to PDF/CSV
• Voice input
• Slack/Discord integration

---

📜 License

MIT License - see LICENSE file for details

---

🙏 Acknowledgments

• Built with Claude by Anthropic
• UI powered by Streamlit
• Calendar sync supports Calcurse, Todo.txt, and Microsoft Outlook

---

📞 Support

• Documentation: See docs/ directory
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Happy time blocking! ⚡📅