Ricochet

Ricochet is the product-facing terminal orchestration surface. MAS is the underlying orchestration technology, and PC/PCE provide the persistent context layer underneath it.

Ricochet is setup-first. Shipped builds do not need to bundle Feynman or assume Claude/Codex/Gemini are already wired to local hardcoded paths.

What it does

• Runs Ricochet agent processes directly from the terminal
• Lets you switch the active agent and send prompts from a REPL
• Auto-starts the Ricochet Orchestrator and injects its system prompt on boot
• Loads a boot-time agent registry and user profile summary from Personal Context
• Makes every specialist session aware of both PC and PCE before delegated work begins
• Supports pasting a system prompt file into the active agent on demand
• Shows prefixed live output for each running agent
• Keeps basic per-agent status and recent output history
• Supports explicit and automatic handoff to specialist CLI agents
• Persists session state and delegated tasks under .ricochet-home
• Exposes a Ricochet-native terminal bridge so agents can read, type into, and key other agent terminals

Product shape

This repo is intended to ship on its own.

• Ricochet runtime and setup live inside this repo
• the orchestrator system prompt is bundled in .\prompts\orchestrator-system-prompt.txt
• local runtime state is written to .ricochet-home
• ricochet.config.json is generated locally by ricochet configure
• ricochet.config.example.json is the checked-in reference file

Install

Global CLI install:

npm install -g ricochet-cli

Run:

ricochet

One-off without a global install:

npx ricochet

When installed globally, Ricochet stores its generated config and runtime state in your user profile instead of inside the npm package directory.

Current release:

• 0.1.6 fixes Windows UTF-8 BOM config loading, defaults PC/PCE to MAS\Repos\MAS and MAS\Repos\PCE when available, and scaffolds starter PC markdown files automatically

Usage

The ricochet command now forwards into the PTY-backed Python runtime (ricochet_cli.py) so interactive agents can actually answer inside the Ricochet UI.

First-time configure:

cd path\to\ricochet-cli
ricochet configure

That wizard:

• detects installed CLI tools such as Codex, Claude Code, Gemini, and Feynman
• auto-configures machine-local defaults for workspace and Personal Context on first run
• creates starter PC files such as identity.md, background.md, preferences.md, projects.md, and repositories.md when they do not exist yet
• keeps MAS / PC / PCE path customization behind an advanced prompt instead of requiring manual path entry
• asks which ones you want Ricochet to enable
• writes a local ricochet.config.json
• keeps optional tools out of the shipped Ricochet repo
• can automatically install Codex through npm install -g openai-codex
• can automatically install Gemini through npm install -g @google/gemini-cli
• can automatically install Claude Code through winget, brew, or the official PowerShell installer
• can automatically install Feynman through bun, pnpm, or curl | bash, and on Windows can bootstrap pnpm first when npm is available but Feynman prerequisites are missing

cd path\to\ricochet-cli
.\ricochet.cmd
# or, if installed through npm/bin
ricochet
# remove a global npm install
ricochet uninstall
# direct entrypoint
python .\ricochet_cli.py

You can think of the naming like this:

• Ricochet: the product surface and operator-facing identity
• MAS: the underlying orchestration technology
• PC / PCE: the persistent context layer

Ricochet Bridge

Ricochet includes a Windows-native bridge inspired by smux, built for Ricochet-on-MAS instead of tmux.

Use it from another terminal or from inside an agent session:

.\ricochet-bridge.cmd list
.\ricochet-bridge.cmd read codex-specialist 20
.\ricochet-bridge.cmd message claude "Please summarize the findings."
.\ricochet-bridge.cmd read claude 20
.\ricochet-bridge.cmd keys claude Enter

Bridge behavior:

• read marks a target as safe to interact with
• type, message, and keys enforce read-before-act
• message prepends [mas-bridge from:<agent>]
• bridge requests go through .ricochet-home\bridge

Manual Stable Launch

For Windows-native CLIs that behave better when they own the terminal directly, use the manual Ricochet launcher:

.\ricochet-agent.cmd claude
.\ricochet-agent.cmd codex-specialist
.\ricochet-agent.cmd ricochet-orchestrator
.\ricochet-agent.cmd gemini
.\ricochet-agent.cmd feynman

What it does:

• generates a role-specific Ricochet bootstrap file under .ricochet-home\memory
• exports MAS_PC_ROOT, MAS_PCE_ROOT, RICOCHET_BRIDGE_HOME, and MAS_AGENT_ID
• launches the CLI in your terminal instead of through the Ricochet subprocess manager
• passes the bootstrap directly to Claude and Codex-family agents on startup
• passes the bootstrap directly to Claude, Codex-family agents, and Gemini on startup

If you only want to inspect the bootstrap first:

python .\ricochet_agent.py bootstrap claude

REPL commands

• /help
• /agents
• /boot
• /run <agent|all>
• /stop <agent|all>
• /switch <agent>
• /status
• /prompt [path]
• /send <text>
• /task <agent> <prompt>
• /handoff <prompt>
• /tasks
• /registry
• /profile
• /configure
• /logs [agent]
• /clear
• /exit

Any line that does not start with / is sent to the active agent.

Handoff routing

/handoff classifies the prompt and routes it to the best configured specialist:

• research -> feynman when configured
• coding -> codex-specialist
• synthesis -> claude
• general -> gemini or fallback

/task bypasses heuristics and sends a framed delegated task to a specific agent.

Scale features borrowed from Feynman

• durable local home directory: .ricochet-home
• persistent state files for tasks and session status
• explicit agent capability registry
• boot-time runtime identity
• configure and self-inspection commands
• always-on user profile loading from Personal Context
• specialist bootstrap with Ricochet identity plus PC/PCE awareness
• MAS task tags for progress, blocked, result, and failure tracking
• Ricochet bridge CLI for terminal-to-terminal specialist messaging

Notes

• The PTY-backed Python runtime is the real path for interactive agents.
• ricochet_cli.py is the production entrypoint for Ricochet.
• Delegated tasks now include PC/PCE-aware context and MAS task-tag instructions, but reliability still improves as individual specialists follow those tags more consistently.
• Cross-agent terminal messaging is Ricochet-native and file-backed, so it does not depend on the browser UI or tmux.
• On Windows, the most stable workflow for Codex and Claude is currently manual terminal launch through launch-agent.cmd, with Ricochet still providing identity, PC/PCE awareness, and bridge access.
• Gemini, Codex, Claude Code, and Feynman can all be discovered or installed during ricochet configure, so the repo does not need to ship those CLIs inside it.

Shipping hygiene

• node_modules/, .ricochet-home/, and Python cache output are local-only and should not be committed
• ricochet.config.json is local generated state and should not be committed
• optional tools such as Feynman, Gemini, Codex, and Claude Code should be detected or installed through setup rather than shipped inside the repo