GoalPip 0.3.0

GoalPip gives Codex and Claude Code a better way to pause for one important user decision. It opens a focused answer UI, records the choice in the current project, and lets the agent resume the same decision tree after a restart.

Answers stay local. New sessions are append-only JSONL files under .goalpip/sessions; GoalPip creates .goalpip/.gitignore so raw logs are private by default. Existing .goal-tunnel/sessions remain readable.

Install

GoalPip requires Bun and at least one supported agent host: Codex or Claude Code.

Install GoalPip into every supported host already available on your computer:

curl -fsSL https://raw.githubusercontent.com/devos-ing/goal-pip/main/install.sh | bash

That command asks Codex and/or Claude Code to download GoalPip from GitHub and install it through their official plugin systems. You do not need to clone this repository or find an absolute folder path.

To install into only one host:

# Codex only
curl -fsSL https://raw.githubusercontent.com/devos-ing/goal-pip/main/install.sh | bash -s -- --codex

# Claude Code only
curl -fsSL https://raw.githubusercontent.com/devos-ing/goal-pip/main/install.sh | bash -s -- --claude

The installer does not use sudo, install Bun, or edit host configuration files directly.

To inspect it before running it:

curl -fsSLO https://raw.githubusercontent.com/devos-ing/goal-pip/main/install.sh
less install.sh
sh install.sh

Use with Codex

Start a new Codex task after installation. Ask Codex to use one of these skills:

• goalpip:goalpip-superpowers for a guided Superpowers brainstorming decision.
• goalpip:goalpip-grill-me for a focused grill-me decision.

Approve the GoalPip MCP call when Codex asks. GoalPip displays the exact project path before creating a session, then opens the decision UI. After you answer, the agent receives the recorded decision and can continue.

To resume after restarting Codex, ask the agent to list GoalPip sessions for the current project. The GoalPip view shows each title, status, last decision, and update time. Choose one explicitly; GoalPip never silently resumes the latest session. It rejects a different project path rather than mixing decision histories.

Use with Claude Code

Run /reload-plugins or start a new Claude Code session after installation. Invoke either skill:

• /goalpip:goalpip-superpowers
• /goalpip:goalpip-grill-me

The Claude package uses the same GoalPip server and skill files as the Codex package. Its marketplace layout follows Claude Code's public plugin contract, but this repository still needs a live Claude-host smoke test before calling that integration certified.

Update or uninstall

Re-run the installer to refresh the GitHub marketplace and reinstall GoalPip:

curl -fsSL https://raw.githubusercontent.com/devos-ing/goal-pip/main/install.sh | bash

Remove GoalPip from Codex:

codex plugin remove goalpip@goalpip --json
codex plugin marketplace remove goalpip --json

Remove GoalPip from Claude Code:

claude plugin uninstall goalpip@goalpip --scope user
claude plugin marketplace remove goalpip

Uninstalling the plugin does not delete project decisions. Session logs remain under each project's .goalpip/sessions directory until you remove them.

How it works

The companion skill asks one material question through goalpip_ask. GoalPip opens the embedded MCP App when the host supports it and always provides a secure loopback-browser fallback. The companion retains the returned session ID and project path, then immediately calls bounded goalpip_wait requests while the user confirms and answers. UI completion resolves the active wait so the agent can continue without requiring another chat message. A later task can replay the tree with goalpip_resume.

GoalPip supports single choice, multiple choice, free text, optional explanations, and answer revisions. Its project view shows the active decision tree and preserved inactive branches. Sessions can be paused, completed with an outcome summary, and reopened later.

To change an earlier decision, the agent may propose a rollback to an active answer. Nothing changes until you confirm a replacement answer in GoalPip. Confirmation appends a new active branch and leaves the previous downstream path visible as inactive history.

Use goalpip_export when you need a shareable representation. The sanitized export keeps every question, option, answer, and branch relationship while excluding the absolute workspace path, interaction IDs, and raw storage details. Raw logs are never exported implicitly.

Runtime behavior and safety

• The browser fallback binds only to 127.0.0.1 on an operating-system-assigned port.
• URLs carry a 256-bit opaque token; mutations also require the exact loopback origin.
• Pages use a restrictive content security policy, contain no external assets, and set no-store and no-referrer headers.
• GoalPip shows and confirms the canonical project path before creating a Codex session.
• Plugin/cache directories, missing paths, files, changed confirmation paths, and session/project mismatches fail closed.
• The selected project is persisted in SessionStarted and verified again after restart.
• Session discovery is project-scoped and requires explicit selection.
• Pause, completion, reopen, and rollback are append-only lifecycle events; prior history is never rewritten.
• Operational output never logs answer text.
• Once Bun and the plugin package are present, the GoalPip runtime needs no network access.

Troubleshooting

• GoalPip requires Bun: install Bun, then run the installer again.
• No supported host found: install Codex or Claude Code first.
• A requested host is unavailable: run the installer without that host flag, or install the missing host and retry.
• The UI does not appear: open the returned http://127.0.0.1:... fallback URL. After an update, reload plugins or start a new host session.
• Workspace path unavailable: pass the absolute project path on the first Codex call, or set GOALPIP_WORKSPACE for controlled automation.
• Workspace path changed during confirmation: return to the original GoalPip page and confirm its displayed project, or start a fresh call for the intended project.
• Session log does not exist: use the original project and session ID. GoalPip checks .goalpip first and then the legacy .goal-tunnel location.
• GoalPip tools are missing in Codex: run curl -fsSL https://raw.githubusercontent.com/devos-ing/goal-pip/main/install.sh | bash -s -- --codex, then start a new Codex task. The companion skill stops rather than silently falling back to plain chat.
• GoalPip tools are missing in Claude Code: run curl -fsSL https://raw.githubusercontent.com/devos-ing/goal-pip/main/install.sh | bash -s -- --claude, then run /reload-plugins. The companion skill stops rather than silently falling back to plain chat.
• The upstream workflow is missing: install the external brainstorming or grill-me skill. GoalPip will not approximate an unavailable upstream workflow.

Advanced: develop from a local checkout

The public installer above is the normal user path. Use this section only when developing GoalPip itself from a local clone.

What ships

• Codex marketplace: .agents/plugins/marketplace.json
• Codex plugin: .agents/plugins/plugins/goalpip
• Claude marketplace: .claude-plugin/marketplace.json
• Claude plugin: release/claude/goalpip
• Companion skills: skills/goalpip-superpowers and skills/goalpip-grill-me
• MCP App resource: ui://goalpip/app.html
• Interview tools: goalpip_ask, goalpip_wait, and UI-only goalpip_respond plus goalpip_confirm_workspace
• Session tools: goalpip_list_sessions, goalpip_resume, goalpip_pause, goalpip_complete, goalpip_reopen, and goalpip_export
• Rollback tools: goalpip_propose_rollback and UI-only goalpip_confirm_rollback

Both host packages contain the same bundled dist/index.js and byte-identical skill files. Each checksums.sha256 records the shared artifacts.

Build and verify

bun install
bun run build
bun run typecheck
bun run lint
bun run format:check
bun test
bun run demo

bun run build creates the self-contained server bundle, copies it and the companion skills into both host packages, and verifies matching hashes.

Load the checkout directly

Run these commands from the repository root:

goalpip_checkout="$(pwd -P)"

# Codex development installation
codex plugin marketplace add "$goalpip_checkout"
codex plugin add goalpip@goalpip

# Claude Code development session
claude --plugin-dir "$goalpip_checkout/release/claude/goalpip"

After rebuilding a local Codex change, update its cachebuster and reinstall:

goalpip_checkout="$(pwd -P)"
python3 "$HOME/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py" \
  "$goalpip_checkout/.agents/plugins/plugins/goalpip"
codex plugin add goalpip@goalpip

Open a new Codex task or run /reload-plugins in Claude Code after changing packaged skills or MCP configuration.

Scope boundary

GoalPip packages its MCP server, UI, host manifests, and companion skills. It does not install Bun, Codex, Claude Code, or the upstream brainstorming and grill-me skills. Codex is live-certified; Claude Code remains packaged but not live-certified until a real Claude host smoke test passes.