pit is a project-aware task CLI. It keeps project discovery and backend routing outside Pi, so task operations work from a normal terminal without an LLM session.

npm install
npm run build
npm link
pit config add-root /home/soleone/src/pi
pit config add-root /home/soleone/src/products
pit scan
pit projects
pit new my-project Add playlist sharing
pit ai Polish the onboarding wizard before the next release.
pit list --all

Configuration lives at $XDG_CONFIG_HOME/pi-tasks/projects.json (or ~/.config/pi-tasks/projects.json). The disposable scan index lives at $XDG_STATE_HOME/pi-tasks/index.json (or ~/.local/state/pi-tasks/index.json).

The scanner only traverses configured roots, does not follow directory symlinks, skips dependency/build directories, and never creates task files. A project may be a git root, a directory with a task marker, or a package directory. Use an override in projects.json for monorepos or duplicate names:

{
  "roots": ["/home/soleone/src/pi"],
  "defaults": { "backend": "sq" },
  "overrides": {
    "pi-tasks": {
      "path": "/home/soleone/src/pi/pi-tasks",
      "backend": "sq",
      "aliases": ["tasks"]
    }
  }
}

pit config show
pit config add-root PATH
pit scan [--dry-run] [--json]
pit projects [--json]
pit project PATH_OR_ID [--json]
pit new | n [PROJECT] [p0-p4] TITLE. DESCRIPTION
        [--title TEXT] [--description TEXT] [--priority p0-p4]
        [--status STATUS] [--task-type TYPE] [--due-at TIMESTAMP]
        [--blocked-by IDS] [--json]
pit ai | a TEXT
pit list [--project PROJECT] [--all] [--ready] [--json]
pit show REF [--project PROJECT] [--json]
pit edit REF --set-title TEXT [--json]
pit close REF [--json]
pit rm REF [--json]

One capture verb, two styles. pit new parses the line itself with no agent; pit ai hands the line to the pi agent, which extracts the fields and creates the task using its default model (a model override is a future idea, not wired in yet).

For pit new, the project is specified as the first word or omitted entirely:

pit new pool-remote p1 implement latest schema. Migrate callers before removing the old path.
pit new p1 write release notes for v0.2        # project resolved from the current directory
pit new fix login bug                          # also resolved from the current directory

The project word must be a single word with no spaces, and it must match an indexed id, name, or alias exactly (case and separators are still ignored, so pool-remote matches a project whose id or alias normalizes to pool remote). Omitted means "use the innermost indexed project containing the current directory". Project names that cannot be spelled as one word need an alias in projects.json, or pass --project instead. Any word that does not exactly match a project is treated as the start of the title (this keeps pit new fix login bug from inside a project working). p0-p4 as the token right after the project word becomes the priority, and the words after the first period after that become the description. Pass --title to keep a title verbatim, for example when it contains a period such as fix v1.2. Neither pit new nor pit ai needs quotes around plain task words: everything after the project word (or after the verb) is rejoined. Quotes only matter for pit show refs and for flag values that contain spaces, like --project "pool remote" or --title "Fix bug in v1.2".

pit ai passes everything after the verb to pi --print --skill <pi-tasks-cli SKILL.md>, so the agent extracts project, priority, title, description, task type, due date, and blockers conversationally before calling pit itself:

pit ai "implement latest schema, migrate callers before removing the old path"

Simple task capture can also be conversational at the CLI:

pit new pool-remote p1 implement latest schema. Migrate callers before removing the old path.

When used through the Pi skill, task creation is intentionally conversational. Describe the work naturally and let the agent extract a concise title, context, priority, task type, deadline, and explicit blockers into one pit new call. It should ask only when the project or an important field is ambiguous, then verify the returned JSON before reporting success.

Aggregate output uses qualified refs such as my-project:abc123. Project selectors also accept a unique short name, including names with spaces when quoted, so freestyle:abc123 can select 2026-04-12-freestyle and "pool remote:77q" can select 2026-05-23-pool-remote. Matching ignores date prefixes, case, and separators; ambiguous selectors still fail instead of guessing. sq operations always pass the selected absolute queue path, and Pi metadata is kept under metadata.pi_tasks.

tq, beads, TODO.md adapters and the watch TUI are intentionally separate follow-up slices. The router detects those backends and reports a clear error rather than silently routing to another project.