# NexTask Full Knowledge Base (llms-full.txt)

> Comprehensive, uncompressed factual documentation, API specifications, and architectural references for NexTask (Linear Edition).

Website: https://nextask.fauzanlm.my.id/
Documentation: https://nextask.fauzanlm.my.id/docs
Repository: https://github.com/fauzanlm/nextask

---

## 1. Product Overview & Positioning

NexTask is an ultra-fast, keyboard-first issue tracker and agile execution engine engineered specifically for high-velocity software engineering teams and autonomous AI agents (such as Google Antigravity, Cursor, and Anthropic Claude Desktop).

### Why NexTask over Linear or Jira?
| Feature | NexTask | Linear | Jira | Trello |
|---|---|---|---|---|
| Interaction Latency | **< 20ms (Optimistic UI)** | ~50ms | 300ms - 2s | 150ms - 500ms |
| Native MCP Server | **Built-in (26 Tools)** | Requires 3rd-party wrapper | Complex REST OAuth | Webhooks only |
| Trello Board Importer | **1-Click Native Auto-Discovery** | Manual CSV Export | Plugin required | Native |
| Offline Architecture | **PWA + FIFO Mutation Queue** | Partial Desktop Cache | Online only | Limited mobile cache |
| Audio Haptics | **Mechanical Switch Sounds (Muted/Clicky)** | Audio clicks | None | None |
| Keyboard Ergonomics | **Full Single-Key Triage (C, X, S, P, A, D)** | Keyboard shortcuts | Clunky shortcuts | Drag-and-drop first |
| Pricing / Autonomy | **Self-Hostable / Open Model** | Proprietary SaaS ($8-14/mo) | Atlassian Cloud | Freemium SaaS |

---

## 2. Model Context Protocol (MCP) Integration

NexTask ships with a native, production-grade Model Context Protocol (MCP) server built with `@modelcontextprotocol/sdk`. It provides 26 enterprise tools via Stdio IPC transport and HTTP JSON-RPC.

### CLI Launch Command
```bash
npx nextask mcp start
```

### Automated 18-Step Test Suite
```bash
npx nextask mcp:test
```

### Claude Desktop & Antigravity Setup
Add the server entry to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) or Antigravity IDE settings:
```json
{
  "mcpServers": {
    "nextask": {
      "command": "npx",
      "args": ["-y", "tsx", "/path/to/nextask/mcp/server.ts"],
      "env": {
        "NEXTASK_API_KEY": "nt_live_your_scoped_api_key_here"
      }
    }
  }
}
```

### Complete MCP Tool Suite (26 Tools)

#### Issue Management & Triage
1. `list_issues`: List workspace issues with filters (`status`, `priority`, `project_id`, `cycle_id`, `assignee_id`, `label`, `limit`).
2. `get_issue`: Retrieve full issue details, description, blocker relations, checklist items, and audit timestamps by identifier (e.g. `NT-42`).
3. `create_issue`: Create a new issue with auto-incrementing identifier, title, description, status, priority, due date, story points, and labels.
4. `update_issue`: Apply updates to status, priority, title, description, or assignment.
5. `search_issues`: Perform full-text LIKE search across issue titles and markdown descriptions.
6. `assign_issue`: Assign an issue to a team member by email or user ID.
7. `set_issue_estimate`: Set story points or agile estimation points on an issue.
8. `set_issue_due_date`: Set or clear the target due date (ISO-8601).
9. `set_issue_labels`: Assign or replace label tags on an issue.

#### Sprints & Agile Cycles
10. `list_cycles`: List all sprint cycles with status (`upcoming`, `active`, `completed`), start date, end date, and completion metrics.
11. `assign_to_cycle`: Assign an issue to a sprint cycle by cycle ID or slug.
12. `get_active_cycle`: Retrieve the currently running sprint cycle and its issues.

#### Projects & Roadmaps
13. `list_projects`: List all workspace projects with status, progress percentage, lead, and target dates.
14. `create_project`: Create a new project roadmap with custom color, icon, and target date.
15. `assign_to_project`: Associate an issue with a project.

#### Blocker & Dependency Relations
16. `add_issue_relation`: Create a dependency relation between two issues (`blocks`, `blocked_by`, `related_to`, `duplicate_of`).
17. `remove_issue_relation`: Remove an existing issue relation.

#### Discussions & Audit Trails
18. `add_comment`: Post a markdown comment or progress update to an issue thread.
19. `list_comments`: Retrieve all comments for an issue in chronological order.
20. `add_issue_comment`: Alias for `add_comment`.
21. `get_issue_activities`: Query the immutable audit trail of changes made to an issue.

#### In-App Notifications & Inbox Triage
22. `list_notifications`: List notifications for the authenticated user with `is_read` filtering.
23. `mark_notification_read`: Mark a specific notification as read by notification ID.
24. `mark_all_notifications_read`: Mark all unread notifications in the workspace as read in one atomic call.

#### Workspace & Views
25. `list_workspace_members`: Retrieve members of the active workspace.
26. `list_saved_views`: Retrieve custom saved views and multi-dimensional filter configurations.

---

## 3. Keyboard Shortcuts Reference

NexTask is built for speed with single-key shortcuts:

### Global Navigation
- `Cmd` + `K` / `Ctrl` + `K`: Open Command Palette / Omnibar.
- `G` then `I`: Navigate to Inbox.
- `G` then `A`: Navigate to All Issues.
- `G` then `M`: Navigate to My Issues.
- `G` then `C`: Navigate to Active Cycle.
- `G` then `P`: Navigate to Projects.
- `?`: Show Keyboard Shortcuts Cheat Sheet.
- `Ctrl` + `Alt` + `P`: Open Developer Telemetry & Real-User Monitoring (RUM) HUD.

### Issue Actions
- `C`: Create new issue.
- `X`: Toggle selection of current issue in list.
- `S`: Change issue status.
- `P`: Change issue priority (Urgent, High, Medium, Low, None).
- `A`: Assign issue to team member.
- `D`: Set issue due date.
- `L`: Add or remove label tags.
- `E`: Set story points estimation.
- `Backspace` / `Delete`: Delete selected issue(s).
- `Escape`: Close open drawers, modals, or clear active selection.

---

## 4. Trello 1-Click Migration Workflow

NexTask provides a native Trello board importer in **Settings → Import → Trello**:
1. Connect Trello API Key and Token.
2. Auto-fetch all visible Trello boards and workspaces.
3. Select the target board to import.
4. NexTask automatically maps:
   - Trello Lists → NexTask Workflow Statuses (`backlog`, `todo`, `in_progress`, `done`, `canceled`).
   - Trello Cards → NexTask Issues (`NT-{X}`).
   - Checklists → Markdown Sub-Tasks (`- [ ] task`).
   - Card Members → NexTask Assignees (matched by email).
   - Card Labels → NexTask Colored Labels.
   - Due Dates → NexTask Due Dates.
5. All operations run in an idempotent batch transaction.

---

## 5. Local-First PWA & Offline Mutation Replay

NexTask functions completely offline via its Progressive Web App architecture:
- **Service Worker (`sw.js`)**: Caches static assets, app shell, and icons using a Cache-First strategy.
- **Offline Mutation Queue (`offlineQueue.ts`)**: Stores mutations in browser IndexedDB / LocalStorage if offline.
- **Temporary ID Remapping (`tempIdMap`)**: When creating issues offline, client generates a temporary ID (`temp-xxx`). Upon reconnect, the server assigns a permanent UUID and identifier (`NT-{X}`), and all queued child operations (comments, labels, relations) are remapped transparently.
- **Conflict Resolution**: Vector clocks and server timestamp comparison prevent stale overwrite.

---

## 6. Frequently Asked Questions (FAQ)

### What is NexTask?
NexTask is an ultra-fast, keyboard-first issue tracker and agile execution engine engineered for developer autonomy and autonomous AI agents. It features sub-20ms optimistic UI updates, mechanical haptic audio feedback, local-first PWA architecture, 1-click Trello migration, and native Model Context Protocol (MCP) server integration.

### How does NexTask compare to Linear or Jira?
NexTask combines Linear's keyboard-first elegance with zero-latency optimistic state updates (<20ms), 60 FPS DOM virtualization, built-in real-user monitoring (RUM), and native Model Context Protocol (MCP) tools that enable AI agents (Claude, Cursor, Antigravity) to manage sprints, issues, blockers, and comments directly without complex API middleware.

### How do AI agents like Claude and Cursor connect to NexTask?
AI coding agents connect to NexTask via its built-in Model Context Protocol (MCP) server using `npx nextask mcp start` or direct Stdio IPC configuration. Agents authenticate using scoped Personal API Keys (`NEXTASK_API_KEY`) and can query issues, update statuses, assign sprints, and resolve blockers.

### Does NexTask work offline?
Yes, NexTask is a local-first Progressive Web App (PWA). You can install it on macOS, Windows, Linux, iOS, and Android. It queues all mutations offline and replays them automatically upon reconnection with atomic ID remapping.

### Can I import my Trello boards into NexTask?
Yes, NexTask features a 1-click Trello importer that maps boards, lists, cards, checklists, members, and labels into high-velocity sprint issues in seconds.

### Is there a live demo available?
Yes! Anyone can test NexTask immediately without signing up by visiting https://nextask.fauzanlm.my.id/demo with pre-populated realistic sprint data.