--- title: "@henryqw/pi-goal" seo: description: "Persistent Pi goals that continue automatically until completion is proven with evidence." ---
Version v0.1.0
Monthly npm downloadsMIT license
Give the agent one goal, and Pi continues the work after each stop. The loop ends when the agent gives evidence for each deliverable, or when a stop limit applies. ## Install ```bash pi install npm:@henryqw/pi-goal ``` ## Use Ask the agent to work toward a goal, for example: "Make this a goal: all tests pass and the README documents `/export`." The agent calls `goal` with action `create`. When the agent stops before completion, Pi sends a hidden continuation, and the agent continues. | Surface | Type | Purpose | | --- | --- | --- | | `/goal` | command | For users: show the goal, its status, and tokens used. | | `/goal drop` | command | For users: drop the active goal and stop continuation. | | `goal` | tool | For agents: create, get, complete, or drop the goal. | | Footer status | ui | Shows the active goal objective and tokens used. | The `goal` tool is available to the model only. Other tools, such as `codemode`, cannot call it. ### Tool actions | Action | Parameters | Result | | --- | --- | --- | | `create` | `objective`, optional `deliverables` and `token_budget` | Starts a goal. Fails when a goal is already active. | | `get` | — | Shows the goal, tokens used, and remaining budget. | | `complete` | `evidence`: one `{ deliverable, evidence }` item for each deliverable | Completes the goal. | | `drop` | — | Drops the active goal. | When the goal has no deliverables, `complete` needs one evidence item with deliverable `objective`. The tool rejects missing, blank, duplicate, or unknown evidence items. The agent must get evidence from current state, such as files, command output, or tests. Memory of earlier turns is not evidence. ## Flow ![Pi Goal flow: a user prompt starts the agent run with hidden goal context; when the agent stops, stop guards add a hidden continuation or let Pi settle](data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjgwIiBoZWlnaHQ9IjcyMCIgdmlld0JveD0iMCAwIDEyODAgNzIwIiByb2xlPSJpbWciIGFyaWEtbGFiZWxsZWRieT0iZ29hbC1mbG93LXRpdGxlIGdvYWwtZmxvdy1kZXNjIiBpZD0iZ29hbC1mbG93LXJvb3QiPgo8dGl0bGUgaWQ9ImdvYWwtZmxvdy10aXRsZSI+UGkgR29hbCBjb250aW51YXRpb24gZmxvdzwvdGl0bGU+CjxkZXNjIGlkPSJnb2FsLWZsb3ctZGVzYyI+QSB1c2VyIHByb21wdCBzdGFydHMgYW4gYWdlbnQgcnVuIHdpdGggaGlkZGVuIGdvYWwgY29udGV4dC4gV2hlbiB0aGUgYWdlbnQgc3RvcHMsIHN0b3AgZ3VhcmRzIGRlY2lkZTogaWYgYWxsIHBhc3MsIGEgaGlkZGVuIGNvbnRpbnVhdGlvbiBzdGFydHMgdGhlIG5leHQgdHVybiBpbiB0aGUgc2FtZSBydW47IGlmIGFueSBndWFyZCBzdG9wcywgUGkgc2V0dGxlcy4gQSBjb21wbGV0ZSBvciBkcm9wcGVkIGdvYWwgZW5kcyB0aGUgbG9vcC48L2Rlc2M+CjxkZWZzPgogICAgICA8c3R5bGU+QGltcG9ydCB1cmwoJ2h0dHBzOi8vZm9udHMuZ29vZ2xlYXBpcy5jb20vY3NzMj9mYW1pbHk9SW5zdHJ1bWVudCtTZXJpZjppdGFsQDA7MSZhbXA7ZmFtaWx5PUdlaXN0OndnaHRANDAwOzUwMDs2MDAmYW1wO2ZhbWlseT1HZWlzdCtNb25vOndnaHRANDAwOzUwMDs2MDAmYW1wO2Rpc3BsYXk9c3dhcCcpOwogICAgICAjZ29hbC1mbG93LXJvb3QgeyBjb2xvcjogIzEwMTgyODsgfTwvc3R5bGU+CjxtYXJrZXIgaWQ9ImdvYWwtZmxvdy1hcnJvdyIgdmlld0JveD0iMCAwIDggOCIgcmVmWD0iNyIgcmVmWT0iNCIgbWFya2VyV2lkdGg9IjgiIG1hcmtlckhlaWdodD0iOCIgb3JpZW50PSJhdXRvIj48cGF0aCBkPSJNMCAwIEw4IDQgTDAgOFoiIGZpbGw9IiM0YzU2NjUiLz48L21hcmtlcj4KPG1hcmtlciBpZD0iZ29hbC1mbG93LWFycm93LWJsdWUiIHZpZXdCb3g9IjAgMCA4IDgiIHJlZlg9IjciIHJlZlk9IjQiIG1hcmtlcldpZHRoPSI4IiBtYXJrZXJIZWlnaHQ9IjgiIG9yaWVudD0iYXV0byI+PHBhdGggZD0iTTAgMCBMOCA0IEwwIDhaIiBmaWxsPSIjMWQ0ZWQ4Ii8+PC9tYXJrZXI+CjwvZGVmcz4KPHJlY3Qgd2lkdGg9IjEyODAiIGhlaWdodD0iNzIwIiBmaWxsPSIjZjBlZWU5Ii8+Cjx0ZXh0IHg9IjQwIiB5PSI1MiIgZm9udC1mYW1pbHk9Ikluc3RydW1lbnQgU2VyaWYsIHNlcmlmIiBmb250LXNpemU9IjI4IiBmaWxsPSIjMTAxODI4Ij5PbmUgZ29hbCwgY29udGludWVkIHVudGlsIGV2aWRlbmNlIG9yIGEgc3RvcCBsaW1pdDwvdGV4dD4KPCEtLSBDb25uZWN0aW9ucyBwcmVjZWRlIG5vZGVzLiBFYWNoIHBhdGggaGFzIGl0cyBvd24gYXR0YWNobWVudCBwb2ludC4gLS0+CjxnIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzRjNTY2NSIgc3Ryb2tlLXdpZHRoPSIxLjIiIG1hcmtlci1lbmQ9InVybCgjZ29hbC1mbG93LWFycm93KSI+CjxwYXRoIGQ9Ik0yNDAgMTY4IEgzMjAiLz4KPHBhdGggZD0iTTU2MCAxNjggSDY0MCIvPgo8cGF0aCBkPSJNODYwIDE2OCBIOTYwIi8+CjxwYXRoIGQ9Ik0xMTAwIDQwMCBWNDgwIi8+CjxwYXRoIGQ9Ik0zODAgMjE2IFY0ODAiLz4KPHBhdGggZD0iTTU2MCA1MjggSDk2MCIvPgo8L2c+CjxnIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzFkNGVkOCIgc3Ryb2tlLXdpZHRoPSIxLjYiIG1hcmtlci1lbmQ9InVybCgjZ29hbC1mbG93LWFycm93LWJsdWUpIj4KPHBhdGggZD0iTTk2MCAzNTIgSDg2MCIvPgo8cGF0aCBkPSJNNjQwIDM1MiBINTA4IFE1MDAgMzUyIDUwMCAzNDQgVjIxNiIvPgo8L2c+CjwhLS0gTGFiZWwgbWFza3Mgc3RheSBjbGVhciBvZiB0aGVpciBjb25uZWN0b3JzIGFuZCBhbGwgbm9kZSByZWN0YW5nbGVzLiAtLT4KPGcgZmlsbD0iI2YwZWVlOSI+CjxyZWN0IHg9Ijg4MCIgeT0iMzMyIiB3aWR0aD0iNjAiIGhlaWdodD0iMTIiLz4KPHJlY3QgeD0iNTMyIiB5PSIzMzIiIHdpZHRoPSI3NiIgaGVpZ2h0PSIxMiIvPgo8cmVjdCB4PSIxMTA0IiB5PSI0MzYiIHdpZHRoPSI4NCIgaGVpZ2h0PSIxMiIvPgo8cmVjdCB4PSIzODQiIHk9IjI5MiIgd2lkdGg9Ijg0IiBoZWlnaHQ9IjEyIi8+CjxyZWN0IHg9IjY5NiIgeT0iNTA4IiB3aWR0aD0iMTI4IiBoZWlnaHQ9IjEyIi8+CjwvZz4KPGcgZm9udC1mYW1pbHk9IkdlaXN0IE1vbm8sIG1vbm9zcGFjZSIgZm9udC1zaXplPSI4IiBmaWxsPSIjNGM1NjY1Ij4KPHRleHQgeD0iOTEwIiB5PSIzNDEiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZpbGw9IiMxZDRlZDgiPkFMTCBQQVNTPC90ZXh0Pgo8dGV4dCB4PSI1NzAiIHk9IjM0MSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZmlsbD0iIzFkNGVkOCI+Q09OVElOVUU6IFRSVUU8L3RleHQ+Cjx0ZXh0IHg9IjExMDgiIHk9IjQ0NSI+QU5ZIEdVQVJEIFNUT1BTPC90ZXh0Pgo8dGV4dCB4PSIzODgiIHk9IjMwMSI+Q09NUExFVEUgT1IgRFJPUDwvdGV4dD4KPHRleHQgeD0iNzYwIiB5PSI1MTciIHRleHQtYW5jaG9yPSJtaWRkbGUiPk5FWFQgU1RPUDogTk8gQUNUSVZFIEdPQUw8L3RleHQ+CjwvZz4KPHJlY3QgeD0iNDAiIHk9IjEyMCIgd2lkdGg9IjIwMCIgaGVpZ2h0PSI5NiIgcng9IjgiIGZpbGw9IiNmZmZmZmYiIHN0cm9rZT0iIzEwMTgyOCIgc3Ryb2tlLW9wYWNpdHk9IjAuMiIvPgo8cmVjdCB4PSIzMjAiIHk9IjEyMCIgd2lkdGg9IjI0MCIgaGVpZ2h0PSI5NiIgcng9IjgiIGZpbGw9IiNmZmZmZmYiIHN0cm9rZT0iIzEwMTgyOCIgc3Ryb2tlLW9wYWNpdHk9IjAuMiIvPgo8cmVjdCB4PSI2NDAiIHk9IjEyMCIgd2lkdGg9IjIyMCIgaGVpZ2h0PSI5NiIgcng9IjgiIGZpbGw9IiNmZmZmZmYiIHN0cm9rZT0iIzEwMTgyOCIgc3Ryb2tlLW9wYWNpdHk9IjAuMiIvPgo8cmVjdCB4PSI5NjAiIHk9Ijk2IiB3aWR0aD0iMjgwIiBoZWlnaHQ9IjMwNCIgcng9IjgiIGZpbGw9IiNlNmU0ZGUiIHN0cm9rZT0iIzEwMTgyOCIgc3Ryb2tlLW9wYWNpdHk9IjAuMiIvPgo8cmVjdCB4PSI2NDAiIHk9IjMwNCIgd2lkdGg9IjIyMCIgaGVpZ2h0PSI5NiIgcng9IjgiIGZpbGw9IiMxZDRlZDgiIGZpbGwtb3BhY2l0eT0iMC4wOCIgc3Ryb2tlPSIjMWQ0ZWQ4Ii8+CjxyZWN0IHg9IjMyMCIgeT0iNDgwIiB3aWR0aD0iMjQwIiBoZWlnaHQ9Ijk2IiByeD0iOCIgZmlsbD0iI2ZmZmZmZiIgc3Ryb2tlPSIjMTAxODI4IiBzdHJva2Utb3BhY2l0eT0iMC4yIi8+CjxyZWN0IHg9Ijk2MCIgeT0iNDgwIiB3aWR0aD0iMjgwIiBoZWlnaHQ9Ijk2IiByeD0iOCIgZmlsbD0iI2U2ZTRkZSIgc3Ryb2tlPSIjMTAxODI4IiBzdHJva2Utb3BhY2l0eT0iMC4yIi8+CjxnIGZvbnQtZmFtaWx5PSJHZWlzdCwgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMiIgZm9udC13ZWlnaHQ9IjYwMCIgZmlsbD0iIzEwMTgyOCI+Cjx0ZXh0IHg9IjYwIiB5PSIxNTIiPlVzZXIgcHJvbXB0PC90ZXh0Pgo8dGV4dCB4PSIzNDAiIHk9IjE1MiI+QWdlbnQgcnVuPC90ZXh0Pgo8dGV4dCB4PSI2NjAiIHk9IjE1MiI+QWdlbnQgc3RvcHM8L3RleHQ+Cjx0ZXh0IHg9Ijk4NCIgeT0iMTI4Ij5TdG9wIGd1YXJkczwvdGV4dD4KPHRleHQgeD0iNjYwIiB5PSIzMzYiPkhpZGRlbiBjb250aW51YXRpb248L3RleHQ+Cjx0ZXh0IHg9IjM0MCIgeT0iNTEyIj5Hb2FsIGNvbXBsZXRlIG9yIGRyb3BwZWQ8L3RleHQ+Cjx0ZXh0IHg9Ijk4NCIgeT0iNTEyIj5TZXR0bGU8L3RleHQ+CjwvZz4KPGcgZm9udC1mYW1pbHk9IkdlaXN0IE1vbm8sIG1vbm9zcGFjZSIgZm9udC1zaXplPSI4IiBmaWxsPSIjNGM1NjY1Ij4KPHRleHQgeD0iNjAiIHk9IjE3NiI+YmVmb3JlX2FnZW50X3N0YXJ0PC90ZXh0Pgo8dGV4dCB4PSI2MCIgeT0iMTk2Ij4rIGhpZGRlbiBwaS1nb2FsLWNvbnRleHQ8L3RleHQ+Cjx0ZXh0IHg9IjM0MCIgeT0iMTc2Ij5tb2RlbCB0dXJucyBhbmQgdG9vbCBjYWxsczwvdGV4dD4KPHRleHQgeD0iMzQwIiB5PSIxOTYiPmdvYWw6IGNyZWF0ZSAvIGdldDwvdGV4dD4KPHRleHQgeD0iNjYwIiB5PSIxNzYiPmFnZW50X2JlZm9yZV9zZXR0bGU8L3RleHQ+Cjx0ZXh0IHg9IjY2MCIgeT0iMTk2Ij5nb2FsIHJlYWQgZnJvbSBicmFuY2g8L3RleHQ+Cjx0ZXh0IHg9Ijk4NCIgeT0iMTUyIj5hbm90aGVyIGhhbmRsZXIgY29udGludWVzPC90ZXh0Pgo8dGV4dCB4PSI5ODQiIHk9IjE3NiI+bm8gYWN0aXZlIGdvYWw8L3RleHQ+Cjx0ZXh0IHg9Ijk4NCIgeT0iMjAwIj5ubyBVSTwvdGV4dD4KPHRleHQgeD0iOTg0IiB5PSIyMjQiPm91dGNvbWU6IGFib3J0IG9yIGVycm9yPC90ZXh0Pgo8dGV4dCB4PSI5ODQiIHk9IjI0OCI+Y29tcGFjdGlvbiBhYm9ydHMgdGhlIHJ1bjwvdGV4dD4KPHRleHQgeD0iOTg0IiB5PSIyNzIiPnRva2VucyB1c2VkICYjODgwNTsgdG9rZW5fYnVkZ2V0PC90ZXh0Pgo8dGV4dCB4PSI5ODQiIHk9IjI5NiI+MjAgY29udGludWF0aW9ucyBzaW5jZSBwcm9tcHQ8L3RleHQ+Cjx0ZXh0IHg9Ijk4NCIgeT0iMzIwIj5zYW1lIHRvb2wgYWN0aXZpdHkgdHdpY2U8L3RleHQ+Cjx0ZXh0IHg9IjY2MCIgeT0iMzYwIj5waS1nb2FsLWNvbnRpbnVhdGlvbjwvdGV4dD4KPHRleHQgeD0iNjYwIiB5PSIzODAiPmZ1bGwgZ29hbCBjb250ZXh0PC90ZXh0Pgo8dGV4dCB4PSIzNDAiIHk9IjUzNiI+Y29tcGxldGU6IGV2aWRlbmNlIHBlciBkZWxpdmVyYWJsZTwvdGV4dD4KPHRleHQgeD0iMzQwIiB5PSI1NTYiPi9nb2FsIGRyb3A8L3RleHQ+Cjx0ZXh0IHg9Ijk4NCIgeT0iNTM2Ij5hZ2VudF9zZXR0bGVkPC90ZXh0Pgo8dGV4dCB4PSI5ODQiIHk9IjU1NiI+YW4gYWN0aXZlIGdvYWwgc3RheXMgYWN0aXZlPC90ZXh0Pgo8L2c+Cjx0ZXh0IHg9Ijk4NCIgeT0iMzc2IiBmb250LWZhbWlseT0iR2Vpc3QsIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iMTIiIGZpbGw9IiM0YzU2NjUiPkFueSBtYXRjaCBzdG9wcyBjb250aW51YXRpb24uPC90ZXh0Pgo8cGF0aCBkPSJNNDAgNjQ0IEgxMjQwIiBzdHJva2U9IiMxMDE4MjgiIHN0cm9rZS1vcGFjaXR5PSIwLjEyIi8+Cjx0ZXh0IHg9IjQwIiB5PSI2ODAiIGZvbnQtZmFtaWx5PSJHZWlzdCwgc2Fucy1zZXJpZiIgZm9udC1zaXplPSIxMiIgZmlsbD0iIzRjNTY2NSI+SGlkZGVuIG1lc3NhZ2VzIGFyZSBub3Qgc2hvd24gaW4gdGhlIHRyYW5zY3JpcHQuIEVhY2ggY2hlY2sgcmVhZHMgdGhlIGdvYWwgZnJvbSB0aGUgY3VycmVudCBjb252ZXJzYXRpb24gYnJhbmNoLjwvdGV4dD4KPC9zdmc+Cg==) 1. Before each user prompt, Pi Goal adds the goal, the budget numbers, and the completion rules as hidden context. 2. When the agent stops, Pi Goal checks the stop limits. If no limit applies, it adds a hidden continuation with the same goal context. 3. The agent continues in the same run. A successful `complete` or `drop` ends the loop. Pi Goal does not add a continuation when another extension already continues the same stop. One continuation request then serves both extensions. ## State and storage Pi Goal keeps no goal state in memory or in files. It reads the latest goal record from the current conversation branch each time: - `goal` tool results store the full goal in their `details`. - `/goal drop` appends a `pi-goal` custom entry. - Each continuation is a hidden `pi-goal-continuation` message. Branch navigation, `/tree`, forks, resume, and `/undo` rewinds show the goal of the selected branch. A rewind to a point before `create` removes the goal from that branch. ## Limits and recovery | Limit | Behavior | Recovery | | --- | --- | --- | | Interactive only | Continuation needs a UI. Print mode and other modes without UI do not continue. | Send each next prompt manually. | | Maximum continuations | Continuation stops after 20 automatic turns since the latest user prompt. The count includes all goals, so a new goal does not reset it. | Send a prompt to continue. | | No progress | Continuation stops when two automatic turns in sequence show identical tool activity. | Send a prompt with new direction, or run `/goal drop`. | | Budget | Tokens used are the input, cache write, and output tokens of assistant responses after `create`. Cache reads do not count, because each turn reads the cached context again. Continuation stops when tokens used reach `token_budget`. The goal stays active; it is not complete. | Send a prompt to continue, or run `/goal drop`. | | Abort, error, compaction | Continuation stops after an abort or error. A compaction aborts the run, and Pi itself then stops continuation. | Send a prompt to continue. | | Evidence | Evidence is model-reported text. Pi Goal checks that it is present, not that it is true. | Examine the evidence in the `complete` result before you accept the work. |