Taskosaur
Open Source Project Management with Conversational AI Task Execution
📹 Watch Taskosaur in Action
Click to watch: See how Conversational AI Task Execution works in Taskosaur
Taskosaur is an open source project management platform with conversational AI for task execution in-app. The AI assistant handles project management tasks through natural conversation, from creating tasks to managing workflows directly within the application.
Taskosaur combines traditional project management features with Conversational AI Task Execution, allowing you to manage projects through natural conversation. Instead of navigating menus and forms, you can create tasks, assign work, and manage workflows by simply describing what you need.
Key Features
- 🤖 Conversational AI for Task Execution - Execute project tasks through natural conversation directly in-app
- 💬 Natural Language Commands - "Create sprint with high-priority bugs from last week" executes automatically
- 🏠 Self-Hosted - Your data stays on your infrastructure
- 💰 Bring Your Own LLM - Use your own API key with OpenAI, Anthropic, OpenRouter, or local models
- 🔧 In-App Browser Automation - AI navigates the interface and performs actions directly within the application
- 📊 Full Project Management - Kanban boards, sprints, task dependencies, time tracking
- 🌐 Open Source - Available under Business Source License (BSL)
Table of Contents
- Key Features
- Quick Start
- Development
- Project Structure
- Deployment
- API Documentation
- Contributing
- License
- Support
Quick Start
Prerequisites
- Node.js 22+ and npm 10+
- PostgreSQL 16+ (or Docker)
- Redis 7+ (or Docker)
[!NOTE] Default Ports: Both
docker compose -f docker-compose.dev.yml upandnpm run devwill automatically start the Backend on port 3000 and the Frontend on port 3001 by default. Please ensure these ports are available on your system before proceeding.
Docker Setup (Recommended)
The fastest way to get started with Taskosaur is using Docker Compose:
-
Clone the repository
git clone https://github.com/Taskosaur/Taskosaur.git taskosaur cd taskosaur -
Set up environment variables
cp .env.example .envThis creates the .env file used for the app, you may customize the values, if you need.
-
Start with Docker Compose
docker compose -f docker-compose.dev.yml upThis automatically:
- ✅ Starts PostgreSQL and Redis
- ✅ Installs all dependencies
- ✅ Generates Prisma client
- ✅ Runs database migrations
- ✅ Seeds the database with sample data
- ✅ Starts both backend and frontend (on default ports 3000 and 3001 respectively)
-
Access the application
- Frontend: http://localhost:3001
- Backend API: http://localhost:3000
- API Documentation: http://localhost:3000/api/docs
See DOCKER_DEV_SETUP.md for detailed Docker documentation.
Manual Setup
If you prefer to run services locally:
-
Clone the repository
git clone https://github.com/Taskosaur/Taskosaur.git taskosaur cd taskosaur -
Install dependencies
npm install -
Environment Setup
Create a
.envfile in the root directory:# Database Configuration DATABASE_URL="postgresql://taskosaur:taskosaur@localhost:5432/taskosaur" # Application NODE_ENV=development # Authentication & Security JWT_SECRET="your-jwt-secret-key-change-this" JWT_REFRESH_SECRET="your-refresh-secret-key-change-this-too" JWT_EXPIRES_IN="15m" JWT_REFRESH_EXPIRES_IN="7d" # Encryption for sensitive data ENCRYPTION_KEY="your-64-character-hex-encryption-key-change-this-to-random-value" # Redis Configuration (for Bull Queue) REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASSWORD= # Email Configuration (optional, for notifications) SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USER=your-email@taskosaur.com SMTP_PASS=your-app-password SMTP_FROM=noreply@taskosaur.com EMAIL_DOMAIN="taskosaur.com" # Frontend URL (for email links and CORS) FRONTEND_URL=http://localhost:3001 CORS_ORIGIN="http://localhost:3001" # Backend API URL (for frontend to connect to backend) NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api # File Upload UPLOAD_DEST="./uploads" MAX_FILE_SIZE=10485760 # Queue Configuration MAX_CONCURRENT_JOBS=5 JOB_RETRY_ATTEMPTS=3 -
Setup Database
# Run database migrations npm run db:migrate # Seed the database (idempotent - safe to run multiple times) npm run db:seed # Or seed with admin user only npm run db:seed:admin -
Start the Application
# Development mode (runs both frontend and backend) npm run dev # Or start individually npm run dev:frontend # Start frontend only (port 3001) npm run dev:backend # Start backend only (port 3000) -
Access the Application
- Frontend: http://localhost:3001
- Backend API: http://localhost:3000
- API Documentation: http://localhost:3000/api/docs
Development
Available Commands
All commands are run from the root directory:
Development
npm run dev # Start both frontend and backend concurrently
npm run dev:frontend # Start frontend only (Next.js on port 3001)
npm run dev:backend # Start backend only (NestJS on port 3000)
Build
npm run build # Build all workspaces (frontend + backend)
npm run build:frontend # Build frontend for production
npm run build:backend # Build backend for production
npm run build:dist # Build complete distribution package
Database Operations
All seed commands are idempotent and safe to run multiple times:
npm run db:migrate # Run database migrations
npm run db:migrate:deploy # Deploy migrations (production)
npm run db:reset # Reset database (deletes all data!)
npm run db:seed # Seed database with sample data
npm run db:seed:admin # Seed database with admin user only
npm run db:generate # Generate Prisma client
npm run db:studio # Open Prisma Studio (database GUI)
npm run prisma # Run Prisma CLI commands directly
Testing
npm run test # Run all tests
npm run test:frontend # Run frontend tests
npm run test:backend # Run backend unit tests
npm run test:watch # Run backend tests in watch mode
npm run test:cov # Run backend tests with coverage
npm run test:e2e # Run backend end-to-end tests
Code Quality
npm run lint # Lint all workspaces
npm run lint:frontend # Lint frontend code
npm run lint:backend # Lint backend code
npm run format # Format backend code with Prettier
Cleanup
npm run clean # Clean all build artifacts
npm run clean:frontend # Clean frontend build artifacts
npm run clean:backend # Clean backend build artifacts
Git Hooks
Automatic code quality checks with Husky:
- Pre-commit: Runs linters on all workspaces before each commit
- Ensures code quality and consistency
- Bypass with
--no-verify(emergencies only)
git commit -m "feat: add feature" # Runs checks automatically
Project Structure
taskosaur/
├── backend/ # NestJS Backend (Port 3000)
│ ├── src/
│ │ ├── modules/ # Feature modules
│ │ ├── common/ # Shared utilities
│ │ ├── config/ # Configuration
│ │ └── gateway/ # WebSocket gateway
│ ├── prisma/ # Database schema and migrations
│ ├── public/ # Static files
│ └── uploads/ # File uploads
├── frontend/ # Next.js Frontend (Port 3001)
│ ├── src/
│ │ ├── app/ # App Router pages
│ │ ├── components/ # React components
│ │ ├── contexts/ # React contexts
│ │ ├── hooks/ # Custom hooks
│ │ ├── lib/ # Utilities
│ │ └── types/ # TypeScript types
│ └── public/ # Static assets
├── docker/ # Docker configuration
│ └── entrypoint-dev.sh # Development entrypoint script
├── scripts/ # Build and utility scripts
├── .env.example # Environment variables template
├── docker-compose.dev.yml # Docker Compose for development
└── package.json # Root package configuration
Conversational AI Task Execution Setup
Enable Conversational AI Task Execution in 3 Steps:
-
Open AI Assistant Settings
User menu (top-right avatar) → Profile → AI Settings button → AI Assistant Settings -
Add Your LLM API Key
- Toggle "Enable AI Chat"