@opentask/ui-sense

Taskin

Modular task management platform with real-time synchronization and LLM integration

✨ Features

• 🎯 Provider-Agnostic: Interface-based architecture (ITaskProvider, ITaskManager)
• 🔄 Real-Time Sync: Bidirectional WebSocket synchronization with auto-reconnect
• 🤖 LLM Integration: Model Context Protocol (MCP) for Claude, GPT-4, and others
• 🎨 Modern UI: Vue 3 + Vite + Pinia dashboard with complete design system
• 📱 Responsive: Optimized interface for desktop, tablet, and mobile
• 💾 Offline-First: Local cache with automatic sync on reconnect
• 🔧 Type-Safe: TypeScript strict mode + Zod schemas
• 📦 Monorepo: pnpm workspaces with optimized builds
• 🎭 Storybook: 30+ interactive stories with autodocs
• 🔒 Security-First: Zod validations, injection protection, secure HTTP headers
• 📊 Smart Filtering: Semantic task filtering (open/closed) across CLI and dashboard
• 📈 Team Metrics: Comprehensive stats with configurable time periods (day/week/month/year)
• ⚙️ Configurable Automation: Three automation levels (manual/assisted/autopilot) for git commits
• 💬 Smart Suggestions: Contextual commit message suggestions, with a configurable CI-skip tag ([skip ci] by default)

🔒 Security Features

Taskin implements multiple layers of security to protect against common attacks:

Input Validation (Layer 1)

• Host Validation: Rejects malicious hosts (;, &&, |, ../, etc.)
• Port Validation: Validates ports 1-65535, rejects strings with injected commands
• IPv4 Validation: Checks each octet (0-255), rejects malformed IPs (256.1.1.1)
• Path Validation: Blocks path traversal (../, ~/, absolute paths)
• WebSocket URL: Validates ws:// and wss:// protocols only

Output Escaping (Layer 2)

• HTML Escaping: Escapes <, >, &, ", ' before injecting into HTML
• XSS Prevention: Protects against <script>, <img onerror>, <iframe>

HTTP Security Headers (Layer 3)

• X-Frame-Options: DENY - Prevents clickjacking
• X-Content-Type-Options: nosniff - Prevents MIME type sniffing
• X-XSS-Protection: 1; mode=block - Enables browser XSS protection
• Content-Security-Policy - Restricts script and style sources
• X-Powered-By: disabled - Removes Express fingerprinting

Auto-commits (Layer 4)

The commits Taskin makes on its own carry only what their message says:

• Status commits (start, pause, finish, review, and the MCP start_task/finish_task) commit only the task file. Whatever you had staged stays staged and out of the commit.
• Work commits (pause, and finish in autopilot) look at every change before git add -A. If one looks sensitive — an .env file, a private key, a credentials file, or an added line carrying a token — nothing is staged or committed, and Taskin lists the file, the line and the reason for you to decide. .env.example and friends are fine; deleting a sensitive file is fine; a secret already in history that the change does not touch is not flagged.
• The commit body lists the files, so the subject never hides what went in.
• No shell: git runs with an argument list, so a task title with quotes or $(...) is written literally.

This is a safety net, not a secret scanner: keep secrets in .gitignore and use a real scanner in CI.

Testing

• 46 unit tests covering injection attacks, XSS, path traversal
• TDD revealed and fixed 3 validation bugs before production
• Continuous integration with security validation

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/opentask/taskin.git
cd taskin

# Install dependencies
pnpm install

# Build all packages
pnpm -r build

# List tasks
npx taskin list

# View all commands
taskin --help

# Create a new task
taskin new -t feat -T "Add login feature" -u ana-souza

🔍 Task Linter - Validate your task markdown files (language-agnostic):

taskin lint
taskin lint --path ./TASKS

Basic Usage

1. CLI Task Management

# Initialize project
taskin init

# Create new task
taskin new "Implement authentication"

# List tasks — only the open ones by default
taskin list
taskin list --all               # Every task, closed ones included

# Filter tasks
taskin list --open              # Only open tasks (already the default)
taskin list --closed            # Only closed tasks
taskin list --status pending    # Specific status
taskin list --scored            # Only tasks that already have a difficulty
taskin list --unscored          # Only tasks still waiting for a difficulty
taskin list fix                 # Free text over id, title, type, status and assignee

# Machine-readable output, for another tool to consume
taskin list --json              # JSON array, no header and no framing
taskin list --json --all        # The same filters and default apply

# View statistics
taskin stats --user             # User stats
taskin stats --team --period year  # Team yearly stats

# Configure automation
taskin config --level assisted  # manual | assisted | autopilot

# Manage tasks
taskin start task-01            # Suggests commits
taskin pause task-01            # Auto-commits work, unless something looks sensitive
taskin finish task-01           # Suggests commits

# Group and prioritise, without editing the file by hand
taskin group create "Login" --parent g-cli  # A group inside another (up to 4 levels)
taskin group nest g-auth g-cli  # Or put an existing group inside another
taskin group unnest g-auth      # And back to the top level
taskin group join 042 g-cli     # Put a task in an existing group
taskin group leave 042          # Take it out
taskin priority 042 150         # Absolute number, lower comes first
taskin priority 042 --before 017  # Or relative: right before (or --after) another
taskin priority 042 --top         # Or to the top (or --bottom) — of its group, when grouped
taskin group move g-cli --top     # A whole group: --top, --bottom, --before/--after a task or group
taskin new -t feat -T "Login" --group g-cli --priority 150  # Born in place
taskin difficulty 042 3           # Score it, 1 (trivial) to 5 (very hard) — works the --unscored queue
taskin new -t feat -T "Login" --difficulty 2                 # Born scored

2. Dashboard with WebSocket

# Start WebSocket server + web dashboard
taskin dashboard

# With filters
taskin dashboard --filter-open    # Show only open tasks
taskin dashboard --filter-closed  # Show only closed tasks

# The top bar filters both screens (Board and Prioritization) by the same
# rules as `taskin list`, and keeps them in the URL, so a reload or a shared
# link shows the same cut:
#   ?view=board|prioritization  ?filter=open|active|closed|all
#   ?q=<text>  ?sort=manual|diff-desc|diff-asc  ?score=all|scored|unscored

# Access: http://localhost:5173
# WebSocket: ws://localhost:3001

On the prioritization board, the arrows, top, bottom and dragging don't compute numbers in the browser: they send move-before / move-after (or the group versions) with the first, last or neighbouring visible row as the reference, and the domain numbers it — the same rule as taskin priority --before. A move to the top writes one file; a group of three writes three. Undo re-sends the previous values of only the tasks the move changed.

Dropping a task on another of the same group creates a real subgroup, and dropping a group on another creates a parent with both inside: the board sends create-group (with parentId) and nest-group, so the nesting is saved in .taskin/.taskin-groups.json and survives a reload. Undo covers it too — undoing a nesting goes out as unnest-group. See docs/RDT/grupos-aninhados.md.

3. LLM Integration (Claude, GPT-4)

# Start MCP server
taskin mcp-server

The server exposes three tools — list_tasks, start_task and finish_task — and the taskin://tasks resource. See docs/MCP_CLAUDE_SETUP.md.

To register it in your own project:

taskin mcp-install

It writes the .mcp.json at the project root (not wherever you ran it from), detects your package manager, merges with any servers already configured, and then starts the server to check the entry actually works — because a command can resolve to a different taskin, and an older one will answer happily with the wrong set of tools.

Use --force to replace an existing taskin entry that differs, and --no-probe to skip the check.

taskin init does not write that file: registering an MCP server is a deliberate step, not a side effect of setting up a project.

🔀 Git Flow: Automatic Sync

Implemented in TASKS/task-019: automation.autoSync and automation.originBranch control remote sync of task bookkeeping commits. autoSync defaults to true but is only active when automation.defaultBranch is configured.

Example configuration, using tasks as the shared defaultBranch and develop as the originBranch:

{
  "automation": {
    "level": "autopilot",
    "autoSync": true,
    "defaultBranch": "tasks",
    "originBranch": "develop"
  }
}

With this config:

1. tasks is a long-lived shared branch (branched once from develop) where every taskin new and status-change commit lands — regardless of which local branch the user is on.
2. taskin new: before computing the next task number, autoSync does fetch + rebase on tasks, then commits the new task file and pushes. If the push is rejected (another user pushed first), it retries the whole cycle (fetch → rebase → renumber → commit → push) up to 3 times.
3. Status changes (taskin start/taskin pause/taskin finish): committed to tasks automatically (commitTaskStatusChangeOnBranch).
4. When a task's status becomes done (taskin finish): taskin takes the final content of that task's file only from tasks and creates a single squash commit directly on develop (originBranch) — without dragging in other tasks still open on tasks.
5. tasks keeps accumulating many small bookkeeping commits; develop only ever receives one clean commit per finished task.

---
config:
  gitGraph:
    mainBranchName: 'develop'
---
gitGraph
   commit id: "release-1.2.0"
   branch tasks
   checkout tasks
   commit id: "task-042: new (pending)"
   commit id: "task-042: in-progress"
   commit id: "task-043: new (pending)"
   commit id: "task-042: done"
   checkout develop
   merge tasks id: "squash: task-042 done" tag: "auto"
   checkout tasks
   commit id: "task-043: in-progress"
   commit id: "task-043: done"
   checkout develop
   merge tasks id: "squash: task-043 done" tag: "auto"

• develop (originBranch) only ever sees the two squash commits — one per finished task — no matter how many pending/in-progress commits happened on tasks in between.
• Disabling autoSync (or leaving defaultBranch/originBranch unset) falls back to today's behavior: fully local commits, no push/pull/squash.

📦 Packages

Core Packages

• @opentask/taskin-core - Core abstractions and logic
• @opentask/taskin-types-ts - Zod schemas and TypeScript types
• @opentask/taskin-task-manager - Task lifecycle orchestration
• @opentask/taskin-file-system-provider - Filesystem-based provider

Server Packages

• @opentask/taskin-task-server-ws - Multi-client WebSocket server
• @opentask/taskin-task-server-mcp - Model Context Protocol server
• @opentask/taskin-api - REST API (planned)

Frontend Packages

• @opentask/taskin-task-provider-pinia - Pinia store with WebSocket sync
• @opentask/taskin-dashboard - Vue 3 + Vite dashboard with complete UI components
• @opentask/taskin-design-vue - Vue 3 design system with Taskin mascot and UI elements
  • 🎨 Live Storybook → Interactive component showcase with 30+ stories

CLI & Utils

• @opentask/taskin-cli - Command-line interface
• @opentask/taskin-git-utils - Git utilities
• @opentask/taskin-utils - Shared functions

Integration Packages (Planned)

• @opentask/taskin-directus-extension - Directus CMS extension
• @opentask/taskin-n8n-plugin - n8n plugin
• @opentask/taskin-chatbot - Chatbot integrations

Python Packages (Planned)

• @opentask/taskin-types-py - Generated Pydantic models
• @opentask/taskin-py-sdk - Python SDK

🏗️ Architecture

Vue Dashboard (Pinia)
    ↕ WebSocket
TaskWebSocketServer
    ↕
TaskManager ← → TaskProvider
    ↕
FileSystem (Markdown)

LLM (Claude/GPT-4)
    ↕ MCP Protocol
TaskMCPServer
    ↕
TaskManager ← → TaskProvider

📚 Complete Architecture Documentation

🛠️ Development

Prerequisites

• Node.js ≥ 18
• pnpm ≥ 8
• Git

Setup

# Clone
git clone https://github.com/opentask/taskin.git
cd taskin

# Install
pnpm install

# Build
pnpm -r build

Available Commands

Build & Development

• pnpm build - Build all packages
• pnpm dev - Watch mode
• pnpm clean - Clean builds
• pnpm typecheck - Check TypeScript types
• pnpm lint - ESLint + manifest validation
• pnpm test - Run tests
• pnpm test:coverage - Tests with coverage

Task Structure

Tasks are Markdown files with inline metadata (compact and readable):

# 🧩 Task 001 — Implement authentication

Status: in-progress  
Type: feat  
Assignee: sidarta

## Description

Implement JWT authentication system with secure token generation.

## Tasks

- [x] Create user schema
- [x] Implement login endpoint
- [ ] Add token refresh logic
- [ ] Write integration tests

## Notes

Using bcrypt for password hashing.
Token expiration: 24h.

Metadata Format

• Inline metadata (Status, Type, Assignee) uses two trailing spaces for line breaks
• Assignee holds the user's id from .taskin/.taskin-users.json, not the display name: the name changes, the id is the key. taskin new -u accepts either and writes the id; taskin lint warns about a display name and taskin lint --fix rewrites it to the id
• Blank lines after title and before description improve readability
• Section headers (Description, Tasks, Notes) can be localized
• Multi-language support: English and Portuguese (automatically detected)
• Status values: pending, in-progress, done, blocked, canceled
• Type values: feat, fix, docs, refactor, test, chore

Task Linter

The built-in linter validates format and converts legacy section-based metadata:

# Validate all tasks
taskin lint

# Auto-fix format issues (adds trailing spaces, blank lines).
# Exits 1 if an error is left that --fix cannot correct, such as an oversized attachment.
taskin lint --fix

# Validate specific directory
taskin lint --path ./custom-tasks

Linter features:

• ✅ Validates inline metadata format
• ✅ Detects and converts section-based format (## Status\nvalue)
• ✅ Multi-language support (English, Portuguese)
• ✅ Preserves localized content sections
• ✅ Enforces consistent formatting

📚 Documentation

• 📖 Quick Start Guide
• 🏗️ Detailed Architecture
• ⬆️ Upgrade Guide - Moving between major versions
• 🎨 Design System
• 🎭 Taskin Design Vue - Mascot and UI components
• 🔌 WebSocket Examples
• 🤖 MCP Server Guide
• 📦 Pinia Provider

🤝 Contributing

Contributions are welcome! Please:

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

# Create new package
mkdir -p packages/new-package/src
cd packages/new-package

# Follow monorepo patterns
# See docs/QUICKSTART.md for details

📄 License

MIT License - see LICENSE for details.

👥 Authors

• OpenTask - https://opentask.com.br
• Sidarta Veloso - Lead Contributor

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• Vue.js, Pinia, Vite and the entire Vue ecosystem

🔗 Links

• 🎨 Storybook (Design System) - Interactive component showcase
• 📦 npm: taskin - CLI package
• 📦 npm: @opentask/taskin - Alias package
• 💻 GitHub Repository - Source code
• 🐛 Issues - Bug reports and feature requests
• 🔀 Pull Requests - Contributions
• 📝 Changelog - Version history

Status: Active development 🚧

Version: 0.1.0

Made with ❤️ by OpenTask