Docs

Commands grouped by what they do. Run sidekar help or sidekar help <command> for the full flag list.

Quickstart

Install

curl -fsSL https://sidekar.dev/install | sh

Wrap an agent

sidekar claude
sidekar codex

Run Sidekar directly

sidekar repl -c claude -m claude-sonnet-4-20250514

Optional device login

sidekar device login

Runtime

Sidekar is a sidecar binary plus a skill file. It is not an orchestrator or agent OS. You either wrap an existing agent CLI, or run Sidekar as the agent in the REPL.

  • PTY wrapper: sidekar <agent> [args] runs Claude Code, Codex, Cursor, Gemini CLI, and others with bus registration, browser hooks, and optional relay.
  • REPL: sidekar repl is Sidekar's own agent loop with sessions, slash commands, and built-in tools.

Use PTY mode when

  • You already use an external agent CLI and want Sidekar around it.
  • You need relay or web-terminal support on that wrapped process.

Use REPL mode when

  • You want Sidekar itself to drive the conversation.
  • You want slash commands like /model, /session, /compact, /relay, and /proxy.

PTY flags

sidekar claude --proxy          # MITM capture (see Proxy)
sidekar codex --relay           # web terminal tunnel
sidekar gemini --no-relay

REPL

sidekar repl -c claude -m claude-sonnet-4-20250514
sidekar repl -r                  # resume latest session
sidekar repl -p "summarize repo" # single-turn

Skill install

The install script runs sidekar install, which drops SKILL.md into detected agent skill directories. You can rerun it anytime.

sidekar install
sidekar skill

Communication

Local agent bus backed by SQLite on your machine. No account required.

Note: registering on the bus is not the same as owning a Chrome/CDP session. PTY and REPL agents show up on the bus; browser tabs are tracked separately.

sidekar bus who
sidekar bus send claude-2 "Please review the PR"
sidekar bus done qa-bot "LGTM" "Ship it"
sidekar bus requests --status=open
sidekar bus replies --msg-id=msg_123

Relay

Remote session bridge through relay.sidekar.dev. Requires sidekar device login. Everything else in Sidekar works offline; relay is the main cloud-backed runtime feature.

  • Streams PTY I/O to a web terminal. Your local terminal stays in control.
  • Lists active sessions on the dashboard and sessions page.
  • Can fan out bus messages when agents run on different machines.

Turn it on

sidekar device login
sidekar claude --relay
sidekar repl --relay
sidekar config set relay on

In the REPL, toggle with /relay on or /relay off.

Web terminal flow

Sign in at sidekar.dev, open the dashboard or sessions list, and attach to a running session. The relay mirrors what your local PTY shows; it does not replace it.

Manage authorized machines at /devices. Optional Telegram and Slack hooks live in settings. Session metadata goes to the relay; see the privacy policy for what that includes.

Proxy (MITM)

Local HTTPS capture of traffic between an agent and its LLM API. Rows land in ~/.sidekar/sidekar.sqlite3, table proxy_log. For debugging on your own machine, not a hosted service.

sidekar claude --proxy
sidekar repl --proxy
# REPL: /proxy on | /proxy off

sidekar proxy log
sidekar proxy show 1685
sidekar proxy clear

Entries older than seven days are pruned automatically. With the daemon running, you can also browse traces at http://127.0.0.1:21517 (localhost only).

Browser

Chrome automation through CDP. CLI commands are grouped as Browser, Page, Interact, and Data, but it is one surface.

Start or attach

sidekar launch
sidekar connect
sidekar navigate https://example.com
sidekar tabs
sidekar new-tab https://news.ycombinator.com

Pick a read surface

  • sidekar read: articles, docs, search results (reader mode).
  • sidekar text: full page text plus numbered refs for clicking.
  • sidekar observe: actionable elements rendered as commands.
  • sidekar ax-tree -i: flat interactive list with ref numbers.
  • sidekar dom: HTML structure when you need selectors, not prose.

Common interaction flow

sidekar text
sidekar click 12
sidekar type "#email" "me@example.com"
sidekar fill "#email" "me@example.com" "#password" "secret"
sidekar wait-for "button[type=submit]"
sidekar screenshot --full

Inspect state

sidekar console
sidekar network capture 10
sidekar cookies
sidekar storage get
sidekar viewport desktop

Research shortcuts

sidekar search "rust async programming"
sidekar read-urls https://example.com https://example.org

Extension

Use CDP for most browser work. Reach for the Chrome extension when you need your everyday profile, browsing history, in-page context, or DOM watchers.

  • CDP first for launches, clicks, and reads in an automation profile.
  • sidekar ext when the extension bridge fits better than raw CDP.
sidekar ext tabs
sidekar ext read
sidekar ext context
sidekar ext history "terraform vpc"
sidekar ext watch "span.notification-count"

Install steps and trust model: extension page.

Desktop

macOS only. Native UI through the Accessibility API.

sidekar desktop apps
sidekar desktop screenshot --app Safari
sidekar desktop click --app Finder "New Folder"
sidekar desktop press Meta+Space
sidekar desktop type "hello world"

Background

Jobs that outlive the current prompt.

sidekar monitor start all
sidekar cron list
sidekar cron create "0 9 * * *" --prompt="check deployment status"
sidekar loop 10m "summarize recent errors" --once

monitor watches tab title and favicon changes. cron runs scheduled tools or prompts. loop is a shorthand for recurring prompt jobs.

Tools

Project context stored locally in SQLite. No account required.

Memory

Explicit entries you or an agent write. Searchable and scoped by project.

sidekar memory write convention "Use Readability.js before scraping"
sidekar memory search readability
sidekar memory context

Tasks

sidekar tasks add "Ship task graph" --priority=2
sidekar tasks list --ready
sidekar tasks depend 12 8
sidekar tasks show 12

Journal

Automatic REPL session summaries written after idle time. Good for recall inside a session; use memory when you want something durable across sessions. Toggle with /journal in the REPL.

sidekar journal list
sidekar journal show 42

Repo

sidekar repo tree
sidekar repo pack

Compact

Shrink noisy shell output before it hits the model context.

sidekar compact run cargo test
cargo test 2>&1 | sidekar compact filter cargo test

Secrets

Encrypted KV and TOTP on disk. Device login unlocks full encryption.

sidekar device login
sidekar kv set github_token abc123
sidekar kv get github_token
sidekar kv list
sidekar totp add github alice JBSWY3DPEHPK3PXP
sidekar totp get github alice

System

sidekar daemon status
sidekar config
sidekar event list --level=error 100
sidekar skill
sidekar install
sidekar update

The daemon holds the CDP pool, extension bridge, and a local web UI at 127.0.0.1:21517 for SQLite browsing and proxy traces.

Per-command help

This page is an index. For exact syntax on any command, run sidekar help and sidekar help <command>.