Breadcrumbs — Project Memory for Codex and Claude Code

The npm package is @andriilavrekha/breadcrumbs. The unscoped package breadcrumbs belongs to an unrelated project.

Why

Agent sessions end. Context windows reset. New sessions start cold, burning the first few minutes re-deriving "what was I doing?"

Breadcrumbs 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. 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 ──┘

Features

• 🗂️ One file per project, human-readable — plain Markdown you can read, edit, diff, and commit.
• 🔁 Automatic resume context — SessionStart injects the Resume Snapshot and Next Action at kickoff.
• Last runtime memo — Progress.md records the provider, agent, model, and effort of the session that last updated it, and SessionStart repeats that line.
• 🛡️ Sensitive-commit guard — blocks git commit when staged progress is marked commit_progress: false or sensitivity: sensitive.
• ⏰ Stop reminders — 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 — answers "what am I working on?" across every tracked project (see MCP Server).
• 🩺 Scriptable health checks — doctor --json gives a non-zero exit code and a diagnostic report when setup is broken.

Choose Your Path

Requires Node.js >= 18. Hooks and MCP server run entirely on Node — no Python needed.

After installing a plugin, start a new agent session. Run breadcrumbs doctor -g codex (or --json for scripting) to check setup.

Install As A Claude Code Plugin (recommended)

Zero-config: one marketplace add + install wires the skill, MCP server, and lifecycle hooks — no edits to CLAUDE.md or ~/.claude.json.

/plugin marketplace add AndriiLavrekha/breadcrumbs
/plugin install breadcrumbs@breadcrumbs

Or from the CLI:

claude plugin marketplace add AndriiLavrekha/breadcrumbs
claude plugin install breadcrumbs@breadcrumbs

What you get (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.

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 — installs through the native flow, no manual config.toml editing:

codex plugin marketplace add AndriiLavrekha/breadcrumbs
codex plugin add breadcrumbs@breadcrumbs

This wires the same skill, MCP server, and lifecycle hooks as the Claude Code plugin. Restart Codex after installing or updating so the manifest, MCP server, and hooks reload.

[!NOTE]Codex doesn't auto-trust plugin-bundled hooks: the first time SessionStart / PreToolUse / Stop fire, Codex asks you to review and trust them. Approve once.

Codex

codex plugin marketplace upgrade
codex plugin add breadcrumbs@breadcrumbs
codex plugin list

Start a new Codex session afterward. If prompted, review and trust the updated hooks in /hooks.

Claude Code

claude plugin update breadcrumbs@breadcrumbs
claude plugin list

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

On an initialized project, SessionStart injects resume context from Progress.md. On an uninitialized project, the agent asks before creating project-progress/:

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

• Yes → run breadcrumbs init . --project "<name>"
• No → record an opt-out so future sessions stay quiet:

breadcrumbs state set . --state opted-out

The opt-out lives outside the repo, under the tool's user data directory — it never dirties the project.

Because skills follow the open SKILL.md standard, the same skill also works in Gemini CLI, Copilot, and Cursor when placed under ~/.agents/skills or a repo's .agents/skills.

Install For Hermes Agent

Hermes Agent is supported today through the managed skill + MCP path: supported Skill + MCP installation with the install, doctor, and uninstall commands, plus status for inspection. lifecycle hooks are deferred for Hermes, so this path does not yet wire SessionStart, PreToolUse, or Stop automation.

If Hermes isn't installed yet, follow the official Hermes Agent installation instructions, then confirm the CLI works:

hermes --version

Wire the integration:

npx --package=github:AndriiLavrekha/breadcrumbs breadcrumbs install -g hermes

Named collisions stop the install before any changes are made. If Hermes already has a breadcrumbs skill or breadcrumbs MCP server, remove or rename the existing entry first and rerun the installer.

After install or update, restart Hermes so it reloads the managed skill and MCP registry. Because lifecycle hooks are deferred for Hermes, drive things manually for now:

• initialize with breadcrumbs init . --project "<name>" when the user opts in
• check setup with breadcrumbs status -g hermes / doctor -g hermes
• verify directly with hermes skills list --source hub, hermes mcp list, hermes mcp test breadcrumbs

Initialize A Project

# from npm
npx --package=@andriilavrekha/breadcrumbs breadcrumbs init /path/to/repo --project "My Project"

# from GitHub
npx --package=github:AndriiLavrekha/breadcrumbs breadcrumbs init /path/to/repo --project "My Project"

# or installed globally
npm install -g @andriilavrekha/breadcrumbs
breadcrumbs init /path/to/repo --project "My Project"

init creates project-progress/ from templates/project-progress/. Fill in the frontmatter and keep Resume Snapshot, Next Action, Remaining Work, and Blockers compact enough for an agent to load first.

Upgrading From Awesome Progress Tracker

Breadcrumbs is the new name for Awesome Progress Tracker. The primary command is breadcrumbs; awesome-progress-tracker and project-progress remain aliases for the same commands and data.

Your project-progress/ files, ~/.awesome-progress-tracker state and index, PROJECT_PROGRESS_ROOTS, and AWESOME_PROGRESS_TRACKER_HOME stay in place. Starting in v0.8.0, the plugin, marketplace, skill and MCP identities are breadcrumbs. The new plugin selector is breadcrumbs@breadcrumbs. There is no project-data migration.

Uninstall the old plugin and remove its marketplace before adding the renamed one. Run the commands for your provider only:

# Claude Code
claude plugin uninstall project-progress@awesome-progress-tracker
claude plugin marketplace remove awesome-progress-tracker
claude plugin marketplace add AndriiLavrekha/breadcrumbs
claude plugin install breadcrumbs@breadcrumbs

# Codex
codex plugin remove project-progress@awesome-progress-tracker
codex plugin marketplace remove awesome-progress-tracker
codex plugin marketplace add AndriiLavrekha/breadcrumbs
codex plugin add breadcrumbs@breadcrumbs

For a CLI-managed Hermes install, run breadcrumbs uninstall -g hermes before breadcrumbs install -g hermes; the new uninstaller recognizes both old and new managed names. Manual Claude/Codex CLI reinstalls replace old owned configuration blocks and server keys with the new identity. Restart the agent after switching plugins, and avoid enabling both plugin identities at once.

When switching a global install to a new npm package identity, first check which package owns the old commands:

npm ls -g --depth=0

If it is awesome-progress-tracker, remove only that npm package before installing Breadcrumbs. It owns the legacy command names, so installing a second package with those aliases can otherwise fail with EEXIST. Upgrade with:

npm uninstall -g awesome-progress-tracker
npm install -g @andriilavrekha/breadcrumbs
breadcrumbs help

Do not use --force to overwrite another package's commands. npm package removal leaves your project files, provider configuration, and saved opt-out state intact; it is different from running the application's uninstall command. Package-name changes do not update existing npm installations automatically. Use @andriilavrekha/breadcrumbs; do not run npm install breadcrumbs or bare npx breadcrumbs.

Install the global bootstrap for your agent (claude is the default; swap -g codex where shown). This installs global instructions telling the agent to check for project-progress/Progress.md at kickoff — it does not initialize every project automatically. It also configures the agent's MCP client (~/.claude.json for Claude Code, ~/.codex/config.toml for Codex).

Replace ... with npx --package=github:AndriiLavrekha/breadcrumbs breadcrumbs.

Manual instruction files are also available:

• skills/breadcrumbs/SKILL.md — install or reference for Codex
• agent-instructions/AGENTS-snippet.md — paste into a project or global AGENTS.md
• agent-instructions/CLAUDE-snippet.md — paste into Claude Code memory
• agent-instructions/HOOKS.md — 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

These wrappers run the compiled hook (dist/src/hook/cli.js) on Node — run npm run build first (or install the published package, which builds on prepare). For direct use: node dist/src/hook/cli.js --project-root . --session-started-at <iso>.

Keep Progress Files Small

Hooks report when progress files grow: session start shows a Progress health: line and the stop hook lists problems once per session. compact moves old history into Archive.md verbatim apart from heading levels:

breadcrumbs compact            # preview what moves
breadcrumbs compact --write    # apply

The directory argument is optional and defaults to the current directory. For plugin installs without the binary on PATH, use the exact node "…/cli.js" compact "…" command the hook message prints, or npx --package=github:AndriiLavrekha/breadcrumbs breadcrumbs compact.

It moves:

• unknown or duplicate Progress.md sections and old Done items
• Session Log.md dated entries beyond the newest 20 (undated entries stay)
• finished Tasks.md ## sections (no open task) beyond the newest 3, so keep reference notes elsewhere, and checked tasks beyond the newest 10

It also repairs garbled characters in all five progress files and refuses files that are not valid UTF-8. Commit before running --write so the move is one reviewable diff.

MCP Server

npx --package=@andriilavrekha/breadcrumbs breadcrumbs mcp
# or from GitHub
npx --package=github:AndriiLavrekha/breadcrumbs breadcrumbs mcp

Configure discovery with a semicolon-separated PROJECT_PROGRESS_ROOTS:

$env:PROJECT_PROGRESS_ROOTS = "C:/Users/you/Documents;C:/Users/you/Projects"
npx --package=github:AndriiLavrekha/breadcrumbs breadcrumbs mcp

For local development in this repo:

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

MCP clients installed from npm/GitHub should use the package binary (breadcrumbs mcp or project-progress mcp) to keep stdio clean.

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

The server maintains a lightweight global index (~/.awesome-progress-tracker/projects.json and Projects.md) as a fast "what projects exist?" view. Progress.md remains the source of truth; refresh_projects, init, update_project_progress, and mark_project_status all keep the index in sync.

Verification

See TESTING.md and agent-instructions/SELF-TEST.md for full scenarios.

npm test
npm run build

Verify package creation and npx-style execution locally:

PACKAGE_TGZ="$(npm pack --silent)"
npx --yes --package="./$PACKAGE_TGZ" breadcrumbs 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 in order:

1. Plugin installed and enabled: codex plugin list.
2. Hooks trusted: open /hooks in Codex and trust the project-progress hooks.
3. Restarted Codex/Claude Code (or new session) after install or update.
4. Project is actually uninitialized: project-progress/Progress.md is missing.
5. Project isn't opted out: breadcrumbs state list; reset with state reset ..
6. Task is non-trivial: hooks only nudge for multi-step feature/investigation/refactor/setup/debugging/deployment/release work.
7. MCP is running: /mcp in Codex or breadcrumbs doctor -g codex.

The prompt-time hook covers work submitted after startup — if the project was created mid-session, submit the next prompt after trusting the updated hook.

Hooks are best-effort and never block normal Codex operation. If hooks are disabled or untrusted, the breadcrumbs skill and bootstrap instructions still define the workflow.

Contributing

Private, single-maintainer repo for now. See AGENTS.md for structure/conventions and TESTING.md for the verification workflow before opening a PR.

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

License

MIT — see the license field in package.json.