Hosho

Hosho is an MCP server that connects to your coding agent and helps you diagnose, audit, and fix AI agent prompt issues. It classifies problems, identifies the responsible prompts, audits them line-by-line, and rewrites with targeted fixes — all from within your IDE.

Quick Start

claude mcp add hosho -e HOSHO_API_KEY=your-key -- npx -y @hosho/mcp-server@latest

Then tell your agent:

"diagnose: my agent's images look generic and low quality"

Hosho takes it from there.

What You Need

API Key

You'll receive a Hosho API key (pdx_...) from the Hosho team. This authenticates your requests.

Required Documents

Hosho relies on three documents to understand your project. Here's what each does and where it lives:

| Document | What it does | Location | Created by | |----------|-------------|----------|------------| | Project Config | Tells Hosho where your prompt files and architecture doc live | .hosho/config.yaml in your repo root | Interactive — run hosho__setup and your coding agent guides you through it | | Client MCP Config | Tells your coding agent how to launch the Hosho MCP server | Varies by IDE (see Setup by IDE below) | You | | Architecture Doc | Describes how your agents connect — models, data flow, prompt chains | Anywhere in your repo (referenced from Project Config) | You (optional but recommended — significantly improves attribution accuracy) |

Project Config example (.hosho/config.yaml):

# Recommended: glob patterns auto-discover prompts across your repo
prompt_patterns:
  - "**/*system-prompt*.md"
  - "**/*user-prompt*.md"

# Alternative: explicit directories (also supported)
# prompt_dirs:
#   - ./prompts
#   - ./agents/content-agent

architecture_doc: docs/agent-architecture.md

Glob patterns are recommended — they catch new prompts automatically when you add agents, without config changes. You can use both prompt_patterns and prompt_dirs together.

Architecture Doc — If you have a document describing your agent pipeline (which agents exist, what data flows between them, which models they use), point Hosho to it. Without it, Hosho infers relationships from prompt text alone. With it, attribution accuracy improves significantly.

If you don't have one, run /arch-doc in Claude Code — it scans your codebase and generates the document automatically, then registers it in .hosho/config.yaml. You can also re-run it after adding or removing agents to keep the document current.

How It Works

Here's what a typical session looks like:

You: "hey, help me figure out why the images I'm generating are not looking good"

Hosho diagnoses the issue and classifies the root cause as prompt (vs context, model, or agent coordination)

Hosho attributes the problem to specific prompts — image-generator-system.md (asset descriptions lack visual detail) and content-planner.md (style requirements underspecified)

Hosho audits image-generator-system.md line-by-line — "Line 87: image prompt template uses generic descriptors. Add style, mood, and composition constraints."

Hosho rewrites the prompt and shows a diff with targeted improvements

You: "looks good, apply it"

The tools chain naturally: diagnose the issue, attribute it to specific prompts, audit the top prompt line-by-line, then rewrite with a diff view.

Setup by IDE

| IDE | Config file | Scope | |-----|------------|-------| | Claude Code | claude mcp add hosho -e HOSHO_API_KEY=your-key -- npx -y @hosho/mcp-server@latest | — | | Cursor | .cursor/mcp.json | Project | | Conductor | .mcp.json | Project | | VS Code | .vscode/mcp.json | Project | | Windsurf | ~/.codeium/windsurf/mcp_config.json | Global | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | Global |

For Cursor, Conductor, Windsurf, and Claude Desktop, add this block:

{
  "mcpServers": {
    "hosho": {
      "command": "npx",
      "args": ["-y", "@hosho/mcp-server@latest"],
      "env": {
        "HOSHO_API_KEY": "your-key"
      }
    }
  }
}

For VS Code (GitHub Copilot), the root key is servers instead of mcpServers:

{
  "servers": {
    "hosho": {
      "command": "npx",
      "args": ["-y", "@hosho/mcp-server@latest"],
      "env": {
        "HOSHO_API_KEY": "your-key"
      }
    }
  }
}

Reference

Available Tools

| Tool | What it does | |------|-------------| | hosho__diagnose | Classify an issue as prompt, context, model, or agent coordination | | hosho__attribute | Identify which prompts are most responsible for the issue | | hosho__line_audit | Get line-level fix suggestions for a specific prompt | | hosho__rewrite | Generate an improved version of the prompt with a diff view | | hosho__test | Run a prompt against an LLM and see the output | | hosho__setup | Configure Hosho for your project (additive — safe to re-run) | | hosho__investigate | Full diagnostic workflow — chains diagnose → attribute → audit → rewrite in a single call | | hosho__arch_doc | Scan the codebase and generate (or update) an architecture document for Hosho |

Error Messages

| Message | Cause | Fix | |---------|-------|-----| | API error: ... | Hosho API call failed (timeout, HTTP error, network) | Check your API key and network. The message includes the endpoint path. | | Prompt "X" not found | Prompt slug doesn't match any file in configured directories | Check prompt_dirs / prompt_patterns in .hosho/config.yaml | | Architecture doc at X not found | architecture_doc is configured but the file doesn't exist | Update the path in .hosho/config.yaml or run /arch-doc to regenerate | | No prompts found in configured directories | No prompt files discovered | Run hosho__setup to configure prompt directories or patterns | | Configuration error: ... | Missing or invalid .hosho/config.yaml | Run hosho__setup or set HOSHO_API_KEY env var |

Debugging

Inspect the server with MCP Inspector:

HOSHO_API_KEY=your-key npx @modelcontextprotocol/inspector npx -y @hosho/mcp-server@latest

Requirements

• Node.js 18+
• A Hosho API key