peer-model

Peer model session

The target model runs as a separate background Claude Code session (claude --bg) pointed at an Anthropic-compatible endpoint. It registers as a local peer, so both sides talk through the built-in SendMessage / ListAgents tools. Do not use claude -p for this: headless print sessions are not peers and cannot message back.

0. Configuration

Profiles live in ${XDG_CONFIG_HOME:-~/.config}/cc-peer-model/config.toml (override with CC_PEER_MODEL_CONFIG). List them with:

"${CLAUDE_PLUGIN_ROOT}/scripts/peer.py" profiles

If the file is missing, run peer.py init to write an example and ask the user to fill it in. Each profile:

[profiles.ds]
base_url_env = "PIMM_BASE_URL"  # or base_url = "...", or base_url_cmd = [...]
api_key_env = "PIMM_API_KEY"    # or api_key_cmd = ["security", "find-generic-password", "-s", "pimm", "-w"]
model = "deepseek-v4.1-flash"
max_context_tokens = 1000000    # optional
env = { API_TIMEOUT_MS = "600000" }  # optional, non-secret only

claude --bg runs the peer in a process spawned by the Claude Code daemon, so the caller's environment never reaches it. peer.py therefore passes the profile via --settings: non-secret values in env, the key via apiKeyHelper, which runs inside the peer session:

• api_key_cmd: an argv list (e.g. a macOS keychain lookup), run in the session. Works regardless of how the daemon was started.
• api_key_env: the variable is read in the session, i.e. from the daemon's environment. It works only if the daemon was started from a shell that exports it (e.g. via the shell profile); a daemon started from Claude Desktop, an IDE or launchd will not have it.
• A literal api_key is refused.

Never write secrets into the config or echo resolved values.

1. Spawn

"${CLAUDE_PLUGIN_ROOT}/scripts/peer.py" spawn <profile> -n <name> [-f] [-m <permission-mode>] [-e <effort>] ["<initial task>"]

• <profile>: map the user's wording to a profile name (e.g. "deepseek" → ds). If ambiguous, list profiles and ask.
• -n: peer name, used as the to address. Pick a short task-specific name (e.g. ds-review-auth). Check ListAgents first and reuse an existing peer instead of spawning a duplicate.
• -f: fork the current session so the peer gets the full conversation so far. Use it whenever the task depends on prior discussion; skip it for self-contained tasks (cheaper, cleaner context). A forked peer also inherits the current task, so its initial prompt must state its scope explicitly and say what not to do.
• -m: must equal this session's permission mode (default, acceptEdits, plan, bypassPermissions; default bypassPermissions). On a mismatch, messages are held for the user's manual approval instead of being delivered.
• Initial task: tell it to report back with SendMessage to this session's name (shown by ListAgents as "This session is ..."). Without a task it starts idle and waits for messages.