@leo-alvarenga/pi-todo-list 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonardo A. Alvarenga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# pi-todo-list
+
+Session-aware todo list overlay for the [Pi coding agent](https://github.com/earendil-works/pi-mono).
+The agent manages tasks with a `todo` tool while you watch them live in a panel above the input editor.
+
+## Features
+
+- **`todo` tool** — the agent can add tasks, update their status
+  (`pending` → `in-progress` → `completed`), declare dependencies
+  (`blockedBy`), remove, list, and clear. Invalid operations (unknown ids,
+  self-blocks, dependency cycles) are rejected before any state change.
+- **Live TUI panel** above the input editor — `Todos (done/total)` header,
+  status glyphs (`○` pending, `◐` in-progress, `✓` completed), blocked-task
+  hints, and a hardcoded row budget with a `+N more` summary line.
+- **Toggle with `Ctrl+Shift+T`** — collapsed shows just the header.
+- **`/todos` command** — prints the full list grouped by status straight to
+  the terminal transcript.
+- **Session-isolated state** — each session has its own list; it survives
+  `/reload` and context compaction with no external files, because state is
+  replayed from the session branch (tool results + custom entries), never
+  written by the extension itself.
+- **No configuration, no localization** — all limits are hardcoded constants
+  and all text is English.
+
+## Install
+
+```bash
+pi install ./packages/pi-todo-list
+```
+
+or add the local path / npm spec to your project `.pi/settings.json`, then
+run `/reload`.
+
+## Usage
+
+Tell the agent: *"track these tasks as todos: …"*, or use the tool directly:
+
+- `todo add` with `text`
+- `todo update` with `id` and optional `status` / `text` / `blockedBy`
+- `todo remove` / `todo list` / `todo clear`
+
+Run `/todos` yourself at any time to see the full grouped list.
+
+## Keybinding
+
+`Ctrl+Shift+T` toggles the panel. If your terminal intercepts that chord
+(e.g. GNOME Terminal opens a new tab), pick a free one and change
+`PANEL_TOGGLE_CHORD` in `src/constants.ts`.
+
+## Development
+
+```bash
+pnpm --filter @leo-alvarenga/pi-todo-list typecheck
+pnpm --filter @leo-alvarenga/pi-todo-list test
+```
+
+To release a new version, bump `version` in `package.json`, then push a tag
+(`git tag pi-todo-list@0.1.0 && git push origin pi-todo-list@0.1.0`). The
+`.github/workflows/publish-pi-todo-list.yml` workflow publishes to npm
+(requires the `NPM_TOKEN` repository secret).
+
+## License
+
+MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Leonardo A. Alvarenga.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@leo-alvarenga/pi-todo-list",
+  "version": "0.2.0",
+  "description": "Session-aware todo list overlay for Pi: todo tool, /todos command, and a live TUI panel",
+  "license": "MIT",
+  "repository": "github.com/leo-alvarenga/pi-mono",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-extension",
+    "pi-package",
+    "pi",
+    "todo"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!src/*.test.ts"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/command.ts

@@ -0,0 +1,51 @@
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+import { groupByStatus } from "./core";
+import { REPORT_ENTRY } from "./constants";
+import type { TodoStore } from "./state";
+import type { Todo } from "./types";
+import { getStyledTodo } from "./utils";
+
+const renderList = (todos: Todo[], theme: Theme): string => {
+  if (todos.length === 0) return `  ${theme.fg("dim", "No todos.")}`;
+
+  const { completed, inProgress, pending } = groupByStatus(todos);
+  const lines: string[] = [];
+
+  const section = (label: string, items: Todo[]): void => {
+    if (items.length === 0) return;
+
+    lines.push(`  ${theme.fg("muted", `${label} (${items.length})`)}`);
+    for (const t of items) lines.push(getStyledTodo(t, todos, theme));
+
+    lines.push("");
+  };
+
+  section("Completed", completed);
+  section("In progress", inProgress);
+  section("Pending", pending);
+
+  return lines.join("\n");
+};
+
+export function registerTodosCommand(pi: ExtensionAPI, store: TodoStore): void {
+  pi.registerCommand("todos", {
+    description: "Show all todos grouped by status",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("/todos requires interactive mode", "error");
+        return;
+      }
+
+      pi.appendEntry(REPORT_ENTRY, { todos: [...store.getState(ctx).todos] });
+    },
+  });
+
+  pi.registerEntryRenderer<{ todos: Todo[] }>(
+    REPORT_ENTRY,
+    (entry, _options, theme) => {
+      return new Text(renderList(entry.data?.todos ?? [], theme), 0, 0);
+    },
+  );
+}

package/src/constants.ts

@@ -0,0 +1,34 @@
+import type { KeyId } from "@earendil-works/pi-tui";
+import { TodoStatus, TodoStatusUi } from "./types";
+
+/** Task statuses, in lifecycle order. All limits are hardcoded — no config files. */
+export const STATUSES = ["pending", "in-progress", "completed"] as const;
+
+export const STATUS_STYLES: Record<TodoStatus, TodoStatusUi> = {
+  pending: { icon: " ", fg: "text", color: "text" },
+  "in-progress": { icon: "󱥸 ", fg: "accent", color: "accent", bold: true },
+  completed: { icon: " ", fg: "dim", color: "success", strikethrough: true },
+};
+
+/** Max task rows rendered in the expanded TUI widget. */
+export const MAX_PANEL_ROWS = 8;
+
+/** Max characters per task text. */
+export const MAX_TEXT_LENGTH = 120;
+
+/** Widget key for the panel above the editor. */
+export const WIDGET_KEY = "todos";
+
+/** Custom entry type carrying the durable state snapshot. */
+export const STATE_ENTRY = "todos.state";
+
+/** Custom entry type rendered by the /todos command. */
+export const REPORT_ENTRY = "todos.report";
+
+/** Chord that toggles the panel. Chosen in setup: free in pi's default keybindings. */
+export const PANEL_TOGGLE_CHORD: KeyId = "alt+t";
+
+export const PANEL_STATE_ICON = {
+  collapsed: "󰅂",
+  expanded: "󰅀",
+};

package/src/core.ts

@@ -0,0 +1,257 @@
+import { MAX_TEXT_LENGTH } from "./constants";
+import type { Todo, TodoAction, TodoState, TodoStatus } from "./types";
+
+export type Patch = {
+  text?: string;
+  status?: TodoStatus;
+  blockedBy?: number[];
+};
+
+export type ActionResult =
+  { ok: true; state: TodoState; text: string } | { ok: false; error: string };
+
+const clone = (todos: Todo[]): Todo[] =>
+  todos.map((t) => ({ ...t, blockedBy: [...t.blockedBy] }));
+
+const cleanText = (text: string): string | undefined => {
+  const t = text.trim();
+  return t.length === 0 ? undefined : t;
+};
+
+const textError = (): { ok: false; error: string } => ({
+  ok: false,
+  error: `text is limited to ${MAX_TEXT_LENGTH} characters`,
+});
+
+function add(state: TodoState, text: string): ActionResult {
+  const t = cleanText(text);
+
+  if (!t) return { ok: false, error: "text required for add" };
+  if (t.length > MAX_TEXT_LENGTH) return textError();
+
+  const todo: Todo = {
+    text: t,
+    blockedBy: [],
+    id: state.nextId,
+    status: "pending",
+  };
+
+  return {
+    ok: true,
+    text: `Added todo #${todo.id}: ${todo.text}`,
+    state: { todos: [...state.todos, todo], nextId: state.nextId + 1 },
+  };
+}
+
+function validateBlockedBy(
+  todos: Todo[],
+  id: number,
+  blockedBy: number[],
+): string | undefined {
+  const seen = new Set<number>();
+
+  for (const b of blockedBy) {
+    if (b === id) return "task cannot block itself";
+
+    if (!todos.some((t) => t.id === b)) {
+      return `blockedBy references unknown todo #${b}`;
+    }
+
+    seen.add(b);
+  }
+
+  return undefined;
+}
+
+function update(state: TodoState, id: number, patch: Patch): ActionResult {
+  if (
+    patch.text === undefined &&
+    patch.status === undefined &&
+    patch.blockedBy === undefined
+  ) {
+    return { ok: false, error: "nothing to update" };
+  }
+
+  const target = state.todos.find((t) => t.id === id);
+  if (!target) return { ok: false, error: `todo #${id} not found` };
+
+  const next = clone(state.todos);
+  const idx = next.findIndex((t) => t.id === id);
+
+  if (patch.text !== undefined) {
+    const t = cleanText(patch.text);
+
+    if (!t) return { ok: false, error: "text cannot be empty" };
+    if (t.length > MAX_TEXT_LENGTH) return textError();
+
+    next[idx] = { ...next[idx], text: t };
+  }
+
+  if (patch.blockedBy !== undefined) {
+    const err = validateBlockedBy(next, id, patch.blockedBy);
+    if (err) return { ok: false, error: err };
+
+    next[idx] = { ...next[idx], blockedBy: [...new Set(patch.blockedBy)] };
+  }
+
+  if (patch.status !== undefined) {
+    next[idx] = { ...next[idx], status: patch.status };
+  }
+
+  if (wouldCreateCycle(next, id)) {
+    return { ok: false, error: "would create a dependency cycle" };
+  }
+
+  return {
+    ok: true,
+    text: `Updated todo #${id}`,
+    state: { todos: next, nextId: state.nextId },
+  };
+}
+
+function remove(state: TodoState, id: number): ActionResult {
+  if (!state.todos.some((t) => t.id === id)) {
+    return { ok: false, error: `todo #${id} not found` };
+  }
+
+  const todos = state.todos
+    .filter((t) => t.id !== id)
+    .map((t) =>
+      t.blockedBy.includes(id)
+        ? { ...t, blockedBy: t.blockedBy.filter((b) => b !== id) }
+        : t,
+    );
+
+  return {
+    ok: true,
+    text: `Removed todo #${id}`,
+    state: { todos, nextId: state.nextId },
+  };
+}
+
+const blockedSuffix = (t: Todo, todos: Todo[]): string => {
+  const waiting = t.blockedBy.filter((b) => {
+    const bt = todos.find((x) => x.id === b);
+
+    return !bt || bt.status !== "completed";
+  });
+
+  if (waiting.length > 0) {
+    return ` (blocked by ${waiting.map((b) => `#${b}`).join(", ")})`;
+  }
+
+  return "";
+};
+
+function list(state: TodoState): ActionResult {
+  if (state.todos.length === 0) {
+    return { ok: true, state, text: "No todos" };
+  }
+
+  return {
+    state,
+    ok: true,
+    text: state.todos
+      .map(
+        (t) =>
+          `[${t.status === "completed" ? "x" : " "}] #${t.id}: ${t.text}${blockedSuffix(t, state.todos)}`,
+      )
+      .join("\n"),
+  };
+}
+
+function clear(): ActionResult {
+  return {
+    ok: true,
+    text: "Cleared all todos",
+    state: { todos: [], nextId: 1 },
+  };
+}
+
+/**
+ * Apply a tool action against a copy of the state.
+ * Returns the new state only when validation passes; the caller commits it.
+ */
+export function applyAction(
+  state: TodoState,
+  params: {
+    id?: number;
+    text?: string;
+    action: TodoAction;
+    status?: TodoStatus;
+    blockedBy?: number[];
+  },
+): ActionResult {
+  switch (params.action) {
+    case "add":
+      return add(state, params.text ?? "");
+
+    case "update":
+      if (params.id === undefined) {
+        return { ok: false, error: "id required for update" };
+      }
+
+      return update(state, params.id, params);
+
+    case "remove":
+      if (params.id === undefined) {
+        return { ok: false, error: "id required for remove" };
+      }
+
+      return remove(state, params.id);
+
+    case "list":
+      return list(state);
+
+    case "clear":
+      return clear();
+  }
+}
+
+/**
+ * True if `changedId` can reach itself by following blockedBy edges
+ * (direct, or through a chain) — i.e. the update would create a cycle.
+ */
+export function wouldCreateCycle(todos: Todo[], changedId: number): boolean {
+  const adj = new Map<number, number[]>();
+  for (const t of todos) adj.set(t.id, [...t.blockedBy]);
+
+  const done = new Set<number>();
+  const visiting = new Set<number>();
+
+  const dfs = (id: number): boolean => {
+    if (visiting.has(id)) return true;
+    if (done.has(id)) return false;
+
+    visiting.add(id);
+
+    for (const dep of adj.get(id) ?? []) {
+      if (dfs(dep)) return true;
+    }
+
+    visiting.delete(id);
+    done.add(id);
+
+    return false;
+  };
+
+  return dfs(changedId);
+}
+
+export function groupByStatus(todos: Todo[]): {
+  completed: Todo[];
+  inProgress: Todo[];
+  pending: Todo[];
+} {
+  const completed: Todo[] = [];
+  const inProgress: Todo[] = [];
+  const pending: Todo[] = [];
+
+  for (const t of todos) {
+    if (t.status === "completed") completed.push(t);
+    else if (t.status === "in-progress") inProgress.push(t);
+    else pending.push(t);
+  }
+
+  return { completed, inProgress, pending };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerTodosCommand } from "./command";
+import { STATE_ENTRY, WIDGET_KEY } from "./constants";
+import { TodoStore } from "./state";
+import { registerTodoTool } from "./tool";
+import { registerTodoWidget, refreshWidget } from "./widget";
+
+export default function (pi: ExtensionAPI): void {
+  const store = new TodoStore(
+    (snapshot) => pi.appendEntry(STATE_ENTRY, snapshot),
+    (ctx) => refreshWidget(ctx, store),
+  );
+
+  registerTodoTool(pi, store);
+  registerTodosCommand(pi, store);
+  registerTodoWidget(pi, store);
+
+  pi.on("session_start", (_event, ctx) => store.replay(ctx));
+  pi.on("session_tree", (_event, ctx) => store.replay(ctx));
+  pi.on("session_before_compact", (_event, ctx) => store.persistSnapshot(ctx));
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
+  });
+}

package/src/state.ts

@@ -0,0 +1,82 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { STATE_ENTRY } from "./constants";
+import type { TodoDetails, TodoState } from "./types";
+
+/**
+ * Session-scoped todo state.
+ *
+ * State is keyed by the active session id so forked/parallel sessions never
+ * overwrite each other, and it is replayed from the session branch on every
+ * session event, so it survives /reload and compaction without the extension
+ * writing any of its own files.
+ */
+export class TodoStore {
+  private readonly stateBySession = new Map<string, TodoState>();
+
+  constructor(
+    private readonly persist: (snapshot: TodoState) => void,
+    private readonly emitChange: (ctx: ExtensionContext) => void,
+  ) {}
+
+  private sid(ctx: ExtensionContext): string {
+    return ctx.sessionManager.getSessionId();
+  }
+
+  getState(ctx: ExtensionContext): TodoState {
+    const sid = this.sid(ctx);
+
+    let s = this.stateBySession.get(sid);
+    if (!s) this.stateBySession.set(sid, (s = { todos: [], nextId: 1 }));
+
+    return s;
+  }
+
+  /** Commit a validated snapshot: update memory, persist, refresh the panel. */
+  commit(ctx: ExtensionContext, next: TodoState): void {
+    this.stateBySession.set(this.sid(ctx), next);
+    this.persist(next);
+    this.emitChange(ctx);
+  }
+
+  /** Rebuild the current session's state from the session branch (no disk writes). */
+  replay(ctx: ExtensionContext): void {
+    const s = this.getState(ctx);
+    s.todos = [];
+    s.nextId = 1;
+
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "custom" && entry.customType === STATE_ENTRY) {
+        const d = entry.data as TodoState | undefined;
+
+        if (d) {
+          s.todos = d.todos;
+          s.nextId = d.nextId;
+        }
+
+        continue;
+      }
+
+      if (
+        entry.type === "message" &&
+        entry.message.role === "toolResult" &&
+        entry.message.toolName === "todo"
+      ) {
+        const d = entry.message.details as TodoDetails | undefined;
+
+        if (d && !d.error) {
+          s.todos = d.todos;
+          s.nextId = d.nextId;
+        }
+      }
+    }
+
+    this.emitChange(ctx);
+  }
+
+  /** Persist the latest snapshot right before compaction so it lands after the cut point. */
+  persistSnapshot(ctx: ExtensionContext): void {
+    const s = this.getState(ctx);
+    if (s.todos.length > 0) this.persist(s);
+  }
+}

package/src/tool.ts

@@ -0,0 +1,66 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import { STATUSES } from "./constants";
+import { applyAction } from "./core";
+import type { TodoStore } from "./state";
+import type { TodoDetails } from "./types";
+
+const TodoParams = Type.Object({
+  action: StringEnum(["add", "update", "remove", "list", "clear"] as const),
+  text: Type.Optional(Type.String({ description: "Task text (required for add; optional for update)" })),
+  id: Type.Optional(Type.Number({ description: "Task id (required for update/remove)" })),
+  status: Type.Optional(StringEnum([...STATUSES] as const)),
+  blockedBy: Type.Optional(Type.Array(Type.Number(), { description: "Task ids this task depends on" })),
+});
+
+export function registerTodoTool(pi: ExtensionAPI, store: TodoStore): void {
+  pi.registerTool({
+    name: "todo",
+    label: "Todo",
+    parameters: TodoParams,
+    description:
+      "Manage the session todo list. Actions: add (text), update (id, optional status/text/blockedBy), remove (id), list, clear",
+
+    async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+      const current = store.getState(ctx);
+      const result = applyAction(current, params);
+
+      if (!result.ok) {
+        return {
+          content: [{ type: "text", text: result.error }],
+          details: {
+            action: params.action,
+            todos: [...current.todos],
+            nextId: current.nextId,
+            error: result.error,
+          } satisfies TodoDetails,
+        };
+      }
+
+      store.commit(ctx, result.state);
+      return {
+        content: [{ type: "text", text: result.text }],
+        details: { action: params.action, todos: [...result.state.todos], nextId: result.state.nextId } satisfies TodoDetails,
+      };
+    },
+
+    renderCall(args, theme, _context) {
+      let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", args.action);
+      if (args.text) text += ` ${theme.fg("dim", `"${args.text}"`)}`;
+      if (args.id !== undefined) text += ` ${theme.fg("accent", `#${args.id}`)}`;
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, _options, theme, _context) {
+      const details = result.details as TodoDetails | undefined;
+      if (details?.error) return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+      const text = result.content[0];
+      const msg = text?.type === "text" ? text.text : "";
+      if (details?.action === "list") return new Text(theme.fg("muted", msg), 0, 0);
+      return new Text(theme.fg("success", "✓ ") + theme.fg("muted", msg), 0, 0);
+    },
+  });
+}

package/src/types.ts

@@ -0,0 +1,35 @@
+import { ThemeColor } from "@earendil-works/pi-coding-agent";
+import { STATUSES } from "./constants";
+
+export type TodoStatus = (typeof STATUSES)[number];
+
+export type TodoStatusUi = {
+  icon: string;
+  fg: ThemeColor;
+  bold?: boolean;
+  color: ThemeColor;
+  strikethrough?: boolean;
+};
+
+export interface Todo {
+  id: number;
+  text: string;
+  status: TodoStatus;
+  /** Ids of tasks this task depends on. */
+  blockedBy: number[];
+}
+
+export interface TodoState {
+  todos: Todo[];
+  nextId: number;
+}
+
+export type TodoAction = "add" | "update" | "remove" | "list" | "clear";
+
+/** Shape stored in tool-result details and the todos.state custom entry. */
+export interface TodoDetails {
+  action: TodoAction;
+  todos: Todo[];
+  nextId: number;
+  error?: string;
+}

package/src/utils.ts

@@ -0,0 +1,115 @@
+import { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+import { Todo, TodoStatus } from "./types";
+import { MAX_PANEL_ROWS, PANEL_STATE_ICON, STATUS_STYLES } from "./constants";
+
+export function getStyledTodoList(
+  todos: Todo[],
+  th: Theme,
+  width: number,
+  isCollapsed?: boolean,
+): string[] {
+  const indent = (str: string, level = 1) => "  ".repeat(Math.abs(level)) + str;
+
+  const lines: string[] = [
+    truncateToWidth(
+      indent(getStyledTodoListHeader(todos, th, isCollapsed)),
+      width,
+    ),
+  ];
+
+  if (!isCollapsed) {
+    lines.push("");
+
+    if (todos.length === 0) {
+      lines.push(
+        truncateToWidth(
+          indent(th.fg("dim", "No todos yet. Ask the agent to add some!"), 2),
+          width,
+        ),
+      );
+    } else {
+      const visible = todos.slice(0, MAX_PANEL_ROWS);
+
+      for (const t of visible) {
+        lines.push(
+          truncateToWidth(indent(getStyledTodo(t, todos, th), 2), width),
+        );
+      }
+
+      if (todos.length > visible.length) {
+        lines.push(
+          truncateToWidth(
+            indent(th.fg("dim", `… +${todos.length - visible.length} more`), 3),
+            width,
+          ),
+        );
+      }
+    }
+  }
+
+  lines.push("");
+
+  return lines;
+}
+
+export function getStyledTodoListHeader(
+  todos: Todo[],
+  th: Theme,
+  isCollapsed?: boolean,
+): string {
+  const count = todos.reduce<Record<TodoStatus, number>>(
+    (acc, t) => {
+      acc[t.status] = (acc[t.status] ?? 0) + 1;
+      return acc;
+    },
+    { pending: 0, "in-progress": 0, completed: 0 },
+  );
+
+  const collapseState = isCollapsed ? "collapsed" : "expanded";
+
+  const statuses: TodoStatus[] = ["pending", "in-progress", "completed"];
+
+  const counter = statuses
+    .map((s) => {
+      const { icon, color } = STATUS_STYLES[s] ?? STATUS_STYLES.pending;
+
+      return th.fg(color, `${icon}${count[s] ?? 0}`);
+    })
+    .join(th.fg("dim", " / "));
+
+  return th.fg(
+    "accent",
+    `${PANEL_STATE_ICON[collapseState]}  Todos - ${counter}`,
+  );
+}
+
+export function getStyledTodo(t: Todo, todos: Todo[], th: Theme): string {
+  const { icon, fg, bold, strikethrough, color } =
+    STATUS_STYLES[t.status] ?? STATUS_STYLES.pending;
+
+  const check = th.fg(color, icon);
+  const id = th.fg("accent", `#${t.id}`);
+
+  let text = th.fg(fg, t.text);
+
+  if (bold) text = th.bold(text);
+  if (strikethrough) text = th.strikethrough(text);
+
+  const waiting = t.blockedBy.filter((b) => {
+    const bt = todos.find((x) => x.id === b);
+
+    return !bt || bt.status !== "completed";
+  });
+
+  let line = `  ${check} ${id} ${text}`;
+  if (waiting.length > 0) {
+    line += th.fg(
+      "dim",
+      ` (blocked by ${waiting.map((b) => `#${b}`).join(", ")})`,
+    );
+  }
+
+  return line;
+}

package/src/widget.ts

@@ -0,0 +1,76 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+} from "@earendil-works/pi-coding-agent";
+
+import { PANEL_TOGGLE_CHORD, WIDGET_KEY } from "./constants";
+import type { TodoStore } from "./state";
+import type { TodoState } from "./types";
+import { getStyledTodoList } from "./utils";
+
+let collapsed = true;
+const hideIfEmpty = true;
+
+class TodoWidget {
+  private cachedWidth: number | undefined;
+  private cachedLines: string[] | undefined;
+
+  constructor(
+    private readonly theme: Theme,
+    private readonly snapshot: () => TodoState,
+    private readonly isCollapsed: () => boolean,
+  ) {}
+
+  render(width: number): string[] {
+    if (hideIfEmpty && this.snapshot().todos.length === 0) {
+      return [];
+    }
+
+    if (this.cachedLines !== undefined && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+
+    const lines = getStyledTodoList(
+      this.snapshot().todos,
+      this.theme,
+      width,
+      this.isCollapsed(),
+    );
+
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+
+    return lines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+
+export function refreshWidget(ctx: ExtensionContext, store: TodoStore): void {
+  if (!ctx.hasUI) return;
+
+  ctx.ui.setWidget(
+    WIDGET_KEY,
+    (_tui, theme) =>
+      new TodoWidget(
+        theme,
+        () => store.getState(ctx),
+        () => collapsed,
+      ),
+  );
+}
+
+export function registerTodoWidget(pi: ExtensionAPI, store: TodoStore): void {
+  pi.registerShortcut(PANEL_TOGGLE_CHORD, {
+    description: "Toggle todos panel",
+    handler: (ctx) => {
+      collapsed = !collapsed;
+
+      refreshWidget(ctx, store);
+    },
+  });
+}