Skip to content

najef1979-code/TaskPulse

BranchesTags

Repository files navigation

⚡ TaskPulse

A modern, feature-rich task management application with Kanban boards to assist human and AI Assistent Project progress.

TaskPulse License Node React

What is TaskPulse?

Taskpulse is a Project Management system that helps you know and understand the progress your AI Assistent is maling on your shared Project and Project tasks. It's build to give you insights what Tasks the AI Assistent is not able to complete without your input. The AI Assistent can create Projects, Tasks and subtast and even assign you to them when you need to complete something before it can continue.

Built with: React, Node.js, Express, and SQLite
Perfect for: Development teams, project managers, freelancers, and anyone who needs to organize their work efficiently.

Key Features

AI Assistant Integration

  • API Skill File - AI assistants can download GET /api/skill.md to learn TaskPulse API
  • Smart Task Creation - AI can create projects, tasks, and subtasks programmatically
  • Automated Workflows - Bots handle routine task management operations
  • Decision Support - Subtasks capture AI-driven decisions (multiple choice or open questions)
  • File Reference Tracking - Track emailed and on-disk files for AI workflows

Team-Based System

  • Team Isolation - Each team has its own projects and tasks
  • Team Admin - Admin users can manage team members
  • Join Requests - Request to join teams with approval workflow
  • Data Migration - Seamless migration from personal to team-based work

Bot API & Permissions

  • Bot Creation - Create API bots with custom permissions
  • Granular Permissions - Fine-tuned access control (read, create, update, delete)
  • Token Authentication - Secure API tokens for programmatic access
  • Bot Management - CLI tools for bot lifecycle management
  • Activity Tracking - Track bot actions in activity log

Visual Task Management

  • Kanban Board - Drag and drop tasks between columns (To Do, In Progress, Done)
  • Task Cards - Rich cards with priority badges, due dates, and assignees
  • Subtasks - Break down complex tasks into manageable pieces
    • Multiple Choice - Select from predefined options (great for decisions)
    • Open Answer - Provide free-text responses (great for feedback)
    • File Tracking - Track emailed files and on-disk references
  • Priority Levels - Low, Medium, High, and Critical with color coding
  • Task Assignment - Assign tasks to team members for collaboration

Mobile-First Design

  • Responsive UI - Works perfectly on desktop, tablet, and mobile
  • Touch Gestures - Swipe to move tasks, tap to edit
  • PWA Support - Install as a mobile app (iOS, Android, Desktop)
  • Offline Mode - Continue working without internet connection

Security & Authentication

  • User Accounts - Secure session-based authentication
  • Bot API - Create API bots with granular permissions
  • Token-Based Auth - For programmatic access and integrations
  • Permission System - Fine-grained access control

Developer-Friendly

  • REST API - Full API for integrations and automation
  • Bot SDKs - Easy bot creation for CI/CD workflows
  • Webhooks Ready - Architecture supports webhook integrations
  • Comprehensive Docs - API reference, admin guide, and quick start

Productivity Boosters

  • Due Dates - Never miss a deadline with visual indicators
  • Task Assignments - Delegate work to team members
  • Completion Tracking - Automatic timestamps when tasks are completed
  • Productivity Metrics - Track tasks completed per day/week/month
  • Real-time Updates - Instant synchronization across devices
  • Search & Filter - Find tasks quickly

Why Use TaskPulse?

For Teams

  • Collaboration Made Easy - Assign tasks, track progress, and coordinate work
  • Transparent Workflow - See everyone's tasks in one place
  • AI Assistance - Let AI help prioritize and distribute work
  • Bot Automation - Integrate with CI/CD pipelines and tools
  • Secure Bot Integration - Whitelist known bot IPs for API access while allowing human users from anywhere

For Individuals

  • Simple Yet Powerful - Get started in minutes, scale as needed
  • Mobile Productivity - Manage tasks on the go with PWA
  • Offline Support - Never lose access to your tasks
  • Focus Mode - Clean, distraction-free interface

For Developers

  • Self-Hosted - Full control over your data
  • Open Source - Free to use, modify, and distribute
  • API-First - Build custom integrations easily
  • Modern Stack - Built with industry-standard technologies

Compared to Alternatives

Feature TaskPulse Trello Jira Asana
Self-Hosted ✅ Free ❌ No ✅ Paid ❌ No
AI Features ✅ Built-in ❌ No ✅ Paid ✅ Paid
Mobile PWA ✅ Native-feel ✅ Good ✅ Good ✅ Good
Bot API ✅ Included ❌ Limited ✅ Paid ❌ No
Offline Mode ✅ Yes ❌ No ❌ No ❌ No
Free Forever ✅ Yes ❌ Limited ❌ No ❌ No
Open Source ✅ Yes ❌ No ❌ No ❌ No

📸 Screenshots

Login Screen

TaskPulse Login Screen

Clean, modern login interface with optional registration link

Dashboard - Kanban Board light theme

TaskPulse Dashboard

Full-featured Kanban board with drag-and-drop task management, priority badges, and project navigation

Dashboard - Kanban Board dark theme

TaskPulse Dashboard

Full-featured Kanban board with drag-and-drop task management, priority badges, and project navigation

Quick Start

Prerequisites

  • Node.js v16.0 or higher (v18+ recommended)
  • npm v8.0 or higher
  • curl (for API testing)
  • jq (optional, for JSON parsing)

Installation

1. Clone the Repository

git clone https://github.com/najef1979-code/TaskPulse.git
cd taskpulse

2. Backend Setup

cd server

# Install dependencies
npm install

# Initialize database
node init-db.js

# Configure environment
cp .env.example .env
# Edit .env with your settings (default values work for development)

3. Frontend Setup

cd ../client

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your settings (default values work for development)

4. Start TaskPulse

Method 1: Using the Runner Script (Recommended)

cd ..  # Back to project root
./taskpulse-runner.sh

Method 2: Manual Startup

# Terminal 1: Start backend
cd server
npm start

# Terminal 2: Start frontend
cd ../client
npm run dev

5. Access TaskPulse

Usage Guide

First Steps

  1. Create an Account

    • Click "Register" in the top right corner
    • Enter your username, email, and password
    • Click "Register"

  2. Create Your First Project

    • Click "+ New Project" button
    • Enter project name and description
    • Click "Create Project"

  3. Add Tasks

    • Click "+ Add Task" or double-click anywhere on the board
    • Fill in task details (title, description, priority, due date)
    • Click "Create Task"

  4. Manage Tasks

    • Drag and Drop - Move tasks between columns
    • Click to Edit - Modify task details
    • Right-click - Quick actions (start, complete, delete)

Advanced Features

  • Subtasks - Click a task, then add subtasks in the details modal
  • Assignments - Type a username to assign tasks to team members
  • Due Dates - Click the date picker to set deadlines
  • Priorities - Choose from Low, Medium, High, or Critical
  • Mobile App - Install TaskPulse as a PWA on your phone

Creating API Bots

cd server
node user-cli.js
# Select option 2 (Create new bot)

Use bots for:

  • CI/CD integrations
  • Automated task creation
  • Custom workflows
  • Third-party tool integrations

Configuration

Environment Variables

Backend (server/.env)

# Database
DB_PATH=./taskpulse.db

# Server
PORT=3000
NODE_ENV=development

# Authentication
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# AI Configuration (Optional)
AI_ENABLED=true
AI_API_KEY=your-openai-api-key
AI_MODEL=gpt-4

Frontend (client/.env)

# API URL
VITE_API_URL=http://localhost:3000/api

# Application
VITE_APP_NAME=TaskPulse
NODE_ENV=development

Port Configuration

  • Backend API: Default 3000 (change in server/.env)
  • Frontend: Default 3050 (change in client/vite.config.js)

Database

TaskPulse uses SQLite by default for simplicity. The database file is created automatically at server/taskpulse.db.

To use PostgreSQL or MySQL:

  1. Install the appropriate driver (pg or mysql2)
  2. Modify server/lib/database.js to use your preferred database
  3. Update connection string in .env

Documentation

User Documentation

Developer Documentation

  • AI_MANUAL.md - Complete API reference (CLI and REST) for AI assistants and bot developers
  • Includes CLI commands and examples
  • Full REST API documentation
  • Authentication guide
  • Testing examples

Administrator Documentation

  • ADMIN_GUIDE.md - Complete setup, deployment, and management guide
  • System prerequisites and installation
  • Configuration and running TaskPulse
  • Team system management
  • User and bot management
  • Database management
  • Production deployment
  • Monitoring and maintenance
  • Troubleshooting guides
  • SCRIPTS.md - Quick reference for management scripts

Additional Documentation

Contributing

We welcome contributions! Here's how you can help:

Reporting Issues

  1. Check existing GitHub Issues
  2. Create a new issue with:
    • Clear title and description
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment details (OS, Node version, etc.)

Pull Requests

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow the existing code style
  • Write meaningful commit messages
  • Add tests for new features
  • Update documentation as needed
  • Ensure all tests pass before submitting

Setting Up Development Environment

# Clone your fork
git clone https://github.com/YOUR_USERNAME/taskpulse.git
cd taskpulse

# Install dependencies
cd server && npm install
cd ../client && npm install

# Run tests
cd server && npm test
cd ../client && npm test

# Start development servers
cd ..
./taskpulse-runner.sh --no-test

🧪 Testing

Run All Tests

# Using the runner script
./taskpulse-runner.sh

# Tests include:
# - Health checks
# - Create project
# - Create task
# - Start task
# - Complete task
# - Delete task
# - Delete project

Run Integration Tests Only

# Servers must be running
./taskpulse-runner.sh --test-only

Manual API Testing

# Health check
curl http://localhost:3000/health

# List projects (with bot token)
curl http://localhost:3000/api/projects \
  -H "x-api-token: bot_YOUR_TOKEN"

# Create task
curl -X POST http://localhost:3000/api/tasks \
  -H "x-api-token: bot_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":1,"title":"Test Task"}'

Deployment

Production Deployment

  1. Set Environment Variables

    # server/.env
NODE_ENV=production
JWT_SECRET=<secure-random-string>

# client/.env
VITE_API_URL=https://yourdomain.com/api

  2. Build Frontend

    cd client
npm run build
# Output in client/dist/

  3. Deploy with PM2

    pm2 start server/server.js --name "taskpulse-backend"
pm2 start "cd client && npm run dev" --name "taskpulse-frontend"

  4. Set Up Reverse Proxy (Nginx)

    • Configure Nginx to proxy to ports 3000 and 3050
    • Set up SSL/TLS with Let's Encrypt
    • See ADMIN_GUIDE.md for details

Docker Deployment

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Security

Security Best Practices

  1. Change JWT Secret - Generate a secure random string for production

    openssl rand -base64 32

  2. Use HTTPS - Always use SSL/TLS in production

  3. Limit Bot Permissions - Give bots only the permissions they need

  4. Regular Updates - Keep dependencies up to date

  5. Database Backups - Automate regular backups

  6. Monitor Logs - Watch for suspicious activity

Security Features

  • ✅ Password hashing with bcrypt
  • ✅ JWT-based authentication
  • ✅ Secure session cookies (httpOnly, secure, sameSite)
  • ✅ Granular bot permissions
  • ✅ Whitelisted bot access (restrict API to known IPs)
  • ✅ Flexible human access (users can access from anywhere)
  • ✅ SQL injection prevention
  • ✅ XSS protection

Performance

Performance Targets

Metric Target Status
First Contentful Paint (FCP) < 1.5s ✅ Met
Largest Contentful Paint (LCP) < 2.5s ✅ Met
Time to Interactive (TTI) < 3.5s ✅ Met
Cumulative Layout Shift (CLS) < 0.1 ✅ Met
API Response Time (p95) < 500ms ✅ Met

Optimization Features

  • Lazy loading for images
  • Debounced API calls
  • Virtual scrolling for large lists
  • Response caching
  • Performance monitoring built-in

Roadmap

Upcoming Features

  • Advanced Analytics - Charts and reports
  • File Attachments - Upload files to tasks
  • Comments - Discussion threads on tasks
  • Tags/Labels - Better categorization
  • Dark Mode - Theme switching
  • Email Notifications - Stay updated via email
  • Multi-Language Support - i18n

Long-term Vision

  • Mobile Apps - Native iOS and Android apps
  • Calendar View - Alternative task visualization
  • Gantt Charts - Project timeline view

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2026 TaskPulse Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Acknowledgments

Support

⭐ Star History

If you like TaskPulse, please consider giving us a star on GitHub! And if you find it helpfull please considere to buy me a coffee using the GitHub sponsor button.

Star History Chart

** Build to help you get the most out of your AI assistent or other type of working relationship. ** ** We hope that it helps make your interactions more efficient **

TaskPulse Version: v1.29.0
Last Updated: 2026-02-17

⬆ Back to Top

About

TaskPulse is a Project Management system for Humans and their AI assistents

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages