---

Table of Contents

• What Is Sidecar?
• Use Cases
• Getting Started
• Quick Start
• How It Works
• Features
• Commands
• Agent Modes
• Models
• MCP Integration
• Configuration
• Understanding Sidecar Output
• Troubleshooting
• Documentation
• Contributing
• Built On
• License

---

What Is Sidecar?

Sidecar is a literal second window that runs alongside your Claude Code or Cowork session. It:

1. Shares your context. Your current conversation history is automatically extracted and passed to the sidecar. No copy-pasting, no re-explaining.
2. Runs in parallel. Your main Claude session keeps working while you interact with the sidecar. It's not sequential, it's simultaneous.
3. Connects to any model. Gemini 3.1 Pro (1M context), GPT-5.4, DeepSeek v3.2, Qwen, Grok: whatever's best for the job.
4. Folds back cleanly. When you're done, click FOLD and a structured summary returns to your main context. No noise, just results.

---

Use Cases

Fact-Check Claude's Work

Claude just proposed an architecture or made a claim? Open a sidecar to a different model and verify it, with full context already loaded.

Get a Second Opinion on a Feature

Designing something complex? Fork the conversation to Gemini or GPT-5.4 for an independent take. Compare approaches before committing to one.

Deep-Dive Without Polluting Context

Need to explore a rabbit hole (trace a bug, read a huge file, research an API)? Do it in the sidecar. Your main session stays clean and focused.

Parallel Investigation

While Claude implements a fix, spin up a sidecar to review the test coverage, audit security implications, or draft documentation, all at the same time.

Leverage Model Strengths

• Gemini 3.1 Pro: 1M token context for analyzing entire codebases
• GPT-5.4: Strong at code generation and refactoring
• DeepSeek v3.2: Cost-effective reasoning at scale
• Qwen 3.5: High-quality open-weight reasoning
• Grok: Fast iteration and broad knowledge

---

Getting Started

Prerequisites

• Node.js 18+

1. Install

npm install -g claude-sidecar

On install, sidecar automatically configures itself for all supported clients:

• Claude Code CLI: Registers an MCP server and installs a Skill, so Claude can launch and manage sidecars on your behalf
• Claude Desktop & Cowork: Registers an MCP server, so sidecar tools appear natively in the UI

No manual registration needed. Just install and run setup.

2. Run Setup

sidecar setup

This launches a graphical setup wizard that walks you through everything:

Step	What It Does
1. API Keys	Enter keys for OpenRouter, Google, OpenAI, and/or Anthropic. Each key is validated live against the provider's API. Keys are stored locally at ~/.config/sidecar/.env with restricted permissions (0600).
2. Default Model	Choose your go-to model from 20+ aliases (Gemini, GPT, Opus, DeepSeek, Qwen, Grok, and more). This is what sidecar uses when you omit --model.
3. Model Routing	Configure which provider serves each model. If you have both an OpenRouter key and a direct Google key, you can route Gemini through Google directly and everything else through OpenRouter.
4. Review	Summary of your configuration before saving.

Headless environments: If Electron isn't available, the wizard falls back to a readline-based setup in the terminal.

You can also manage individual settings without re-running the full wizard:

sidecar setup --add-alias fast=openrouter/google/gemini-3.1-flash-lite-preview

3. Verify

sidecar start --model gemini --prompt "Hello, confirm sidecar is working"

A window should open alongside your editor with Gemini ready to chat, pre-loaded with your Claude Code context.

---

Quick Start

# Fact-check: open a sidecar to verify Claude's approach
sidecar start --model gemini --prompt "Fact-check the auth approach Claude just proposed"

# Second opinion: get a different model's take
sidecar start --model gpt --prompt "Review this feature design. Is there a simpler approach?"

# Deep dive: investigate without polluting your main context
sidecar start --model gemini-pro --prompt "Analyze the entire codebase architecture"

# Headless: autonomous, no UI, summary returns automatically
sidecar start --model gemini --prompt "Generate Jest tests for src/utils/" --no-ui

# Use your configured default model (just omit --model)
sidecar start --prompt "Security review the payment module"

---

How It Works

1. Context sharing. Sidecar reads your Claude Code session from ~/.claude/projects/[project]/[session].jsonl and passes it to the sidecar model automatically.
2. Window launch. An Electron window opens alongside your editor with the sidecar UI (OpenCode-powered).
3. Parallel interaction. You converse with the sidecar model while your main Claude session continues working independently.
4. Fold. Click FOLD (or press Cmd+Shift+F) to generate a structured summary.
5. Context return. The summary flows back into your Claude Code context for Claude to act on.

The Electron shell uses a BrowserView architecture: the OpenCode web UI loads in a dedicated viewport, while the sidecar toolbar (branding, timer, Fold button) renders in the bottom 40px. No CSS conflicts with the host app.

---

Features

Interactive + Headless Modes

Interactive (default): Opens a window alongside Claude Code. You converse with the sidecar, steer the investigation, then click FOLD to generate a structured summary. Switch models mid-conversation without restarting.

Headless (--no-ui): The agent works autonomously in the background. When done, outputs a [SIDECAR_FOLD] summary automatically. Ideal for bulk tasks: test generation, documentation, linting.

Context Passing

Your conversation history is automatically shared with the sidecar. No re-explaining needed. Filter by turns (--context-turns) or time window (--context-since 2h).

Adaptive Personality

Sidecar detects its launch context and adapts:

• From Claude Code (--client code-local): Engineering-focused (debug, implement, review)
• From Cowork (--client cowork): General-purpose (research, analyze, write, brainstorm)

MCP Server Inheritance

Sidecar automatically discovers MCP servers configured in your Claude Code session (~/.claude.json) and passes them through to the sidecar's OpenCode instance. Your sidecar has access to the same tools you do. Control this with:

• --no-mcp disables MCP inheritance entirely
• --exclude-mcp <name> excludes specific servers (repeatable)
• --mcp name=url adds additional servers

Safety Features

• Conflict detection: Warns when files changed externally while the sidecar was running
• Drift awareness: Indicates when the sidecar's context may be stale relative to your current session
• Pre-flight validation: All CLI inputs are validated before anything launches

Auto-Update

Sidecar checks the npm registry for updates once every 24 hours (cached, zero-latency background check). When an update is available:

• CLI: A notification box appears in your terminal after any command
• Electron UI: A banner appears above the toolbar with a one-click Update button. No terminal commands needed.

Updating installs the latest code and re-runs the postinstall step, so your Claude Code Skill file and MCP registrations are always kept in sync with the latest version. No manual re-registration needed.

# Or update manually from the CLI
sidecar update

Session Persistence

Every sidecar is persisted. List past sessions, read their summaries, reopen them, or chain them together.

sidecar list                           # See all past sidecars
sidecar read abc123                    # Read the summary
sidecar resume abc123                  # Reopen the exact session
sidecar continue abc123 --prompt "..." # New session building on previous findings

MCP Integration

Full MCP server for Claude Desktop and Cowork. Sidecar tools appear natively inside Cowork's sandboxed environment. No CLI required.

---

Commands

sidecar start: Launch a Sidecar

sidecar start --model <model> --prompt "<task>"

Option	Description	Default
--model	Model to use (alias or full string)	Config default
--prompt	Task description	(required)
--no-ui	Headless autonomous mode	false
--agent	Agent mode: chat, plan, build	chat
--timeout	Headless timeout in minutes	15
--context-turns N	Max conversation turns to include	50
--context-since	Time filter: 30m, 2h, 1d
--context-max-tokens N	Context size cap	80000
--no-context	Skip parent conversation context	false
--thinking	Reasoning effort: none minimal low medium high xhigh	medium
--summary-length	Output verbosity: brief normal verbose	normal
--session-id	Explicit Claude Code session ID	Most recent
--mcp	Add MCP server: name=url or name=command
--mcp-config	Path to opencode.json with MCP config
--no-mcp	Don't inherit MCP servers from parent	false
--exclude-mcp	Exclude specific MCP server (repeatable)
--client	Client context: code-local cowork (code-web experimental)	code-local

sidecar list: Browse Past Sessions

sidecar list                    # Current project
sidecar list --status complete  # Completed only
sidecar list --all              # All projects
sidecar list --json             # JSON output

sidecar resume: Reopen a Session

sidecar resume <task_id>

Reopens the exact OpenCode session with full conversation history preserved.

sidecar continue: Build on Previous Work

sidecar continue <task_id> --prompt "Now implement the fix from the analysis"

Starts a new session with the previous session's conversation as read-only background context. Optionally switch models.

sidecar read: Read Session Output

sidecar read <task_id>                  # Summary (default)
sidecar read <task_id> --conversation   # Full conversation
sidecar read <task_id> --metadata       # Session metadata

sidecar abort: Stop a Running Session

sidecar abort <task_id>

Immediately stops a running sidecar session. The session status changes to aborted.

sidecar setup: Configure Sidecar

sidecar setup                                           # Full setup wizard (GUI)
sidecar setup --add-alias fast=openrouter/google/gemini-3.1-flash-lite-preview

Opens the graphical setup wizard for API keys, default model, model routing, and aliases. See Getting Started for details.

sidecar update: Update to Latest Version

sidecar update

Updates sidecar to the latest npm release. In the Electron UI, click the Update button in the banner instead. No terminal needed.

---

Agent Modes

Three primary modes control what the sidecar can do autonomously:

Agent	Reads	Writes/Bash	Best For
Chat (default)	Auto-approved	Asks permission	Questions, analysis, fact-checking, guided exploration
Plan	Auto-approved	Blocked entirely	Code review, architecture analysis, security audits
Build	Auto-approved	Auto-approved	Implementation tasks, test generation, headless batch work

# Chat: good for fact-checking and analysis with human-in-the-loop (default)
sidecar start --model gemini --prompt "Verify Claude's approach to the auth refactor"

# Plan: strict read-only, no changes possible
sidecar start --model gemini --agent Plan --prompt "Security review of the payment module"

# Build: full autonomy, use when you explicitly want it to write code
sidecar start --model gemini --agent Build --no-ui \
  --prompt "Generate comprehensive Jest tests for src/utils/"

Headless mode note: --no-ui defaults to Build. The Chat agent requires interactive UI for write permissions and stalls in headless mode.

---

Models

Using Aliases (after sidecar setup)

Alias	Model	Notes
gemini	Gemini 3.1 Flash Lite	Fast, cost-effective
gemini-pro	Gemini 3.1 Pro	Deep analysis, 1M context
gpt	GPT-5.4	Code generation, refactoring
gpt-pro	GPT-5.4 Pro	Extended reasoning
codex	GPT-5.3 Codex	Code-specialized
claude / sonnet	Claude Sonnet 4.6	Balanced capability
opus	Claude Opus 4.6	Complex reasoning
haiku	Claude Haiku 4.5	Fast, lightweight
deepseek	DeepSeek v3.2	Cost-effective reasoning
qwen	Qwen 3.5 397B	High-quality open-weight
qwen-coder	Qwen 3 Coder	Code-specialized
qwen-flash	Qwen 3.5 Flash	Fast inference
mistral	Mistral Large	Strong European model
devstral	Devstral	Code-focused Mistral
grok	Grok 4.1 Fast	Fast iteration
kimi	Kimi K2.5	Multilingual
glm	GLM-5	Chinese-English bilingual
minimax	MiniMax M2.5	Multimodal
seed	Seed 2.0 Mini	Lightweight
(omit --model)		Your configured default

Using Full Model Strings

Access	Format	Example
OpenRouter	openrouter/provider/model	openrouter/google/gemini-3.1-pro-preview
Direct Google	google/model	google/gemini-3.1-flash-lite-preview
Direct OpenAI	openai/model	openai/gpt-5.4
Direct Anthropic	anthropic/model	anthropic/claude-opus-4-6

The prefix determines which credentials are used. Model names evolve; verify current names:

curl https://openrouter.ai/api/v1/models | jq '.data[].id' | grep -i gemini

---

MCP Integration

For Claude Desktop and Cowork, sidecar exposes a full MCP server auto-registered on install.

To register manually:

claude mcp add-json sidecar '{"command":"npx","args":["-y","claude-sidecar@latest","mcp"]}' --scope user

MCP Tool	Description
sidecar_start	Spawn a sidecar (returns task ID immediately)
sidecar_status	Poll for completion
sidecar_read	Get results: summary, conversation, or metadata
sidecar_list	List past sessions
sidecar_resume	Reopen a session
sidecar_continue	New session building on previous
sidecar_abort	Stop a running session
sidecar_setup	Open setup wizard
sidecar_guide	Get usage instructions

Async pattern: sidecar_start returns a task ID immediately. Poll with sidecar_status, then read results with sidecar_read. This is non-blocking: the calling agent can do other work while the sidecar runs.

---

Configuration

Environment Variables

Variable	Description	Default
OPENROUTER_API_KEY	API key for OpenRouter (multi-model access)	(required)
GOOGLE_GENERATIVE_AI_API_KEY	Direct Google API key (bypasses OpenRouter)
OPENAI_API_KEY	Direct OpenAI API key
ANTHROPIC_API_KEY	Direct Anthropic API key
LOG_LEVEL	Logging verbosity: error warn info debug	error
SIDECAR_CONFIG_DIR	Override config directory	~/.config/sidecar
SIDECAR_ENV_DIR	Override .env file directory
SIDECAR_TIMEOUT	Default headless timeout in minutes	15
OPENCODE_COMMAND	Override OpenCode binary path	opencode

API keys configured via sidecar setup are stored in ~/.config/sidecar/.env with restricted permissions (0600). You can also set them as environment variables directly.

---

Understanding Sidecar Output

Every fold produces a structured summary:

## Sidecar Results: [Title]

**Context Age:** [How stale the context might be]
**FILE CONFLICT WARNING** [If files changed while the sidecar ran]

**Task:** What was requested
**Findings:** Key discoveries
**Attempted Approaches:** What was tried but didn't work
**Recommendations:** Concrete next steps
**Code Changes:** Specific diffs with file paths
**Files Modified:** List of changed files
**Assumptions Made:** Things to verify
**Open Questions:** Remaining uncertainties

---

Troubleshooting

Issue	Cause	Solution
command not found: opencode	OpenCode binary not found	Reinstall: npm install -g claude-sidecar (opencode-ai is bundled)
401 Unauthorized / auth errors	API key missing or wrong provider prefix	Run sidecar setup to configure keys, or verify openrouter/... prefix matches your credentials
Headless stalls silently	Chat agent in headless mode	Use --agent build, not --agent chat in headless mode
Session not found	No matching session ID	Run sidecar list, or omit --session-id to use most recent
No conversation history found	Project path encoding	Check ls ~/.claude/projects/. / and _ are encoded as - in path
Headless timeout	Task too complex for default timeout	Increase with --timeout 30
Summary corrupted	Debug output leaking to stdout	Use LOG_LEVEL=debug to diagnose
Multiple active sessions	Ambiguous session resolution	Pass --session-id explicitly
Setup wizard won't open	Electron not available	Falls back to terminal setup automatically; ensure electron is in dependencies

Debug logging:

LOG_LEVEL=debug sidecar start --model gemini --prompt "test" --no-ui

---

Documentation

Doc	Description
SKILL.md	Complete skill reference for Claude Code
Electron Testing	Chrome DevTools Protocol patterns for UI testing
Agentic Evals	End-to-end eval system for testing LLM interactions with sidecar

---

Contributing

Contributions are welcome!

git clone https://github.com/jrenaldi79/claude-sidecar.git
cd claude-sidecar
npm install
npm test

Autonomous UI Testing via Chrome DevTools Protocol

Sidecar uses a novel approach for testing Electron UI features: instead of fragile DOM mock tests, we verify the real UI by connecting to the running Electron app via the Chrome DevTools Protocol (CDP).

How it works:

1. Launch sidecar with SIDECAR_DEBUG_PORT=9223 (avoids conflict with Chrome on 9222)
2. Use SIDECAR_MOCK_UPDATE=available or other mock env vars to force specific UI states
3. Connect to http://127.0.0.1:9223/json to discover debug targets
4. Execute JavaScript in the Electron renderer via WebSocket to inspect DOM state
5. Take a screenshot with screencapture to visually verify

# Launch with mock update banner and debug port
SIDECAR_MOCK_UPDATE=available SIDECAR_DEBUG_PORT=9223 \
  sidecar start --model gemini --prompt "test"

# Find the toolbar page
TOOLBAR_ID=$(curl -s http://127.0.0.1:9223/json | \
  node -e "const d=require('fs').readFileSync(0,'utf8'); \
  const p=JSON.parse(d).find(p=>p.url?.startsWith('data:')); \
  console.log(p?.id||'NOT_FOUND')")

# Inspect toolbar state (update banner, buttons, timer)
node -e "
const WebSocket = require('ws');
const ws = new WebSocket('ws://127.0.0.1:9223/devtools/page/$TOOLBAR_ID');
ws.on('open', () => ws.send(JSON.stringify({
  id: 1, method: 'Runtime.evaluate',
  params: { expression: '({banner: document.getElementById(\"update-banner\")?.style?.display, text: document.getElementById(\"update-text\")?.textContent})', returnByValue: true }
})));
ws.on('message', d => { const m=JSON.parse(d.toString()); if(m.id===1){console.log(JSON.stringify(m.result?.result?.value,null,2));ws.close();process.exit(0);} });
setTimeout(() => { ws.close(); process.exit(0); }, 3000);
"

This approach tests real rendering in a real Electron window, not mocked DOM behavior. See docs/electron-testing.md for the full reference.

---

Built On

Sidecar is a harness built on top of OpenCode, the open-source AI coding engine. OpenCode provides the conversation runtime, tool execution framework, agent system, and web UI. Sidecar adds context sharing from Claude Code, the Electron shell, fold/summary workflow, session persistence, and multi-client support (CLI, MCP, Cowork). We don't reinvent the wheel. OpenCode handles the hard parts of LLM interaction so Sidecar can focus on the parallel-window workflow.

---

License

MIT. John Renaldi