A LangChain-powered AI agent that automates workflow management in Things3, helping you organize tasks, clean up your today view, and maintain productive daily routines.

• 🧠 AI-Powered: Uses LangChain with OpenAI models for intelligent task management
• 🔧 Custom Tools: Specialized MCP tools for Things3 operations
• 💬 Natural Language: Interact using plain English descriptions of what you want to accomplish
• ⚡ Quick Commands: CLI interface for both interactive chat and one-off operations

1. Things3: Must be installed and running on macOS
2. Python 3.8+: Required for the agent
3. OpenAI API Key: For the AI functionality

1. Clone the repository:

   git clone <repository-url>
   cd things3agent

2. Install Python dependencies:

   pip install -r requirements.txt

3. Run the interactive setup:

   python main.py setup

   This will:

   • Create a .env file for configuration
   • Prompt for your OpenAI API key
   • Test the connection to Things3
   • Verify everything is working

4. Alternative manual setup:

   cp .env.example .env
   # Edit .env and add your OPENAI_API_KEY

Start a conversation with the agent:

python main.py chat

Example conversations:

Setting up your work day:

You: I want to setup my today view so I can get to work. I need to focus on the MCP migration project and respond to Slack messages.

Agent: I'll help you set up your today view for work. Let me first check what's currently there...
[Agent analyzes current tasks, suggests cleanup actions, and creates relevant work tasks]

Cleaning up a cluttered today view:

You: My today view is messy and has old tasks. Help me clean it up and focus on high priority items.

Agent: I'll analyze your today view and suggest cleanup actions...
[Agent categorizes tasks, suggests moving low-priority items, and identifies what to keep]

Check current status:

python main.py status

• python main.py chat - Interactive chat session
• python main.py status - Show current Things3 status
• python main.py analyze "<query>" - Analyze today view with specific intent
• python main.py setup - Interactive setup and configuration
• python main.py --help - Show all available commands

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   User Input    │───▶│  LangChain Agent │───▶│  Things3 Tools  │
│  (Natural Lang) │    │  (GPT-4 + Tools) │    │   (MCP Based)   │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   Workflows     │    │ Things3 Client  │
                       │ (Smart Logic)   │    │  (things.py)    │
                       └─────────────────┘    └─────────────────┘
                                                       │
                                                       ▼
                                              ┌─────────────────┐
                                              │ Things3 Database│
                                              └─────────────────┘

1. Things3 Integration Layer (src/things3/): Wraps the things.py library with domain-specific operations
2. Custom MCP Tools (src/tools/): LangChain-compatible tools for Things3 operations
3. LangChain Agent (src/agent/): AI orchestrator that uses tools to accomplish tasks
4. Workflow Engine (src/workflows/): Specific implementations for common patterns
5. User Configuration (src/config/): Your personal taxonomy and organization patterns

The agent has access to these specialized tools:

• get_today_tasks - View current today view
• search_tasks - Find tasks by keyword
• get_work_tasks - Get all AMPL-tagged tasks
• create_task - Add new tasks with proper metadata (not implemented -- lib limiation requires an applet to be built)
• update_task_when - Reschedule or remove tasks from today -- (not implemented -- lib limiation requires an applet to be built)
• analyze_today_view - Smart analysis and cleanup suggestions

Create a .env file with:

# Required
OPENAI_API_KEY=your_openai_api_key_here

# Optional
AGENT_MODEL=gpt-4-turbo-preview     # AI model to use
AGENT_TEMPERATURE=0.1               # Model creativity (0.0-1.0)
LOG_LEVEL=INFO                      # Logging verbosity

Edit src/config/user_patterns.py to match your organization style:

# Your work tag
work_tag: str = "AMPL"

# Your work areas
work_areas: List[str] = ["Amplitude", "Other Work Area"]

# Priority tag range
priority_tags: Set[str] = {str(i) for i in range(1, 10)}

Query: "I want to setup my today view so that I can get to work. Here's what's on my mind — I want to get the ask amp -> mcp migration done for work, to respond to slack messages, and to get started on global chat"

What the agent does:

1. Analyzes current today view
2. Finds existing "mcp migration" tasks in the Amplitude area
3. Creates "Respond to Slack messages" task with AMPL tag
4. Finds existing "global chat" tasks or creates new ones
5. Suggests moving non-work tasks out of today view
6. Presents plan for confirmation

Query: "My today view is cluttered with old stuff. Help me clean it up."

What the agent does:

1. Analyzes all tasks in today view
2. Identifies old, low-priority, or irrelevant tasks
3. Suggests moving medium-priority tasks to tomorrow
4. Suggests removing when-date from low-priority tasks
5. Keeps high-priority and relevant tasks
6. Shows cleanup plan for approval

"Failed to connect to Things3"

• Ensure Things3 is installed and running
• Check that the Things3 database is accessible
• Try restarting Things3

"OpenAI API key not found"

• Verify your .env file contains OPENAI_API_KEY=your_key
• Ensure the .env file is in the project root directory
• Check that your API key is valid and has credits

"No tasks found" when you know tasks exist

• Things3 database might be in a different location
• Try restarting the application
• Check Things3 is the latest version

Run with verbose logging to see what's happening:

python main.py --log-level DEBUG chat

The agent auto-detects your Things3 database. If needed, you can manually specify:

export THINGS_DB_PATH="/path/to/Things3/database"

This project is designed to be customized for personal workflows. Key areas for customization:

1. User Patterns (src/config/user_patterns.py) - Modify to match your organization style
2. Workflows (src/workflows/) - Add new workflow automation
3. Tools (src/tools/) - Extend with new Things3 operations
4. Agent Prompts (src/agent/things3_agent.py) - Adjust AI behavior

Do whatever you'd like.

• things.py - Python library for Things3 integration
• LangChain - AI agent framework
• Things3 - The excellent todo app that makes this possible