{"id":46787299,"url":"https://github.com/jrenaldi79/sidecar","last_synced_at":"2026-03-15T05:47:33.037Z","repository":{"id":336531084,"uuid":"1142010874","full_name":"jrenaldi79/sidecar","owner":"jrenaldi79","description":"A parallel AI window for Claude Code. Fork conversations to Gemini, GPT, DeepSeek, or any model via OpenRouter, then fold results back.","archived":false,"fork":false,"pushed_at":"2026-03-06T05:40:40.000Z","size":1067,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T09:43:15.599Z","etag":null,"topics":["claude-code","cowork","electron","fork-and-fold","llm","multi-model","opencode","openrouter","parallel","sidecar"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/claude-sidecar","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jrenaldi79.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-25T20:08:11.000Z","updated_at":"2026-03-06T05:40:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jrenaldi79/sidecar","commit_stats":null,"previous_names":["jrenaldi79/sidecar"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jrenaldi79/sidecar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrenaldi79%2Fsidecar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrenaldi79%2Fsidecar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrenaldi79%2Fsidecar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrenaldi79%2Fsidecar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jrenaldi79","download_url":"https://codeload.github.com/jrenaldi79/sidecar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrenaldi79%2Fsidecar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30314628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T20:05:46.299Z","status":"ssl_error","status_checked_at":"2026-03-09T19:57:04.425Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","cowork","electron","fork-and-fold","llm","multi-model","opencode","openrouter","parallel","sidecar"],"created_at":"2026-03-10T02:00:51.486Z","updated_at":"2026-03-15T05:47:33.030Z","avatar_url":"https://github.com/jrenaldi79.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Claude Sidecar\n\n**A parallel AI window that shares your context. Talk to any model while your main session keeps working.**\n\n![Claude Sidecar: Fork, Work, Fold](./docs/hero.png)\n\nSidecar opens a real UI alongside Claude Code or Cowork, pre-loaded with your conversation context, connected to Gemini, GPT, DeepSeek, Qwen, Grok, or any other model. You interact with the sidecar in parallel (fact-check Claude's work, get a second opinion, explore a tangent) then fold the results back when you're ready.\n\n[![Watch the demo](https://img.youtube.com/vi/Cl_RA8HAZJE/maxresdefault.jpg)](https://youtu.be/Cl_RA8HAZJE)\n\n\u003e **Supported clients:** Claude Code CLI and Claude Cowork are fully tested and supported. Claude Code web and Claude Desktop are experimental.\n\n[![npm version](https://img.shields.io/npm/v/claude-sidecar?color=D97757\u0026labelColor=1A1C29)](https://www.npmjs.com/package/claude-sidecar)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue?labelColor=1A1C29)](./LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?labelColor=1A1C29)](https://nodejs.org)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?labelColor=1A1C29)](./CONTRIBUTING.md)\n[![GitHub last commit](https://img.shields.io/github/last-commit/jrenaldi79/sidecar?labelColor=1A1C29)](https://github.com/jrenaldi79/sidecar/commits)\n[![GitHub stars](https://img.shields.io/github/stars/jrenaldi79/sidecar?style=social)](https://github.com/jrenaldi79/sidecar)\n\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n- [What Is Sidecar?](#what-is-sidecar)\n- [Use Cases](#use-cases)\n- [Getting Started](#getting-started)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [Features](#features)\n- [Commands](#commands)\n- [Agent Modes](#agent-modes)\n- [Models](#models)\n- [MCP Integration](#mcp-integration)\n- [Configuration](#configuration)\n- [Understanding Sidecar Output](#understanding-sidecar-output)\n- [Troubleshooting](#troubleshooting)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [Built On](#built-on)\n- [License](#license)\n\n---\n\n## What Is Sidecar?\n\nSidecar is a **literal second window** that runs alongside your Claude Code or Cowork session. It:\n\n1. **Shares your context.** Your current conversation history is automatically extracted and passed to the sidecar. No copy-pasting, no re-explaining.\n2. **Runs in parallel.** Your main Claude session keeps working while you interact with the sidecar. It's not sequential, it's simultaneous.\n3. **Connects to any model.** Gemini 3.1 Pro (1M context), GPT-5.4, DeepSeek v3.2, Qwen, Grok: whatever's best for the job.\n4. **Folds back cleanly.** When you're done, click FOLD and a structured summary returns to your main context. No noise, just results.\n\n![What Is Sidecar: Fork and Fold](./docs/what-is-sidecar.png)\n\n---\n\n## Use Cases\n\n### Fact-Check Claude's Work\nClaude just proposed an architecture or made a claim? Open a sidecar to a different model and verify it, with full context already loaded.\n\n### Get a Second Opinion on a Feature\nDesigning something complex? Fork the conversation to Gemini or GPT-5.4 for an independent take. Compare approaches before committing to one.\n\n### Deep-Dive Without Polluting Context\nNeed 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.\n\n### Parallel Investigation\nWhile Claude implements a fix, spin up a sidecar to review the test coverage, audit security implications, or draft documentation, all at the same time.\n\n### Leverage Model Strengths\n- **Gemini 3.1 Pro**: 1M token context for analyzing entire codebases\n- **GPT-5.4**: Strong at code generation and refactoring\n- **DeepSeek v3.2**: Cost-effective reasoning at scale\n- **Qwen 3.5**: High-quality open-weight reasoning\n- **Grok**: Fast iteration and broad knowledge\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 18+\n\n### 1. Install\n\n```bash\nnpm install -g claude-sidecar\n```\n\nOn install, sidecar automatically configures itself for all supported clients:\n- **Claude Code CLI**: Registers an MCP server and installs a Skill, so Claude can launch and manage sidecars on your behalf\n- **Claude Desktop \u0026 Cowork**: Registers an MCP server, so sidecar tools appear natively in the UI\n\nNo manual registration needed. Just install and run setup.\n\n### 2. Run Setup\n\n```bash\nsidecar setup\n```\n\nThis launches a **graphical setup wizard** that walks you through everything:\n\n| Step | What It Does |\n|------|-------------|\n| **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). |\n| **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`. |\n| **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. |\n| **4. Review** | Summary of your configuration before saving. |\n\n\u003e **Headless environments:** If Electron isn't available, the wizard falls back to a readline-based setup in the terminal.\n\nYou can also manage individual settings without re-running the full wizard:\n\n```bash\nsidecar setup --add-alias fast=openrouter/google/gemini-3.1-flash-lite-preview\n```\n\n### 3. Verify\n\n```bash\nsidecar start --model gemini --prompt \"Hello, confirm sidecar is working\"\n```\n\nA window should open alongside your editor with Gemini ready to chat, pre-loaded with your Claude Code context.\n\n---\n\n## Quick Start\n\n```bash\n# Fact-check: open a sidecar to verify Claude's approach\nsidecar start --model gemini --prompt \"Fact-check the auth approach Claude just proposed\"\n\n# Second opinion: get a different model's take\nsidecar start --model gpt --prompt \"Review this feature design. Is there a simpler approach?\"\n\n# Deep dive: investigate without polluting your main context\nsidecar start --model gemini-pro --prompt \"Analyze the entire codebase architecture\"\n\n# Headless: autonomous, no UI, summary returns automatically\nsidecar start --model gemini --prompt \"Generate Jest tests for src/utils/\" --no-ui\n\n# Use your configured default model (just omit --model)\nsidecar start --prompt \"Security review the payment module\"\n```\n\n---\n\n## How It Works\n\n1. **Context sharing.** Sidecar reads your Claude Code session from `~/.claude/projects/[project]/[session].jsonl` and passes it to the sidecar model automatically.\n2. **Window launch.** An Electron window opens alongside your editor with the sidecar UI (OpenCode-powered).\n3. **Parallel interaction.** You converse with the sidecar model while your main Claude session continues working independently.\n4. **Fold.** Click FOLD (or press `Cmd+Shift+F`) to generate a structured summary.\n5. **Context return.** The summary flows back into your Claude Code context for Claude to act on.\n\nThe 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.\n\n![Sidecar Architecture](./docs/architecture.png)\n\n---\n\n## Features\n\n### Interactive + Headless Modes\n\n**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.\n\n**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.\n\n### Context Passing\n\nYour conversation history is automatically shared with the sidecar. No re-explaining needed. Filter by turns (`--context-turns`) or time window (`--context-since 2h`).\n\n### Adaptive Personality\n\nSidecar detects its launch context and adapts:\n- **From Claude Code** (`--client code-local`): Engineering-focused (debug, implement, review)\n- **From Cowork** (`--client cowork`): General-purpose (research, analyze, write, brainstorm)\n\n### MCP Server Inheritance\n\nSidecar 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:\n\n- `--no-mcp` disables MCP inheritance entirely\n- `--exclude-mcp \u003cname\u003e` excludes specific servers (repeatable)\n- `--mcp name=url` adds additional servers\n\n### Safety Features\n\n- **Conflict detection**: Warns when files changed externally while the sidecar was running\n- **Drift awareness**: Indicates when the sidecar's context may be stale relative to your current session\n- **Pre-flight validation**: All CLI inputs are validated before anything launches\n\n### Auto-Update\n\nSidecar checks the npm registry for updates once every 24 hours (cached, zero-latency background check). When an update is available:\n\n- **CLI:** A notification box appears in your terminal after any command\n- **Electron UI:** A banner appears above the toolbar with a one-click **Update** button. No terminal commands needed.\n\nUpdating 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.\n\n```bash\n# Or update manually from the CLI\nsidecar update\n```\n\n### Session Persistence\n\nEvery sidecar is persisted. List past sessions, read their summaries, reopen them, or chain them together.\n\n```bash\nsidecar list                           # See all past sidecars\nsidecar read abc123                    # Read the summary\nsidecar resume abc123                  # Reopen the exact session\nsidecar continue abc123 --prompt \"...\" # New session building on previous findings\n```\n\n### MCP Integration\n\nFull MCP server for Claude Desktop and Cowork. Sidecar tools appear natively inside Cowork's sandboxed environment. No CLI required.\n\n---\n\n## Commands\n\n### `sidecar start`: Launch a Sidecar\n\n```bash\nsidecar start --model \u003cmodel\u003e --prompt \"\u003ctask\u003e\"\n```\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--model` | Model to use (alias or full string) | Config default |\n| `--prompt` | Task description | *(required)* |\n| `--no-ui` | Headless autonomous mode | false |\n| `--agent` | Agent mode: `chat`, `plan`, `build` | `chat` |\n| `--timeout` | Headless timeout in minutes | 15 |\n| `--context-turns N` | Max conversation turns to include | 50 |\n| `--context-since` | Time filter: `30m`, `2h`, `1d` | |\n| `--context-max-tokens N` | Context size cap | 80000 |\n| `--no-context` | Skip parent conversation context | false |\n| `--thinking` | Reasoning effort: `none` `minimal` `low` `medium` `high` `xhigh` | `medium` |\n| `--summary-length` | Output verbosity: `brief` `normal` `verbose` | `normal` |\n| `--session-id` | Explicit Claude Code session ID | Most recent |\n| `--mcp` | Add MCP server: `name=url` or `name=command` | |\n| `--mcp-config` | Path to `opencode.json` with MCP config | |\n| `--no-mcp` | Don't inherit MCP servers from parent | false |\n| `--exclude-mcp` | Exclude specific MCP server (repeatable) | |\n| `--client` | Client context: `code-local` `cowork` (`code-web` experimental) | `code-local` |\n\n### `sidecar list`: Browse Past Sessions\n\n```bash\nsidecar list                    # Current project\nsidecar list --status complete  # Completed only\nsidecar list --all              # All projects\nsidecar list --json             # JSON output\n```\n\n### `sidecar resume`: Reopen a Session\n\n```bash\nsidecar resume \u003ctask_id\u003e\n```\n\nReopens the exact OpenCode session with full conversation history preserved.\n\n### `sidecar continue`: Build on Previous Work\n\n```bash\nsidecar continue \u003ctask_id\u003e --prompt \"Now implement the fix from the analysis\"\n```\n\nStarts a **new** session with the previous session's conversation as read-only background context. Optionally switch models.\n\n### `sidecar read`: Read Session Output\n\n```bash\nsidecar read \u003ctask_id\u003e                  # Summary (default)\nsidecar read \u003ctask_id\u003e --conversation   # Full conversation\nsidecar read \u003ctask_id\u003e --metadata       # Session metadata\n```\n\n### `sidecar abort`: Stop a Running Session\n\n```bash\nsidecar abort \u003ctask_id\u003e\n```\n\nImmediately stops a running sidecar session. The session status changes to `aborted`.\n\n### `sidecar setup`: Configure Sidecar\n\n```bash\nsidecar setup                                           # Full setup wizard (GUI)\nsidecar setup --add-alias fast=openrouter/google/gemini-3.1-flash-lite-preview\n```\n\nOpens the graphical setup wizard for API keys, default model, model routing, and aliases. See [Getting Started](#2-run-setup) for details.\n\n### `sidecar update`: Update to Latest Version\n\n```bash\nsidecar update\n```\n\nUpdates sidecar to the latest npm release. In the Electron UI, click the **Update** button in the banner instead. No terminal needed.\n\n---\n\n## Agent Modes\n\nThree primary modes control what the sidecar can do autonomously:\n\n| Agent | Reads | Writes/Bash | Best For |\n|-------|-------|-------------|----------|\n| **Chat** *(default)* | Auto-approved | Asks permission | Questions, analysis, fact-checking, guided exploration |\n| **Plan** | Auto-approved | Blocked entirely | Code review, architecture analysis, security audits |\n| **Build** | Auto-approved | Auto-approved | Implementation tasks, test generation, headless batch work |\n\n```bash\n# Chat: good for fact-checking and analysis with human-in-the-loop (default)\nsidecar start --model gemini --prompt \"Verify Claude's approach to the auth refactor\"\n\n# Plan: strict read-only, no changes possible\nsidecar start --model gemini --agent Plan --prompt \"Security review of the payment module\"\n\n# Build: full autonomy, use when you explicitly want it to write code\nsidecar start --model gemini --agent Build --no-ui \\\n  --prompt \"Generate comprehensive Jest tests for src/utils/\"\n```\n\n\u003e **Headless mode note:** `--no-ui` defaults to `Build`. The `Chat` agent requires interactive UI for write permissions and stalls in headless mode.\n\n---\n\n## Models\n\n### Using Aliases (after `sidecar setup`)\n\n| Alias | Model | Notes |\n|-------|-------|-------|\n| `gemini` | Gemini 3.1 Flash Lite | Fast, cost-effective |\n| `gemini-pro` | Gemini 3.1 Pro | Deep analysis, 1M context |\n| `gpt` | GPT-5.4 | Code generation, refactoring |\n| `gpt-pro` | GPT-5.4 Pro | Extended reasoning |\n| `codex` | GPT-5.3 Codex | Code-specialized |\n| `claude` / `sonnet` | Claude Sonnet 4.6 | Balanced capability |\n| `opus` | Claude Opus 4.6 | Complex reasoning |\n| `haiku` | Claude Haiku 4.5 | Fast, lightweight |\n| `deepseek` | DeepSeek v3.2 | Cost-effective reasoning |\n| `qwen` | Qwen 3.5 397B | High-quality open-weight |\n| `qwen-coder` | Qwen 3 Coder | Code-specialized |\n| `qwen-flash` | Qwen 3.5 Flash | Fast inference |\n| `mistral` | Mistral Large | Strong European model |\n| `devstral` | Devstral | Code-focused Mistral |\n| `grok` | Grok 4.1 Fast | Fast iteration |\n| `kimi` | Kimi K2.5 | Multilingual |\n| `glm` | GLM-5 | Chinese-English bilingual |\n| `minimax` | MiniMax M2.5 | Multimodal |\n| `seed` | Seed 2.0 Mini | Lightweight |\n| *(omit `--model`)* | | Your configured default |\n\n### Using Full Model Strings\n\n| Access | Format | Example |\n|--------|--------|---------|\n| OpenRouter | `openrouter/provider/model` | `openrouter/google/gemini-3.1-pro-preview` |\n| Direct Google | `google/model` | `google/gemini-3.1-flash-lite-preview` |\n| Direct OpenAI | `openai/model` | `openai/gpt-5.4` |\n| Direct Anthropic | `anthropic/model` | `anthropic/claude-opus-4-6` |\n\nThe prefix determines which credentials are used. Model names evolve; verify current names:\n\n```bash\ncurl https://openrouter.ai/api/v1/models | jq '.data[].id' | grep -i gemini\n```\n\n---\n\n## MCP Integration\n\nFor Claude Desktop and Cowork, sidecar exposes a full MCP server auto-registered on install.\n\nTo register manually:\n```bash\nclaude mcp add-json sidecar '{\"command\":\"npx\",\"args\":[\"-y\",\"claude-sidecar@latest\",\"mcp\"]}' --scope user\n```\n\n| MCP Tool | Description |\n|----------|-------------|\n| `sidecar_start` | Spawn a sidecar (returns task ID immediately) |\n| `sidecar_status` | Poll for completion |\n| `sidecar_read` | Get results: summary, conversation, or metadata |\n| `sidecar_list` | List past sessions |\n| `sidecar_resume` | Reopen a session |\n| `sidecar_continue` | New session building on previous |\n| `sidecar_abort` | Stop a running session |\n| `sidecar_setup` | Open setup wizard |\n| `sidecar_guide` | Get usage instructions |\n\n**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.\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `OPENROUTER_API_KEY` | API key for OpenRouter (multi-model access) | *(required)* |\n| `GOOGLE_GENERATIVE_AI_API_KEY` | Direct Google API key (bypasses OpenRouter) | |\n| `OPENAI_API_KEY` | Direct OpenAI API key | |\n| `ANTHROPIC_API_KEY` | Direct Anthropic API key | |\n| `LOG_LEVEL` | Logging verbosity: `error` `warn` `info` `debug` | `error` |\n| `SIDECAR_CONFIG_DIR` | Override config directory | `~/.config/sidecar` |\n| `SIDECAR_ENV_DIR` | Override `.env` file directory | |\n| `SIDECAR_TIMEOUT` | Default headless timeout in minutes | `15` |\n| `OPENCODE_COMMAND` | Override OpenCode binary path | `opencode` |\n\nAPI keys configured via `sidecar setup` are stored in `~/.config/sidecar/.env` with restricted permissions (0600). You can also set them as environment variables directly.\n\n---\n\n## Understanding Sidecar Output\n\nEvery fold produces a structured summary:\n\n```markdown\n## Sidecar Results: [Title]\n\n**Context Age:** [How stale the context might be]\n**FILE CONFLICT WARNING** [If files changed while the sidecar ran]\n\n**Task:** What was requested\n**Findings:** Key discoveries\n**Attempted Approaches:** What was tried but didn't work\n**Recommendations:** Concrete next steps\n**Code Changes:** Specific diffs with file paths\n**Files Modified:** List of changed files\n**Assumptions Made:** Things to verify\n**Open Questions:** Remaining uncertainties\n```\n\n---\n\n## Troubleshooting\n\n| Issue | Cause | Solution |\n|-------|-------|---------|\n| `command not found: opencode` | OpenCode binary not found | Reinstall: `npm install -g claude-sidecar` (opencode-ai is bundled) |\n| 401 Unauthorized / auth errors | API key missing or wrong provider prefix | Run `sidecar setup` to configure keys, or verify `openrouter/...` prefix matches your credentials |\n| Headless stalls silently | `Chat` agent in headless mode | Use `--agent build`, not `--agent chat` in headless mode |\n| Session not found | No matching session ID | Run `sidecar list`, or omit `--session-id` to use most recent |\n| No conversation history found | Project path encoding | Check `ls ~/.claude/projects/`. `/` and `_` are encoded as `-` in path |\n| Headless timeout | Task too complex for default timeout | Increase with `--timeout 30` |\n| Summary corrupted | Debug output leaking to stdout | Use `LOG_LEVEL=debug` to diagnose |\n| Multiple active sessions | Ambiguous session resolution | Pass `--session-id` explicitly |\n| Setup wizard won't open | Electron not available | Falls back to terminal setup automatically; ensure `electron` is in dependencies |\n\n**Debug logging:**\n```bash\nLOG_LEVEL=debug sidecar start --model gemini --prompt \"test\" --no-ui\n```\n\n---\n\n## Documentation\n\n| Doc | Description |\n|-----|-------------|\n| [SKILL.md](./skill/SKILL.md) | Complete skill reference for Claude Code |\n| [Electron Testing](./docs/electron-testing.md) | Chrome DevTools Protocol patterns for UI testing |\n| [Agentic Evals](./evals/README.md) | End-to-end eval system for testing LLM interactions with sidecar |\n\n---\n\n## Contributing\n\nContributions are welcome!\n\n```bash\ngit clone https://github.com/jrenaldi79/claude-sidecar.git\ncd claude-sidecar\nnpm install\nnpm test\n```\n\n### Autonomous UI Testing via Chrome DevTools Protocol\n\nSidecar 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).\n\n**How it works:**\n\n1. Launch sidecar with `SIDECAR_DEBUG_PORT=9223` (avoids conflict with Chrome on 9222)\n2. Use `SIDECAR_MOCK_UPDATE=available` or other mock env vars to force specific UI states\n3. Connect to `http://127.0.0.1:9223/json` to discover debug targets\n4. Execute JavaScript in the Electron renderer via WebSocket to inspect DOM state\n5. Take a screenshot with `screencapture` to visually verify\n\n```bash\n# Launch with mock update banner and debug port\nSIDECAR_MOCK_UPDATE=available SIDECAR_DEBUG_PORT=9223 \\\n  sidecar start --model gemini --prompt \"test\"\n\n# Find the toolbar page\nTOOLBAR_ID=$(curl -s http://127.0.0.1:9223/json | \\\n  node -e \"const d=require('fs').readFileSync(0,'utf8'); \\\n  const p=JSON.parse(d).find(p=\u003ep.url?.startsWith('data:')); \\\n  console.log(p?.id||'NOT_FOUND')\")\n\n# Inspect toolbar state (update banner, buttons, timer)\nnode -e \"\nconst WebSocket = require('ws');\nconst ws = new WebSocket('ws://127.0.0.1:9223/devtools/page/$TOOLBAR_ID');\nws.on('open', () =\u003e ws.send(JSON.stringify({\n  id: 1, method: 'Runtime.evaluate',\n  params: { expression: '({banner: document.getElementById(\\\"update-banner\\\")?.style?.display, text: document.getElementById(\\\"update-text\\\")?.textContent})', returnByValue: true }\n})));\nws.on('message', d =\u003e { 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);} });\nsetTimeout(() =\u003e { ws.close(); process.exit(0); }, 3000);\n\"\n```\n\nThis approach tests real rendering in a real Electron window, not mocked DOM behavior. See [docs/electron-testing.md](docs/electron-testing.md) for the full reference.\n\n---\n\n## Built On\n\nSidecar is a harness built on top of [**OpenCode**](https://opencode.ai), 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.\n\n---\n\n## License\n\nMIT. [John Renaldi](https://github.com/jrenaldi79)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrenaldi79%2Fsidecar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjrenaldi79%2Fsidecar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrenaldi79%2Fsidecar/lists"}