harness-homies

A read-only MCP server that lists coding-agent sessions on your machine — Claude Code, OpenCode, Cursor, and Codex — in one place: what's running, its topic, its todos, its transcript.

It never writes to another agent's session and never sends messages.

Install

Claude Code (plugin)

/plugin marketplace add nikp29/harness-homies
/plugin install harness-homies@harness-homies

This installs the MCP server (run via npx -y harness-homies) and the inspect-agents skill.

Agent Plugins clients

plugin/ is an Agent Plugins 1.0.0 package: plugin.json, mcp.json, and skills/inspect-agents/SKILL.md. Point any conformant client at that directory. The same directory also carries .claude-plugin/plugin.json and .mcp.json for Claude Code.

OpenCode

OpenCode plugins are JS modules and can't register MCP servers or skills, so set it up with config instead:

1. Merge opencode/opencode.json into ~/.config/opencode/opencode.json (or a project's opencode.json).
2. Copy the skill: cp -r plugin/skills/inspect-agents ~/.config/opencode/skills/

Codex

codex mcp add harness-homies -- npx -y harness-homies

Cursor

Add an entry to ~/.cursor/mcp.json:

{ "mcpServers": { "harness-homies": { "type": "stdio", "command": "npx", "args": ["-y", "harness-homies"] } } }

From source

pnpm install
pnpm build
claude mcp add --scope user harness-homies -- node /path/to/harness-homies/dist/cli.js

Tools

| Tool | Args | Does | |---|---|---| | list_sessions | agent?, cwd?, running_only?, limit? | List sessions across one or all agents, live and historical, most recent first | | get_session | agent, session_id | Title, cwd, status, todos, message count | | get_transcript | agent, session_id, cursor?, limit?, role?, raw? | Paginated transcript, secrets redacted by default | | search_sessions | query, agent?, limit? | Substring search over titles and recent transcript content |

agent is one of claude-code | opencode | cursor | codex. All tools are readOnlyHint: true.

Develop

pnpm test        # builds, then runs the suite against dist/
pnpm typecheck
node dist/cli.js doctor   # per-adapter availability + session counts

Notes

• Redaction is on by default for transcript text (API keys, tokens, PEM blocks, etc.). Pass raw: true to skip it.
• Claude Code: reads ~/.claude/sessions/*.json (live) and ~/.claude/projects/**/*.jsonl (history).
• OpenCode: reads ~/.local/share/opencode/opencode.db directly.
• Cursor: reads ~/Library/Application Support/Cursor/User/globalStorage/{conversation-search,state}.db. macOS only. Status is always unknown — no running signal is available.
• Codex: reads ~/.codex/state_5.sqlite, falling back to scanning ~/.codex/sessions/**/*.jsonl directly if the DB schema doesn't match.
• All formats are undocumented by their vendors. Adapters degrade (fewer fields) rather than crash on an unrecognized record.
• setup subcommand and Cursor auto-registration are not implemented — register manually as shown above.
• The plugin configs pin harness-homies@<version>. When releasing, bump the version in package.json, plugin/plugin.json, plugin/.claude-plugin/plugin.json, both MCP configs in plugin/, opencode/opencode.json, and src/server.ts.