@matheusbbarni/pi-goal-extension

Interactive, resumable Codex /goal sessions from inside Pi.

The extension calls the Codex CLI directly, keeps session metadata for resume, and renders a compact Codex-style live transcript in Pi. Managed goals persist under .codex-goals/ so you can stop, come back, and continue the same Codex session.

Features

• One-shot /goal runs and managed start/resume sessions
• Codex session ids stored for codex exec resume
• Live widget with recent Codex messages and command activity
• Reusable Markdown templates with {{placeholder}} substitution
• Agent tools so Pi can start or resume a goal for you
• Compact result messages appended to the Pi session after a manual run

Install

pi install npm:@matheusbbarni/pi-goal-extension

From this repo:

pi -e ./pi-goal-extension

Or as a local package:

pi install ./pi-goal-extension

[!NOTE] Codex CLI must be available on your PATH. The extension shells out to codex.

If an older global extension already registers /goal, Pi may suffix this one as /goal:1. Disable or remove the old extension if you want this package to own /goal.

Commands

/goal <text>                         Run one-shot Codex goal
/goal run <text> [options]           Run one-shot Codex goal
/goal start <name|path> [objective]  Create and run a managed goal
/goal resume [name] [prompt]         Resume a managed Codex session
/goal stop                           Abort/pause current goal
/goal status                         Show goals
/goal templates [query]              List reusable goal templates
/goal log [name]                     Show last output/log path
/goal edit [name]                    Edit the task file
/goal cancel <name> [--all]          Delete state
/goal archive <name>                 Archive state/task
/goal clean [--all]                  Remove completed goals
/goal nuke [--yes]                   Delete all .codex-goals data

Managed goals store lightweight state under .codex-goals/ and Codex JSONL transcripts under .codex-goals/logs/. When a manually-run /goal finishes, the extension appends a compact result message to the Pi session so the next Pi turn has the Codex outcome in context.

Reusable templates

Store Markdown or text templates under one of these workspace-root directories:

.pi-goals/
.ai/.pi-goals/
.codex-goals/templates/

Templates support simple frontmatter plus {{placeholder}} and {{args}} substitution:

---
description: Fix an issue with verification
aliases: fix, issue
---
Fix {{issue}}.

Extra context: {{args}}

Start a managed Codex goal from a template:

/goal templates
/goal start fix-123 --template fix-issue --issue ISSUE-123 -- update docs too

Agent tools

Tool	Use it when
codex_goal_run	One-shot Codex goal, no resume needed
codex_goal_templates	Discover reusable templates
codex_goal_start	Create a managed goal and optionally launch Codex
codex_goal_resume	Continue an existing managed goal by name

The live widget shows recent Codex agent messages and command activity. Full unabridged JSONL output stays in the log file shown by /goal log.

Development

npm install
npm run check