# 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](https://agent-plugins.org/) 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`](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

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

### Cursor

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

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

### From source

```bash
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

```bash
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`.