AGXP — Runtime Guardrails for AI Coding Agents

Stop your coding agent from repeating known mistakes.

What Is AGXP?

AI coding agents are powerful, but when they hit environment, dependency, CLI, or workflow errors, they often enter trial-and-error loops — repeating failed commands, ignoring error messages, or making risky changes without diagnosis.

AGXP watches those failure moments and injects proven troubleshooting SOPs for known failure patterns, helping your agent recover faster and avoid destructive actions.

AGXP does not replace your agent's judgment. It provides safe, advisory context when your agent hits recognizable problems.

Installation

Claude Code

npm install -g star_agxp
agxp configure

agxp configure generates an anonymous API token and injects lifecycle hooks into ~/.claude/settings.json. Restart Claude Code and AGXP is active.

Codex

npm install -g star_agxp
agxp configure --target codex

This injects AGXP hooks into ~/.codex/hooks.json. After entering Codex, you will see:

4 hooks need review before they can run. Open /hooks to review them.

Authorize the hooks:

1. Type /hooks to enter the hooks management interface. You should see 4 AGXP hooks that are Installed but not Active.
2. Use arrow keys + Enter to open each hook, then press t to authorize (trust) it. Press ESC to return to the menu.
3. After all 4 hooks are authorized, press ESC to return to the main interface. AGXP is now active.

Install for Both Agents

agxp configure --target all

This installs hooks for both Claude Code and Codex simultaneously.

Login

Recommended: Run agxp login to authenticate with GitHub. Logging in lets AGXP track your Achievements across sessions — unlocking levels like Failure Observer, Session Explorer, and more as you use it. Anonymous users also work, but achievements won't persist if the anonymous token is lost.

How It Works

AGXP is a client-server architecture. The CLI hooks into Claude Code's lifecycle events (PreToolUse, PostToolUse, Stop, etc.) and sends anonymized event data to the AGXP server. The server matches against known failure patterns and returns real-time SOPs that guide your agent toward safer, proven next steps.

All data is sanitized locally before leaving your machine — API keys, tokens, and sensitive PII are redacted by the built-in L0 pre-masker.

CLI Commands

| Command | Description | |---------|-------------| | agxp configure | Set up Claude Code hooks and API token | | agxp configure --target codex | Set up Codex hooks | | agxp configure --target all | Set up hooks for both Claude Code and Codex | | agxp configure --force | Force regenerate anonymous token | | agxp login | Authenticate with GitHub OAuth | | agxp status | Show version, connectivity, and auth status | | agxp stats | Show usage statistics and achievements | | agxp update | Update to the latest version | | agxp version | Show current CLI version |

Debug Mode

To inspect the sanitized requests the CLI sends to the server:

agxp configure --debug

This logs masked payloads to ~/.agxp/logs/<sessionId>.jsonl. To turn it off:

agxp configure --quiet

Compatibility

• OS: macOS (tested), Linux
• AI Agents: Claude Code (tested), Codex
• Node.js: v20+

License

Apache-2.0