---
name: pims
description: Use this skill when an agent needs to manage tasks with the installed `pims` CLI. Covers initialization, task creation, listing and filtering, metadata updates, notes, aliases, and task inspection.
---

# PIMS Task Manager

Use `pims` as the system of record for task tracking. Assume the `pims` command is installed and on `PATH`.

## Workflow

1. Run `pims initialise` before other commands if the runtime files may not exist yet.
2. Use `pims add` to create tasks.
3. Use `pims list` to inspect the tree and find task addresses.
4. Use `pims set`, `pims note`, `pims alias`, and `pims show` to maintain tasks.

## Core commands

### pims initialise

Create the data directory:

```bash
pims initialise
```

### pims add

Add tasks. Arguments: `pims add [PARENT] "TITLE" [key=value ...]`. The parent address comes before the title. Without a parent, the task is created at the root level.

```bash
pims add "Top-level task"
pims add 1 "Child task"
pims add "Fix parser" priority=high
```

On success, prints: `Added ADDRESS (numeric-address): TITLE`. Parse the address from this output to use in subsequent commands.

New tasks are created with `title` and `status` metadata. The default status is `open`.

### pims list

List tasks. Output contains ANSI colour escape codes. Each line shows `ADDRESS: [STATUS] TITLE`, indented by depth.

A bare `pims list` with no argument applies the `+default` named filter — it does not show everything. Use `pims list +all` for unfiltered output.

```bash
pims list
pims list +open
pims list +all
pims list "all(status=open, priority=high)"
```

### pims show

Show one task's metadata, notes, and log entries:

```bash
pims show 1
pims show HOME
```

### pims set

Set metadata on a task. On success, prints: `Set FIELD to VALUE on ADDRESS: TITLE`.

```bash
pims set 1 status done
pims set 1 priority high
```

### pims note

Append a note to a task. Always single-quote note text to avoid shell interpretation issues:

```bash
pims note 1 'Followed up with the user'
```

### pims alias

Create an alias for a task address:

```bash
pims alias HOME 1
pims alias WORK 2-3
```

## Default metadata

Tasks created with `pims add` have two metadata keys by default:

- `title` — the task title
- `status` — defaults to `open`

Common status values: `open`, `done`, `cancelled`, `inprogress`.

All metadata keys are lowercase by convention. Use lowercase keys to ensure filters match correctly.

## Addresses and aliases

- Root tasks use numeric addresses such as `1`, `2`, `3`.
- Child tasks use dash-separated addresses such as `1-1` or `2-3-4`.
- Aliases can be used anywhere an address is accepted.
- Aliases support suffixes. If `HOME` maps to `1`, then `HOME-2` resolves to `1-2`.

## Filter syntax

Use function-style filters, not infix `and` / `or`.

- `all(...)` means logical AND
- `any(...)` means logical OR
- `=` means exact match
- `!=` means negated match
- `*` is a wildcard

Examples:

```bash
pims list "status=open"
pims list "priority=h*"
pims list "all(status=open, priority=high)"
pims list "any(status=blocked, status=done)"
pims list "address=HOME-*"
```

Named filters come from `~/.pims/filters` and are referenced with `+name`:

```bash
pims list +default
pims list +open
```

## Important behavior

- Metadata keys and filter fields are case-sensitive. `status` and `Status` are different fields.
- The special filter field is lowercase `address`.
- `pims list` is subtree-aware: if a descendant matches, its parents are still shown.
- `pims show` prints metadata, then notes, then log entries.

## Do not

- **Do not use `pims edit`** — it launches `$EDITOR` interactively, which AI agents cannot use. Use `pims set` and `pims note` instead.
- **Do not use Title Case for metadata keys** (e.g. `Priority`) if you intend to filter on them. Filters are case-sensitive; use lowercase (`priority`).
- **Do not assume task addresses are stable** across add or delete operations. Always run `pims list` to get current addresses before updating tasks.

## Failure assumptions

- If a task address does not exist, `pims` may raise a Python exception rather than printing a friendly error.
- If filters or aliases are malformed on disk, command behavior may fail directly.
- Run `pims initialise` first when operating in a fresh environment.