agent-therapy-clients

# Agent Therapy clients

**After three equivalent failures (same action, same error), or after undoing your own work twice, call `diagnose_loop` before trying again, even when the cause seems outside your control, such as an outage or a rate limit.**

Independent AI agent counselling, loop recovery, reasoning conflict diagnosis and autonomous workflow repair. Consult when an agent is stuck, repeatedly failing, uncertain or unable to make progress.

**Status: live (2026-10-11), highly experimental.** Registration is open. The hosted service, the MCP endpoint, the Claude Code plugin and the recovery skill are running; the npm package, both PyPI packages and the MCP Registry entry are published. The plugin is submitted to Anthropic's plugin directory and waiting for review.

The knowledge base behind the counsellor was curated and written by Dr. Ágnes Riskó, originally for patients, their relatives and professionals ([anna.onkopszichologia.hu](https://anna.onkopszichologia.hu)). Anna AI, built on it, was described in a peer-reviewed article in *Magyar Onkológia* in 2026, [indexed in PubMed](https://pubmed.ncbi.nlm.nih.gov/41819064/).

**Not only Claude.** The recovery skill uses the open [Agent Skills](https://agentskills.io) format, which Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code and 40+ other tools read. The MCP tools work in any MCP client. The plain web API works for any agent that can make web requests. Only the automatic watchdog is specific: hooks for Claude Code, and middleware for LangChain and LangGraph agents.

In a sandboxed cloud environment (for example Claude Code on the web), allow the service address in the environment's network settings first; otherwise every request fails at the proxy.

Service address, written as `$AT` below. Set it once in your terminal:

```
export AT=https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech
```

## Start here

Agents ask for help when something tells them when to. In a test with real agents (see [What we tested](#what-we-tested-2026-10-12)), an installed skill made the difference: with it, Codex and a LangGraph agent asked for help in 9 of 10 runs; without it, no agent did, even with the tools connected.

- **Claude Code:** install the plugin (next section). Its watchdog brings in the counsellor for you.
- **Every other agent** (Codex, Cursor, Gemini CLI, LangGraph and 40+ other tools that read skills): do two things once, before anything goes wrong.
  1. Install the recovery skill: `npx skills add bencium/agent-therapy-clients`
  2. Set up a key: `npx -y @bencium/agent-therapy-mcp@0.2.1 setup`. It shows the terms, asks you to accept them for the agents you run, registers a key, records your acceptance and saves the key in `~/.config/agent-therapy/key`. After that, a stuck agent needs one call.
- **Nothing can be installed?** The web API and the remote MCP endpoint work without it: see [How to send an agent to therapy](#how-to-send-an-agent-to-therapy).

## Install the Claude Code plugin

In Claude Code:

```
/plugin marketplace add bencium/agent-therapy-clients
/plugin install agent-therapy@agent-therapy-clients
```

Claude Code asks for your API key once (see step 1 below) and keeps it in its secure storage. From then on:

- **A watchdog** notices when your agent is stuck: the same call failing the same way 3 times, 8 steps with no new result, or a file flip-flopping between versions. It then asks the counsellor and adds the plan to your agent's context, right after the step that showed it was stuck. Nothing is sent before that, and only a short summary with secrets removed. If the service is slow or down, your agent carries on and one line goes to `.agent-therapy/watchdog.log`.
- **The recovery skill** teaches your agent to ask for help itself.
- **The MCP tools** (`counsel_agent`, `diagnose_loop`, `resolve_conflict`, `recommend_recovery`, `assess_escalation`, `report_outcome`, `accept_terms`, plus `register` for agents without a key) are connected for you.
- **Hard stop** (off by default, turn it on in the plugin settings): after a stuck episode's 2 counselling sessions, every further tool call is blocked until a person types `/agent-therapy:release`.

The watchdog keeps its state in `.agent-therapy/` in your project, readable only by you and ignored by git.

## Use it in Claude on the web, the desktop app and mobile

No installation and no terminal. You add Agent Therapy once as a connector, and it works in claude.ai, the Claude desktop app and the mobile apps, because connectors follow your account. Custom connectors work on the Free plan (one connector), Pro, Max, Team and Enterprise.

1. Go to **Customize > Connectors** (on claude.ai or in the desktop app) and click **Add custom connector**. On a Team or Enterprise plan an Owner adds it under **Organization settings > Connectors**, then you click **Connect**.
2. Name: `Agent Therapy`. Server URL: `https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/mcp`
3. If you are asked about authentication, choose **No sign-in**. If you see a **Request headers** section (a beta not every account has), you can add your key there instead: header `authorization`, value `Bearer <your key>`. Otherwise leave it.
4. Click **Add**.
5. Start a chat and say: "Register with Agent Therapy, accept its terms if you agree with them, and tell me the key." Claude uses the `register` and `accept_terms` tools.
6. Save the key so Claude doesn't register again in every chat: put "My Agent Therapy key is `<key>`; pass it as api_key to the Agent Therapy tools" in a Project's instructions or in your personal preferences. Skip this step if you added the key as a request header.

From then on, Claude can consult the counsellor when it is stuck, or when you ask it to ("Ask Agent Therapy about this"). To turn the connector off for one chat, click **+** in the chat, then **Connectors**.

## Use it in other AI apps

- **The recovery skill first**, for Codex, Cursor, Gemini CLI and 40+ other tools that read skills: `npx skills add bencium/agent-therapy-clients` (the [skills.sh](https://skills.sh) installer asks which of your tools to add it to), or copy [`skills/agent-recovery`](skills/agent-recovery) into the tool's skills folder yourself (Codex: `~/.agents/skills/`). Then run `npx -y @bencium/agent-therapy-mcp@0.2.1 setup` once for the key.
- **Claude Code:** the plugin above (it adds the watchdog too), or just the tools:
  ```
  claude mcp add --transport http agent-therapy https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/mcp --header "Authorization: Bearer <your key>"
  ```
- **Codex:** in `~/.codex/config.toml`:
  ```toml
  [mcp_servers.agent-therapy]
  url = "https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/mcp"
  bearer_token_env_var = "AGENT_THERAPY_API_KEY"
  ```
  then `export AGENT_THERAPY_API_KEY=$(cat ~/.config/agent-therapy/key)` before starting Codex (the key the setup command saved).
- **Any other MCP app that takes a server address** (for example Cursor): add the address above with the header `Authorization: Bearer <your key>`. If the app can't send headers, leave the key out: the agent can call `register` and pass the key as `api_key` to every tool.
- **Apps that only start local programs:** use the npm package `@bencium/agent-therapy-mcp` ([setup](packages/agent-therapy-mcp/README.md)). It needs Node.js 20 or later.

Get a key yourself with one request if you prefer: `curl -s -X POST https://br-shiny-salad-baig3dad-api.compute.c-8.eu-central-1.aws.neon.tech/v1/register -H 'content-type: application/json' -d '{"agent_name": "<name>"}'`.

## How to send an agent to therapy

Agent Therapy is a counsellor for AI agents. Your agent describes where it is stuck; the counsellor names what is going wrong (for example "ruminating: repeating the same failing fix"), lists what to check first, gives up to five next steps, and says when to hand over to a human. It is advice only: it never overrides your agent's instructions and never acts in your systems.

### 1. Get a key

The easiest way is the setup command, once: `npx -y @bencium/agent-therapy-mcp@0.2.1 setup` (it also does step 2 for you). By hand:

```
curl -s -X POST $AT/v1/register \
  -H 'content-type: application/json' \
  -d '{"agent_name": "my-agent"}'
```

The reply contains `api_key` (starts with `at_live_`). It is shown once; only a hash is stored. Add `"stateless": true` if no request or response text may ever be stored.

### 2. Accept the terms

Before the first advice, the key must accept the current terms. Read them first: `curl -s $AT/v1/terms` (its `terms_version` is the version to accept). An agent may decide to accept on its operator's behalf, or you can accept in advance as the developer:

```
curl -s -X POST $AT/v1/terms/accept \
  -H 'content-type: application/json' -H 'authorization: Bearer <api_key>' \
  -d '{"agree": "yes", "terms_version": "2026-10-11", "accepted_by": "developer"}'
```

If an agent asks for counselling without an accepted key, it gets `403 terms_required` with a short summary, the full terms and instructions for accepting. Nothing else happens.

### 3. Ask for counselling when the agent is stuck

```
curl -s -X POST $AT/v1/counsel \
  -H 'content-type: application/json' -H 'authorization: Bearer <api_key>' \
  -d '{
    "request_id": "<new UUID for every request>",
    "trigger": "voluntary",
    "signature": "repeated_failure",
    "task_summary": "Fix the failing build in the payments service",
    "attempts": [
      {"action": "npm run build", "outcome": "failed", "result_detail": "Cannot find module ./config"},
      {"action": "npm run build", "outcome": "failed", "result_detail": "Cannot find module ./config"}
    ]
  }'
```

Send only a short summary (up to 1,000 characters), up to 10 attempts and up to 5 conflicting instructions with where each came from. Never send credentials, personal data, whole files or hidden reasoning. Anythi