Skip to content
Back to search

todo-for-ai

πŸ€– A comprehensive task management system specifically designed for AI assistants. Supports project management, task tracking, team collaboration, and seamless AI integration through MCP (Model Context Protocol). Built with modern tech stack including React, Flask, and Docker. Try it now at https://todo4ai.org/

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/todo-for-ai--todo-for-ai/badge.svg)](/listings/todo-for-ai--todo-for-ai)

HTML

<a href="/listings/todo-for-ai--todo-for-ai"><img src="/api/listings/todo-for-ai--todo-for-ai/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Choose your preferred installation method:

🐳 **Option 1: Docker (Recommended)**

The fastest way to get started - everything included in one container:

# Pull and run the latest image
docker run -d --name todo-for-ai \
  -p 50111:80 \
  -p 50110:50110 \
  -e DATABASE_URL="mysql+pymysql://username:password@host.docker.internal:3306/todo_for_ai" \
  -e GMAIL_USER="your-email@gmail.com" \
  -e GMAIL_PASSWORD="your-app-password" \
  -e GITHUB_TOKEN="your-github-token" \
  -e SECRET_KEY="your-secret-key-here" \
  -e JWT_SECRET_KEY="your-jwt-secret-key-here" \
  --add-host=host.docker.internal:host-gateway \
  todoforai/todo-for-ai:latest

# Access the application
# Frontend: http://localhost:50111/todo-for-ai/pages/projects
# API: http://localhost:50110/todo-for-ai/api/v1/

πŸ“¦ **Option 2: MCP Package Only**

If you only need the MCP server for AI assistant integration:

# Install via npm
npm install -g @todo-for-ai/mcp

# Or install locally
npm install @todo-for-ai/mcp

# Configure and start
todo-for-ai-mcp --config config.json

πŸ› οΈ **Option 3: Development Setup**

For developers who want to contribute or customize:

# 1. Clone the project (including submodules)
git clone --recursive https://github.com/todo-for-ai/todo-for-ai.git
cd todo-for-ai

# 2. Initialize submodules (if not using --recursive)
git submodule update --init --recursive

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# 4. Start with Docker Compose
docker-compose up -d

# Or build and run manually
docker build -t todo-for-ai:latest .
docker run -d --name todo-for-ai [environment variables] todo-for-ai:latest

⚑ **Option 4: Source Installation**

For advanced users who prefer manual setup:

# 1. Clone and setup
git clone --recursive https://github.com/todo-for-ai/todo-for-ai.git
cd todo-for-ai

# 2. Backend setup
cd todo-for-ai-api-server
pip install -r requirements.txt
python app.py

# 3. Frontend setup (new terminal)
cd ../todo-for-ai-webpage
npm install
npm run build
npm run preview

# 4. MCP server setup (new terminal)
cd ../todo-for-ai-mcp
npm install
npm run build
npm start

βœ… Runtime E2E Validation (Local)

From repository root, you can run one-shot runtime validation:

# auto-create one AI task and verify commit -> DONE
./scripts/runtime_e2e_once.sh

# strict mode: first observed commit must match the target task
TARGET_TASK_ID=123456 STRICT_TARGET_ONLY=true ./scripts/runtime_e2e_once.sh

This wrapper calls `agent-runtime/scripts/run_docker_e2e_once.sh` and works with Colima/Docker local environments.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 528 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Todo for AI
  2. [![GitHub stars](https://img.shields.io/github/stars/todo-for-ai/todo-for-ai?style=flat-square)](https://github.com/todo-for-ai/todo-for-ai/stargazers)
  3. [![GitHub license](https://img.shields.io/github/license/todo-for-ai/todo-for-ai?style=flat-square)](https://github.com/todo-for-ai/todo-for-ai/blob/main/LICENSE)
  4. [![GitHub issues](https://img.shields.io/github/issues/todo-for-ai/todo-for-ai?style=flat-square)](https://github.com/todo-for-ai/todo-for-ai/issues)
  5. [![GitHub forks](https://img.shields.io/github/forks/todo-for-ai/todo-for-ai?style=flat-square)](https://github.com/todo-for-ai/todo-for-ai/network)
  6. [![npm version](https://img.shields.io/npm/v/@todo-for-ai/mcp?style=flat-square&label=MCP%20version)](https://www.npmjs.com/package/@todo-for-ai/mcp)
  7. [![Docker Pulls](https://img.shields.io/docker/pulls/todoforai/todo-for-ai?style=flat-square)](https://hub.docker.com/r/todoforai/todo-for-ai)
  8. [![Website](https://img.shields.io/website?url=https%3A//todo4ai.org&style=flat-square)](https://todo4ai.org)
  9. [δΈ­ζ–‡η‰ˆζœ¬](README_zh.md) | **English**
  10. πŸš€ **A powerful task management system specifically designed for AI assistants**, supporting intelligent project management, automated task tracking, and seamless team collaboration through MCP (Model Context Protocol) integration.
  11. > πŸš€ **Try it now**: Visit [https://todo4ai.org/](https://todo4ai.org/) to experience our product!
  12. ## πŸ€– Why Todo for AI?
  13. **Todo for AI** bridges the gap between AI assistants and human productivity workflows. Unlike traditional task management tools, our system is built from the ground up to work seamlessly with AI agents through the Model Context Protocol (MCP).
  14. ### 🎯 **Core Value Propositions**
  15. - **πŸ”— Native AI Integration**: First-class support for AI assistants through MCP, enabling natural language task management
  16. - **🧠 Intelligent Automation**: AI agents can create, update, and manage tasks autonomously based on context and user needs
  17. - **πŸ“Š Smart Project Insights**: AI-powered analytics and recommendations for better project planning and execution
  18. - **πŸ”„ Seamless Workflow**: Bridge between AI capabilities and human oversight with intelligent task delegation
  19. - **🌐 Universal Compatibility**: Works with Claude, GPT, and other AI assistants through standardized MCP protocol
  20. - **⚑ Real-time Collaboration**: Instant synchronization between AI agents and human team members
  21. ### πŸš€ **Perfect For**
  22. - **AI-First Teams** building the future of work
  23. - **Developers** integrating AI assistants into their workflows
  24. - **Product Managers** coordinating between AI agents and human teams
  25. - **Researchers** managing complex AI-driven projects
  26. - **Anyone** looking to supercharge their productivity with AI assistance
  27. ## πŸ“Έ Screenshots & Demo
  28. ### πŸ–₯️ **Web Interface**
  29. <div align="center">
  30. ![Todo for AI Dashboard](docs/images/en/dashboard-preview.png)
  31. *Modern, intuitive dashboard for project and task management*
  32. ![Task Management](docs/images/en/task-management.png)
  33. *Comprehensive task management with AI integration*
  34. ![AI Assistant Integration](docs/images/en/ai-integration.png)
  35. *Seamless AI assistant integration through MCP*
  36. </div>
  37. ### 🎬 **Demo Video**
  38. [![Todo for AI Demo](https://img.youtube.com/vi/L5SjoKRzJXQ/0.jpg)](https://www.youtube.com/watch?v=L5SjoKRzJXQ&t=30s)
  39. *Click to watch a full demo of Todo for AI in action*
  40. ### ✨ **Key Features in Action**
  41. - πŸ€– **AI-Powered Task Creation**: Watch AI assistants create and organize tasks naturally
  42. - πŸ“Š **Real-time Analytics**: See project progress and insights update live
  43. - πŸ”„ **Seamless Collaboration**: Experience smooth coordination between AI and human team members
  44. - 🎯 **Smart Prioritization**: Observe AI-driven task prioritization and scheduling
  45. ## πŸ“ Project Structure
  46. This project uses Git Submodule architecture, splitting different modules into independent repositories:
  47. - **todo-for-ai-api-server/**: Backend API server β†’ [todo-for-ai-api-server](https://github.com/todo-for-ai/todo-for-ai-api-server)
  48. - **todo-for-ai-webpage/**: Frontend web application β†’ [todo-for-ai-webpage](https://github.com/todo-for-ai/todo-for-ai-webpage)
  49. - **todo-for-ai-mcp/**: MCP server β†’ [todo-for-ai-mcp](https://github.com/todo-for-ai/todo-for-ai-mcp)
  50. ## πŸ“š Architecture & Specs
  51. - [Agent Platform Spec v1.0](docs/AGENT_PLATFORM_SPEC.md)
  52. - [API Documentation](docs/API.md)
  53. - [Database Design](docs/database-design.md)
  54. ## πŸš€ Installation & Quick Start
  55. Choose your preferred installation method:
  56. ### 🐳 **Option 1: Docker (Recommended)**
  57. The fastest way to get started - everything included in one container:
  58. ```bash
  59. # Pull and run the latest image
  60. docker run -d --name todo-for-ai \
  61. -p 50111:80 \
  62. -p 50110:50110 \
  63. -e DATABASE_URL="mysql+pymysql://username:password@host.docker.internal:3306/todo_for_ai" \
  64. -e GMAIL_USER="your-email@gmail.com" \
  65. -e GMAIL_PASSWORD="your-app-password" \
  66. -e GITHUB_TOKEN="your-github-token" \
  67. -e SECRET_KEY="your-secret-key-here" \
  68. -e JWT_SECRET_KEY="your-jwt-secret-key-here" \
  69. --add-host=host.docker.internal:host-gateway \
  70. todoforai/todo-for-ai:latest
  71. # Access the application
  72. # Frontend: http://localhost:50111/todo-for-ai/pages/projects
  73. # API: http://localhost:50110/todo-for-ai/api/v1/
  74. ```
  75. ### πŸ“¦ **Option 2: MCP Package Only**
  76. If you only need the MCP server for AI assistant integration:
  77. ```bash
  78. # Install via npm
  79. npm install -g @todo-for-ai/mcp
  80. # Or install locally
  81. npm install @todo-for-ai/mcp
  82. # Configure and start
  83. todo-for-ai-mcp --config config.json
  84. ```
  85. ### πŸ› οΈ **Option 3: Development Setup**
  86. For developers who want to contribute or customize:
  87. ```bash
  88. # 1. Clone the project (including submodules)
  89. git clone --recursive https://github.com/todo-for-ai/todo-for-ai.git
  90. cd todo-for-ai
  91. # 2. Initialize submodules (if not using --recursive)
  92. git submodule update --init --recursive
  93. # 3. Set up environment variables
  94. cp .env.example .env
  95. # Edit .env with your configuration
  96. # 4. Start with Docker Compose
  97. docker-compose up -d
  98. # Or build and run manually
  99. docker build -t todo-for-ai:latest .
  100. docker run -d --name todo-for-ai [environment variables] todo-for-ai:latest
  101. ```
  102. ### ⚑ **Option 4: Source Installation**
  103. For advanced users who prefer manual setup:
  104. ```bash
  105. # 1. Clone and setup
  106. git clone --recursive https://github.com/todo-for-ai/todo-for-ai.git
  107. cd todo-for-ai
  108. # 2. Backend setup
  109. cd todo-for-ai-api-server
  110. pip install -r requirements.txt
  111. python app.py
  112. # 3. Frontend setup (new terminal)
  113. cd ../todo-for-ai-webpage
  114. npm install
  115. npm run build
  116. npm run preview
  117. # 4. MCP server setup (new terminal)
  118. cd ../todo-for-ai-mcp
  119. npm install
  120. npm run build
  121. npm start
  122. ```
  123. ### βœ… Runtime E2E Validation (Local)
  124. From repository root, you can run one-shot runtime validation:
  125. ```bash
  126. # auto-create one AI task and verify commit -> DONE
  127. ./scripts/runtime_e2e_once.sh
  128. # strict mode: first observed commit must match the target task
  129. TARGET_TASK_ID=123456 STRICT_TARGET_ONLY=true ./scripts/runtime_e2e_once.sh
  130. ```
  131. This wrapper calls `agent-runtime/scripts/run_docker_e2e_once.sh` and works with Colima/Docker local environments.
  132. ## 🎯 Quick Start Examples
  133. ### πŸ€– **Using with AI Assistants (MCP)**
  134. Once installed, you can immediately start using Todo for AI with your favorite AI assistant:
  135. ```javascript
  136. // Example: Claude Desktop MCP Configuration
  137. {
  138. "mcpServers": {
  139. "todo-for-ai": {
  140. "command": "npx",
  141. "args": ["@todo-for-ai/mcp"],
  142. "env": {
  143. "TODO_API_URL": "http://localhost:50110/todo-for-ai/api/v1",
  144. "TODO_API_KEY": "your-api-key"
  145. }
  146. }
  147. }
  148. }
  149. ```
  150. ```bash
  151. # Example AI Commands (Natural Language)
  152. "Create a new project called 'Website Redesign'"
  153. "Add a task 'Design homepage mockup' to the Website Redesign project"
  154. "List all my pending tasks"
  155. "Mark the homepage mockup task as completed"
  156. "Show me project progress for this week"
  157. ```
  158. ### 🌐 **Web Interface Usage**
  159. ```bash
  160. # 1. Access the web interface
  161. open http://localhost:50111/todo-for-ai/pages/projects
  162. # 2. Login with GitHub OAuth or create account
  163. # 3. Create your first project
  164. # 4. Add tasks and start collaborating with AI assistants
  165. ```
  166. ### πŸ”§ **API Integration**
  167. ```javascript
  168. // Example: Creating a project via API
  169. const response = await fetch('http://localhost:50110/todo-for-ai/api/v1/projects', {
  170. method: 'POST',
  171. headers: {
  172. 'Content-Type': 'application/json',
  173. 'Authorization': 'Bearer your-jwt-token'
  174. },
  175. body: JSON.stringify({
  176. name: 'My AI Project',
  177. description: 'A project managed by AI assistants'
  178. })
  179. });
  180. // Example: Adding a task
  181. const taskResponse = await fetch('http://localhost:50110/todo-for-ai/api/v1/tasks', {
  182. method: 'POST',
  183. headers: {
  184. 'Content-Type': 'application/json',
  185. 'Authorization': 'Bearer your-jwt-token'
  186. },
  187. body: JSON.stringify({
  188. project_id: 1,
  189. title: 'Implement user authentication',
  190. content: 'Add OAuth integration for secure user login',
  191. priority: 'high',
  192. is_ai_task: true
  193. })
  194. });
  195. ```
  196. ### πŸ“± **MCP Server Configuration**
  197. ```json
  198. // config.json for MCP server
  199. {
  200. "server": {
  201. "host": "localhost",
  202. "port": 3001
  203. },
  204. "api": {
  205. "baseUrl": "http://localhost:50110/todo-for-ai/api/v1",
  206. "timeout": 30000
  207. },
  208. "auth": {
  209. "type": "jwt",
  210. "token": "your-jwt-token"
  211. },
  212. "features": {
  213. "autoCreateProjects": true,
  214. "smartTaskBreakdown": true,
  215. "contextualInsights": true
  216. }
  217. }
  218. ```
  219. ## πŸš€ Docker Deployment
  220. ### 1. Build image
  221. ```bash
  222. docker build -t todo-for-ai:latest .
  223. ```
  224. ### 2. Start container
  225. ```bash
  226. docker run -d --name todo-for-ai \
  227. -p 50111:80 \
  228. -p 50110:50110 \
  229. -e DATABASE_URL="mysql+pymysql://username:password@host.docker.internal:3306/todo_for_ai" \
  230. -e GMAIL_USER="your-email@gmail.com" \
  231. -e GMAIL_PASSWORD="your-app-password" \
  232. -e GITHUB_TOKEN="your-github-token" \
  233. -e SECRET_KEY="your-secret-key-here" \
  234. -e JWT_SECRET_KEY="your-jwt-secret-key-here" \
  235. --add-host=host.docker.internal:host-gateway \
  236. todo-for-ai:latest
  237. ```
  238. ### 3. Access URLs
  239. - Frontend: http://localhost:50111/todo-for-ai/pages/projects
  240. - API: http://localhost:50110/todo-for-ai/api/v1/
  241. ### 4. Environment Variables
  242. | Variable | Description |
  243. |----------|-------------|
  244. | DATABASE_URL | Database connection string |
  245. | GMAIL_USER | Gmail email address |
  246. | GMAIL_PASSWORD | Gmail app password |
  247. | GITHUB_TOKEN | GitHub access token |
  248. | GITHUB_CLIENT_ID | GitHub OAuth app ID |
  249. | GITHUB_CLIENT_SECRET | GitHub OAuth app secret |
  250. | SECRET_KEY | Flask secret key |
  251. | JWT_SECRET_KEY | JWT secret key |
  252. ## πŸ”§ Configuration
  253. ### GitHub OAuth App Setup
  254. 1. Visit [GitHub Developer Settings](https://github.com/settings/developers)
  255. 2. Click "New OAuth App"
  256. 3. Fill in application information:
  257. - **Application name**: Todo for AI
  258. - **Homepage URL**: http://localhost:50111
  259. - **Authorization callback URL**: http://localhost:50110/todo-for-ai/api/v1/auth/callback
  260. 4. Get `Client ID` and `Client Secret` after creation
  261. ### Gmail App Password Setup
  262. 1. Login to Gmail account
  263. 2. Go to "Manage your Google Account"
  264. 3. Select "Security" β†’ "2-Step Verification"
  265. 4. Generate "App passwords"
  266. ### GitHub Token Setup
  267. 1. Login to GitHub
  268. 2. Go to Settings β†’ Developer settings β†’ Personal access tokens
  269. 3. Generate new token with appropriate permissions
  270. ## ✨ Key Features
  271. ### 🎯 **Core Task Management**
  272. - πŸ“‹ **Smart Project Organization** - Hierarchical project and task structure with AI-powered categorization
  273. - βœ… **Intelligent Task Tracking** - Real-time status updates with automated progress monitoring
  274. - 🏷️ **Dynamic Tagging System** - Flexible labeling with AI-suggested tags for better organization
  275. - ⏰ **Smart Scheduling** - AI-assisted deadline management and priority optimization
  276. - πŸ“Š **Progress Analytics** - Visual dashboards with AI-generated insights and recommendations
  277. ### πŸ€– **AI Integration**
  278. - πŸ”Œ **MCP Protocol Support** - Native integration with Claude, GPT, and other AI assistants
  279. - πŸ—£οΈ **Natural Language Interface** - Create and manage tasks using conversational commands
  280. - 🧠 **Intelligent Automation** - AI agents can autonomously manage tasks based on context
  281. - πŸ“ **Smart Task Generation** - AI-powered task breakdown and subtask creation
  282. - πŸ” **Contextual Insights** - AI-driven project analysis and optimization suggestions
  283. ### πŸ‘₯ **Collaboration & Communication**
  284. - πŸ” **Secure Authentication** - Multi-factor authentication with GitHub OAuth integration
  285. - πŸ“§ **Smart Notifications** - Intelligent email alerts with customizable triggers
  286. - πŸ”„ **Real-time Sync** - Instant updates across all connected AI agents and team members
  287. - πŸ’¬ **Integrated Feedback** - Seamless communication between AI assistants and human users
  288. - 🌐 **Cross-platform Access** - Web interface with API access for custom integrations
  289. ### πŸ› οΈ **Developer Experience**
  290. - 🐳 **Docker Ready** - One-command deployment with full containerization
  291. - πŸ”§ **RESTful API** - Comprehensive API for custom integrations and extensions
  292. - πŸ“š **Rich Documentation** - Detailed guides for setup, usage, and customization
  293. - πŸ”’ **Enterprise Security** - Production-ready security features and compliance
  294. - πŸš€ **Scalable Architecture** - Microservices design for high-performance deployments
  295. ## πŸ” Troubleshooting
  296. ### Common Issues
  297. #### 1. Database Connection Failed
  298. ```bash
  299. # Check if database is running
  300. mysql -u username -p -h localhost
  301. # Check container logs
  302. docker logs todo-for-ai
  303. ```
  304. #### 2. Port Already in Use
  305. ```bash
  306. # Check port usage
  307. lsof -i :50110
  308. lsof -i :50111
  309. # Kill process
  310. kill -9 <PID>
  311. ```
  312. #### 3. Frontend Page Cannot Load
  313. ```bash
  314. # Check nginx configuration
  315. docker exec todo-for-ai nginx -t
  316. # Restart nginx
  317. docker exec todo-for-ai supervisorctl restart nginx
  318. ```
  319. #### 4. API Authentication Failed
  320. - Check if environment variables are set correctly
  321. - Confirm Gmail app password format is correct
  322. - Verify GitHub Token permissions
  323. ### Log Viewing
  324. ```bash
  325. # View all logs
  326. docker logs todo-for-ai
  327. # View Flask logs
  328. docker exec todo-for-ai tail -f /var/log/supervisor/flask.out.log
  329. # View Nginx logs
  330. docker exec todo-for-ai tail -f /var/log/nginx/access.log
  331. ```
  332. ## πŸ§ͺ Testing
  333. ### API Testing
  334. ```bash
  335. # Test backend health
  336. curl http://localhost:50110/
  337. # Test API proxy
  338. curl http://localhost:50111/todo-for-ai/api/v1/projects
  339. # Test frontend page
  340. curl http://localhost:50111/todo-for-ai/pages/projects
  341. ```
  342. ### Functional Testing
  343. 1. Access frontend page
  344. 2. Try login functionality
  345. 3. Create projects and tasks
  346. 4. Test email notifications
  347. ## πŸš€ Production Deployment
  348. ### Security Configuration
  349. 1. **Use Strong Passwords**: Ensure database and application keys are complex enough
  350. 2. **HTTPS Configuration**: Configure SSL certificates for production environment
  351. 3. **Firewall Settings**: Restrict unnecessary port access
  352. 4. **Regular Backups**: Set up automatic database backups
  353. ### Performance Optimization
  354. 1. **Resource Limits**: Set memory and CPU limits for containers
  355. 2. **Load Balancing**: Configure load balancing for multi-instance deployment
  356. 3. **Cache Configuration**: Consider adding Redis cache
  357. 4. **Monitoring & Alerting**: Configure application monitoring and alerting
  358. ## 🀝 Contributing
  359. Issues and Pull Requests are welcome!
  360. ### Development Workflow
  361. 1. Fork the project
  362. 2. Create a feature branch
  363. 3. Commit your changes
  364. 4. Create a Pull Request
  365. ### Git and File Management
  366. #### .gitignore Configuration
  367. The project uses comprehensive `.gitignore` files to prevent sensitive data and build artifacts from being committed:
  368. - **Root `.gitignore`**: Main project-level ignore rules
  369. - **Subproject `.gitignore`**: Each subproject (api-server, mcp, webpage) has its own rules
  370. **Verify .gitignore:**
  371. ```bash
  372. # Run verification script
  373. ./scripts/verify-gitignore.sh
  374. # Check if a file is ignored
  375. git check-ignore -v <file>
  376. ```
  377. **Common ignored files:**
  378. - Environment variables (`.env`, `.env.local`)
  379. - SSL certificates (`*.key`, `*.pem`, `*.crt`)
  380. - Build outputs (`dist/`, `build/`, `lib/`)
  381. - Dependencies (`node_modules/`, `venv/`)
  382. - Logs (`*.log`, `logs/`)
  383. - User uploads (`uploads/`, `media/`)
  384. - Deployment scripts (`deploy.sh`, `setup-*.sh`)
  385. **Documentation:**
  386. - See [.gitignore-quickref.md](.gitignore-quickref.md) for quick reference
  387. - See [.gitignore-improvements.md](.gitignore-improvements.md) for detailed changes
  388. **Clean up accidentally tracked files:**
  389. ```bash
  390. # Remove from git but keep locally
  391. git rm --cached <file>
  392. # Or use the cleanup script (for sensitive files)
  393. ./scripts/cleanup-git-cache.sh
  394. ```
  395. ## πŸ“„ License
  396. MIT License
  397. ---
  398. **🌟 Ready to get started?** Visit [https://todo4ai.org/](https://todo4ai.org/) and experience the power of AI-driven task management!

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.