Codex Goal Control Experiment

Local Codex thread goal control panel and installable Codex skill.

This is an experiment, not an official Codex surface. Use it with that constraint in mind: the Codex goals feature and app-server goal methods are still an evolving surface, so this repo can break when Codex changes its internal/app-server contract.

The intended use is local operator convenience:

• keep a small goal panel open inside the Codex in-app browser;
• point that panel at the current Codex thread;
• inspect and control the thread goal without jumping to the CLI/TUI.

Do not treat this as production infrastructure or as a stable integration contract yet.

This repo packages a self-contained skill that can:

• claim the current CODEX_THREAD_ID;
• open a localhost goal panel;
• read, set, pause, resume, complete, and clear the current thread goal through Codex app-server;
• show token budget progress when a budget exists;
• animate the progress rail when no budget is set.

Screenshot

Requirements

• Codex CLI/app with app-server available.
• The Codex goals feature enabled.
• Node.js available on the host.
• Localhost access to 127.0.0.1:43873.

Enable goals in your Codex user config:

[features]
goals = true

Codex normally reads this from:

~/.codex/config.toml

You can verify the feature from a terminal with:

codex features list | rg '^goals'

Expected shape:

goals  under development  true

If goals is false or unavailable, the panel can still load, but goal reads/writes will fail.

Install Skill

Clone this repo, then install the bundled skill into your Codex home:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
rm -rf "${CODEX_HOME:-$HOME/.codex}/skills/codex-goal-control"
cp -R ./codex-goal-control "${CODEX_HOME:-$HOME/.codex}/skills/codex-goal-control"

Restart/reload Codex after installing if the skill does not appear immediately.

What The Skill Does

The codex-goal-control skill gives Codex a repeatable way to open the panel for the thread you are currently using.

When invoked, the skill:

1. reads the current CODEX_THREAD_ID from the running Codex thread;
2. writes that thread ID to a local claim file under the OS temp directory;
3. ensures the localhost panel server is running;
4. returns a URL like http://127.0.0.1:43873/?threadId=<current-thread-id>.

That threadId step matters. Opening http://127.0.0.1:43873/ by itself is not enough unless a thread has already been claimed. The skill is what makes the browser panel follow the active Codex thread instead of showing stale or empty state.

Ask Codex something like:

Use the codex-goal-control skill and open the goal panel for this thread.

or:

Open the Codex goal panel for the current thread.

Open The Panel

From any Codex thread:

node "${CODEX_HOME:-$HOME/.codex}/skills/codex-goal-control/scripts/codex_goal_panel_open.js" --json

Open the returned url, normally:

http://127.0.0.1:43873/?threadId=<current-thread-id>

The app is local-only and served from the installed skill files. It does not require a separate build step.

Direct Commands

The direct commands are useful for testing or for terminal workflows. They expect CODEX_THREAD_ID to exist unless you pass --thread <thread-id> explicitly.

node "${CODEX_HOME:-$HOME/.codex}/skills/codex-goal-control/scripts/codex_goal.js" get
node "${CODEX_HOME:-$HOME/.codex}/skills/codex-goal-control/scripts/codex_goal.js" set "ship the thing" --budget 3000
node "${CODEX_HOME:-$HOME/.codex}/skills/codex-goal-control/scripts/codex_goal.js" pause
node "${CODEX_HOME:-$HOME/.codex}/skills/codex-goal-control/scripts/codex_goal.js" resume
node "${CODEX_HOME:-$HOME/.codex}/skills/codex-goal-control/scripts/codex_goal.js" complete
node "${CODEX_HOME:-$HOME/.codex}/skills/codex-goal-control/scripts/codex_goal.js" clear

Safety

The panel binds to 127.0.0.1 only. It refuses non-localhost bind addresses.

The goal commands use codex app-server and default to CODEX_THREAD_ID, so they target the current Codex thread unless --thread is explicitly passed.

Known Limits

• This depends on Codex goals, which currently appears as under development in codex features list.
• This does not add native /goal slash-command support to the Codex desktop composer.
• The browser panel is a convenience view. It is not proof that the agent intrinsically received or adopted the goal.
• The strongest goal truth remains the Codex thread goal API or native goal state for the active thread.
• In sandboxed runs, the helper may report started-unverified-sandbox because the sandbox cannot verify the localhost listener even though the server started.