Personal Assistant (PA)

A personal context system for AI agents that manages markdown-based context for efficient time management and task tracking.

Features

• Smart Scheduling: AI-powered scheduling based on task duration and profile preferences
• Task Management: Add, complete, and track tasks with markdown-based storage
• Email Integration: Create drafts or send emails directly from CLI
• Profile Learning: AI learns your work patterns to improve scheduling accuracy
• Rich CLI Interface: Beautiful terminal output with colors and tables
• Background Daemon: Optional background process for continuous monitoring
• Markdown Storage: All data stored in human-readable markdown files

Installation

Install the package in development mode:

pip install -e .

Setup

Initialize the Personal Assistant system:

tm init

This creates the data directory at ~/.tm with the following structure:

.tm/
├── today.md          # Today's schedule and tasks
├── tasks/
│   ├── backlog.md    # Unscheduled tasks
│   └── completed/    # Completed task archives
├── profile.json      # Your work profile and preferences
├── config.json       # System configuration
├── email.json       # Email configuration
├── daemon.log       # Background process logs
└── backups/         # Daily backup archives

Usage

Basic Commands

# Show today's schedule and tasks
tm today

# Add a task to today
tm add "Task description"

# Add a task with specific time
tm add "Task" --schedule "2pm"

# Mark a task as complete
tm complete "Task description"

# Generate a schedule from backlog
tm schedule today

# Generate schedule for tomorrow
tm schedule tomorrow

# Limit number of scheduled tasks
tm schedule today --max-tasks 3

Email Integration

# Create email draft
tm email --to recipient@example.com --subject "Meeting" "Meeting agenda..."

# Send email directly
tm email --to recipient@example.com --subject "Update" "Project update..." --send

# Use template
tm email --to team@company.com --template meeting.txt --subject "Team Meeting" "Hi team..."

Advanced Features

Profile Learning

The system learns your work patterns automatically. Tasks are scheduled based on:

• Historical completion times
• Preferred working hours
• Task complexity estimates
• Your personal productivity patterns

Smart Scheduling

• Tasks are assigned optimal time slots
• Buffer time is automatically added between tasks
• Breaks are scheduled based on your profile
• Overbooking is prevented

Background Daemon

Start the background process for continuous monitoring:

# Run daemon in background
tm daemon start

# Stop daemon
tm daemon stop

# Check daemon status
tm daemon status

Directory Structure

tm/
├── __init__.py         # Package initialization
├── cli.py             # Command-line interface
├── config.py          # Configuration management
├── daemon.py          # Background daemon process
├── email.py           # Email integration service
├── init.py            # Data directory initialization
├── learning.py        # Profile learning engine
├── markdown.py        # Markdown file parser/writer
├── scheduler.py       # Smart scheduling algorithm
└── writer.py          # Schedule file writer

File Formats

today.md

# Today - 2024-01-15

## Schedule
- 09:00-10:00: Morning standup meeting
- 10:30-12:00: Work on feature implementation

## Tasks
- [x] Morning standup meeting
- [ ] Work on feature implementation
- [ ] Review pull requests

backlog.md

# Backlog

- [ ] Implement user authentication
- [ ] Write unit tests
- [ ] Update documentation
- [ ] Deploy to staging

profile.json

{
  "working_hours": {
    "start": "09:00",
    "end": "17:00"
  },
  "preferred_break_duration": 15,
  "average_task_duration": 60,
  "productivity_patterns": {
    "morning": "high",
    "afternoon": "medium",
    "evening": "low"
  }
}

AI Agent Integration

Example Session with Claude

User: I need to finish the user authentication feature by Friday
Claude: I'll help you schedule this task. Let me check your current workload and find the best time slot.

tm add "Implement user authentication" --schedule "2pm today"

tm schedule today --max-tasks 5

User: Also need to write documentation for the new API endpoints
Claude: Adding that to your backlog...

tm add "Write API documentation"

tm schedule tomorrow --max-tasks 4

Prompts for AI Integration

1. Task Addition: "Add [task] to my schedule for [time/day]"
2. Schedule Review: "Show me my schedule for [today/tomorrow]"
3. Task Completion: "Mark [task] as complete"
4. Rescheduling: "Move [task] to [time/day]"
5. Email Integration: "Send email to [recipient] about [subject]"
6. Priority Adjustment: "I have more energy today, schedule harder tasks first"

Configuration

Email Setup

Create ~/.tm/email.json:

{
  "smtp_server": "smtp.gmail.com",
  "smtp_port": 587,
  "username": "your_email@gmail.com",
  "password": "your_app_password",
  "template_dir": "/path/to/templates"
}

System Configuration

Create ~/.tm/config.json:

{
  "data_dir": "~/.tm",
  "backup_enabled": true,
  "backup_interval": "daily",
  "daemon_enabled": false,
  "log_level": "INFO"
}

Testing

Run all tests:

pytest tests/ -v

Development

Running Tests

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_cli_commands.py -v

# Run with coverage
pytest tests/ --cov=tm --cov-report=html

Contributing

1. Create a new feature branch
2. Add tests for new functionality
3. Run the test suite
4. Submit a pull request

License

MIT License - see LICENSE file for details.