Repository navigation
docs(harness): Document pointing a Harness you run yourself at ai-buddy - #859
Merged
Merged
Conversation
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
ADR-0010 is superseded by ADR-0018, which carries the credential rules. The new section inherited the stale number from mcp_http.rs, so both move. Refs #166. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A headless claude -p turn, registered from the Settings box alone, called speak and the overlay drew it. First row to leave the unverified state. Refs #166. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Settings ships a Point a Harness you run yourself at ai-buddy box (
BYO_HEADING, #599) that generates a per-Harness MCP registration, and nothing in the repository documents it. #166's 2026-09-10 comment says the knowledge lives indocs/DEVELOPMENT.md→ Pointing a Harness you run yourself at ai-buddy; that section was PR #579, which closed unmerged, sogrep "Point.* a Harness" docs/ README.mdfinds nothing onmain. The issue's acceptance criterion — no Harness silently implied to work — has no table to hold it.What changed
docs/DEVELOPMENT.mdgains that section under MCP Server: Developer Flow, between How it works (the attached path) and What MCP implements today.mcp_http.rsbinds127.0.0.1:0so the OS picks the port, and mints the bearer token from 32 fresh random bytes into memory on every launch. Only the running app knows either value, and both change on restart, so registration is per launch.byo_registrationinsettings.rsknows.One row is verified by hand and the rest are config generated, unverified, because that is what the evidence supports:
claude— verified by hand on 2026-09-21, macOS 26.6.2, Claude Code 2.1.278. The two lines were read out of the Settings box by accessibility dump rather than copied from the source, run from a scratch directory at the default local scope, and a headlessclaude -pturn then calledmcp__ai-buddy__speak. The overlay drew it, and the screenshot is in the section. Earlier evidence in fix(mcp): Serve MCP from the app on loopback HTTP so a Harness's speak lands on screen (#470) #491 covered the loopback endpoint but handed the URL and token over ACP rather than through this command, so the two are kept distinct in the footnote.codex,grok,hermes,opencode— registration shapes checked against the CLI or its docs (spike(harness): How each Harness registers a BYO MCP server, and whether it can send a bearer token #580, docs(research): BYO Harness MCP reconfiguration and reload #644); no BYOspeakrecorded.codexin particular rests on documentation per the 2026-09-10 comment.cursor-agent,pi— share onemcpServersJSON fragment; shapes come from documentation. The README's "pidoes not receive ai-buddy's MCP" is the attached path (pi-acpadvertises no HTTP MCP capability), sopiis unverified, not not supported — Pi reads~/.pi/agent/mcp.json, and the fragment targets it.Nothing is not supported today. The section says so plainly rather than leaving the state to be inferred.
Deliberately not done: no hand verification of any row (no Harness CLI run, no personal config touched, no app launched), no README change, no re-documentation of TCP MCP, #16, or the old StubWindowSource blocker — the existing section already describes the loopback HTTP design and the relay shim correctly.
How to verify
From the worktree:
node --test tests/*.test.js— 285 pass, 0 fail.pre-commit run --all-files— all hooks passed, including codespell andcargo clippy (workspace).grep -n "Pointing a Harness" docs/DEVELOPMENT.mdfinds the section at line 560.Notes
Hand verification of the six remaining rows is still outstanding, which is why this is
Refsand notCloses. Each takes one recordedspeakthrough its own box.claudewas verified from a scratch directory at local scope, so nothing was written to a user-scope or project-scope config, and the entry was removed afterwards.hermesandcodexhave no project scope and would write a home-level file, which is why neither was touched.One defect found and fixed at its root while writing this: the section first cited ADR-0010 for the token being kept off disk. ADR-0010 is superseded by ADR-0018, which carries the credential rules. The number was inherited from a comment in
src-tauri/src/mcp_http.rs, so both moved.Refs #166
— Claude Code agent, on @omesser's behalf.
🤖 Generated with Claude Code