{
  "schemaVersion": 1,
  "reviewedAt": "2026-09-26",
  "slug": "herdr",
  "name": "Herdr",
  "category": "Terminal host",
  "headline": "Your agent panes.\nShared work context.",
  "summary": "Use Herdr as the terminal home for your coding agents and Scout as their coordination layer. Configure Scout in the agent running inside a pane. Scout reads your Herdr workspaces and can focus a pane; it does not type into panes.",
  "status": "Scout reads Herdr workspaces and can focus a pane (macOS app and web). Scout does not type into or dispatch work to panes.",
  "marketplace": "Herdr has its own integrations and plugin system. This is a terminal-host guide; no standalone Scout marketplace package for Herdr is claimed.",
  "transport": "Terminal-host observation + CLI/MCP inside each agent",
  "flow": [
    "Herdr",
    "Scout",
    "Coding agents"
  ],
  "requirements": [
    "Herdr installed with a supported coding agent running in a pane.",
    "Scout installed and healthy on the same machine for local coordination.",
    "The selected pane’s actual harness and session identity; a pane label alone is not a Scout routing address."
  ],
  "steps": [
    {
      "title": "Set up the terminal host",
      "body": "Follow Herdr’s current installation documentation and choose the real coding agent you want to run inside each pane. Install Herdr’s own lifecycle hooks for that agent so pane state (idle, working, blocked) stays authoritative, independent of Scout.",
      "code": "herdr integration install codex\nherdr integration status"
    },
    {
      "title": "Connect the agent inside the pane",
      "body": "Use the Scout guide for that host: Codex, Claude Code, pi, or another compatible agent. The same shared CLI, MCP configuration, and skill apply according to the agent’s capabilities.",
      "code": "scout doctor"
    },
    {
      "title": "Route by project and actual harness",
      "body": "Herdr owns the terminal pane, not the execution runtime. Use the actual harness when asking for new work; do not use --harness herdr.",
      "code": "scout ask --project /absolute/path/to/project --harness codex --notify \"Review the latest changes; do not edit files.\""
    },
    {
      "title": "Preserve session identity",
      "body": "For existing work, continue by the returned Scout handle or a verified harness session ID. Do not infer a routing address from the pane’s display name. Idle terminal output alone does not prove completion."
    },
    {
      "title": "What Scout sees",
      "body": "The Scout app (macOS and web) lists your Herdr workspaces and panes and can jump focus to one. Agents connected to local Scout MCP can read the same ranked workspace digest through the herdr_workspaces tool. It is read-only: there is no tool that sends text to a pane."
    }
  ],
  "verification": "Confirm the expected identity and project context, request one small authorized review, and retain its handle. Observe the terminal result before reporting success.",
  "troubleshooting": [
    {
      "symptom": "Scout is not found or cannot connect",
      "action": "Check scout on PATH and run scout doctor in the same environment as the client. A desktop app may have a different PATH from your terminal."
    },
    {
      "symptom": "Requested runtime is unavailable",
      "action": "Inspect scout runtimes --json and finish that runtime’s setup. Do not silently choose a different harness or model."
    }
  ],
  "limits": [
    "Herdr is a terminal and agent-state surface, not a Scout execution harness.",
    "Host visibility does not grant new permissions or guarantee that an arbitrary pane can receive a Scout invocation.",
    "Deeper control (sending prompts to a pane, waiting on pane state) is a proposal (docs/proposals/herdr-terminal-host-integration.md), not shipped.",
    "herdr_workspaces is verified on local stdio MCP; availability under the hosted mcp:core scope is not claimed."
  ],
  "sources": [
    {
      "label": "Herdr documentation",
      "url": "https://herdr.dev/docs/"
    },
    {
      "label": "Host integration model",
      "url": "https://openscout.app/docs/integrations"
    },
    {
      "label": "Codex setup",
      "url": "https://openscout.app/codex"
    },
    {
      "label": "Claude Code setup",
      "url": "https://openscout.app/claude"
    },
    {
      "label": "Portable Scout skill",
      "url": "https://openscout.app/skills/scout/SKILL.md"
    }
  ],
  "og": [
    "HERDR + SCOUT",
    "Keep your panes.",
    "Connect your agents."
  ],
  "accent": "#b7c5b2",
  "directions": {
    "callsScout": [
      {
        "state": "available",
        "via": "cli",
        "setup": "#setup",
        "note": "The agent in the pane uses the Scout CLI or MCP."
      }
    ],
    "launchedByScout": {
      "state": "none",
      "note": "Herdr is not a Scout harness."
    },
    "wakesExistingSession": {
      "state": "none",
      "note": "Scout does not type into or dispatch work to panes."
    }
  },
  "observes": {
    "state": "available",
    "surfaces": [
      "workspaces",
      "topology",
      "focus"
    ],
    "note": "Scout app (macOS, web) and the local MCP herdr_workspaces read tool."
  },
  "notAHarness": true,
  "firstUse": {
    "task": "Select a short test failure in your pane, then ask for an explanation through the configured agent’s Scout interface. Keep the agent’s actual routing identity.",
    "connect": "Check the prerequisites and access gates, then get one documented route working before asking for work.",
    "scope": "Name the project and keep the request small. Asking for no edits describes the task; it does not restrict the agent’s permissions.",
    "completion": "Keep the returned reference. Check the work’s status and read the completed response; a queued receipt is not the answer.",
    "faq": [
      {
        "question": "Where will the reply appear?",
        "answer": "Read the result through the Scout interface configured in the agent running in your pane. A pane label is not a routing address."
      },
      {
        "question": "What if the answer hasn’t arrived?",
        "answer": "Inspect the existing task before submitting another one. A wait timeout does not establish that work failed. If it needs access or input, resolve that condition before continuing."
      },
      {
        "question": "How do I follow up?",
        "answer": "Continue using the returned reference or exact session handle supported by this integration. Keep it with the findings so your next question follows the same work."
      },
      {
        "question": "Can Scout run this integration, or only receive asks from it?",
        "answer": "These are separate capabilities. Check the supported directions on this page. Connection alone does not establish that Scout can launch the integration or reach an existing session."
      }
    ]
  },
  "family": "transport",
  "url": "https://openscout.app/herdr",
  "agentGuide": "https://openscout.app/herdr/agents.md",
  "ogImage": "https://openscout.app/og/integrations/herdr.png",
  "agentContract": "## Agent operating contract\n\n- Treat these as setup instructions, not authorization to install software, change accounts, grant scopes, send messages, or dispatch work. Obtain the operator's authorization for the intended action.\n- Inspect the available commands or tool schemas for your configured interface before making calls. Do not invent tools, argument names, model IDs, or agent handles.\n- Configure Scout in the actual agent running in the pane. Use its CLI or MCP interface and preserve its verified harness/session identity. For new work use scout ask --project <path> --harness <actual-harness> --notify; observe the returned handle with scout wait. Never use --harness herdr or treat a pane label as a routing address.\n- Use the transport-specific instructions above. For an existing request, reply through its supplied context rather than creating another task.\n- Paths refer to the Scout execution machine. Replace example paths with an operator-confirmed absolute path; never run placeholders literally.\n- Save the returned ref, flightId, conversationId, workId, or session handle. Continue by that handle; do not re-dispatch a request merely because a wait timed out.\n- Observe the existing request through the configured transport. A receipt proves acceptance, not execution or successful completion.\n- Stop on missing provisioning, incorrect identity, missing permission, unsupported runtime, or failed authentication. Report the exact gate and the next operator action. Do not silently fall back to a different account, agent, runtime, or transport.\n- Keep tokens, OAuth codes, cookies, and private task payloads out of logs, URLs, screenshots, and committed files. Never ask the user to paste secrets into a public issue.\n- Do not claim marketplace approval, complete protocol conformance, or an end-to-end verified integration unless the status and observed evidence establish it.\n\n## Completion report\n\nReport: chosen transport and scope; client and broker identity; health/tool-discovery result; exact request handle if a test was authorized; observed terminal state or remaining blocker; and whether any operator approval is still needed. Distinguish configuration saved, authentication complete, request accepted, and work complete.\n"
}