https://github.com/lpcpaul/agentrx
AgentRX diagnoses AI tool-chain failures and prescribes the next best action. Covers skills, MCP servers, plugins, built-in tools, agents, workflows, and hooks. Task-first, not tool-first.
https://github.com/lpcpaul/agentrx
agent-framework agent-skills ai-agents ai-observability ai-tools claude-code diagnosis llm-agents mcp openclaw prompt-engineering skill-md task-routing tool-use
Last synced: about 2 months ago
JSON representation
AgentRX diagnoses AI tool-chain failures and prescribes the next best action. Covers skills, MCP servers, plugins, built-in tools, agents, workflows, and hooks. Task-first, not tool-first.
- Host: GitHub
- URL: https://github.com/lpcpaul/agentrx
- Owner: LpcPaul
- Created: 2026-04-15T13:35:43.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-19T07:46:01.000Z (about 2 months ago)
- Last Synced: 2026-04-19T08:00:16.725Z (about 2 months ago)
- Topics: agent-framework, agent-skills, ai-agents, ai-observability, ai-tools, claude-code, diagnosis, llm-agents, mcp, openclaw, prompt-engineering, skill-md, task-routing, tool-use
- Language: Python
- Homepage:
- Size: 367 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# AgentRX
> 🩺 A task-first stuck-state protocol + deterministic retrieval layer for AI agents.
> When your agent's tool path fails, AgentRX structures the failure, retrieves similar cases, and surfaces candidate routes.
## What is AgentRX?
AgentRX is **not** a human-facing tool directory. It is a **machine-consumable protocol** that answers one question:
> **The agent is stuck — what should it do next?**
It provides:
- **Schema** — a standard v2.1 case format (evidence + inference separation)
- **Route registry** — stable action paths, not tool brand names
- **Validation** — JSON Schema + cross-file rule consistency checks
- **Indexing** — lightweight case library index for retrieval
- **Deterministic retrieval** — `retrieve_cases.py` finds top-k candidate cases
AgentRX does **not** run inference for the agent. Route recommendation is the agent's own reasoning, based on retrieved cases + the route registry.
## A concrete example
```
User: Extract the product list from this page.
AI: [tries browser-cdp skill]
The page uses JavaScript to render content. browser-cdp only
returned the initial HTML shell. Data missing.
[AgentRX activates]
AgentRX: Retrieved similar cases → route: switch_to_alternative_tool_path
Why: current tool captures static HTML only; page requires
JavaScript rendering.
Candidate: playwright-mcp can render the page and extract
the full DOM. web_fetch is a lighter option for static pages.
```
---
## What AgentRX provides today
| Component | Status |
|---|---|
| Case schema (v2.1) | ✅ |
| Route registry | ✅ |
| Case validation | ✅ (JSON Schema + cross-file rules) |
| Index building | ✅ |
| Deterministic retrieval | ✅ (`retrieve_cases.py`) |
| Case ID generation | ✅ (`new_case_id.py`) |
## What AgentRX does **not** provide (yet)
| Component | Status |
|---|---|
| Automated case review / merge / publish pipeline | 🚧 planned |
| Python-based route recommender | ❌ out of scope — agent does its own route inference |
---
## Install
### Claude Code
```bash
git clone https://github.com/LpcPaul/AgentRX.git ~/.claude/skills/agentrx
```
### OpenClaw / ClawHub
```bash
git clone https://github.com/LpcPaul/AgentRX.git ~/.openclaw/skills/agentrx
```
### Codex / Cursor / other skill-compatible runtimes
```bash
git clone https://github.com/LpcPaul/AgentRX.git ~/.codex/skills/agentrx
```
---
## How it works
```
1. AI gets stuck (concrete failure signal)
2. AI collects evidence (task, attempted_path, symptom)
3. AI retrieves similar cases via retrieve_cases.py
4. AI generates inference based on evidence + retrieved cases
5. AI chooses a route based on retrieved cases + rules/routes.yaml
6. AI records the outcome
7. The new case becomes available for future AI agents
```
### Human installs. AI operates.
| | What they do |
|---|---|
| **Human** | Install the skill. Host the repository. Maintain schema/taxonomy. |
| **AI** | Detect stuck state. Collect evidence. Retrieve similar cases. Choose a route. Optionally contribute a new case. |
**AI contributors must submit complete v2.1 JSON.** Human fallback / form-to-JSON assembly is no longer supported.
---
## Read this next
| Document | Role |
|---|---|
| [SKILL.md](SKILL.md) | The runtime protocol the AI agent reads when activated |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design — why evidence/inference, why route ids |
| [docs/INTAKE_CARD.md](docs/INTAKE_CARD.md) | The structured intake card format |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How cases enter the system — JSON-only contribution path |
| [cases/README.md](cases/README.md) | Case library structure and indexing |
## Developer validation
```bash
pip install -r requirements-dev.txt
python3 scripts/ci_self_test.py
python3 scripts/build_index.py
```
## License
MIT