myorg-assistant/README.md

MyOrg Personal Assistant

An AI-powered personal assistant that helps manage daily life using the myorg GTD system.

Overview

The MyOrg Personal Assistant is an intelligent agent that helps you manage your personal organization system (myorg). It acts as a trusted assistant that can read, understand, and modify your GTD-based task management system, providing proactive help throughout your day.

Features

🤖 Intelligent Task Management

• Natural language task entry via Discord or web interface
• Automatic parsing of projects, contexts, priorities, and due dates
• Smart task completion with timestamps
• Context-aware task filtering

📅 Proactive Scheduling

• Morning Briefing (8:00 AM): Today's calendar, priority tasks, due soon items
• Evening Summary (8:00 PM): Accomplishments, tomorrow prep, reflection prompts
• Deadline Warnings: Hourly checks for overdue and upcoming deadlines
• Waiting List Follow-ups: Weekly reminders (Mondays 9 AM)
• Git Sync: Automatic sync every 15 minutes

💬 Multiple Interfaces

• Discord Bot: Quick access via mobile or desktop Discord
• Web Dashboard: Rich visual interface for detailed management
• CLI Mode: Testing and local development

🧠 Smart Features

• Context inference from time and calendar
• Project progress tracking
• Goal alignment (with telos.md integration)
• Automatic git commits for all changes

Technology Stack

• Backend: Python 3.11+, FastAPI, Discord.py
• AI: Claude Sonnet 4.5 via LiteLLM proxy
• Frontend: Vanilla CSS, HTMX, Jinja2 templates
• Storage: Git repository (todo.txt, calendar.txt, projects.txt)
• Deployment: Docker + Kubernetes (k3s)

Quick Start

Prerequisites

1. Python 3.11+
2. Git
3. LiteLLM Endpoint - Running instance with Claude API access
4. Discord Bot (optional) - For Discord integration
5. myorg Repository - Your GTD data repository

1. Clone and Install

# Clone repository
git clone <repository-url>
cd myorg-assistant

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configure Environment

# Copy example configuration
cp .env.example .env

Edit .env with your configuration:

# LiteLLM Configuration (REQUIRED)
LITELLM_ENDPOINT=http://localhost:4000  # Your LiteLLM proxy URL
LITELLM_API_KEY=your-api-key
LITELLM_MODEL=claude-sonnet-4-5

# Myorg Repository (REQUIRED)
MYORG_REPO_PATH=/path/to/your/myorg  # Local path to your myorg repo
GIT_REPO_URL=https://github.com/yourusername/myorg.git
GIT_USERNAME=yourusername
GIT_TOKEN=ghp_your_github_token
GIT_BRANCH=main

# Discord Bot (REQUIRED for Discord features)
DISCORD_BOT_TOKEN=your.discord.bot.token
DISCORD_CHANNEL_ID=123456789012345678

# Web Interface (OPTIONAL)
WEB_HOST=0.0.0.0
WEB_PORT=8000
WEB_SECRET_KEY=generate-random-secret-key-here
WEB_PASSWORD=optional-password-for-basic-auth

# Scheduling
TIMEZONE=Europe/Madrid  # Your timezone

3. Set Up Your myorg Repository

The assistant expects a myorg repository with these files:

myorg/
├── todo.txt          # Tasks in todo.txt format
├── calendar.txt      # Calendar events
├── projects.txt      # Active projects
├── waiting.txt       # Items waiting on others
├── telos.md          # Life vision and missions
└── goals/            # Quarterly goals (optional)

If you don't have one, you can use the test repository:

# For testing, point to the included test data
export MYORG_REPO_PATH=./tests/fixtures/test_myorg

4. Run Locally

CLI Mode (Testing)

python -m src.main cli

Example interactions:

• "List files in the repository"
• "Add task: Test the assistant with context computer-deep"
• "Show all active tasks"
• "What's on my calendar today?"

Discord Bot Mode

python -m src.main bot

The bot will connect to Discord and respond to mentions or DMs.

Web Interface Mode

python -m src.main web

Then visit: http://localhost:8000

Discord Bot Setup

Create Discord Bot

1. Go to Discord Developer Portal
2. Click "New Application" → Give it a name
3. Go to "Bot" section → Click "Add Bot"
4. Under "Privileged Gateway Intents", enable:
   • ✅ Message Content Intent
   • ✅ Server Members Intent
5. Click "Reset Token" → Save this token to .env as DISCORD_BOT_TOKEN
6. Go to "OAuth2" → "URL Generator"
   • Scopes: bot, applications.commands
   • Bot Permissions: Send Messages, Read Messages/View Channels, Read Message History
7. Copy the generated URL and invite bot to your server

Discord Commands

Once the bot is running:

Natural Conversation:

@MyOrgBot Add task: Buy groceries tomorrow @recados
@MyOrgBot What should I work on? I have 2 hours @computer-deep
@MyOrgBot Show my calendar for today

Commands:

• /help - Show all commands
• /briefing - Get daily briefing
• /add [task] - Quick task addition
• /tasks [filter] - Show tasks (optionally filtered)
• /today - Today's schedule and priority tasks
• /context [context] - Set current context
• /reset - Clear conversation history

Web Interface

The web interface provides:

Dashboard (/)

• Stats overview (events, tasks, projects)
• Today's schedule
• Priority tasks
• Due soon items
• Active projects

Chat (/chat)

• Full conversation with the agent
• HTMX-powered dynamic updates
• Natural language interaction

Tasks (/tasks)

• Complete task list
• Filter by project, context, priority
• Mark tasks complete
• Add new tasks

Calendar (/calendar)

• Today's events
• Upcoming week view
• All-day and timed events

Projects (/projects)

• All projects by status
• Task count per project
• Filter by status (active, waiting, someday, completed)

Kubernetes Deployment

Prerequisites

• k3s cluster running
• kubectl configured
• Docker for building images

1. Build and Load Image

# Build image
docker build -t myorg-assistant:latest .

# Load into k3s
docker save myorg-assistant:latest | sudo k3s ctr images import -

2. Create Secret

cd k8s
cp secret.yaml.example secret.yaml
# Edit secret.yaml with your actual credentials
kubectl apply -f secret.yaml

Important: Never commit secret.yaml to version control!

3. Deploy

# Automated deployment (recommended)
./deploy.sh

# Or manually
kubectl apply -f configmap.yaml
kubectl apply -f pvc.yaml
kubectl apply -f service.yaml
kubectl apply -f deployment.yaml
kubectl apply -f cronjobs/
kubectl apply -f ingress.yaml  # Optional: for external access

4. Verify Deployment

# Check pod status
kubectl get pods -l app=myorg-assistant

# View logs
kubectl logs -f deployment/myorg-assistant

# Check CronJobs
kubectl get cronjobs

# Expected output:
# myorg-morning-briefing     0 8 * * *       ...
# myorg-evening-summary      0 20 * * *      ...
# myorg-deadline-checker     0 * * * *       ...
# myorg-git-sync            */15 * * * *     ...
# myorg-waiting-followup     0 9 * * 1       ...

5. Access Web Interface

Internal Access (within cluster):

http://myorg-assistant-service.default.svc.cluster.local:8000

External Access (via Ingress):

1. Edit k8s/ingress.yaml with your domain
2. Apply: kubectl apply -f ingress.yaml
3. Access: https://myorg.yourdomain.com

Scheduled Jobs

The system runs these automated jobs:

Job	Schedule	Description
Morning Briefing	Daily 8:00 AM	Calendar + priority tasks + due soon
Evening Summary	Daily 8:00 PM	Completed tasks + tomorrow prep
Deadline Checker	Every hour	Warns about overdue/upcoming deadlines
Git Sync	Every 15 min	Pull/push repository changes
Waiting Follow-up	Mon 9:00 AM	Review waiting list items

All times use the timezone configured in TIMEZONE environment variable.

Configuration Reference

Environment Variables

Variable	Required	Default	Description
LITELLM_ENDPOINT	Yes	-	LiteLLM proxy URL
LITELLM_API_KEY	Yes	-	API key for LiteLLM
LITELLM_MODEL	No	claude-sonnet-4-5	Model name
MYORG_REPO_PATH	Yes	/data/myorg	Path to myorg repository
GIT_REPO_URL	Yes	-	Git repository URL
GIT_USERNAME	Yes	-	Git username
GIT_TOKEN	Yes	-	Git personal access token
GIT_BRANCH	No	main	Git branch to use
DISCORD_BOT_TOKEN	Yes*	-	Discord bot token (*for Discord)
DISCORD_CHANNEL_ID	Yes*	-	Default Discord channel ID
WEB_HOST	No	0.0.0.0	Web server host
WEB_PORT	No	8000	Web server port
WEB_SECRET_KEY	Yes**	-	Secret for sessions (**for web)
WEB_PASSWORD	No	-	Password for basic auth (optional)
TIMEZONE	No	Europe/Madrid	Timezone for schedules

File Formats

todo.txt Format:

(A) 2026-01-31 Write blog post +project @context due:2026-02-15
x 2026-01-30 Completed task +project

calendar.txt Format:

2026-02-01 09:00 Team meeting @telefon +work
2026-02-15 Birthday party @personal

projects.txt Format:

+project-name Description [active] @context goal:q1-2026 due:2026-02-28

Troubleshooting

Common Issues

Bot not responding in Discord:

• Check bot is online: kubectl logs -f deployment/myorg-assistant
• Verify Discord token in secret
• Ensure bot has proper permissions in server
• Check bot was mentioned or is receiving DMs

LiteLLM connection failed:

• Verify LITELLM_ENDPOINT is correct
• Check LiteLLM service is running: kubectl get svc litellm-service
• Test API key is valid

Git sync errors:

• Check git credentials in secret
• Verify repository URL is accessible
• Ensure PAT has repo permissions
• Check logs: kubectl logs job/myorg-git-sync-xxxxx

Web interface not accessible:

• Check pod is running: kubectl get pods
• Verify service: kubectl get svc myorg-assistant-service
• For external access, check ingress: kubectl get ingress

Logs and Debugging

# Main application logs
kubectl logs -f deployment/myorg-assistant

# Specific CronJob logs
kubectl logs job/myorg-morning-briefing-xxxxx

# Get into pod shell
POD=$(kubectl get pods -l app=myorg-assistant -o name | head -1)
kubectl exec -it $POD -- /bin/bash

# Inside pod:
cd /data/myorg
git status
ls -la
cat todo.txt

Development

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_todo_parser.py

# Run with coverage
pytest --cov=src tests/

Project Structure

src/
├── agent/              # Agent orchestration
│   ├── core.py         # MyOrgAgent class
│   └── prompts.py      # System prompts
├── tools/              # Agent tools
│   ├── file_ops.py     # File operations
│   ├── task_ops.py     # Task management
│   └── git_ops.py      # Git operations
├── parsers/            # Format parsers
│   ├── todo_parser.py
│   ├── calendar_parser.py
│   └── project_parser.py
├── api/                # Web interface
│   ├── app.py          # FastAPI app
│   └── routes/         # API routes
├── bot/                # Discord bot
│   ├── discord_bot.py
│   └── formatters.py
├── scheduler/          # Scheduled jobs
│   ├── briefings.py    # Briefing generators
│   └── jobs.py         # Job runners
└── utils/              # Utilities
    └── context.py      # Context inference

Documentation

• DEPLOYMENT.md - Detailed deployment guide
• project-plan.md - Full vision and architecture
• implementation-plan.md - Development phases
• todo.md - Implementation progress

Status

Version: 1.0.0
Status: Production Ready ✅
Completion: 83% (5 of 6 phases complete)

Completed Features

• ✅ Phase 0: Project Setup & Foundation
• ✅ Phase 1: Core Agent with File Tools
• ✅ Phase 2: Discord Bot Integration
• ✅ Phase 3: Scheduled Briefings & Reminders
• ✅ Phase 4: Web Interface

Optional Enhancements

• ⏳ Phase 5: Advanced Intelligence (goal tracking, analytics)
• ⏳ Phase 6: Polish & Optimization (caching, monitoring)

The system is fully functional and ready for daily use!

Contributing

This is a personal project, but suggestions and improvements are welcome via issues.

License

Private project for personal use.