Ricochet

🚀 AI Coding Agent with Live Mode — Control from Telegram/Discord

Features • Live Mode • Installation • Architecture

Ricochet is the first hybrid coding agent that lives in your IDE and your pocket. Code autonomously with a powerful VS Code assistant, then switch to Ether Mode to control your development environment remotely via messenger. Build, debug, and deploy from anywhere.

✨ Features

Core Capabilities

IDE Support

• ✅ VSCode — Full support
• ✅ Cursor — Full support (VSCode fork)
• ✅ Windsurf — Full support (VSCode fork)
• 🔜 JetBrains — Coming soon

AI Providers (BYOK — Bring Your Own Key)

📱 Live Mode

Ricochet's killer feature — continue working with your AI agent from your phone.

sequenceDiagram
    participant User as 📱 User (Telegram)
    participant TG as Telegram Bot
    participant Core as ricochet-core
    participant AI as AI Agent
    
    User->>TG: "Fix the auth bug"
    TG->>Core: Route message
    Core->>AI: Execute task
    AI->>Core: Response/Tool calls
    Core->>TG: Send update
    TG->>User: 📩 Notification

Ether Stages

When Live Mode is active, the UI shows real-time activity:

Messages from Telegram appear in chat with a 📱 badge.

Setup

1. Create a Telegram bot via @BotFather
2. Get your Chat ID via @userinfobot
3. Enter credentials in Ricochet Settings
4. Toggle Live Mode ON

� Installation

From Marketplace (Recommended)

# VSCode / Cursor / Windsurf
ext install ricochet.ricochet

From Source

# Clone repository
git clone https://github.com/Grik-ai/ricochet.git
cd ricochet

# Install dependencies
cd extension-vscode && npm install
cd ../webview && npm install

# Build everything
./scripts/build-all.sh

# Launch in dev mode (VSCode)
cd extension-vscode && npm run watch
# Press F5 to launch Extension Development Host

🏗️ Architecture

Ricochet follows a modular sidecar architecture for maximum performance and maintainability.

┌─────────────────────────────────────────────────────────────┐
│                    VSCode Extension                         │
│  ┌───────────────┐    ┌──────────────────────────────────┐ │
│  │ extension.ts  │◄──►│          Webview (React)         │ │
│  │ core-process  │    │  ChatView, Settings, LiveMode    │ │
│  └───────┬───────┘    └──────────────────────────────────┘ │
└──────────┼──────────────────────────────────────────────────┘
           │ JSON-RPC (stdio)
           ▼
┌─────────────────────────────────────────────────────────────┐
│                   ricochet-core (Go)                        │
│  ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│  │   Agent     │   Tools     │    MCP      │  Live Mode  │ │
│  │ Controller  │  Executor   │    Hub      │ Controller  │ │
│  └─────────────┴─────────────┴─────────────┴─────────────┘ │
│  ┌─────────────┬─────────────┬─────────────┬─────────────┐ │
│  │  Safeguard  │   Modes     │   Config    │   Bridge    │ │
│  │ Checkpoints │  Manager    │   Store     │   (Cloud)   │ │
│  └─────────────┴─────────────┴─────────────┴─────────────┘ │
└─────────────────────────────────────────────────────────────┘

Project Structure

Ricochet/
├── extension-vscode/          # VSCode extension (TypeScript)
│   ├── src/
│   │   ├── extension.ts       # Entry point (~55 lines)
│   │   ├── core-process.ts    # Sidecar lifecycle
│   │   └── webview-provider.ts
│   ├── bin/                   # Cross-platform binaries
│   │   ├── darwin-arm64/
│   │   ├── darwin-x64/
│   │   ├── linux-x64/
│   │   └── win32-x64/
│   └── package.json

├── webview/                   # React UI
│   ├── src/
│   │   ├── components/
│   │   │   ├── chat/          # ChatView, Messages, Input
│   │   │   ├── live-mode/     # LiveModeSwitch, Status
│   │   │   └── settings/      # Settings panel
│   │   └── hooks/
│   │       ├── useChat.ts
│   │       ├── useLiveMode.ts
│   │       └── useAudioRecorder.ts
│   └── package.json

├── core/                      # Go backend
│   ├── cmd/
│   │   ├── ricochet/          # Main binary
│   │   └── eval/              # Evaluation runner
│   └── internal/
│       ├── agent/             # AI orchestration
│       ├── tools/             # Native tool implementations
│       ├── mcp/               # MCP Hub & OAuth
│       ├── modes/             # Custom agent personas
│       ├── safeguard/         # Checkpoints & permissions
│       ├── config/            # Settings persistence
│       ├── context/           # Tree-sitter parser
│       ├── livemode/          # Telegram/Discord control
│       ├── whisper/           # Voice transcription
│       └── bridge/            # Cloud WebSocket (yamux)

└── scripts/
    └── build-all.sh           # Cross-compile script

� Core Modules

Agent (internal/agent/)

• controller.go — Session & conversation management
• anthropic.go / openai.go — Provider implementations
• state.go — Thread-safe message handling

Tools (internal/tools/)

• executor.go — Native tool dispatcher
• fs_tools.go — File system operations with consent
• cmd_tools.go — Command execution
• browser_tools.go — Chromedp integration

MCP Hub (internal/mcp/)

• hub.go — Multi-server connection manager
• oauth.go — OAuth2 token management
• config.go — mcp_settings.json parser

Modes (internal/modes/)

• manager.go — Hot-reloading mode configuration
• types.go — Mode schema (roles, restrictions, tool groups)

Safeguard (internal/safeguard/)

• manager.go — Shadow git checkpoints
• permissions.go — "Always Allow" rule persistence

Context (internal/context/)

• treesitter.go — Multi-language AST parsing (JS/TS/Python/Rust)
• parser/ — Native Go AST for .go files
• tracker.go — Environment & file context injection

Config (internal/config/)

• store.go — ~/.ricochet/settings.json management

Live Mode (internal/livemode/)

• controller.go — Telegram/Discord bot orchestration

⚙️ Configuration

Settings Persistence

All settings are stored in ~/.ricochet/:

Custom Modes

Create .ricochet/modes.yaml in your project:

modes:
  - slug: qa
    name: QA Engineer
    roleDefinition: "Expert in testing and quality assurance"
    customInstructions: "Focus on edge cases and test coverage"
    groups:
      - read
      - edit:[**/*_test.go, **/*.spec.ts]
      - command

MCP Settings

Compatible with Cline's format — mcp_settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "..." }
    }
  }
}

🛠️ Development

Build Commands

# Build Go core (current platform)
cd core && go build ./cmd/ricochet

# Build all platforms
./scripts/build-all.sh

# Run evals
cd core && go run ./cmd/eval cases/

# Watch webview
cd webview && npm run dev

# Watch extension
cd extension-vscode && npm run watch

Testing

# Go tests
cd core && go test ./...

# Webview tests
cd webview && npm test

# Extension tests
cd extension-vscode && npm test

❤️ Support the Project

Ricochet is an independent open-source project maintained by Igor Pryimak. I apologize for asking, but without your help, it will be very difficult to maintain and develop this project further. If this tool helps you code faster and you want to support existing development, you can:

• ⭐ Star the repo (it really helps!)
• ☕ Buy me a coffee (Ko-fi): ko-fi.com/igoryan34
• � PayPal: Donate via PayPal
• �💎 Crypto Support:
  • TON: UQB93GTsF6ZI7ljBViLr-IHIf93HpqwolC51jR5Und7GAwm4
  • USDT (TRC20): TH1ZvpbmNKtArQ2zNyoeAq4zvU3koNTFhj
  • EVM (BNB / USDT / BTC - BEP20): 0x048911b8690cd7c85a0898dffbd5e3b9ba50dd10
  • Bitcoin (BTC): 13fC3C2yRq4i8meaUqHWK6H5UQ2V1Bk8Ct

📄 License

Apache 2.0 © 2025 Igor Pryimak, TK BAZIS - M / GRIK - AI

Built with ❤️ for developers who want to code even from their couch