agent-blocked

CLI installer and reporter for Agent Blocked.

Published package: https://www.npmjs.com/package/agent-blocked

Run one setup command from the project where the coding agent runs:

npx agent-blocked@latest install --tool=codex --token="your-scoped-token"

This writes the Agent Blocked helper files, installs the selected adapter, saves the scoped token to .agent-blocked/env, and offers to send a real test alert when run interactively. The env file is ignored by the generated .agent-blocked/.gitignore. Reporters and hooks read it automatically, so new terminals do not need repeated export commands.

Install adapters for every supported tool in the repo:

npx agent-blocked@latest install --tool=all --token="your-scoped-token"

Respond and Continue

Respond and Continue supports Aider, Claude Code, Codex, and Gemini CLI. The migrated server enables it automatically; no server feature flags are required. Approval emails are reserved for unattended sessions launched with agent-blocked run. Ordinary interactive sessions use each platform's native permission prompt and do not send routine approval emails.

For a managed resumable run:

npx agent-blocked@latest run \
  --tool=claude \
  --prompt="Implement the release and request approval before deploying"

Use --tool=aider, --tool=claude, --tool=codex, or --tool=gemini. The manager uses an exact saved chat/session/thread and never falls back to “resume latest.” It does not add vendor permission-bypass flags. Aider's managed path uses a private history file under .agent-blocked/runs/, which the installer adds to .gitignore.

See the repository's RESPOND_AND_CONTINUE.md for the protocol, security invariants, and release verification command.

To update only the saved token later, run npx agent-blocked@latest configure --token="your-scoped-token".

Troubleshoot the local hook/instruction setup when needed:

npx agent-blocked@latest doctor --tool=codex

If you skipped the configure test or want to repeat delivery proof, run npx agent-blocked@latest doctor --tool=codex --send-test. It defaults to a hard_blocked / critical event and fails unless the webhook response includes at least one matched contact, at least one sent delivery, and the new incident is visible through the scoped recent-notifications endpoint.

Report a notifiable issue manually:

npx agent-blocked@latest report --event=needs_direction --severity=medium --reason="Need human direction"

Do not use a low-severity manual report as a delivery test. Use doctor --send-test when you need proof that a notification matched a contact and was sent.

The installer adds a small .agent-blocked/ directory plus tool-specific config, hooks, or instruction files for the selected agent tools. Codex instructions are written to AGENTS.md, Claude Code instructions to CLAUDE.md, Gemini instructions to GEMINI.md, and Aider instructions to CONVENTIONS.md. Those files include mandatory guidance on material blockers and provide a local reporter command that sends notification events to your Agent Blocked alert profile.

For tools with supported native hooks, such as Claude Code, installing the adapter turns the hook on for that project. Codex uses AGENTS.md instructions and the local reporter command instead of broad lifecycle hooks. Make sure npx agent-blocked@latest configure has saved the scoped token in the project before starting the agent.

Rerun the install command after upgrading the package to refresh Agent Blocked-owned helper files under .agent-blocked/.

If a report does not arrive, run:

npx agent-blocked@latest doctor

The doctor checks helper files, selected tool hooks or instructions, stale instructions, and token availability. Use --tool=codex, --tool=claude, --tool=gemini, --tool=aider, or --tool=all. With --send-test, it also verifies delivery. Reporters and hooks append sanitized status entries to .agent-blocked/events.ndjson, including missing-token, HTTP, network, and send-attempt outcomes. The log never includes token values.

Agents should send material alerts when there is something the user should know or do: work is blocked, progress cannot safely continue, a decision or approval is needed, credentials or access are missing, repeated tool/provider failures are happening, an external service or quota limit prevents progress, context or token limits are approaching, or the next step has high risk or low confidence.

Agents should send reports for material blockers, risks, and user-action items. Routine recoverable errors that are fixed in one or two attempts can stay in normal progress output. Reports should be actionable and focused on what the user needs to know or do.

Before sending a non-critical report, and before sending another report for the same issue, agents should check recent sent notifications when tool access is available:

npx agent-blocked@latest recent --limit=20

A duplicate should not be sent if a recent notification already covers the same underlying issue and nothing material changed. A new report is justified when the issue is new, materially worse, needs a different user action, a previous next step is stale, or enough time has passed that another notification is useful. Critical first-time reports should not be delayed just to check history.

Agents should not wait for an exact event type. If a generic external blocker stops progress, such as a provider quota, GitHub Actions limit, spending cap, rate limit, account restriction, unavailable service, missing approval, or blocked deployment, the agent should send a report with the closest existing event type:

• needs_credentials for missing API keys, OAuth, permissions, roles, or secrets.
• needs_direction for ambiguous goals, tradeoffs, architecture, product behavior, or priorities.
• tool_failure for repeated command, API, dependency, deployment, or external-tool failures.
• approval_required when user approval is still needed before sending, buying, deploying, deleting, or another irreversible action.
• low_confidence when the agent can continue but the chance of being wrong is high.
• context_limit when the agent is approaching context window, token budget, or conversation memory limits and still has enough room to report a checkpoint.
• hard_blocked when no productive path remains without human input.
• other for an important issue that does not fit the named categories.

Run the setup command from the project where the agent runs. It saves the scoped token to the local ignored config file and installs the adapter:

npx agent-blocked@latest install --tool=codex --token="your-scoped-token"

Use npx agent-blocked@latest configure --token="your-scoped-token" only when you need to update the saved token without reinstalling adapter files.

Agents can report through the installed local reporter:

node .agent-blocked/report.mjs --event=needs_credentials --severity=critical --reason="Missing deploy credentials"

Agents can check recent sent notifications through the installed local helper:

node .agent-blocked/recent.mjs --limit=20

Codex reporting is instruction-driven. npx agent-blocked@latest install --tool=codex writes the Agent Blocked section to AGENTS.md; restart Codex or start a new Codex session after installation so the instructions are loaded.

If you already had a Codex session open in that repo, exit the old session and choose the session to resume with:

npx agent-blocked@latest restart --tool=codex

To skip the picker and resume the most recent session:

npx agent-blocked@latest restart --tool=codex --last

Claude Code has the same restart helper:

npx agent-blocked@latest restart --tool=claude

To resume the most recent Claude Code conversation:

npx agent-blocked@latest restart --tool=claude --last

Codex can also be run through the wrapper when you want hard process exits reported:

npx agent-blocked@latest codex -- codex "implement the requested change"