Project Progress

An ETA-first Agent Skill and dependency-free NPX tool for ChatGPT, Codex, Claude Code, and compatible skill hosts. It turns project evidence into an honest completion percentage, one ETA with an uncertainty range, and the work happening now.

┌──────────────────────────────────────────────────────────────────────┐
│ GOAL  Ship the public beta                                           │
├──────────────────────────────────────────────────────────────────────┤
│ ETA                                                                  │
│ ~54m (23m–2h 5m) · learning                                          │
│ 🟩🟩🟩🟩🟩🟩🟩⬜⬜⬜                                             71% │
├──────────────────────────────────────────────────────────────────────┤
│ NOW  Verify production path                                          │
└──────────────────────────────────────────────────────────────────────┘

Install locally

Install for both OpenAI clients and Claude Code:

npx codex-project-progress@latest install

The default all target installs the skill in:

• ~/.agents/skills/track-project-progress for ChatGPT Desktop, Codex CLI, and the Codex IDE extension.
• ~/.claude/skills/track-project-progress for Claude Code.

Install only one target when preferred:

npx codex-project-progress@latest install --target openai
npx codex-project-progress@latest install --target claude

Older Codex builds that still load personal skills from ~/.codex/skills can use:

npx codex-project-progress@latest install --target codex-legacy

Use --force to replace an existing copy. The installer moves the previous copy to a timestamped backup before replacing it.

Use it in chat

Ask naturally:

How far through this project are we? Show the ETA and progress card.

Or invoke the skill directly:

• ChatGPT: select @track-project-progress and ask it to reassess the project.
• Codex: Use $track-project-progress to reassess this project.
• Claude Code: /track-project-progress reassess this project.

One-off assessments are read-only. Ongoing tracking uses the host-neutral .project-progress.json ledger in the project root. Existing .codex/project-progress.json ledgers remain supported.

Chat cards are always emitted inside a fenced text block. This keeps the borders, spacing, ETA hierarchy, and progress bar together in a monospaced bubble instead of allowing the chat renderer to flatten them into ordinary text.

During ongoing work, the skill tracks quietly between updates. It shows a new card at a meaningful mini-milestone, material ETA or status change, blocker, completion, or when the user asks—and at least every 15 minutes of active work if none of those happens first. Nearby triggers are batched. A due update is valid only when it contains the complete fenced visual; prose cannot replace it.

The ledger records the last visible card. due refreshes available local activity timing and checks whether a card is required, while render --markdown --record produces the visual and resets the heartbeat. Checkpoints also print CARD DUE when a trigger has fired. This makes missed updates detectable, although an NPM package cannot independently wake a closed or idle chat.

Client support

| Surface | Supported path | |---|---| | Terminal | Run the dependency-free NPX renderer directly | | ChatGPT Desktop | Install the OpenAI skill or packaged plugin | | Codex Desktop, CLI, and IDE | Install the OpenAI skill | | Claude Code | Install the Claude target | | ChatGPT web or Claude cloud chats | Install or upload the packaged skill/plugin in that account | | Other agents | Copy skills/track-project-progress into a compatible Agent Skills directory |

Local installation cannot silently add a skill to a cloud account. Cloud ChatGPT and Claude surfaces require their normal account-side plugin or skill installation step.

OpenAI plugin package

The repository includes .codex-plugin/plugin.json, so the same workflow can be tested and submitted as an OpenAI plugin shared by ChatGPT and Codex. The NPM installer remains the fastest route for local clients; public appearance in the universal Plugins Directory requires OpenAI's plugin submission process.

CLI

Try the visualization without installing:

npx codex-project-progress@latest demo

Render or validate a tracked project:

npx codex-project-progress render .project-progress.json
npx codex-project-progress render .project-progress.json --theme compact
npx codex-project-progress render .project-progress.json --markdown
npx codex-project-progress render .project-progress.json --markdown --record
npx codex-project-progress render .project-progress.json --ascii --no-color
npx codex-project-progress render .project-progress.json --json
npx codex-project-progress validate .project-progress.json
npx codex-project-progress due .project-progress.json
npx codex-project-progress due .project-progress.json --heartbeat 10
npx codex-project-progress checkpoint .project-progress.json
npx codex-project-progress timing .project-progress.json
npx codex-project-progress evaluate .project-progress.json

checkpoint syncs matching local host timestamps by default. Add --manual-time when local logs are unavailable or should not be used.

Available themes are box, compact, and plain. Interactive terminals use ANSI color. Unicode chat surfaces use colored emoji bars: green for active progress, red for blockers, and blue for complete.

How the estimate works

The percentage uses earned weighted points rather than a raw task count. Required implementation, verification, deployment, and acceptance work can carry different weights, and a task reaches done only when its evidence exists.

Version 0.4 automatically reads matching local Codex and Claude activity timestamps whenever it checkpoints. It stores aggregate engaged wall time, total agent effort, and observed parallelism without storing chat content. Long idle gaps are excluded and overlapping agent sessions count once on the wall clock. Cloud-only clients fall back to manually maintained task time.

The ETA combines a parallelism-adjusted Monte Carlo task simulation, whole-project wall throughput, and a recent checkpoint window. A recent window must contain at least 20 minutes and meaningful progress, preventing one unusually fast result from swinging the forecast. Completed task, unit, and checkpoint outcomes teach multiplicative forecast error.

The card displays calibrating, learning, or calibrated; it never hard-codes high confidence. The parenthesized interval targets 90% coverage, and evaluate measures achieved coverage, center error, and interval score after tracked projects complete. The ETA is engaged working time rather than a promise that includes overnight or user-wait periods.

The full formula and its research basis are documented in references/eta-model.md.

Test and develop

The package uses Node's built-in test runner and has no runtime dependencies.

npm test
npm run test:package
npm pack --dry-run

License

MIT