[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81642":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":15,"stars30d":16,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":13,"rankGlobal":10,"rankLanguage":10,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":18,"hasPages":18,"topics":20,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":13,"starSnapshotCount":13,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},81642,"pi-goals","transcendr\u002Fpi-goals","transcendr","Persistent goal tracking for Pi with durable objectives, goal queues, budgets, reusable prompts, churn monitoring, and context-managed handoffs.","https:\u002F\u002Fwithbryan.work",null,"TypeScript",24,0,21,1,3,"MIT License",false,"develop",[21,22,23,24,25,26,5],"codex","codex-cli","goals","pi","pi-dev","pi-extensions","2026-06-12 02:04:17","# pi-goals\n\nPersistent goal tracking for [Pi](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@earendil-works\u002Fpi-coding-agent).\n\nInspired by Codex CLI’s `\u002Fgoal`, `pi-goals` adds Pi-native goal management: durable objectives, queues, execution limits, reusable prompt templates, churn monitoring, context cleanup, and compact status integration.\n\n> Early preview: `pi-goals` is usable, but install ergonomics and APIs may change before `1.0.0`.\n\n## What’s new\n\nGoals can now clean up their own execution context when they finish.\n\nYou 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.\n\nThat lets a queue keep moving without carrying every previous goal’s full branch forward, and without requiring a full-session compaction between goals.\n\nSee the [changelog](CHANGELOG.md) for details.\n\n## Features\n\n- `\u002Fgoal` command for creating, pausing, resuming, replacing, and clearing a persistent objective.\n- Goal state that survives reloads, compaction, context-overflow recovery, and `\u002Ftree` navigation.\n- Queue handoff recovery for completed goals, satisfied orchestration queue items, and compaction\u002Fcontext-overflow recovery, so queued work does not strand silently.\n- Maximum execution limits with warning and cutoff enforcement.\n- Minimum work thresholds that require a goal to run for at least a configured amount of time or tokens before completion is allowed.\n- Reusable token-aware prompt templates from bounded `.pi-goals\u002F` and `.ai\u002F.pi-goals\u002F` directories.\n- Durable FIFO goal queue for sequential goal work.\n- Agent-friendly queue controls for listing, enqueuing, starting, dequeuing, and removing queued goals.\n- Natural-language reusable prompt discovery, so agents can turn project workflows into concrete goals.\n- Natural-language goal inspection and updates.\n- Automated churn monitoring for long-running goals.\n- Compact Pi status\u002Fwidget integration.\n\n## Install\n\nInstall globally for your Pi environment:\n\n```bash\npi install npm:pi-goals\n```\n\nInstall project-locally:\n\n```bash\npi install -l npm:pi-goals\n```\n\n## Suggested AGENTS.md\n\nWithout 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.\n\n```md\n## Goal queue prompt routing\n\nWhen handling queued pi-goals prose, treat `.ai\u002F.pi-goals\u002F*` as reusable workflows. Before `start_queued_goal` for an abstract\u002Ftask-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.\n\nNever 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.\n\n### Goal queue processing and semantics\n\nIf 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.\n\nNever violate the queue semantics by batching queue work and then dequeuing multiple queued work items at once as if it had run individually. Each goal on the queue MUST be run individually — no exceptions.\n\nProcess each queued item as its own concrete goal. If the queued goal objective indicates or references a goal template, treat the goal as an orchestration-type goal and create it with `create_goal_from_template`.\n```\n\n## `\u002Fgoal` command\n\nUse `\u002Fgoal` to create and manage a persistent objective that survives across turns, reloads, compaction, and `\u002Ftree` navigation.\n\n```text\n\u002Fgoal\n\u002Fgoal \u003Cobjective>\n\u002Fgoal queue\n\u002Fgoal queue \u003Cobjective-or-template>\n\u002Fgoal pause\n\u002Fgoal resume\n\u002Fgoal clear\n\u002Fgoal tools\n```\n\nSubcommands:\n\n- `\u002Fgoal` — show the current goal summary, status, budgets, and progress metadata.\n- `\u002Fgoal \u003Cobjective>` — create a new active goal. If a goal already exists, Pi asks before replacing it.\n- `\u002Fgoal queue` — list queued goals.\n- `\u002Fgoal queue \u003Cobjective-or-template>` — enqueue a direct objective or reusable template invocation for later.\n- `\u002Fgoal pause` — pause continuation and churn monitoring. If a goal-driven turn is active, Pi interrupts it.\n- `\u002Fgoal resume` — resume a paused goal and schedule continuation\u002Fmonitoring again.\n- `\u002Fgoal clear` — remove the current goal from active state.\n- `\u002Fgoal tools` — enable pi-goals tool-created goals to manage context.\n\nAgents can also inspect, create, update, pause, resume, complete, clear, or queue goals from natural-language instructions without requiring users to type slash commands for every operation.\n\n## Natural-language goal management\n\nYou do not have to use explicit `\u002Fgoal` commands for every operation. The Pi agent can manage goals from ordinary natural-language instructions.\n\nExamples:\n\n```text\nKeep working toward shipping this release, but pause the persistent goal while I answer email.\n```\n\n```text\nSet a goal to finish the README cleanup with a 30-minute budget, then keep going until it is done or blocked.\n```\n\n```text\nMark the current goal complete and summarize what changed.\n```\n\nUse `\u002Fgoal` when you want direct command control. Use natural language when you want the agent to choose the right goal operation from context.\n\nAgents can:\n\n- create goals,\n- update goals,\n- pause and resume goals,\n- queue goals,\n- complete goals,\n- summarize completed work,\n- modify execution limits and minimum work thresholds.\n\n## Goal execution limits and minimum work thresholds\n\n`pi-goals` supports both maximum execution limits and minimum required work thresholds.\n\nThese solve different problems:\n\n- maximum limits cap total execution,\n- minimum thresholds require the agent to spend at least a certain amount of time or tokens working on the goal before completion is allowed.\n\nYou can combine both on the same goal.\n\n### Maximum execution limits\n\nMaximum execution limits define the total allowed execution window for a goal.\n\nBoth time and token limits are supported.\n\nEnforcement happens in phases:\n\n- Near the configured limit, `pi-goals` sends a warning message asking the agent to begin wrapping up.\n- If execution exceeds the configured allowance, a small overage window is allowed.\n- After the overage window expires, hard cutoff enforcement terminates the goal automatically.\n\nThe warning and cutoff thresholds currently operate at roughly ±10% around the configured maximum.\n\nGoals terminated by hard enforcement cannot continue until the limit is raised or the goal is cleared.\n\n### Minimum work thresholds\n\nMinimum work thresholds require a goal to run for at least a configured amount of time or token usage before completion is allowed.\n\nFor example:\n\n- “Work on this for at least 10 minutes.”\n- “Spend at least 10 million tokens before considering this complete.”\n\nIf an agent attempts to complete a goal before the configured threshold has been satisfied:\n\n- the completion attempt is rejected,\n- the goal remains active,\n- the agent receives a follow-up instruction telling it to continue working.\n\n`pi-goals` tries to push the agent toward useful additional work instead of allowing meaningless quota-filling churn.\n\nTypical follow-up passes include:\n\n- requirement-gap audits,\n- validation expansion,\n- edge-case review,\n- adversarial review,\n- implementation simplification,\n- evidence gathering,\n- compatibility review,\n- documentation and handoff cleanup.\n\n> NOTE: there is currently no `\u002Fgoal` argument syntax for configuring limits or thresholds directly. They can still be configured through natural-language instructions, including while a goal is already running.\n\nExamples:\n\n```text\nCreate a goal for xyz and work on it for a minimum of 10 minutes.\n```\n\n```text\nStart working on the goal, and when you finish the initial implementation, set a time threshold for 8 minutes more than the current elapsed time.\n```\n\n## Goal queue\n\n`pi-goals` supports a durable FIFO queue for sequential work.\n\nQueued goals survive reloads and stay aligned with the rest of the session history.\n\n```text\n\u002Fgoal queue\n\u002Fgoal queue write the release notes\n\u002Fgoal queue fix-issue --issue ISSUE-123 -- verify the fix\n```\n\nFor larger batches, `\u002Fgoal queue` also accepts multi-item queue blocks so agents can enqueue an ordered stack before executing it head-to-tail.\n\nExample:\n\n```md\n\u002Fgoal queue [1] do thing one\n[2] do thing two\n[3] do thing three\n```\n\n> IMPORTANT: any line beginning with `[N]` is parsed as a new goal to enqueue immediately.\n\nNatural language works too:\n\n```md\nqueue up this goal stack pls:\n1. run execute-issue-stack goal for those two issues\n2. run `deslop-pipeline` on the full commit range since the last release 0.3.0.\n3. begin prepare pi-goals for release: run `release-readme-review` goal\n4. bump version to appropriate next version based on changes\n5. run `dirty-worktree-cleanup` goal\n6. read and execute everything here `solo:\u002F\u002Fproj\u002F2\u002Fscratchpad\u002Fpi-goals-release-cyc--10`\n7. report on the full goal stack and release readiness status (ready to push, ready to publish) when done\n```\n\n> NOTE: tags like `deslop-pipeline` refer to reusable goal templates. You can create a `.pi-goals` directory in your project and place your templates there. See [`.ai\u002F.pi-goals`](.ai\u002F.pi-goals) in this repository for examples.\n\nAgents can manage the queue through natural language just like individual goals:\n\n- list queued work,\n- enqueue items,\n- start the next queued goal,\n- resolve queued prose through reusable templates,\n- remove completed items after satisfaction.\n\nQueued prose that looks like a reusable workflow can be resolved through goal templates, worked as a concrete instantiated goal, and only then removed from the queue.\n\nManual dequeues require rationale and authority so queue history remains auditable.\n\n## Reusable `.pi-goals` prompts\n\n`pi-goals` can turn project-local prompt templates into reusable goal workflows.\n\nSupported template directories:\n\n```text\n.pi-goals\u002F\n.ai\u002F.pi-goals\u002F\n```\n\nExample structure:\n\n```text\n.pi-goals\u002F\n  fix-issue.md\n  release\u002Fchecklist.md\n\n.ai\u002F.pi-goals\u002F\n  create-issue-doc.md\n```\n\n`pi-goals` intentionally checks only these bounded root-level directories instead of recursively scanning the entire workspace. This keeps autocomplete responsive even when Pi is started from very large folders such as a home directory.\n\nInvoke templates through `\u002Fgoal`:\n\n```text\n\u002Fgoal fix-issue --issue ISSUE-123 -- verify the fix and update docs\n\u002Fgoal release\u002Fchecklist --version 0.1.1\n```\n\nTemplates support simple frontmatter:\n\n```markdown\n---\ndescription: Fix an issue using the repo workflow\naliases: fix, issue\nallow_commands: false\n---\nFix {{issue}}.\n\nExtra context: {{args}}\n```\n\nTemplate features:\n\n- `{{name}}` placeholders resolve from `--name value` or `--name=value` flags.\n- `{{args}}` resolves to text after ` -- `.\n- `description` appears in command completion.\n- `aliases` provide alternate invocation names.\n- Inline shell snippets using ``!`command` `` are supported only when `allow_commands: true`.\n- Shell execution is bounded by timeout and output limits.\n\nReusable templates work through both slash commands and natural-language workflows.\n\nAgents can:\n\n- discover templates,\n- match aliases\u002Fdescriptions\u002Fplaceholders,\n- fill required values from user requests,\n- create concrete goals from resolved prompts,\n- enqueue template invocations for later execution.\n\n## Between-goal context management\n\nLong-running queues can accumulate large amounts of one-off execution detail.\n\n`pi-goals` can remove completed execution branches from the active session and replace them with compact summaries before continuing to the next queued goal.\n\nThis keeps queue execution moving without forcing every previous execution branch to remain in active context.\n\n### Direct `\u002Fgoal` commands\n\n```text\n\u002Fgoal write the release notes and summarize context\n\u002Fgoal repo-worktree-inventory -- current state and summarize context\n\u002Fgoal queue clean the worktree and summarize context\n```\n\nTemplates behave the same way.\n\nWhen a template invocation includes “summarize context,” the summarization instruction is removed before template expansion so the workflow prompt itself stays clean.\n\n### Plain-language goal creation\n\nExample:\n\n```text\nCreate a goal to triage the release notes, summarize context before the next queued goal, then continue the queue.\n```\n\nPi currently exposes the internal session-tree context object only to slash-command handlers.\n\nNatural-language requests create goals through pi-goals tool calls. Those tool calls can create goals, but they cannot independently capture the navigation context object needed for later branch cleanup.\n\nIn a fresh session, run `\u002Fgoal tools` before creating natural-language goals that summarize context. It captures the internal Pi context object needed to navigate the session tree:\n\n```text\n\u002Fgoal tools\n```\n\nCreating any slash-command goal also captures the required context object:\n\n```text\n\u002Fgoal \u003Cyour first task> and summarize context\n```\n\nOnce captured, later natural-language-created goals can summarize context correctly.\n\nIf summarization fails, `pi-goals` reports the failure and continues processing the queue instead of stopping execution.\n\n## Automated churn monitor\n\nLong-running goals can drift, loop, or stop making meaningful progress.\n\n`pi-goals` runs a lightweight goal-scoped churn monitor that periodically checks whether useful progress is still happening.\n\nThe monitor can:\n\n- detect repeated no-progress loops,\n- detect repeated automatic turns,\n- send corrective follow-up instructions,\n- escalate when a safety pause is needed,\n- distinguish useful follow-up work from meaningless quota-filling churn,\n- maintain compact monitor history tied to the active goal.\n\nMonitor history survives reloads and `\u002Ftree` navigation.\n\n> NOTE: the churn monitor currently runs as an invisible headless Pi agent session. This is still experimental, but already works reasonably well. Yellow notices shown in the Pi UI are user-visible monitor notices. Separate instructions sent directly to the worker agent can be inspected through `\u002Ftree`.\n\n## This repository as a reference\n\nThis repository is both:\n\n1. the source for the `pi-goals` extension;\n2. a working reference for real-world goal-oriented workflows.\n\nThe repository intentionally includes:\n\n- reusable goal templates in [`.ai\u002F.pi-goals\u002F`](.ai\u002F.pi-goals\u002F),\n- issue docs in [`.ai\u002Fissues\u002F`](.ai\u002Fissues\u002F),\n- issue workflow artifacts in [`.ai\u002Fdocs\u002Fissue-workflow\u002F`](.ai\u002Fdocs\u002Fissue-workflow\u002F),\n- a prompt-template authoring guide in [`.ai\u002Fdocs\u002Fprompt-template-authoring.md`](.ai\u002Fdocs\u002Fprompt-template-authoring.md).\n\nThese examples demonstrate:\n\n- release-review workflows,\n- issue execution workflows,\n- queue-stack orchestration,\n- acceptance verification,\n- deslop workflows,\n- evidence and handoff patterns.\n\nIf you want to build your own reusable workflows, adapt the patterns instead of copying them blindly.\n\n## Roadmap\n\nCurrent execution-ready roadmap items include:\n\n- durable completion proofs,\n- `\u002Fgoal audit`,\n- agent-managed subgoals,\n- idle-tolerant waiting,\n- dependency watchers,\n- worktree starts,\n- multi-goal collections,\n- history\u002Fcheckpoints,\n- progress estimates,\n- widget hardening,\n- safer natural-language `\u002Fgoal update` editing,\n- stronger queue continuation and dequeue reminders.\n\n## Development\n\n```bash\nnpm install\nnpm run gates:quality\n```\n\n`npm run gates:quality` runs the project quality gate for the extension, including:\n\n- Sentrux structure checks,\n- TypeScript validation,\n- Pi extension load validation.\n\nDevelopment quality checks require the `sentrux` CLI to be available on `PATH`.\n\n## Status\n\nThis is an early public preview intended for collaborators and early testers.\n\nExpect rough edges and breaking changes before `1.0.0`.\n\n## License\n\nMIT\n","pi-goals 是一个为 Pi 编程代理设计的持久目标跟踪工具，支持持久化的目标管理、队列处理、预算控制、可重用的提示模板、流失监控以及上下文管理的手动切换。项目采用 TypeScript 编写，并提供了一系列功能，如通过 `\u002Fgoal` 命令创建和管理目标，目标状态在重新加载或上下文溢出恢复后仍然保持，自动化的长运行目标监控，以及紧凑的状态集成等。它适用于需要对多个连续任务进行自动化管理和监控的场景，特别是在涉及复杂工作流和长期运行的任务时。当前版本为早期预览版，部分API和安装方式可能会在正式1.0.0版本前有所调整。",2,"2026-06-11 04:05:48","CREATED_QUERY"]