Taskin

> Task management system integrated with Git workflows

Taskin is a command-line tool that helps you manage tasks directly from your terminal, with seamless Git integration and dynamic provider loading.


✨ Features

- 🎯 Multiple Task Providers - File System, Redmine, Jira, GitHub Issues (and more!)
- 🔌 Dynamic Provider Installation - Automatically installs providers when needed
- 📦 Lightweight CLI - Only installs what you use
- 🔒 Secure Configuration - API keys protected in .gitignore
- 🎨 Beautiful CLI - Colorful, interactive, and user-friendly
- ⚡ Fast & Efficient - Built with performance in mind
- 🧪 Well Tested - Comprehensive test coverage

🚀 Installation

``bash

Using npx (recommended - no installation needed!)

npx taskin init

Or install globally

npm install -g taskin

Or with pnpm

pnpm add -g taskin

Or with yarn

yarn global add taskin
`

> Note: Please report any issues on GitHub.

📦 Available Packages

Taskin is built as a modular ecosystem. Besides the CLI, you can use individual packages:

$3

| Package | Description | npm |
| --------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------- |
| taskin | Complete CLI + programmatic API | ![npm](https://www.npmjs.com/package/taskin) |
| @opentask/taskin-types | TypeScript types and Zod schemas | Coming soon |
| @opentask/taskin-core | Core task management logic | Coming soon |
| @opentask/taskin-task-manager | Task lifecycle orchestration | Coming soon |

$3

| Provider | Description | Status | npm |
| ----------------------------------------- | ------------------------------------- | -------------- | ----------- |
| @opentask/taskin-file-system-provider | File System provider (Markdown files) | ✅ Stable | Coming soon |
| @opentask/taskin-redmine-provider | Redmine integration | 🚧 Coming Soon | - |
| @opentask/taskin-jira-provider | Jira Cloud integration | 🚧 Coming Soon | - |
| @opentask/taskin-github-provider | GitHub Issues integration | 🚧 Coming Soon | - |

$3

| Package | Description | npm |
| ------------------------------ | -------------------- | ----------- |
| @opentask/taskin-git-utils | Git workflow helpers | Coming soon |
| @opentask/taskin-utils | Shared utilities | Coming soon |

> 💡 Tip: When you run taskin init, providers are automatically installed on-demand. You don't need to install them manually!

Quick Start

1. Initialize Taskin in your project:
\\\bash
npx taskin init
\\\

Select your preferred task provider:
- 📁 File System - Store tasks as Markdown files locally
- 🔴 Redmine - Sync with Redmine issues (coming soon)
- 🔵 Jira - Sync with Jira issues (coming soon)
- 🐙 GitHub Issues - Sync with GitHub (coming soon)

2. List all tasks:
\\\bash
taskin list
\\\

3. Start working on a task:
\\\bash
taskin start task-001
\\\

Commands

- taskin init - Initialize Taskin in your project with interactive setup
- taskin list [options] - List all tasks
- --open - Show only open tasks (pending, in-progress, blocked)
- --closed - Show only closed tasks (done, canceled)
- --status - Filter by specific status
- --type - Filter by task type
- taskin new - Create a new task (alias: create)
- taskin start - Start working on a task (suggests commits)
- taskin pause - Pause work on a task (auto-commits work in progress)
- taskin finish - Complete a task (suggests commits)
- taskin stats [options] - Show statistics
- --user - User statistics
- --team - Team statistics
- --period - Time period for stats
- taskin config [options] - Configure automation level
- --level - Set commit automation level
- taskin lint - Validate task files
- taskin dashboard [options] - Start the web dashboard
- --filter-open - Show only open tasks
- --filter-closed - Show only closed tasks
- taskin mcp-server - Start MCP server for Claude Desktop integration (alias: mcp)
- taskin help - Show help information

$3

Taskin supports three automation levels for git commits:

- manual - You're in control: all commits are suggestions only
- assisted (default) - Smart suggestions: auto-commits status changes, suggests work commits
- autopilot - Let Taskin drive: auto-commits everything

Configure with: taskin config --level

🤖 MCP Server (Model Context Protocol)

Taskin includes an MCP server that allows AI assistants like Claude Desktop to interact with your tasks:

`bash
taskin mcp-server
`

$3

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

`json
{
"mcpServers": {
"taskin": {
"args": ["taskin@beta", "mcp-server"],
"command": "npx"
}
}
}
`

Or if installed globally:

`json
{
"mcpServers": {
"taskin": {
"args": ["mcp-server"],
"command": "taskin"
}
}
}
`

Available MCP Tools:

- start_task - Start working on a task
- finish_task - Mark a task as finished

Available MCP Prompts:

- start-task-workflow - Guide for starting tasks
- finish-task-workflow - Guide for finishing tasks
- task-summary - Get task summary and insights

Available MCP Resources:

- taskin://tasks - Access all tasks

📦 Programmatic Usage

Taskin can also be used as a library in your TypeScript/JavaScript projects:

`bash
npm install taskin
`

`typescript
import { createTaskin, getTaskin, type ITaskin } from 'taskin';

// Create a Taskin instance with custom tasks directory
const taskin = createTaskin('./my-tasks');

// Or use the default instance (uses ./TASKS)
const taskin = getTaskin();

// Use the API
const tasks = await taskin.list();
await taskin.start('task-001');
await taskin.pause('task-001', { message: 'Break time!' });
await taskin.finish('task-001');

// Lint tasks
const lintResult = await taskin.lint({ path: './TASKS' });
console.log(Checked ${lintResult.tasksChecked} tasks);
`

$3

Taskin is written in TypeScript and exports full type definitions:

`typescript
import type { Task, TaskId, TaskStatus, ITaskin } from 'taskin';

// All types are available for your TypeScript projects
function processTask(task: Task): void {
console.log(Processing ${task.title});
}
`

🏗️ Architecture

Taskin uses a plugin-based architecture with dynamic provider loading:

- Providers are loaded on-demand (only when selected)
- Automatic installation via npm/pnpm/yarn
- Easy to extend with custom providers

📚 See ARCHITECTURE.md for detailed technical documentation.

📝 Creating Tasks

Use the taskin new command to create new task files:

$3

Simply run without arguments for a guided experience:

`bash
taskin new
`

You'll be prompted to select:

- Task type (feat, fix, refactor, docs, test, chore)
- Title
- Description (optional)
- Assignee (optional)

$3

Or provide all options directly:

`bash


Create a new feature task

taskin new -t feat -T "Add user authentication" -d "Implement JWT-based auth" -u "John Doe"

Create a bug fix task

taskin new --type fix --title "Fix login error" --user "Developer"

Using the 'create' alias

taskin create -t docs -T "Update README"
`

Options:

- -t, --type - Task type: feat, fix, refactor, docs, test, chore
- -T, --title