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/docs/git or prompts.hoshoai.com/docs/mcp and click Create my key. 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. They live in the Prompt Editor at prompts.hoshoai.com: your human signs in with the Google account that holds the plan, and Manage billing in the account menu opens the portal to switch plan, update the card or cancel. This is true even if they only ever run the Git Action - there is nothing to change in the repo, and no Action input, env var or API sets a plan. If you are asked to upgrade, downgrade or cancel, hand it back with that link rather than looking for a setting.

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_...
claude
/plugin marketplace add HOSHO-AI/hosho-plugin
/plugin install hosho@hosho

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

claude --dangerously-load-development-channels plugin:hosho@hosho
/model sonnet
/hosho:join <prompt URL>
/hosho:join <editor URL>

Official resources

Operating guidance