# sidekar - Full Reference

> A sidecar binary and skill for agent CLIs. Wrap existing agent CLIs or run Sidekar as its own REPL agent. Not an orchestrator, harness, or agent OS.

## What is sidekar?

sidekar gives agents browser and desktop control, a local message bus, background jobs, encrypted secrets, optional remote relay, and local MITM debugging. Install with `curl -fsSL sidekar.dev/install | sh`. That downloads the binary and runs `sidekar install` to add `SKILL.md` to each detected agent skills directory.

Most features run locally. Relay (web terminal, session registry) requires `sidekar device login` and talks to `relay.sidekar.dev`.

## Install

```sh
curl -fsSL sidekar.dev/install | sh
```

## Getting started

1. **Install:** run the curl command above (binary + `sidekar install` for skills).
2. **Launch an agent:** `sidekar <agent> [args…]` for any agent CLI on PATH (e.g. `sidekar claude`, `sidekar codex`).
3. **Or REPL:** `sidekar repl -c <credential> -m <model>`.
4. **Device login (optional):** auth against sidekar.dev for relay, encrypted secrets, dashboard.
5. **Chrome extension (optional):** load from `extension/`, sign in from popup, then `sidekar ext ...`.

## Components

### Runtime (PTY wrapper + REPL)

**PTY:** `sidekar <agent> [args]` wraps claude, codex, copilot, cursor (cursor-agent), gemini, grok, opencode, pi. Registers on the bus, wires browser integration, optional `--relay` and `--proxy`.

**REPL:** `sidekar repl` is Sidekar's own agent loop. Session persistence, slash commands (`/model`, `/session`, `/compact`, `/relay`, `/proxy`, `/journal`).

Use PTY when you keep your existing agent CLI. Use REPL when Sidekar should drive the conversation.

**Skill:** `sidekar install` / `sidekar skill`.

### Communication (local bus)

SQLite-backed broker on the machine. Agents discover and message each other without cloud dependency.

**Commands:** `bus who`, `bus send`, `bus done`, `bus requests`, `bus replies`

**Message kinds:** request (expects response, nudges until replied), response, fyi (informational, tagged `[no reply needed]`). Plain `bus send` defaults to request; closing acks ("ok", "done") auto-downgrade to fyi.

**Note:** bus registration is separate from Chrome/CDP session ownership.

### Relay (remote sessions)

WebSocket bridge to `relay.sidekar.dev`. Requires device login. Multiplexes PTY I/O to a web terminal; local terminal stays authoritative. Session metadata on sidekar.dev dashboard and sessions page. Cross-device bus fan-out when agents run on different machines.

**Commands:** `device login`, `--relay`, `config set relay on/off`, REPL `/relay on|off`

### Proxy (MITM)

Local HTTPS capture of agent-to-LLM API traffic into `~/.sidekar/sidekar.sqlite3` table `proxy_log`. For debugging, not surveillance. Seven-day automatic prune.

**PTY/REPL:** `--proxy`, REPL `/proxy on|off`

**CLI:** `sidekar proxy log`, `proxy show <id>`, `proxy clear`

**Local UI:** daemon serves traces at `http://127.0.0.1:21517` (localhost only).

### Browser (CDP + extension)

Full Chrome DevTools Protocol. Navigate, click, type, screenshot, read page content. Optional Chrome extension for everyday profiles and history.

**Web search and multi-page reads** (`search`, `read-urls`) and **batch** (multi-step sequences) are use cases on this stack.

**Key tools:** navigate, read, text, ax-tree, observe, dom, screenshot, click, type, fill, press, scroll, keyboard, search, read-urls, batch

**batch** example:
```json
{"actions": [
  {"tool": "click", "target": "--text Continue", "retries": 2},
  {"tool": "wait-for-nav"},
  {"tool": "screenshot"}
]}
```

**Perception escalation order (stop at the first that works):**
1. `read` - Reader-mode text (articles, docs, search results). Low cost.
2. `ax-tree -i` / `observe` - Interactive elements with ref numbers. Low cost.
3. `text` - Full page text with refs. Low-medium cost.
4. `dom` - HTML structure with selectors. Medium cost.
5. `screenshot` (cropped) - Visual of one element. Medium cost.
6. `screenshot` (full page) - Full visual. High cost.

**Element targeting priority:**
1. Refs from ax-tree/observe/text (click 3, type 5 hello)
2. Text search (click --text Submit)
3. CSS selectors (#id, [data-testid="..."])
4. eval with querySelector
5. Coordinates from screenshot (last resort)

**Extension (`sidekar ext`):** tabs, read, context, history, watch. Use when CDP alone is not enough. See sidekar.dev/extension.

### Desktop (macOS)

Accessibility API for native apps, windows, clicks, keys, screenshots outside the browser.

**Key tools:** desktop_screenshot, desktop_apps, desktop_windows, desktop_find, desktop_click, desktop_launch, desktop_activate, desktop_quit

### Background

Tab monitoring (title/favicon changes), cron-scheduled tool runs, recurring prompt loops. Results delivered via the bus.

**Key tools:** monitor start/stop/status, cron create/list/delete, loop

### Tools

**Memory:** explicit durable entries (`memory write`, `search`, `context`).

**Tasks:** local task graph with dependencies (`tasks add/list/depend/show`).

**Journal:** automatic REPL session summaries after idle time. Inspect with `journal list/show`. Toggle `/journal` in REPL. Not a substitute for memory.

**Repo:** `repo tree`, `repo pack`.

**Compact:** token-efficient compaction of noisy shell output (`compact run/filter`).

### Secrets

Encrypted KV and TOTP. Device login unlocks encryption at rest.

**Commands:** `kv set/get/list`, `totp add/get/list`

## Tool Categories (REPL native tool)

Core tools are always available. Extended tools load on demand via `tools(action: "load", category: "<name>")`:

- **forms**: select, upload, drag, clear, focus, dialog, paste, clipboard, inserttext
- **nav**: back, forward, reload, wait-for, wait-for-nav, find, resolve
- **debug**: console, network, block, eval, dom, storage, cookies, sw, security
- **media**: viewport, zoom, grid, media, animations, pdf, download
- **desktop**: desktop_screenshot, desktop_apps, desktop_windows, desktop_find, desktop_click, desktop_launch, desktop_activate, desktop_quit
- **session**: hover, lock, unlock, activate, minimize, kill, monitor, frames, frame
- **meta**: config, install

## Tab Isolation

Multiple agents share the same Chrome instance. Each session owns its tabs. Never touch tabs you didn't create. Use `newtab` to open new tabs, `tabs` to list yours, `close` to remove them.

## Profiles

- `launch` - default shared profile
- `launch --profile <name>` - isolated browser instance
- `launch --profile new` - auto-generated profile ID
- `launch --headless` - no visible window
- `launch --browser brave` - use a specific browser

## Common Patterns

**Navigate and read:** Call navigate with URL. Auto-brief returned.

**Fill a form:** Use `fill` with fields object: `{"#email": "user@example.com", "#password": "secret"}`

**Search the web:** Call search with query. Results extracted automatically.

**Research multiple pages:** Call read-urls with a list of URLs. Content extracted in parallel.

**Rich text editors:** click the editor, then use keyboard (not type) to preserve cursor position.

## Supported agents

`sidekar install` writes the skill file for Claude Code, Codex, Gemini CLI, Grok, OpenCode, and Pi. `sidekar <agent>` PTY-wrapping additionally covers Copilot and Cursor. Any other agent can call the `sidekar` CLI directly.

## Pricing

- Personal: Free (all features, no limits)
- Professional: $9/month (honor system, for work that pays)

## Links

- Website: https://sidekar.dev
- Docs: https://sidekar.dev/docs
- Install: https://sidekar.dev/install
- Compact version: https://sidekar.dev/llms.txt