{"id":29031665,"url":"https://github.com/ashwinma14/todoist-ai-assistant","last_synced_at":"2026-05-15T22:02:42.927Z","repository":{"id":299953658,"uuid":"1004060239","full_name":"ashwinma14/todoist-ai-assistant","owner":"ashwinma14","description":"Supercharge Todoist with AI: intelligent prioritization, labeling and section routing.","archived":false,"fork":false,"pushed_at":"2025-08-06T21:41:02.000Z","size":343,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-06T23:33:19.099Z","etag":null,"topics":["agent","ai-assistant","automation","cron-jobs","gpt","openai","productivity","python","task-manager","todoist","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ashwinma14.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-18T04:08:46.000Z","updated_at":"2025-08-06T21:41:05.000Z","dependencies_parsed_at":"2025-06-20T21:39:28.069Z","dependency_job_id":"77b89597-ddfa-4856-a9c8-5e9306ea79d3","html_url":"https://github.com/ashwinma14/todoist-ai-assistant","commit_stats":null,"previous_names":["ashwinma14/todoist-processor","ashwinma14/todoist-ai-assistant"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ashwinma14/todoist-ai-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashwinma14%2Ftodoist-ai-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashwinma14%2Ftodoist-ai-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashwinma14%2Ftodoist-ai-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashwinma14%2Ftodoist-ai-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashwinma14","download_url":"https://codeload.github.com/ashwinma14/todoist-ai-assistant/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashwinma14%2Ftodoist-ai-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279011293,"owners_count":26084928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai-assistant","automation","cron-jobs","gpt","openai","productivity","python","task-manager","todoist","workflow-automation"],"created_at":"2025-06-26T10:04:54.356Z","updated_at":"2025-10-12T12:37:02.639Z","avatar_url":"https://github.com/ashwinma14.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Todoist AI Assistant\n\nThe Todoist AI Assistant is an intelligent, context-aware automation system that transforms your [Todoist](https://todoist.com) into a clean, actionable workspace. Powered by the **TaskSense AI Engine**, it labels, organizes, and prioritizes your tasks — adapting to your personal work patterns and helping you focus on what matters most. All while maintaining transparency, configurability, and reliability.\n\n---\n\n## 🧠 What It Does\n\n### Smart Task Labeling\n\n- Understands task content in the context of your **user profile** and **current mode** (work, personal, weekend, etc.)\n- Applies the most relevant labels with **confidence scores** and clear explanations\n- Supports **reasoning levels**: minimal (labels only), light (labels + explanation), deep (labels + explanation + rationale)\n- Offers **soft matching mode**, suggesting new labels outside your predefined set for later review\n\n### Smart Daily Focus with GPT-Enhanced Reranker 🚀\n\n-   Ranks your backlog tasks and selects the most relevant ones for **Today**\n-   Populates a dedicated **Today section** with your top priorities\n-   Takes into account task priority, due date, age, and your preferred labels\n-   Leverages GPT to rerank top candidates with semantic understanding of your context\n-   Produces clear, human-readable explanations for each recommended task\n-   Enforces cost controls, confidence thresholds, and fallbacks for reliability\n-   Mode-aware prioritization (work, personal, weekend, evening) for context-appropriate suggestions\n-   Supports `--dry-run` so you can preview your Today list before applying\n    \n### GPT-Enhanced Reranking ✨\n\n- **Human-readable explanations** for every prioritization decision\n- **Cost-limited API usage** with configurable spending controls\n- **Confidence-based filtering** to ensure quality recommendations\n- **Rich CLI output** with urgency indicators and mode alignment insights\n- **JSON-based prompting** for reliable, structured responses\n- **Graceful fallbacks** when API limits or errors occur\n\n### URL \u0026 Domain Awareness\n\n- Detects and formats URLs in tasks into clean, readable `[Title](URL)` links\n- Adds platform-specific labels for common services like GitHub, YouTube, Reddit, and more\n\n### Section Routing\n\n- Moves tasks into appropriate sections (e.g., Links, Meetings, Urgent, Today) based on applied labels and rules\n- Respects existing `create_if_missing` and manual section setup\n\n### Rule \u0026 Fallback Logic\n\n- Processes tasks through a robust pipeline:\n  1. TaskSense AI Engine\n  2. Configurable Rule-Based Labeler (`rules.json`)\n  3. GPT fallback (if enabled)\n  4. Default label\n- Ensures graceful degradation even in case of network errors or API limits\n\n### Mode Awareness\n\n- Automatically adapts to the day of week and time of day (work hours, evenings, weekends)\n- CLI flags let you override or specify mode (`--mode=work`, `--mode=personal`, etc.)\n\n---\n\n## 🚀 Why Use It?\n\n✅ Personalized, context-aware task organization  \n✅ Transparent and trustworthy with clear explanations and logs  \n✅ Automatically identifies what to focus on today  \n✅ Modular and extensible architecture, ready for advanced features  \n✅ Developer-friendly with mock modes, validation tools, and structured logging  \n✅ Backward compatible with your existing Todoist setup and rules\n\n---\n\n## 🧰 Key Components\n\n- **TaskSense AI Engine:** Core semantic engine responsible for intelligent labeling, reasoning, and prioritization\n- **Pipeline Architecture:** Modular stages for labeling, rules, domain detection, ranking, and section routing\n- **Unified Configuration:** Centralized `task_sense_config.json` and `ranking_config.json` plus optional overrides via CLI or env vars\n- **Testing \u0026 Validation:** Mock modes, regression tests, config validation script (`validate_config.py`)\n- **Logging:** Detailed, structured logs with explanations, scores, confidence levels, and version metadata\n\n---\n\n## 🔧 Configuration Setup\n\nAfter cloning the repository, you'll need to set up your personal configuration files:\n\n```bash\n# Copy the example configuration files\ncp task_sense_config.example.json task_sense_config.json\ncp rules.example.json rules.json\ncp ranking_config.example.json ranking_config.json\n\n# Edit them for your personal workflow\n# task_sense_config.json - Contains your user profile, labels, and AI settings\n# rules.json - Contains your labeling rules and section routing preferences\n# ranking_config.json - Controls scoring weights and Today list preferences\n```\n\n**Important:**  \n⚠️ **Never commit `task_sense_config.json`, `rules.json`, or `ranking_config.json` to GitHub** — they contain your personal data  \n✅ The `.example.json` files are templates provided for your customization  \n📝 Customize the `user_profile` field in `task_sense_config.json` and the scoring weights in `ranking_config.json` to match your priorities\n\n### Environment Variables\n\nCreate a `.env` file for your API keys and settings:\n\n```bash\nTODOIST_API_TOKEN=your_todoist_token_here\nOPENAI_API_KEY=your_openai_key_here  # Optional, for GPT fallback\nPROJECT_NAMES=YourProjectName\n```\n\n### Render Deployment\n\nFor deploying to Render.com or similar platforms:\n1. Upload your personalized config files directly to the deployment environment\n2. Or use environment variables to specify custom config paths:\n   - `TASK_SENSE_CONFIG_PATH=/path/to/your/config.json`\n   - `RULES_CONFIG_PATH=/path/to/your/rules.json`\n   - `RANKING_CONFIG_PATH=/path/to/your/ranking_config.json`\n\n---\n\n## 📋 Example CLI Usage\n\n```bash\n# Process inbox in work mode\npython main.py --mode=work\n\n# Generate today's prioritized task list\npython main.py --generate-today --mode=work --limit=3\n\n# Use GPT-enhanced reranking with cost controls\npython main.py --generate-today --gpt-rerank --mode=work --limit=5\n\n# Preview GPT reranking without making changes\npython main.py --generate-today --gpt-rerank --dry-run --limit=3\n\n# Legacy GPT-enhanced ranking (always enabled)\npython main.py --generate-today --gpt-enhanced-ranking --limit=3\n\n# Refresh Today section and regenerate\npython main.py --generate-today --mode=personal --limit=5 --refresh-today\n\n# Auto-detect mode based on time\npython main.py --generate-today --mode=auto\n\n# Ignore last run timestamp (useful for cloud environments)\npython main.py --generate-today --gpt-rerank --ignore-last-run\n```\n\n### 🛠️ CLI Options\n\n- `--mode` - Set TaskSense mode (`personal`, `work`, `weekend`, `evening`, `auto`)\n- `--generate-today` - Generate today's prioritized task list using TaskSense ranking\n- `--gpt-rerank` - Enable GPT-powered reranking with cost controls\n- `--limit` - Number of tasks to select for today (default: 3)\n- `--dry-run` - Preview changes without modifying any tasks\n- `--verbose` - Enable verbose output\n- `--full-scan` - Process all tasks, ignoring last run timestamp\n- `--ignore-last-run` - Bypass last run timestamp check (useful for cloud environments)\n- `--refresh-today` - Clear and regenerate today's task list\n- `--project` - Comma-separated list of project names to process\n- `--fix-sections` - Force section routing for tasks with labels but missing section assignments\n\n---\n\n## 📊 Example Output\n\n```text\nTask 123 | TaskSense: #personal (v1.4.0, light) | Confidence: 0.85 | Explanation: Daycare tour aligns with parenting goals\n\nRANK_CANDIDATES: Task 12345 → Score: 0.82 | Reason: High priority and overdue\nTODAY_MOVE: Task 12345 moved to Today section\n```\n\nSoft-matched labels and daily focus scores are logged and surfaced in the feedback workflow for later review.\n\n---\n\n## 📜 License\n\nMIT License. See `LICENSE` for details.\n\n---\n\n## 🙏 Acknowledgments\n\n- Enhanced with the Todoist API ecosystem\n\n---\n\nThe Todoist AI Assistant turns your cluttered task list into a personalized, focused, and manageable system — so you can spend less time organizing and more time doing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashwinma14%2Ftodoist-ai-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashwinma14%2Ftodoist-ai-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashwinma14%2Ftodoist-ai-assistant/lists"}