taskai-cli 1.8.0__tar.gz → 1.9.0__tar.gz

{taskai_cli-1.8.0 → taskai_cli-1.9.0}/DEVLOG.md

@@ -1,3 +1,118 @@
+# 9-14
+
+Gave the browser DAG chain support (backend chain fields already existed,
+frontend didn't know about them) and cleaned up `canvas.js` along the way.
+Durable versions in DEVPLAN 1.8 (chains) and Phase 3 (frontend cleanup).
+
+- **Layout rewrite.** Bottom-up subtree-width algorithm replaces the old
+  fixed-grid layout — a chain renders as a straight line, its real children
+  push into a row to the right instead of centering below it. Found and
+  fixed a real overlap bug from a screenshot: a chain node's footprint is
+  lopsided (all reach to the right), so layout now tracks separate
+  `left`/`right` extents per node instead of one symmetric width.
+- **Navigation.** Arrow keys are pure tree nav (chain or not); `f`/`b`
+  (and `forward`/`back` from the console) are a separate chain axis along
+  `chainNext`/`chainPrev`. Split out after realizing one direction can't
+  mean "sibling," "child," and "next in chain" at once for a node that's
+  both a chain head and has its own tree children.
+- **Frontend split.** `canvas.js` (one file, ~900 lines) is now
+  `config.js`/`graph.js`/`camera.js`/`navigation.js`/`render.js` plus a
+  slim `canvas.js` holding a `state` object and the event wiring — the
+  three panel scripts (`console.js`/`editpanel.js`/`shortcuts.js`) updated
+  to match.
+
+# 9-10
+
+Browser navigation polish, then a new feature: attribute filters for `task
+show`. Durable versions in DEVPLAN 1.7 (nav) and Phase 5 (filters).
+
+## Canvas navigation (`canvas.js`)
+
+- **Arrow left/right walks the whole depth level, not just direct siblings.**
+  The layout gives every node at a given depth the same `y`, so the "level" is
+  just `nodes` sharing `selectedNode.y` sorted by `x` — no explicit depth
+  bookkeeping. `→` off the last child of a parent now crosses into the next
+  cousin subtree instead of wrapping; wrap happens only at the ends of the
+  level (right off the last → level's first node, left off the first → last).
+- **Arrow up/down has per-parent memory.** `lastChildByParent` (a plain
+  `parentId → childId` map, ids not refs since nodes are rebuilt each
+  `applyTree`) records every arrow move against its parent; `down` returns to
+  the last child visited under that node, falling back to `children[0]`. Also
+  keyed for the synthetic `__root__`, so `down` from the top re-enters the
+  root subtree you were last in. Stale ids just miss and fall back.
+- **Removed up/down wrap-around.** `down` from a leaf and `up` from the top
+  now do nothing (were: wrap to rootNode / dive to the deepest leaf).
+  Left/right still wrap within a level.
+- **`focusOnNode` recomputes its target every frame** from the current
+  `canvas.width/height` instead of once up front. A side panel opening in
+  step with the ease (the `a` shortcut, closing the edit panel) resizes the
+  canvas mid-animation; a target captured once left the node cut off at the
+  edge.
+- **`fitAll` (show all / `0`) clamps zoom-in to `STYLE.zoom.focusScale`**
+  (0.85). A filtered `show` on a handful of nodes was blowing them up to fill
+  the screen; the user can still wheel in past that.
+- **Double-click a node opens the edit panel** (+ selects + eases to it), not
+  just center/zoom.
+
+## Edit panel (`editpanel.js`) + shortcuts (`shortcuts.js`)
+
+- **`Enter` on a single-line field** (name/status/priority/due_by) flushes the
+  1s debounce immediately and blurs — the edit is done. `handleFieldChange`
+  got an `immediate` flag; textarea and checkbox are excluded.
+- **`a` (add child): open the edit panel before `focusOnNode`** so the ease
+  tracks the narrowing canvas and lands centred (pairs with the per-frame
+  target change above).
+- **`Esc` no longer moves the camera.** Was `showAll()` → `fitAll()`. Now:
+  leave a focused field → close the edit panel (with `focusOnNode` on the
+  selection so it re-centres as the canvas widens) → clear the selection.
+  Closing the panel with `e` routes through the same
+  `closeEditPanelAndRefocus()` helper, so `e` and `Esc` behave identically.
+- **Backtick when the console is open but unfocused → focus the input**
+  instead of toggling it closed. Also bound `~`.
+- **`Delete` shortcut: no more `confirm()` dialog** — it broke the flow.
+
+## `task show` attribute filters — new `taskai/filters.py`
+
+    task show 'status=IN PROGRESS' 'priority>=2' 'due_by<12-31-2026'
+
+Implemented logic → CLI → browser, in that order.
+
+- **Logic** (`filters.py`): each arg is one `attr<op>value` test, AND-ed. Ops
+  `= > < >= <=`. `=` on a text attr (`name`/`description`/`status`) is an
+  fnmatch; `priority`/`id`/`parent_id` → int, `due_by`/`created_on` → date
+  (`MM-DD-YYYY`, time dropped), `completed` → bool. `None` never satisfies an
+  ordering op. `looks_like_filters(tokens)` decides filter-query vs. plain
+  id/name target (structural: known attr + operator). `match_items(db, exprs)`
+  → matching ids; `with_ancestors(db, ids)` pads with every match's parent
+  chain so the result is a set of complete root-to-node paths. `FilterError`
+  (a `ValueError`) for a bad token/value.
+- **Renderer** (`views.py`): `view_lists` gained `only_ids` — `_recursive_print`
+  and linked-item display skip anything not in the set. Ancestors are always
+  in the set, so the pruned walk stays a contiguous tree.
+- **CLI** (`cli.py`): `Controller.show_filtered(tokens)` — parse, match,
+  expand, render pruned, print `"N items matched"`. `show` dispatch checks
+  `looks_like_filters` first, else the old `all` / id / name path. Fixed a
+  latent `IndexError` on bare `task show` in passing (`args[1]` with no
+  guard). Documented in `help_menu.py` (also the AI's command reference) and
+  the `docs/` prose pages (`managing-the-tree`, `getting-started`, `index`,
+  `interactive-mode`, `browser-mode`); `commands.md` tracks `help_general`
+  automatically.
+- **Browser** (`browser.py` + `console.js`): `_run_show` routes a filter query
+  to `_run_filter` → a pruned tree (`_filtered_tree` narrows each item's
+  `child_ids`/`linked_ids` to the kept set so the canvas never walks into a
+  removed node) + a `filtered` flag. `console.js`'s `show` handler sees the
+  flag, fits the view, and stores the raw filter args in `activeFilter`.
+- **Filter persistence.** `CommandRequest` gained an optional `filter` string;
+  `_response_tree()` re-prunes every mutation's returned tree to it. `console.js`
+  attaches `activeFilter` to every `/api/command` POST (via `postCommand`,
+  which `sendFieldUpdate`/`sendComment` now also use). So a filtered view
+  survives delete / done / field edits — it was snapping back to the whole
+  forest before. `show all` / navigating to a specific node clears it. Known
+  gap: `a` (add child) under an active filter creates the item but it won't
+  match the filter, so it doesn't appear or get selected.
+
+---
+
 # 9-3
 
 Browser session — console-driven navigation and selection, mostly beyond the

{taskai_cli-1.8.0 → taskai_cli-1.9.0}/DEVPLAN.md

@@ -60,7 +60,14 @@ opening a second connection.
 
 **Views.** [taskai/views.py](taskai/views.py): Rich-based tree rendering
 (`view_lists`, `view_item`), display format configurable via
-`DISPLAY_STRING`/`DISPLAY_COLORS`.
+`DISPLAY_STRING`/`DISPLAY_COLORS`. `view_lists` takes an optional `only_ids`
+set to prune the walk (used by `task show`'s filters).
+
+**Filters.** [taskai/filters.py](taskai/filters.py): parsing + evaluation for
+`task show 'attr<op>value' ...` — `looks_like_filters` / `parse_filters`
+(→ `FilterExpr`, `FilterError`), `match_items(db, exprs)`, and
+`with_ancestors(db, ids)` which pads a match set out with parent chains so it
+renders as a coherent tree. Pure; imported by both `cli.py` and `browser.py`.
 
 **AI services.** [taskai/services/ai.py](taskai/services/ai.py):
 `ai_headstart_service` (single item → LLM suggests a next concrete step,
@@ -404,14 +411,26 @@ the original checklist.
       `edit <id|name>`, mirroring the canvas's single-click vs. double-click
       split.
 - [x] **Tree navigation** — `navigate(direction)` in `canvas.js`, wired to
-      `up` / `down` / `left` / `right` console commands. Nodes carry a
-      `parent` back-reference (set in `buildTree` / `applyTree`) so the walk
-      goes up as well as down: `down` → first child, `up` → parent,
-      `left`/`right` → previous/next sibling. Wraps on both axes — past the
-      last sibling loops to the first; `down` past the deepest leaf and `up`
-      from `rootNode` loop between the top and the deepest first-child leaf.
-      Each move behaves like a `show <target>` (select + ease/zoom; `fitAll`
-      when the target is `rootNode`).
+      `up` / `down` / `left` / `right` console commands and the arrow keys.
+      Nodes carry a `parent` back-reference (set in `buildTree` / `applyTree`)
+      so the walk goes up as well as down. Each move behaves like a `show
+      <target>` (select + ease/zoom; `fitAll` when the target is `rootNode`).
+      Reworked 9-10:
+      - `up` → parent, `down` → a child. **No wrap** — `down` from a leaf and
+        `up` from the top do nothing (was: loop to rootNode / dive to the
+        deepest leaf).
+      - `down` consults **`lastChildByParent`** (a `parentId → childId` map
+        every arrow move updates) and returns to the last child visited under
+        that node, else `children[0]`. Also keyed for `__root__`.
+      - `left`/`right` step through the **whole depth level**, not just direct
+        siblings — the level is `nodes` sharing `selectedNode.y` (the layout
+        gives one `y` per depth) sorted by `x`, so `→` crosses into a cousin
+        subtree. Wrap only at the ends of the level.
+      - `focusOnNode` recomputes its target every frame from the live canvas
+        size, so an ease that overlaps a panel width animation still lands
+        centred. `fitAll` caps zoom-in at `STYLE.zoom.focusScale`.
+      - Double-click a node also opens the edit panel now; `Esc` no longer
+        moves the camera (leave field → close panel + re-centre → deselect).
 - [x] **`.` = the selected node** (`resolveDotRefs` in `console.js`). A bare
       `.` token in any console command is swapped for `selectedNode.id`
       before dispatch, so `update . --priority 3`, `done .`, `edit .` act on
@@ -422,6 +441,36 @@ the original checklist.
       collapsing the right panel and restoring canvas width. Complements the
       existing `edit <id|name>` that opens it.
 
+### 1.8 — Chain rendering & navigation (post-plan, beyond original scope)
+
+The backend chain fields (`is_chain_head`/`prev_chain_id`/`next_chain_id`,
+`task next`) existed with no browser support at all; this gives the DAG a
+view onto them.
+
+- [x] **Layout rewrite.** The old depth-first "leaf counter" layout
+      (`canvas.js`) is now a bottom-up subtree-width algorithm (`graph.js`,
+      `measure`/`place`) — every node's footprint is the sum of its
+      children's real footprints instead of a fixed grid, so sibling
+      subtrees pack at minimum distance instead of getting a fixed spacing
+      regardless of content.
+- [x] **Chains render as a straight line.** A chain node's real children
+      (`child_ids`) push into a row to its right instead of centering below
+      it; its chain successor (`chainNext`) drops straight down, waiting
+      until that side row's height clears so nothing overlaps. Fixed a real
+      bug found via a screenshot: a chain node's footprint is lopsided (all
+      reach is to the right, none to the left), so layout tracks separate
+      `left`/`right` extents per node instead of one symmetric width —
+      otherwise a deep chain could bleed into an unrelated cousin subtree.
+      Chain edges render as bold arrows (`render.js`, `drawChainEdges`),
+      distinct from plain tree edges and dashed soft-link edges.
+- [x] **Navigation.** Arrow keys stay pure tree navigation (up/down =
+      parent/children, left/right = the depth level) — a chain node's real
+      children are still its tree children for this purpose, they just
+      render to the side. `f`/`b` (`navigation.js`, `shortcuts.js`) are a
+      separate chain axis: forward/back along `chainNext`/`chainPrev`,
+      independent of tree position. Also usable from the console as
+      `forward`/`back`.
+
 ---
 
 ## Phase 2 — AI tools
@@ -580,11 +629,17 @@ Re-scope this section before starting 2.4.
 
 ## Phase 3 — Polish
 
-- [ ] **Frontend cleanup.** Once 1.3–1.6 are functional, split `app.js` into
-      small single-purpose files (`api.js`, `dag.js`, `console.js`,
-      `editmenu.js`) and delete anything exploratory left over from getting
-      the DAG layout working. Still no bundler — just multiple `<script>`
-      tags loaded in order.
+- [x] **Frontend cleanup.** `canvas.js` split into `config.js` (`STYLE`),
+      `graph.js` (`Graph` class — tree/chain construction + layout),
+      `camera.js` (`Camera` class — pan/zoom/panel-width transform, never
+      holds a `Graph`, takes one as an argument where it needs one),
+      `navigation.js` (`navigateGraph`, pure aside from its own "last child
+      visited" memory), and `render.js` (drawing only). `canvas.js` itself is
+      now just the `state` object (`{graph, camera, selectedNode,
+      hoveredNode}`) plus DOM event wiring — the readable top-level flow.
+      `console.js`/`editpanel.js`/`shortcuts.js` read and act through `state`
+      instead of the old flat globals. Still no bundler — six `<script>` tags
+      loaded in dependency order.
 - [~] **Docs.** README is synced with `execute_commands` (command list,
       `task ai` flags, Web UI section, `task setup` walkthrough);
       `help_menu.py` lists `task browser` / `task help`, and its stale
@@ -616,10 +671,10 @@ Re-scope this section before starting 2.4.
       needs no edit — it `literalinclude`s the `builder-inited`-generated
       dump of `help_general`.
 - [ ] **UX pass.** Empty/loading state for the DAG when a user has no tasks
-      yet (currently the app would just render nothing); a keyboard shortcut
-      to toggle the console (e.g. backtick); consistent spacing/typography
-      in `style.css`. (Edge legend dropped — depended on 1.4's dependency/
-      link edges, now deferred to 2.0.)
+      yet (currently the app would just render nothing); consistent
+      spacing/typography in `style.css`. (Console-toggle keybind — done in
+      Phase 4's `shortcuts.js` (backtick). Edge legend dropped — depended on
+      1.4's dependency/link edges, now deferred to 2.0.)
 - [ ] Re-check the Phase 0 fixes are still holding once the web UI is
       exercising more command paths than the CLI alone did.
 
@@ -715,16 +770,30 @@ endpoints.
       **`console.js` change:** extracted `toggleConsole(force)` (focus on
       open / blur on close), `showAll()`, and a `postCommand(input)` helper,
       all reused by `shortcuts.js`.
+      **Refinements (9-10):** `Delete` lost its `confirm()` (broke the flow);
+      `Esc` no longer moves the camera (leave field → close edit panel with a
+      re-centre → deselect), and `e` closing the panel shares that path;
+      backtick focuses the console input when the console is open but
+      unfocused rather than toggling it shut; double-click a node opens the
+      edit panel; `Enter` in a single-line edit-panel field commits + blurs.
+      `sendFieldUpdate` / `sendComment` moved onto `postCommand`, which now
+      also carries the active `show` filter (see Phase 5).
 
 ---
 
 ## Phase 5 — CLI view
 
-- [ ] **Expand what `task show` renders, and its options.** Exact scope TBD —
-      needs a working session with Alex to pin down. Candidates: filter by
-      status / priority / completion, depth limits, flat vs. tree layout,
-      sort order, inline comments / links, format and colour toggles. Prompt
-      before implementing.
+- [~] **Expand what `task show` renders, and its options.** Attribute
+      **filtering landed early** (9-10), out of band, driven by a concrete
+      ask: `task show 'attr<op>value' ...` in `taskai/filters.py` —
+      AND-ed tests, ops `= > < >= <=`, `=` on text is fnmatch, matches shown
+      with their parent chain (`view_lists` gained `only_ids`). Wired through
+      the CLI (`Controller.show_filtered`, `show` dispatch) and the browser
+      (`_run_show` → `_run_filter` → pruned tree + `filtered` flag, plus a
+      persisted `activeFilter` on `/api/command` so mutations keep the view).
+      Still open, and still needs a session with Alex to scope: depth limits,
+      flat vs. tree layout, sort order, inline comments / links, format and
+      colour toggles.
 - [ ] **New view-settings config keys.** Extend `CLIConfig` (today just
       `DISPLAY_STRING` / `DISPLAY_COLORS`) with keys backing whatever the
       expanded view supports; document them in `docs/configuration.md` and
@@ -757,3 +826,121 @@ endpoints.
 - [ ] Write a short "show and tell" (what it is, the everything-is-an-item
       model, the AI layer, the canvas view) built around the gif, and decide
       on channels (Show HN, r/commandline, r/productivity, GitHub topics).
+
+---
+
+## Phase 8 — Chain CLI & data integrity
+
+The chain data model (`is_chain_head`/`prev_chain_id`/`next_chain_id` on
+`TodoItem`, `JsonDirectoryDatabase.insert_node_into_chain` /
+`remove_node_from_chain` / `delete_chain`) and the browser rendering/nav for
+it (DEVPLAN 1.8) already exist. This phase is CLI-side: finish the command
+surface and fix the bugs found while designing it, so a chain is a fully
+first-class thing a user can build, browse, and tear down from the terminal
+— blocking the next release. Intended use cases: **(1)** define a sequential
+chain of tasks, **(2)** delete individual items out of a chain — linked-list
+style, the rest re-links around the hole — and **(3)** delete an entire
+chain in one shot. A fourth, explicitly called out as a primary workflow:
+navigate along an in-progress chain and `clear` away the items already
+marked done as you go, tetris-style, leaving just the part still in
+progress.
+
+**Bugs to fix (foundational — the new commands below depend on these):**
+
+- [x] **Deleting a chain head orphans the rest of the chain.**
+      `remove_node_from_chain`'s "node has only a next" branch (fires
+      whenever the item being removed from a chain is currently the head)
+      promotes the next link to head and copies the old head's `parent_id`
+      onto it, but never updates the actual parent's `child_ids` to swap the
+      deleted head's id for the new one. The parent keeps pointing at a
+      dead id; the rest of the chain becomes unreachable from the tree
+      (not anyone's child, not a root) even though the JSON records
+      survive. Fix this at the `remove_node_from_chain`/`delete_item` level
+      itself (not as a special case bolted onto one call site) — `clear`'s
+      item-by-item deletion loop and a plain `task delete <head>` both need
+      to go through this same path and come out correct.
+- [x] **`_get_root_ids` (`cli.py`) doesn't exclude chain members.** It
+      filters on `parent_id is None` only, so `task show all` lists every
+      non-head chain link as a spurious top-level root. Add the same
+      `prev_chain_id is None` check the browser's `Graph` already uses.
+- [x] **`insert_node_into_chain` doesn't detach `node` from a chain it's
+      already in**, and doesn't clear a stale `is_chain_head` on it. Not
+      hit today because the only caller (`next_node`) always hands it a
+      freshly-created item — becomes a real risk once `task chain` (below)
+      lets you splice two *existing* items together, possibly ones already
+      mid-chain.
+
+**New/wired CLI commands:**
+
+- [x] `task next <prev> <name>` — already exists (create + append), keep as
+      is. Fix in passing: `execute_commands`'s `case "next":` doesn't
+      forward `**kwargs` to `Controller.next_node`, so e.g. `--due_by` on
+      `task next` is silently dropped — same landmine class as the old
+      `task ai --context` bug (DEVLOG 8-22). Thread `**kwargs` through like
+      `case "ai":` was fixed to do.
+- [x] **`task chain <prev_id> <node_id>`** — new dispatch wiring the
+      already-written, currently-unreachable `Controller.insert_node_as_chain`.
+      Links two *existing* items. Per Alex: **do not refuse if `node`
+      already has a parent — pop it off that parent (remove from
+      `child_ids`, clear `parent_id`) and splice it into the chain
+      instead.** This is the "malleable graph" call: moving a node from
+      tree-child to chain-member is one command, not detach-then-chain.
+      `node`'s own `child_ids` are untouched either way — a chain member is
+      allowed real children of its own (they render to the side; see
+      DEVPLAN 1.8), only its *parent* relationship is exclusive between
+      "tree child" and "chain member."
+- [x] **`task unchain <node_id>`** — new dispatch wiring the
+      already-written, currently-unreachable `Controller.remove_node_as_chain`.
+      Detaches one item from its chain without deleting it. Per Alex:
+      **symmetric to `chain` above** — after splicing `node` out
+      (`remove_node_from_chain`), add it as a child of *the chain head's
+      parent* (walk `prev_chain_id` to the true head, read that head's
+      `parent_id`, `add_child_to_parent` there; if the head is itself a
+      root, `node` becomes a root too). Pulls it out of the sequence and
+      into the parent's set of children. A no-op on the reparenting step if
+      `node` being unchained *is* the head — it's already that parent's
+      child.
+- [x] **`task delete <id> -chain`** — new flag on the existing `delete`
+      command (same convention as `complete`/`done`'s `-r`/`-recursive`),
+      wiring the already-written, currently-unreachable `db.delete_chain`.
+      Deletes the *entire* chain `id` belongs to, not just `id` onward —
+      walk `prev_chain_id` back to the true head first, so it works no
+      matter which link you target, then cascade forward and detach the
+      head from its tree parent the normal way.
+- [x] **`clear` needs to actually reach chain members.**
+      `Controller._flatten_item_descendants` (used by `task clear <parent>`
+      to scope which completed items to sweep) walks `child_ids` only. A
+      chain's non-head members are never in anyone's `child_ids` — they're
+      only reachable by walking `next_chain_id` from the head — so today
+      `task clear <chain-head-or-ancestor>` silently misses every
+      completed item past the head. Extend the walk to also follow
+      `next_chain_id` (and recurse into each chain member's own
+      `child_ids`, same as the browser's `flatten`/`buildTree` do). Bare
+      `task clear` (no parent) already iterates every item id in the db, so
+      it isn't blind to chain members the same way — it just needs the
+      head-deletion bug fixed above so clearing a *done* head doesn't
+      orphan the still-in-progress rest of the chain out from under itself.
+      This is the primary use case Alex called out: navigate along a chain,
+      `clear` the done items as you pass them, tetris-style, and be left
+      with just the in-progress remainder correctly re-linked (and, if the
+      head itself was cleared, correctly reattached to the tree parent).
+
+**Data structuring:**
+
+- [x] **Drop the stored `is_chain_head` field, derive it instead**
+      (`prev_chain_id is None and next_chain_id is not None`). It's exactly
+      the field that's gone out of sync in the bugs above, the frontend
+      already doesn't use it (uses `chainNext`/`chainPrev` presence
+      instead — DEVPLAN 1.8), and removing it is backward-compatible
+      (Pydantic silently ignores the leftover key in old JSON — no
+      migration needed). Replace the one real remaining consumer,
+      `delete_item`'s cascade check
+      (`get_item_attr(child_id, "is_chain_head")`), with the derived check.
+
+**Docs:** [x] `next`/`chain`/`unchain`/`delete -chain` are now documented in
+[taskai/help_menu.py](taskai/help_menu.py) (a new "Chains:" section, an
+updated "Deleting:" section, and a worked example) — which is also
+`task ai`'s verbatim command reference, so the AI can use all of this too
+now.
+
+Phase 8 is complete.

{taskai_cli-1.8.0 → taskai_cli-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: taskai-cli
-Version: 1.8.0
+Version: 1.9.0
 Author-email: Alex Paskal <alexcpaskal@gmail.com>
 Requires-Python: >=3.12
 Requires-Dist: fastapi>=0.141.1

taskai_cli-1.9.0/docs/browser-mode.md

@@ -0,0 +1,51 @@
+# Browser mode
+
+```bash
+task browser
+```
+
+This starts a local web server and serves a visual view of your task tree.
+
+## The canvas
+
+The whole tree is drawn as connected cards. Drag to pan, scroll to zoom.
+Double-click a card to center on it and open its edit panel.
+
+- **Completed** items are tinted green.
+- **`status`** text appears in the top corner of a card.
+- **Soft links** (`task link`) are drawn as a dashed copy of the linked item
+  under its host, distinct from the solid parent/child connectors.
+
+## The edit panel
+
+Click a card to select it; double-click it, or press `e`, to open the edit
+panel on the right. It has a field for the name, description, status, priority,
+due date, and completion, plus a comment feed. Changes are saved as you make
+them — there is no save button. In a single-line field, `Enter` commits the
+change and leaves the field.
+
+## The console
+
+The panel at the bottom takes raw `task` commands and runs them against the
+same data, printing their output and refreshing the canvas. Anything you can
+type on the command line works here.
+
+Filtering sticks: after `show 'priority>=2'` the canvas shows only the matches
+(and their parents), and it stays scoped that way as you edit and delete —
+until `show all` clears it.
+
+## Keyboard
+
+Press `?` for the full list in the app. The essentials:
+
+| Key | Action |
+|---|---|
+| arrows | move the selection through the tree |
+| `Shift`+arrows | pan the view |
+| `+` / `-` / `0` | zoom in / out / fit |
+| `e` | toggle the edit panel |
+| `` ` `` | focus / close the console |
+| `a` | add a child of the selected card and name it |
+| `d` | toggle done on the selected card |
+| `Delete` | delete the selected card |
+| `Esc` | leave a field, then close the panel, then clear the selection |

{taskai_cli-1.8.0 → taskai_cli-1.9.0}/docs/getting-started.md

@@ -82,6 +82,15 @@ task show "Write first post"
 task show 2
 ```
 
+Or narrow the tree to items matching a set of attribute tests (each shown with
+its parents for context):
+
+```bash
+task show 'priority>=2' 'completed=false'
+```
+
+See [Managing the tree](managing-the-tree.md) for the operators.
+
 ## Work an item and finish it
 
 ```bash

{taskai_cli-1.8.0 → taskai_cli-1.9.0}/docs/index.md

@@ -13,6 +13,8 @@ A command-line task manager with AI features.
   items at any depth; there's no separate notion of "lists"
 - **Attach data to each item** — description, due date, priority, status,
   completion, comments
+- **Filter** — `task show 'priority>=2' 'due_by<10-01-2026'` narrows the tree to
+  matching items and their parents
 - **Soft-link** an item under more than one parent without moving it
 - **Interactive mode** — run `task` with no arguments for a live view that
   redraws as you type commands

{taskai_cli-1.8.0 → taskai_cli-1.9.0}/docs/interactive-mode.md

@@ -18,6 +18,7 @@ redraws with the updated tree.
 
 - A `show` command sets the view that stays on screen — `task show "Launch
   blog"` keeps that subtree visible as you keep working; `show all` goes back to
-  the whole tree.
+  the whole tree. A [filter](managing-the-tree.md) such as `show 'priority>=2'`
+  works here too, and stays applied as the view redraws.
 - Every other command runs, then the view refreshes.
 - Leave with `exit`, `quit`, or Ctrl-C.

{taskai_cli-1.8.0 → taskai_cli-1.9.0}/docs/managing-the-tree.md

@@ -32,6 +32,22 @@ task show 4                # one item in full, by id
 task show "Set up hosting" # one item in full, by name
 ```
 
+## Filter the tree
+
+Give `task show` one or more `attribute<operator>value` tests and it prints only
+the items matching *all* of them, each with its parent chain for context:
+
+```bash
+task show 'name=Write*'                     # = on text is a glob match
+task show 'priority>=2' 'completed=false'
+task show 'status=in review' 'due_by<10-01-2026'
+```
+
+Operators are `=`, `>`, `<`, `>=`, `<=`. Text fields (`name`, `description`,
+`status`) glob-match on `=`; `priority`, `due_by`, `created_on`, and `id`
+compare numerically / by date. Put no space around the operator, and quote each
+test so your shell doesn't treat `>` and `<` as redirects.
+
 ## Move items
 
 ```bash

{taskai_cli-1.8.0 → taskai_cli-1.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taskai-cli"
-version = "1.8.0"
+version = "1.9.0"
 description = ""
 authors = [{name = "Alex Paskal", email = "alexcpaskal@gmail.com"}]
 readme = "README.md"

{taskai_cli-1.8.0 → taskai_cli-1.9.0}/taskai/browser.py

@@ -81,6 +81,25 @@ def get_tree():
 
 class CommandRequest(BaseModel):
     input: str
+    # raw filter args from the last `show <attr><op>value ...` the frontend
+    # ran, if any — so a mutation's refreshed tree stays scoped to that view
+    # instead of snapping back to the whole forest
+    filter: str | None = None
+
+
+def _response_tree(filter_str):
+    """The tree a mutation should return: pruned to `filter_str`'s matches
+    (+ their parent chains) when one is active, else the whole forest."""
+    if not filter_str:
+        return _full_tree()
+    tokens = _parse_arg_string(filter_str)
+    if not looks_like_filters(tokens):
+        return _full_tree()
+    try:
+        exprs = parse_filters(tokens)
+    except FilterError:
+        return _full_tree()
+    return _filtered_tree(with_ancestors(db, match_items(db, exprs)))
 
 
 @app.post("/api/command")
@@ -89,7 +108,7 @@ def run_command(request: CommandRequest):
     args, kwargs = _parse_remaining(arg_parts)
 
     if not args:
-        return {"output": "", "tree": _full_tree(), "focus": None}
+        return {"output": "", "tree": _response_tree(request.filter), "focus": None}
 
     if args[0] == "show":
         return _run_show(args)
@@ -101,7 +120,7 @@ def run_command(request: CommandRequest):
     except TaskCLIError:
         pass  # Controller.throw_error() already printed the error into `output`
 
-    return {"output": output.getvalue(), "tree": _full_tree(), "focus": None}
+    return {"output": output.getvalue(), "tree": _response_tree(request.filter), "focus": None}
 
 
 def _run_show(args):