pTask
PureTensor's sovereign, single-binary task manager. One command — pt — to capture, find, finish, and review work, from terminal, TUI, Telegram, HTTP API, MCP-native agents, or the web cockpit. Rust, SQLite, no subscriptions, no cloud dependency.
Status: production-active on the PureTensor fleet since the v1.0 activation (2026-05-14); the v2 agent-native program completed 2026-07-02. The current version lives in Cargo.toml (workspace.package.version) — this line intentionally names no number, after the v1.1.1/v1.2.0 README drift.
What it does
- Capture fast — inline-token quick-add (
2030-03-01 @home p2 ~1h, every monday at 9am), idempotent capture lane that fast-tracks fleet incidents (severity ≥ 3) into tasks.
- Find fast — Linear-style
PT-N IDs, filter DSL (pt list "(today | overdue) & p1"), FTS5 full-text search, saved views.
- Done means done — acceptance criteria (
pt add … --ac "CI green", pt criteria check PT-7 1 -m "run 3812"): a task with an unchecked criterion cannot close from any surface, and the worker brief carries the checklist.
- File once — every
pt add / MCP task_add reports likely duplicates among open and recently closed tasks (--unique / skip_if_duplicate refuses to file them); pt dupes finds lookalike pairs; pt merge PT-B --into PT-A folds a duplicate in without unblocking anything that waited on it.
- Work in order — DAG dependencies (
pt depend PT-3 --on PT-1; pt next shows only unblocked tasks, a task cannot be closed while a prerequisite is open, and pt done names what a close unblocked; --claim-next / MCP claim_next claims the next ready task in the same step — owner and optional lease, like pt claim / task_claim — never the one this close just advanced), composite priority scoring with explainability (pt why PT-42), recurrence (every vs every!), snooze.
- Stay honest — closure evidence and notes (
pt done PT-42 -m "PR #7 merged, CI green", pt note PT-42 …: append-only, attributed, carried into pt show, pt context worker briefs, the digest, the export and the cockpit drawer; git, recovery and reaper closes record their own evidence), attributed event log (pt log: who did what, via which surface), pt flux (who opened and who closed work over a window, per actor: the closing-pass rule made checkable), pt undo, accountability escalation state machine with Telegram/SMTP/HAL notifications, staleness reaper for machine-generated tasks, operator approval inbox (pt approval / pt approve / pt reject: agents request, only the operator decides, executors consume once — docs/approvals.md), goal tree (pt goal / pt context: every task traces up to the mission — docs/goals.md).
- Feed the agents — MCP server (request/list/status/withdraw for approvals; no decide tool;
goal_list / goal_show / goal_link; goal_chain on show/next/claim) over streamable-HTTP and stdio, atomic task_claim so parallel agents can't collide (with a holder, an optional heartbeat lease, task_release, and pt reclaim for a dead agent's work), discovered_from provenance links, deterministic task_digest session priming, scoped named API tokens.
- Distill the noise — native Rust distillation turns raw fleet signals into deduplicated tasks (LLM classify/consolidate through a local OpenAI-compatible endpoint by default, or Gemini; semantic + temporal dedup, close-on-recovery). Chunked with per-chunk failure isolation, so one unprocessable capture is quarantined instead of wedging the queue behind it (
pt_distill_quarantined_captures). pt distill is canonical; the legacy Python pipeline is archived for reference only.
Quick start
pt add "Renew passport 2030-03-01 @home p2 ~1h" # inline-token quick-add
pt list "(today | overdue) & p1" # filter DSL
pt next # DAG-ready tasks
pt done PT-42 # complete
pt why PT-42 # explain a task's priority score
pt # opens the TUI
pt serve # axum HTTP server: sync API, capture, webhooks, metrics
pt bot # Telegram bot (long-poll)
pt mcp # MCP server over stdio
pt --help lists all ~40 subcommands; pt gen-manpage / pt gen-completions generate the manpage and shell completions. Full reference: docs/cli-reference.md.
Surfaces
| Surface | Entry point | Notes |
|---|
| CLI | pt <verb> | PureTensor fleet terminal theme (fleet-upgrade look); --json for machine output, --no-color / --color, --idempotency-key for safe retries |
| TUI | pt / pt tui | ratatui |
| Sync API | pt serve | axum; canonical store on one host, clients use pt remote |
| Telegram | pt bot | Bot API long-poll |
| MCP (agents) | pt mcp (stdio) or /mcp mount on the server | 27 tools; bearer-gated HTTP for HAL, scoped REST tokens for other agents — docs/agent-surface.md |
| Web | dashboard/ | PTASK Triage Cockpit — read-only Python sidecar over the same DB; writes delegate to the pt binary |
Architecture
Single Cargo workspace, single binary pt. SQLite via rusqlite (bundled), migrations via refinery, TUI via ratatui, HTTP via axum, dates via jiff + interim. Filter DSL and recurrence use hand-written parsers (no parser-combinator dependency).
| Crate | Role |
|---|
ptask-core | Domain logic: storage, parsing, scoring, accountability |
ptask-cli | The pt binary and all subcommands |
ptask-server | Sync API, capture, webhooks, MCP HTTP mount, metrics |
ptask-tui | Terminal UI |
ptask-bot | Telegram bot |
ptask-distill | Native Rust distillation orchestrator + ML stages (native-ml feature) |
ptask-notify | Notification adapters (Telegram/SMTP/HAL) behind ptask-core's Dispatch trait |
Fleet topology (canonical store, Litestream WAL replication to CephFS, per-node roles, ansible rollout): docs/architecture.md. Backups, restore drills, and timers: docs/operations.md.
Documentation
docs/cli-reference.md — every subcommanddocs/dsl.md — the filter DSLdocs/recurrence.md — recurrence semantics (every vs every!)docs/sync-api.md — HTTP APIdocs/agent-surface.md — MCP tools, the atomic claim (owner, lease, heartbeat, release, reclaim), provenancedocs/approvals.md — operator approval inbox (payload binding, consume, authority, threat model)docs/goals.md — goal tree, inheritance, cycle guard, pt contextdocs/architecture.md — self-hosted topology and canonical-store electiondocs/operations.md — backups, timers, runbooksdocs/master-plan.md — the historical 12-phase build plan (complete) and design lineage
Design lineage
Linear's data model (fixed status categories, <TEAM>-<N> IDs, cycles), Todoist's quick-add + filter DSL + recurrence, dstask's git-diffable export. pTask replaced an earlier Python task store (retired at v1.0). See docs/master-plan.md for the design lineage.
License
Proprietary. Copyright (c) 2026 PureTensor, Inc. All rights reserved.
See LICENSE. Source is published for review; use, copying, and
distribution require a written commercial license from PureTensor.
