tasque

Local-first task tracker for coding agents.

• JSONL source of truth
• Git worktree-backed .tasque/ storage by default in git repos
• No DB/service
• Durable restart + replay

Install

npm install -g @bumpyclock/tasque
tsq --version

From source:

cargo build --release
target/release/tsq --version

Quickstart

tsq init --no-wizard
tsq create "First task" --kind task -p 1
tsq find open
tsq find ready --lane coding --format json

Install or refresh the bundled agent skill:

tsq init --install-skill --force-skill-overwrite
tsq skills refresh          # update existing managed installs only

Skill install updates agent skill directories. Sync worktree setup belongs to plain tsq init, tsq migrate, or explicit --sync-branch.

Managed Skill Refresh

tsq skills refresh updates skill files in target directories that already have a managed install. It does not create missing installs — use tsq init --install-skill for first-time setup. Managed installs are identified by the tsq-managed-skill:v1 marker in SKILL.md. Directories containing this marker will be overwritten by refresh. Remove the marker to opt out of automatic updates.

tsq skills refresh is repo-independent: it does not require tsq init or a .tasque/ directory.

The npm postinstall hook runs tsq skills refresh automatically after install. It refreshes only existing managed tasque skill installs and does not create missing ones. Refresh failures produce a warning but do not fail the install. Set TSQ_SKIP_SKILL_REFRESH=1 to skip postinstall refresh entirely.

Command List

Global options:

• --format human|json: output format (human default)
• --json: shorthand for --format json
• --exact-id: disable partial ID resolution

Commands:

• tsq (no args, TTY): open read-only TUI (List/Board views)
• tsq init [--wizard|--no-wizard] [--yes] [--preset <name>] [--sync-branch|--worktree-name <name>]
• tsq init --install-skill|--uninstall-skill [--skill-targets ...] [--skill-name <name>] [--force-skill-overwrite]
• tsq skills refresh
• tsq create <title...> [--kind ...] [-p ...] [--parent <id>] [--from-file tasks.md] [--description <text>] [--external-ref <ref>] [--discovered-from <id>] [--planned|--needs-plan] [--ensure] [--id <id>] [--body-file <path|->] [--force]
• tsq show <id> [--with-spec]
• tsq find ready [--lane <planning|coding>] [--assignee <name>] [--unassigned] [--kind ...] [--label ...] [--planning <needs_planning|planned>] [--tree [--full]]
• tsq find <blocked|open|in-progress|deferred|done|canceled> [filters...] [--tree [--full]]
• tsq find search <query> [--full]
• tsq find similar "<text>"
• tsq watch [--once] [--interval <seconds>] [--status <csv>] [--assignee <name>] [--tree] [--flat]

Notes:

• New root task IDs use tsq-<number>; legacy tsq-<8 crockford base32 chars> IDs remain valid.
• --id <id> accepts tsq-<number> or legacy tsq-<8 crockford base32 chars>.
• Task JSON includes alias, generated from the creation title and stable across title edits.
• Commands that accept a task ID also accept exact aliases and unique alias prefixes unless --exact-id is used.
• tsq find similar "<text>" shows ranked duplicate candidates.
• tsq create refuses similar open/in-progress/blocked/deferred tasks unless --force is passed.

watch renders the task tree by default for human output. Use --tree to explicitly request tree view or --flat for the compact list view. These options are mutually exclusive.

• tsq tui [--once] [--interval <seconds>] [--status <csv>] [--assignee <name>] [--board|--epics]
• tsq stale [--days <n>] [--status <status>] [--assignee <name>] [--limit <n>]
• tsq doctor
• tsq repair [--fix] [--force-unlock]
• tsq edit <id> [--title ...] [--description ...] [--clear-description] [--priority ...] [--external-ref <ref>] [--clear-external-ref] [--discovered-from <id>] [--clear-discovered-from]
• tsq claim <id> [--assignee <a>] [--start] [--require-spec]
• tsq assign <id> --assignee <a>
• tsq start <id>
• tsq planned <id>
• tsq needs-plan <id>
• tsq open <id>
• tsq blocked <id>
• tsq defer <id> [--note <text>]
• tsq done <id...> [--note <text>]
• tsq reopen <id...> [--note <text>]
• tsq cancel <id...> [--note <text>]
• tsq orphans
• tsq spec <id> [--file <path> | --stdin | --text <markdown> | --show | --check] [--force]
• tsq spec <id> --update [--file <path> | --stdin | --text <markdown>]
• tsq spec <id> --patch [--file <path> | --stdin | --text <patch>]
• tsq block <task> by <blocker>
• tsq unblock <task> by <blocker>
• tsq order <later> after <earlier>
• tsq unorder <later> after <earlier>
• tsq deps <id> [--direction <up|down|both>] [--depth <n>]
• tsq relate <src> <dst>
• tsq unrelate <src> <dst>
• tsq duplicate <id> of <canonical-id> [--note <text>]
• tsq duplicates [--limit <n>]
• tsq merge <source-id...> --into <target-id> [--reason <text>] [--force] [--dry-run]
• tsq supersede <old-id> with <new-id> [--note <text>]
• tsq note <id> <text>
• tsq note <id> --stdin
• tsq notes <id>
• tsq label <id> <label>
• tsq unlabel <id> <label>
• tsq labels
• tsq history <id> [--limit <n>] [--type <event-type>] [--actor <name>] [--since <iso>]
• tsq sync [--no-push]
• tsq hooks install [--force]
• tsq hooks uninstall
• tsq migrate [--sync-branch|--worktree-name <name>]
• tsq merge-driver <ancestor> <ours> <theirs>

Git repos default to worktree mode: tsq init creates/configures the tsq-sync branch and stores task data in a dedicated git worktree. Use --sync-branch <name> or --worktree-name <name> to choose a different branch/worktree name. Existing git repos with main-tree .tasque data and no sync_branch migrate automatically on the next tsq command. Fresh clones fetch the configured sync branch and create the worktree on first use. tsq sync pushes the sync branch to origin and sets upstream automatically when needed. Non-git directories use local .tasque/ storage.

tasks.md Batch Format

Use tasks.md when a plan naturally reads as a checklist. Each bullet creates one task. Two-space indentation creates parent/child hierarchy. Checkbox bullets are accepted. Tabs, odd indentation, indentation jumps, and indented first bullets are rejected with line-numbered validation errors.

- Parent task
  - Child task
    - Grandchild task
- [ ] Another parent task

tsq create --from-file tasks.md
tsq create --parent <id> --from-file tasks.md
tsq create --from-file tasks.md --ensure

Version

cargo run -- --version

Build

cargo build --release

Binary output:

• Linux/macOS: target/release/tsq
• Windows: target/release/tsq.exe

Test + Lint + Format

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --quiet
npm run test:postinstall --prefix npm

CI

GitHub Actions CI (.github/workflows/ci.yml) runs:

1. cargo fmt --check
2. cargo clippy --all-targets --all-features -- -D warnings
3. cargo test --quiet
4. npm run test:postinstall --prefix npm

All steps must pass before merging.

Release Workflows

• Release Please (.github/workflows/release-please.yml)
  • Runs Rust quality checks
  • Opens/updates release PRs using Rust release type
• Release From Cargo (.github/workflows/release-from-package.yml)
  • Manual release creation from Cargo.toml version
  • Optional version input must match Cargo version
• Release (.github/workflows/release.yml)
  • On published GitHub release, builds matrix binaries (Linux/macOS/Windows)
  • Uploads release artifacts + checksums
• npm-publish (.github/workflows/npm-publish.yml)
  • On published GitHub release, builds platform npm packages
  • Publishes platform packages, then @bumpyclock/tasque

Storage Layout

Git repos default to a dedicated sync worktree:

• tsq init configures tsq-sync by default and redirects data operations there.
• Fresh clones fetch the configured sync branch and create the worktree on first use.
• tsq sync pushes the sync branch to origin and sets upstream automatically when needed.
• Existing git repos with main-tree .tasque data migrate automatically when tsq next resolves the project root.
• The main worktree keeps .tasque/config.json so tsq can find the sync branch.
• The sync worktree owns the canonical .tasque/events.jsonl, specs, snapshots, and cache.

Non-git directories use repo-local .tasque/:

• events.jsonl: canonical append-only event log
• state.json: derived projection cache (rebuildable, gitignored)
• snapshots/: periodic checkpoints (gitignored by default)
• specs/<task-id>/spec.md: canonical markdown specs attached to tasks
• config.json: config (snapshot_every default 200)
• .lock: ephemeral write lock
• .gitignore: local-only artifacts (state.json, .lock, snapshots/, temp files)
• tasks.jsonl: legacy state-cache name; read-only fallback when state.json is absent, removal target

Recommended commit policy:

• Commit .tasque/events.jsonl and .tasque/config.json
• Do not commit .tasque/state.json
• Do not create or edit .tasque/tasks.jsonl