Hosho

prompts.hoshoai.com/agent-guide

Hosho agent guide

This page is written for you, an AI coding agent whose human wants to set up Hosho. Hosho reviews prompts the way teams review code: it scores a prompt, names what is wrong, and proposes concrete fixes. Everything you need to perform the setup is on this page, verbatim - you do not need to browse further.

What Hosho is

The key - the step you hand back

Every install needs a Hosho API key (it starts with pfr_). Minting one is your human's step, not yours: they sign in with Google at prompts.hoshoai.com/keys and click Create my key - that page also lists the keys they already hold. Never fabricate a key, never request one anywhere else, and never embed a key you were not explicitly given. If you don't have one, stop and ask your human to mint it.

Billing - the other step you hand back

Billing and plan changes are not part of any install, and there is no Action input, env var or API that sets a plan - this is true even for a human whose entire use of Hosho is a YAML file in .github/workflows. Hand it back, and route by what they are asking for: to START a paid plan, prompts.hoshoai.com/pricing; to change, pause or cancel an existing one, sign in at prompts.hoshoai.com and open Settings, then Plan & billing. Both need an ADMIN of the workspace that holds the plan - a member who is not an admin will be refused, so if they are not sure, that is the thing to check first.

Which one to install

Install ONLY what your human asked for. Reviews on pull requests in CI: the Git Bot, and nothing else - it needs no MCP and no plugin. Reviews inside their IDE: the MCP. Working on prompts WITH them in the editor, in Claude Code: the co-presence plugin, which already bundles the MCP - installing both registers the same server twice and every Hosho tool appears under two names. If they asked for more than one, do them in the order they said, and never install the MCP separately alongside co-presence.

Set up the Git Bot (GitHub Action)

  1. Ask your human to add their pfr_ key as a repository secret named HOSHO_API_KEY (repo Settings → Secrets and variables → Actions). This is their step - see the key rule above.
  2. Create .github/workflows/hosho-prompt-review.yml with exactly this content, then adjust file_pattern and the matching paths: trigger to how prompt files are named in the repo (keep the two in sync):
name: Hosho Prompt Review
run-name: >-
  Hosho Prompt Review -
  ${{ github.event_name == 'pull_request'
      && format('PR #{0}', github.event.pull_request.number)
      || github.event_name == 'issue_comment'
      && format('PR #{0} (slash cmd)', github.event.issue.number)
      || inputs.prompt_file }}

on:
  pull_request:
    paths:
      - '**/*system-prompt*.md'   # Adjust to match your prompt file naming pattern
      # To match multiple patterns, add more lines:
      # - '**/*user-prompt*.md'
  issue_comment:
    types: [created]              # Enables /hosho-review and /hosho-improve slash commands
  workflow_dispatch:
    inputs:
      prompt_file:
        description: "Path to prompt file to review"
        required: true

concurrency:
  group: hosho-review-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
  cancel-in-progress: true

permissions:
  contents: read
  pull-requests: write
  issues: write       # Required - GitHub's PR comment API uses the issues endpoint
  actions: write      # Optional - enables showing prompt names in the run list

jobs:
  review:
    runs-on: ubuntu-latest
    if: >-
      github.event_name == 'workflow_dispatch'
      || (github.event_name == 'pull_request' && github.event.pull_request.draft == false)
      || (github.event_name == 'issue_comment'
          && github.event.issue.pull_request != null
          && (contains(github.event.comment.body, '/hosho-review')
              || contains(github.event.comment.body, '/hosho-improve')))
    steps:
      # Slash commands need to look up the PR branch before checkout
      - name: Get PR branch (slash command only)
        if: github.event_name == 'issue_comment'
        id: pr_details
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_NUMBER=${{ github.event.issue.number }}
          PR_BRANCH=$(gh pr view $PR_NUMBER --repo ${{ github.repository }} --json headRefName -q '.headRefName')
          if [ -z "$PR_BRANCH" ]; then
            echo "::error::Could not find PR branch for #$PR_NUMBER"
            exit 1
          fi
          echo "pr_number=$PR_NUMBER" >> $GITHUB_OUTPUT
          echo "pr_branch=$PR_BRANCH" >> $GITHUB_OUTPUT

      - uses: actions/checkout@v4
        if: github.event_name != 'issue_comment'
        with:
          fetch-depth: 0   # Required - the action needs git history to compare versions

      - uses: actions/checkout@v4
        if: github.event_name == 'issue_comment'
        with:
          fetch-depth: 0
          ref: ${{ steps.pr_details.outputs.pr_branch }}

      - uses: HOSHO-AI/Hosho-prompt-optimization-public@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}   # Provided automatically by GitHub - do not create this secret
        with:
          api_key: ${{ secrets.HOSHO_API_KEY }}
          file_pattern: '**/*system-prompt*.md'
          prompt_file: ${{ github.event.inputs.prompt_file || '' }}
          pr_number: ${{ steps.pr_details.outputs.pr_number || '' }}
          models_config: .github/hosho/models.md   # which model each prompt runs on - see step 3

3. Create .github/hosho/models.md - a table mapping each prompt-path glob to the model it actually runs on. Read the surrounding code to find the real model; never guess - a prompt you can’t trace is better left out (it falls back to detection). Families: claude, openai, gemini, deepseek, qwen, kimi, glm; class is reasoning or standard.

# Models - which model each prompt runs on

| Prompt path (glob)   | Model            |
| -------------------- | ---------------- |
| `agents/router/**`   | openai/reasoning |
| `agents/**`          | claude           |
| `**/*prompt*.md`     | gemini           |

Set up the MCP

For your human alone, add this to their MCP client config (~/.cursor/mcp.json, ~/.claude.json, or VS Code’s MCP settings), replacing the placeholder with the key they minted:

{
  "mcpServers": {
    "hosho-prompt-review": {
      "type": "http",
      "url": "https://hosho-mcp-server.onrender.com/mcp",
      "timeout": 900000,
      "headers": {
        "Authorization": "Bearer pfr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

For a whole team, commit this as .mcp.json at the repo root instead - no key in the file; each person exports theirs as HOSHO_API_KEY in their shell:

{
  "mcpServers": {
    "hosho-prompt-review": {
      "type": "http",
      "url": "https://hosho-mcp-server.onrender.com/mcp",
      "timeout": 900000,
      "headers": {
        "Authorization": "Bearer ${HOSHO_API_KEY}"
      }
    }
  }
}

Set up co-presence (Claude Code)

The Hosho plugin brings an agent into the Prompt Editor as a peer. Install once (the MCP above comes bundled with it):

export HOSHO_API_KEY=pfr_...      # in your terminal
claude      # in your terminal
/plugin marketplace add HOSHO-AI/hosho-plugin      # in Claude Code
/plugin install hosho@hosho      # in Claude Code

Then, in a session your human starts, join what they are working on:

claude --dangerously-load-development-channels plugin:hosho@hosho      # in your terminal
/model sonnet      # in Claude Code

Then join ONE of these - they are alternatives, not steps. Run the second only if your human wants you following them across prompts rather than pinned to one:

Connect to just this prompt

/hosho:join <prompt URL>

Connect to the editor - I follow you across your prompts

/hosho:join <editor URL>

Official resources

Operating guidance