Awesome Progress Tracker

Resumable memory for Codex, Claude Code, and any MCP-compatible agent.

Project-local Markdown that survives context resets — so your agent picks up exactly where it left off, every session, in one file it can read in a few hundred tokens.

Why · Features · Quick Start · MCP Tools · Troubleshooting

Why

Agent sessions end. Context windows reset. New sessions start cold, and a lot of the first few minutes gets spent re-deriving "what was I doing?" — or worse, redoing it.

Awesome Progress Tracker fixes that with one convention: every project keeps a project-progress/Progress.md file as its resume source of truth. A SessionStart hook injects the compact bits — Resume Snapshot, Next Action, Blockers — into the agent's context automatically. No dashboards, no databases, nothing to sync. Just a Markdown file the agent reads at kickoff and updates before it stops.

session 1 ──work──► Progress.md updated (Resume Snapshot · Next Action · Blockers)
                                │
new session ◄── SessionStart hook injects the snapshot, no lookup needed ──┘

Related MCP server: agent-coordination-mcp

Features

• 🗂️ One file per project, human-readable — project-progress/Progress.md is plain Markdown. Read it, edit it, diff it, commit it.

• 🔁 Automatic resume context — a SessionStart hook injects the Resume Snapshot and Next Action at kickoff, so the agent never starts blind.

• 🛡️ Sensitive-commit guard — a PreToolUse hook blocks git commit when staged progress declares commit_progress: false or sensitivity: sensitive.

• ⏰ Stop reminders — a Stop hook flags when the working tree changed but Progress.md didn't, and scans for accidentally-committed secrets.

• 🧩 Works everywhere — first-class plugins for Claude Code and Codex, plus an open-standard SKILL.md skill for Gemini CLI, Copilot, and Cursor.

• 🌐 Cross-project index via MCP — a lightweight MCP server answers "what am I working on?" across every tracked project, with a tiny, validated tool surface (see MCP Server).

• 🩺 Scriptable health checks — doctor --json gives a non-zero exit code and a diagnostic report when setup is broken, so CI or a pre-flight script can catch it.

Choose Your Path

Requirements: Node.js >= 18. The hooks and MCP server run entirely on Node; no Python is required.

Start a new agent session after plugin installation. Run awesome-progress-tracker doctor -g codex or awesome-progress-tracker doctor --json for a scriptable setup check.

Install As A Claude Code Plugin (recommended)

This is the zero-config path: one marketplace add + install wires the skill, the MCP index server, and lifecycle hooks with no edits to your global CLAUDE.md or ~/.claude.json.

/plugin marketplace add AndriiLavrekha/awesome-progress-tracker
/plugin install project-progress@awesome-progress-tracker

Or from the CLI:

claude plugin marketplace add AndriiLavrekha/awesome-progress-tracker
claude plugin install project-progress@awesome-progress-tracker

What you get after install (restart the session to load it):

To scope the MCP index to specific roots, set PROJECT_PROGRESS_ROOTS (semicolon-separated) in the environment Claude Code runs in; the server scans those roots on refresh_projects.

The plugin ships prebuilt dist/ so it runs straight from the cloned repo with no build step.

Install As A Codex Plugin (recommended)

The same repo is also a Codex plugin (.codex-plugin/plugin.json + .agents/plugins/marketplace.json), so it installs through the native Codex plugin flow — no manual config.toml editing:

codex plugin marketplace add AndriiLavrekha/awesome-progress-tracker
codex plugin add project-progress@awesome-progress-tracker

This wires the same skill, MCP server, and lifecycle hooks (hooks/hooks-codex.json) as the Claude Code plugin. Codex hook commands use ${PLUGIN_ROOT} and the bundled MCP server uses the Codex-specific .mcp.codex.json file. Restart Codex or start a new Codex session after installing or updating the plugin so the manifest, MCP server, and hooks are reloaded.

Use the command path that matches how you installed the plugin.

Codex

codex plugin marketplace upgrade
codex plugin add project-progress@awesome-progress-tracker
codex plugin list

Codex refreshes configured Git marketplaces with the first command; re-adding the plugin installs the latest marketplace snapshot. Start a new Codex session afterward. If prompted, review and trust the updated hooks in /hooks.

Claude Code

claude plugin update project-progress@awesome-progress-tracker
claude plugin list

Restart Claude Code after the update so the plugin's skills, MCP server, and hooks reload.

Codex hooks are lifecycle context, not interactive modals. On an initialized project, SessionStart injects compact resume context from project-progress/Progress.md. On an uninitialized project, it emits guidance telling the agent to ask before initialization when the requested work is multi-step. The agent and skill perform the user-facing ask:

This project is not initialized with Awesome Progress Tracker. Do you want me to create `project-progress/` here?

If you answer yes, the agent should run awesome-progress-tracker init . --project "<name>" or project-progress init . --project "<name>". If you answer no, the agent should record a local per-project opt-out so future sessions stay quiet:

awesome-progress-tracker state set . --state opted-out

The opt-out is stored outside the repository under the Awesome Progress Tracker user data directory; it does not dirty the project.

Skills follow the cross-tool open standard (SKILL.md), so the same skill also works in Codex, Gemini CLI, Copilot, and Cursor when placed under ~/.agents/skills or a repo's .agents/skills.

Initialize A Project

After npm publication:

npx awesome-progress-tracker init /path/to/repo --project "My Project"

From the private GitHub repository:

npx github:AndriiLavrekha/awesome-progress-tracker init /path/to/repo --project "My Project"

Or install it globally:

npm install -g github:AndriiLavrekha/awesome-progress-tracker
project-progress init /path/to/repo --project "My Project"

The init command creates project-progress/ from templates/project-progress/. Then update project-progress/Progress.md frontmatter and sections for that project. Keep Resume Snapshot, Next Action, Remaining Work, and Blockers compact enough for an agent to load first.

Install the global bootstrap for the agent you use.

Claude Code is the default:

npx github:AndriiLavrekha/awesome-progress-tracker install
npx github:AndriiLavrekha/awesome-progress-tracker install -g claude

Codex:

npx github:AndriiLavrekha/awesome-progress-tracker install -g codex

The installer does not initialize every project automatically. It installs global bootstrap instructions that tell the agent to check for project-progress/Progress.md at kickoff. If the current project is not initialized, the agent must ask before creating project-progress/.

The installer also configures the selected agent's MCP client to run this package:

• Claude Code: updates ~/.claude.json.

• Codex: updates ~/.codex/config.toml.

By default, the MCP server scans the directory where you ran install. To scan other roots:

npx github:AndriiLavrekha/awesome-progress-tracker install -g codex --roots "C:/Users/me/Documents;C:/Users/me/Projects"

Check installation state:

npx github:AndriiLavrekha/awesome-progress-tracker status
npx github:AndriiLavrekha/awesome-progress-tracker status -g codex

Inspect or reset per-project opt-in/opt-out state:

npx github:AndriiLavrekha/awesome-progress-tracker state list
npx github:AndriiLavrekha/awesome-progress-tracker state set /path/to/repo --state opted-out
npx github:AndriiLavrekha/awesome-progress-tracker state reset /path/to/repo

Run a setup health check:

npx github:AndriiLavrekha/awesome-progress-tracker doctor
npx github:AndriiLavrekha/awesome-progress-tracker doctor -g codex

Install and immediately verify:

npx github:AndriiLavrekha/awesome-progress-tracker install --verify
npx github:AndriiLavrekha/awesome-progress-tracker install -g codex --verify

Install only the MCP configuration, without bootstrap instructions:

npx github:AndriiLavrekha/awesome-progress-tracker install-mcp
npx github:AndriiLavrekha/awesome-progress-tracker install-mcp -g codex

Write a project-local MCP config instead of user-global config:

npx github:AndriiLavrekha/awesome-progress-tracker install-mcp --local --roots "."

This writes .mcp.json in the current project.

Remove managed bootstrap and MCP config:

npx github:AndriiLavrekha/awesome-progress-tracker uninstall
npx github:AndriiLavrekha/awesome-progress-tracker uninstall -g codex
npx github:AndriiLavrekha/awesome-progress-tracker uninstall --local

Manual instruction files are also available:

• install or reference skills/project-progress/SKILL.md for Codex

• paste agent-instructions/AGENTS-snippet.md into a project or global AGENTS.md

• paste agent-instructions/CLAUDE-snippet.md into Claude Code memory

• follow agent-instructions/HOOKS.md for lifecycle reminders and validation

Agents should update progress at kickoff when state changes, after milestones, when blockers appear, after verification, and before ending a meaningful session.

Windows

./hooks/project-progress-check.ps1 -ProjectRoot . -SessionStartedAt 2026-06-27T00:00:00+00:00 -MeaningfulWork -CompletionBoundary

POSIX

./hooks/project-progress-check.sh --project-root . --session-started-at 2026-06-27T00:00:00+00:00 --meaningful-work --completion-boundary

The wrappers run the compiled hook (dist/src/hook/cli.js) on Node, so run npm run build (or install the published package, which builds on prepare) before invoking them. For direct use without the wrappers, call node dist/src/hook/cli.js --project-root . --session-started-at <iso>.

MCP Server

After npm publication:

npx awesome-progress-tracker mcp

From the private GitHub repository:

npx github:AndriiLavrekha/awesome-progress-tracker mcp

Configure discovery with a semicolon-separated PROJECT_PROGRESS_ROOTS value:

$env:PROJECT_PROGRESS_ROOTS = "C:/Users/you/Documents;C:/Users/you/Projects"
npx github:AndriiLavrekha/awesome-progress-tracker mcp

For local development in this repo:

npm install
npm run build:mcp
node dist/src/mcp/server.js

For MCP clients installed from npm or GitHub, use the package binary directly (awesome-progress-tracker mcp or project-progress mcp) so stdio output stays clean.

Tool surface — deliberately small; administrative tracking state lives in the CLI (state list/set/reset), not here:

The MCP server maintains a lightweight global index:

~/.awesome-progress-tracker/projects.json
~/.awesome-progress-tracker/Projects.md

project-progress/Progress.md remains the source of truth. The index is only a fast global view for "what projects exist?" queries. refresh_projects rescans PROJECT_PROGRESS_ROOTS and updates the index. init, update_project_progress, and mark_project_status also upsert the affected project into the index.

Verification

For manual and agent-led validation, use:

• TESTING.md

• agent-instructions/SELF-TEST.md

Run the tests and build:

npm test
npm run build

Verify package creation and npx-style execution locally:

npm pack --dry-run
npm pack
npx --yes ./awesome-progress-tracker-0.1.0.tgz help

Run the lifecycle check against this repo:

./hooks/project-progress-check.ps1 -ProjectRoot . -SessionStartedAt 2026-06-27T00:00:00+00:00 -MeaningfulWork -CompletionBoundary

Troubleshooting Codex

Check these in order:

1. Plugin installed and enabled: codex plugin list.

2. Plugin hooks trusted: open /hooks in Codex and trust the project-progress hook definitions.

3. New Codex session started after install or plugin update.

4. The project is actually uninitialized: project-progress/Progress.md is missing.

5. The project is not opted out: awesome-progress-tracker state list; reset with awesome-progress-tracker state reset ..

6. The task is non-trivial: hooks tell the agent to ask only for multi-step feature, investigation, refactor, setup, debugging, deployment, or release work.

7. MCP configured and running: use /mcp in Codex or awesome-progress-tracker doctor -g codex.

Hooks are best-effort and must never block normal Codex operation on their own. If hooks are disabled or untrusted, the project-progress skill and bootstrap instructions still define the workflow.

Contributing

This is currently a private, single-maintainer repo. See AGENTS.md for structure and coding conventions and TESTING.md for the verification workflow before opening a PR.

Each project owns its own progress files. Global vaults, dashboards, hooks, and MCP tools may read or summarize them, but they should not replace them — the source of truth is always the project-progress/ folder inside each project.

License

MIT — see the license field in package.json.