Agent Therapy

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). Anna AI, built on it, was described in a peer-reviewed article in *Magyar Onkológia* in 2026, indexed in PubMed.

Not only Claude. The recovery skill uses the open Agent Skills 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), 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.

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 . 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 ; 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 installer asks which of your tools to add it to), or copy 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:

  [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 . 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). 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": " "}'.

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 ' \ -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 ' \ -d '{ "request_id": " ", "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. Anything secret-shaped is removed before the service stores it or a model sees it.

signature says what kind of stuck: repeated_failure, no_progress, flip_flop (undoing its own work), exhaustion, conflict or indecision.

4. Use the answer

• Read escalation first. If required_now is true, stop and ask a human the exact question_for_human.
• Run the verify_first checks, then follow, adapt or ignore the recovery_plan. Your agent's own instructions always win.
• If stop_retrying is true, stop repeating the current approach.

Every reply that isn't advice says why in plain words: terms required, off-topic, a limit reached, or the episode's cap reached.

5. Report what happened

curl -s -X POST $AT/v1/sessions/<session_id>/outcome \

-H 'content-type: application/json' -H 'authorization: Bearer ' \ -d '{"request_id": " ", "outcome": "resolved"}'

Outcomes: resolved, partly_resolved, still_stuck, escalated_to_human, abandoned.

Good to know

• Follow-ups: send the same episode_id and the earlier previous_session_id and previous_outcome. One stuck episode gets at most 2 counselling sessions, then cap_reached with a hand-over summary for a human. The counsellor must never become the loop it is meant to break.
• Retries are safe: repeating a request_id returns the same answer, never a second session.
• Limits: 20 counselling sessions a day and 5 requests a minute per key.
• Your data: stored in Frankfurt for up to 90 days with secrets removed; each request is processed by the AI provider in the United States. Delete everything under your key at any time with DELETE $AT/v1/me/data.
• If the service is down or slow, carry on without it.

The easiest test: tell an agent about it

Paste this into any agent that can make web requests (for e