pi-goals

Persistent goal tracking for Pi.

Inspired by Codex CLI’s /goal, pi-goals adds Pi-native goal management: durable objectives, queues, execution limits, reusable prompt templates, churn monitoring, context cleanup, and compact status integration.

Early preview: pi-goals is usable, but install ergonomics and APIs may change before 1.0.0.

What’s new

Goals can now clean up their own execution context when they finish.

You can ask Pi to remove a completed goal’s execution branch from the active session and keep only a compact summary. This works for a single long-running goal or for a queue of many goals.

That lets a queue keep moving without carrying every previous goal’s full branch forward, and without requiring a full-session compaction between goals.

See the changelog for details.

Features

• /goal command for creating, pausing, resuming, replacing, and clearing a persistent objective.
• Goal state that survives reloads, compaction, context-overflow recovery, and /tree navigation.
• Queue handoff recovery for completed goals, satisfied orchestration queue items, and compaction/context-overflow recovery, so queued work does not strand silently.
• Maximum execution limits with warning and cutoff enforcement.
• Minimum work thresholds that require a goal to run for at least a configured amount of time or tokens before completion is allowed.
• Reusable token-aware prompt templates from bounded .pi-goals/ and .ai/.pi-goals/ directories.
• Durable FIFO goal queue for sequential goal work.
• Agent-friendly queue controls for listing, enqueuing, starting, dequeuing, and removing queued goals.
• Natural-language reusable prompt discovery, so agents can turn project workflows into concrete goals.
• Natural-language goal inspection and updates.
• Automated churn monitoring for long-running goals.
• Compact Pi status/widget integration.

Install

Install globally for your Pi environment:

pi install npm:pi-goals

Install project-locally:

pi install -l npm:pi-goals

Suggested AGENTS.md

Without prior context, the agent sometimes will not route natural language to goal templates automatically. This short snippet helps it resolve queued prose through reusable workflows instead of treating every queue item as a one-off task.

## Goal queue prompt routing

When handling queued pi-goals prose, treat `.ai/.pi-goals/*` as reusable workflows. Before `start_queued_goal` for an abstract/task-type queue item, call `list_goal_templates` and match by name, aliases, description, and placeholders. If exactly one template fits and inputs are available, use `create_goal_from_template`; dequeue the prose item only after that concrete goal is satisfied. Use `start_queued_goal` only for direct one-off goals.

Never discard queued work. Do not call `dequeue_goal` unless the queue head is actually satisfied or the user explicitly authorizes removing that specific queued item. If uncertain, leave it queued and report the blocker.

### Goal queue processing and semantics

If you are asked to queue multiple goals at once, you must FIRST enqueue each goal, and then create and individually process each goal on the queue.