Skip to content

Harnesses and mirrors

Chapter 09 of the ResearchTools manual. Back to table of contents.

A harness is the tool a person types into: Claude Code, GitHub Copilot, OpenCode, Continue, Aider, Codex. ResearchTools is written once, for Claude Code, in .claude/. Every other harness reads a mirror, a file install.ps1 generates from the canonical definitions. The canonical files are the single source of truth. Never edit a mirror by hand, since the next run overwrites it.

What each harness receives

Harness Generated target Scope From Notes
Claude Code .claude/ itself, linked into ~/.claude/ user none Native. Agents, skills, commands, rules and hooks, see chapter 01
GitHub Copilot, agents .github/agents/<name>.agent.md repo .claude/agents/ Copilot caps an agent prompt at 30,000 characters. A larger agent is replaced by a short stub that reads the canonical file first, and the state is reported stubbed, never ok
GitHub Copilot, prompts .github/prompts/<name>.prompt.md repo .claude/commands/ One prompt per task command, invoked as /<name> in Copilot Chat. The four session modes (concis, slim, focus, ctx) have no meaning outside Claude Code and are skipped on purpose
GitHub Copilot, rules .github/instructions/<name>.instructions.md repo .claude/rules/ One per rules file, applied to all files. mermaid.instructions.md is hand-kept and has no canonical source, by design
GitHub Copilot, master .github/copilot-instructions.md repo the repository Mission, agent routing and a pointer to the skills
GitHub Copilot CLI ~/.copilot/agents/<name>.agent.md user .claude/agents/ Written only with install.ps1 -Personal. Agents added since the last such run are invisible to the CLI
VS Code user profile %APPDATA%/Code/User/prompts/ user prompts and rules Written only with -Personal. Copies the generated prompts and instructions so they work in any workspace
OpenCode .opencode/agent/<name>.md repo .claude/agents/ Full body, no size ceiling, so it never degrades to a stub
Continue .continue/rules/researchtools.md repo .claude/rules/ One rule that points at the canonical files and the routing table
Aider CONVENTIONS.md repo the repository A pointer paragraph. Created once and never overwritten, so your edits survive
Aider, nightly pipeline .claude/skills/aider-setup/config/rules.md repo .claude/rules/ Not made by install.ps1: the kit build regenerates it from the rules, see chapter 14
Any AGENTS.md reader AGENTS.md repo the repository The distilled master: agent list, routing pointer, skills examples, cross-cutting rules. Readers include Hermes Agent, OpenHuman and Codex
Codex, skills .agents/skills/<name>/SKILL.md repo .claude/skills/ Codex is the only harness with a native skill convention. Each mirror holds the frontmatter only, since the description is the whole trigger surface. Descriptions are trimmed to whole sentences to fit Codex's skill-list budget, and the state is reported trimmed
Codex, nested instructions .claude/skills/AGENTS.md repo the repository Adds the script-surface rule for work inside the skills tree. Codex drops the deepest file when the chain exceeds its size cap

OpenHands was considered and is not built: it has no mirror entry, because a target written for a guessed convention would be an invented one.

Generating the mirrors

.\install.ps1                     # repo-level mirrors only, commit the output
.\install.ps1 -Personal           # also ~/.copilot/agents and the VS Code user profile
.\install.ps1 -Profile cosmetic   # also switch the active domain profile

Run it after every edit to an agent, a command or a rule, and commit the regenerated files with the change. Run it with -Personal whenever an agent or command was added, since the ordinary run never touches the two user-level targets. Through the setup entry point: .\setup.ps1 -InstallTools -Personal.

The intent file: mirror-policy.json

mirror-policy.json, at the repository root, holds what the generator is meant to do as data: each target above with its path, scope and flag, the size thresholds (the Copilot stub limit, the Codex skill-list budget), and the empty cells that are deliberate. Both install.ps1 and the dashboard collector read it, so an empty cell is judged against intent: a by-design skip is never reported as a loss, and a lost cell is never softened into by-design. The matrix has eight states: ok, stubbed, trimmed, lost, by-design, orphan, stale and unknown. The page that shows it is in chapter 10.

Session adapters

Separate from the mirrors, the dashboard reads live sessions through adapters declared in .claude/skills/rt-observe/harnesses.json: claude_code (the JSONL transcripts, plus the hooks inventory), copilot_chat (a read-only copy of the VS Code extension's session store) and aider (the run records the nightly driver writes). Adding a harness is one module plus one line in that file, with no change to the core. A harness with no adapter simply shows no session lane.

Rule for a new harness

A mirror is added in mirror-policy.json and in install.ps1 together, with a test, following docs/authoring-and-mirrors.md. The routing table in .claude/CLAUDE.md, README.md and Architecture.md stay the discovery path for every harness that has no native skill convention.


← 08 Rules and conventions | Table of contents | 10 rt-observe & dashboard →