Open-source hybrid AI coding agent for VS Code, CLI, and remote messenger control.
Plan work, edit safely, run tools, coordinate workers, and bring your own model key.

Install · Features · Models and BYOK · Architecture · Development

Ricochet is an autonomous coding agent that runs beside your editor instead of inside a single chat box. It combines a VS Code extension, a React webview, and a Go sidecar core that can inspect a workspace, propose plans, edit files with review, run commands, use MCP tools, and coordinate multiple workers for larger tasks.

It is designed for developers who want an agent that can move through a real codebase while still making changes reviewable and reversible.

Ricochet keeps the UI thin and moves orchestration into a native sidecar:

VS Code / Cursor / Windsurf
  extension host
    webview chat, settings, diff review, checkpoints
      JSON-RPC over stdio
        Go core
          agent controller, tools, MCP hub, skills, safeguards, live mode
            AI providers through BYOK keys

The extension owns IDE integration and review UX. The Go core owns planning, tool execution, provider routing, session state, permissions, checkpoints, and live messenger routing.

• Plan: explores the repository and produces a first-class implementation plan before code changes.
• Act / Implement: applies changes through tools, pending edit review, and command execution.
• Verify: checks results, reports test/build status, and explains remaining risk.
• Swarm: delegates independent work to workers while the coordinator synthesizes results.
• Live Mode / Ether: binds a session to Telegram or Discord so the same agent can be controlled remotely.

Ricochet is open-source and does not require a Ricochet subscription when you use BYOK. You provide the API key for the provider you want to use, and Ricochet routes requests through the configured provider.

Current defaults in core/config/providers.yaml:

Free models are available in the catalog, including the default OpenRouter Qwen 3 Coder (Free) model and free entries from providers such as OpenRouter, Mistral, and Z.AI where configured. Paid provider models are also supported, but their usage is billed by the provider through your own key.

Supported provider families include OpenRouter, OpenAI-compatible APIs, DeepSeek, Mistral, Z.AI/GLM, OpenAI, Gemini, Anthropic, xAI, MiniMax, and Grik gateway models when configured.

Install Ricochet from the VS Code Marketplace:

ext install grik.ricochet

The extension also works in VS Code-compatible editors such as Cursor and Windsurf.

The CLI can be launched from bundled binaries or built from source:

ricochet

For local development:

git clone https://github.com/Grik-ai/ricochet.git
cd ricochet
./scripts/build-all.sh

1. Install the extension with ext install grik.ricochet.
2. Open the Ricochet sidebar.
3. Open Settings and add a provider key, for example OPENROUTER_API_KEY.
4. Choose a model from the model picker, or keep the default qwen/qwen3-coder:free.
5. Ask Ricochet to inspect, plan, implement, or verify a task.
6. Review pending file changes before saving them into your workspace.

Ricochet stores local settings under ~/.ricochet/:

Workspace-specific behavior can also be configured with .ricochet/ files, project rules, skills, and MCP settings.

Ricochet can use Model Context Protocol servers and local skills to extend the agent:

• MCP servers add external tools such as GitHub, databases, browser automation, search, and custom services.
• Skills package reusable project knowledge, workflows, and constraints.
• Project rules and custom instructions are injected into the agent when relevant to the task.

Live Mode lets you continue a Ricochet session from Telegram or Discord:

1. Create and configure a bot token in Ricochet settings.
2. Toggle Live Mode in the extension.
3. Send messages or voice notes from your phone.
4. Receive progress updates, completion summaries, and approval requests remotely.

Only one active window should own a given bot/session binding at a time.

Ricochet/
  extension-vscode/     VS Code extension, commands, webview bridge, diff review
  webview/              React chat UI, settings, task timeline, checkpoints
  core/                 Go sidecar: agent, tools, providers, MCP, skills, safeguards
  scripts/              Build and packaging helpers
  RICOCHET.md           Internal agent/project manifest

Important subsystems:

• core/internal/agent: session orchestration, planning, lifecycle events, workers, provider routing.
• core/internal/tools: filesystem, command, MCP, skill, graph, batch, and research tools.
• core/internal/safeguard: permissions, approval rules, ignored paths, and checkpoints.
• core/internal/livemode and core/internal/telegram: remote control and voice-message handling.
• extension-vscode/src/services: sidecar process, chat bridge, pending changes, checkpoints, sessions, MCP, review UX.
• webview/src/components: chat, settings, agent dashboard, checkpoints, MCP, and account UI.

Build the Go core:

cd core
go build ./cmd/ricochet

Run Go tests:

cd core
go test ./...

Build the VS Code extension:

cd extension-vscode
npm install
npm run build

Build the webview:

cd webview
npm install
npm run build

Build all packaged targets:

./scripts/build-all.sh

Issues, bug reports, feature proposals, and pull requests are welcome. The most useful contributions are reproducible bug reports, provider/tool fixes, UX polish, documentation improvements, and focused tests.

Ricochet is an independent open-source project. If it helps you, please star the repository and share useful issues or pull requests:

• GitHub: github.com/Grik-ai/ricochet

Apache 2.0 © 2025 Igor Pryimak