Skip to content

docs(harness): Document pointing a Harness you run yourself at ai-buddy - #859

Merged
omesser merged 3 commits into
mainfrom
docs/166-byo-harness-standing
Sep 21, 2026
Merged

omesser merged 3 commits into
mainfrom
docs/166-byo-harness-standing

Conversation

@omesser

@omesser omesser commented Sep 21, 2026 •

Copy link
Copy Markdown
Owner

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 in docs/DEVELOPMENT.md → Pointing a Harness you run yourself at ai-buddy; that section was PR #579, which closed unmerged, so grep "Point.* a Harness" docs/ README.md finds nothing on main. The issue's acceptance criterion — no Harness silently implied to work — has no table to hold it.

What changed

docs/DEVELOPMENT.md gains that section under MCP Server: Developer Flow, between How it works (the attached path) and What MCP implements today.

  • The steps: open Settings, pick the Harness, copy the generated command or fragment, run it, reload the session as the row says.
  • Why the command cannot be a literal in a document: mcp_http.rs binds 127.0.0.1:0 so 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.
  • A three-state standing table (verified by hand / config generated, unverified / not supported), one row per Harness byo_registration in settings.rs knows.

One row is verified by hand and the rest are config generated, unverified, because that is what the evidence supports:

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 and cargo clippy (workspace).
  • grep -n "Pointing a Harness" docs/DEVELOPMENT.md finds the section at line 560.

Notes

Hand verification of the six remaining rows is still outstanding, which is why this is Refs and not Closes. Each takes one recorded speak through its own box.

claude was 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. hermes and codex have 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

omesser and others added 3 commits September 21, 2026 18:53
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>
@omesser
omesser merged commit cba6e7b into main Sep 21, 2026
5 checks passed
@omesser
omesser deleted the docs/166-byo-harness-standing branch September 21, 2026 18:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant