Docs

Quickstart

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

sidekar claude
sidekar codex

sidekar repl -c claude -m claude-sonnet-5-5

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-5-5
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

Two classes of participant

The bus is two-way: replies to your messages arrive in your own inbox, under the name you sent as. How they arrive depends on where you run.

• Hosted. A PTY agent (sidekar <agent>), the REPL, and agents started with sidekar spawn. Sidekar owns the runtime, delivers a message into the agent's loop, and wakes it. Nothing to poll.
• External. An agent in another harness, with no Sidekar runtime around it. Sidekar can only leave a message in its mailbox, so the agent is pull-only: it reads its own inbox, in its own turn, or replies sit unseen.

External agents must read their inbox

Register a name as a parked mailbox, then read it in your own turn, act on each message, and report the result in your own chat, all in the same run, at least once a minute or the shortest cadence your harness allows. A read consumes what it prints, so a background job that only logs mail is not a watch: the mail lands in that job's output and your next read finds nothing.

sidekar bus register me --ttl 1h        # prints the token file path
T=~/.sidekar/mailboxes/me.<id>.token    # the path register printed

# each turn, in your own chat: read, act, report
sidekar bus inbox me --token-file "$T"

# for each message: do what it asks, then answer it
sidekar bus send --as me --token-file "$T" claude-2 "LGTM" --reply-to=<id>

sidekar bus register prints these steps on every first registration, and sidekar bus --help states them. For a harness with a scheduler (a watch run, a bot tick), that scheduled turn is the read. A hosted session is delivered to by Sidekar itself and needs no loop.

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 an agent's terminal to a web terminal, both ways: from sidekar.dev you can watch it and type into it, under the relay's access rules.
• Lists active sessions on the sessions page (the dashboard counts them).
• Can fan out bus messages when agents run on different machines.

Turn it on

Signed in, it is on by default (relay auto): sidekar claude, the REPL and spawn open a tunnel. --no-relay turns it off for one agent, sidekar config set relay off for all of them, and relay on also reports a missing sign-in.

sidekar device login
sidekar claude            # relayed, in a session Ctrl+] detaches from
sidekar claude --no-relay
sidekar config set relay off

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

Web terminal flow

Sign in at sidekar.dev, open sessions, and pick a running session to attach to it. The page shows the same terminal as your local one, and you can type in it as well.

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.

Chat (web)

Signed in at sidekar.dev, /chat lists your devices and the agent sessions on each, and opens one as a chat: the agent's messages, its tool calls and their results, and its approval requests, as they arrive. You can send a message, allow or deny a tool call, stop the turn, end the session from the open chat or from the list, start a new agent (any program that device allows, as a chat or a terminal, in a folder it allows), or reopen a past one and continue it. /sessions can end one of your own relay sessions the same way. It needs no terminal.

• A chat is a session on the device (sidekar session new claude, or one the page starts). A running terminal session shows as a chat too, read from the agent's own transcript.
• Every command is signed in your browser with a key it keeps (sidekar device trusted lists it), and the device checks the signature before it acts. Your own devices accept your browser keys on their own; with remote_auto_trust_browsers off, the page shows the sidekar device trust command to run once. Commands need a sign-in from the last 24 hours; the page asks you to sign in again when it is older.
• The device's own rules still apply: which engines and folders a remote chat may use (remote_engines, remote_roots).
• A linked account's devices are listed read-only: you can read their chats, not send to them.
• An approval that waits while the tab is in the background can show a browser notification, if you allow them.
• Nothing of a chat is stored on sidekar.dev: the list and the history live on the device, and only an audit row (sizes and hashes, never text) passes through.

On the machine itself, sidekar daemon web opens the local portal, whose Agents view does the same for this machine's agents without signing in to sidekar.dev: a chat for a claude or codex session, and an attached terminal for a terminal session.

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 them in the local web portal: sidekar daemon web opens it and prints the code to sign in with.

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 browser ext when the extension bridge fits better than raw CDP.

sidekar browser ext status
sidekar browser ext tabs
sidekar browser ext read
sidekar browser ext context
sidekar browser ext history "terraform vpc"
sidekar browser ext watch "span.notification-count"

The installer unpacks the extension into ~/.sidekar/extension. Load that folder in Chrome with Load unpacked, then sign in from its popup. Full 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

Vault (web)

Signed in at sidekar.dev, /vault shows what your machines sync: kv entries (names, tags, values), TOTP codes, memory, and the agents and in-flight messages on the cross-machine bus. Use it to look up a password or a current code from any browser while you sign in somewhere.

• Records are stored on sidekar.dev as AES-256-GCM ciphertext and decrypted in your browser tab with WebCrypto. Values never appear in a server response, log or cache in plaintext; every vault response is Cache-Control: no-store.
• Lists and memory need a session. A kv value or TOTP code needs a sign-in from the last 10 minutes; the page asks you to sign in again when it is older. Each one revealed is recorded under the page's Activity tab with time, IP and browser. Approving a new machine at /approve (sidekar device login) needs a recent sign-in too, since a machine's token can read every synced secret.
• Values hide again after 30 seconds, TOTP codes stop after two minutes.
• You can add a secret (name, value, tags), change or delete one, and add or delete a TOTP entry, from a computer or a phone: paste the setup key a site shows (any case, spaces or dashes) or scan or upload its QR code. It works like a memory edit: the same recent sign-in, encrypted in your browser with your account key, and every signed-in machine gets it the next time it runs sidekar, as sidekar kv list and sidekar totp list show. Nothing needs setting up first. If the entry changed on a machine since the page loaded, nothing is saved and the page asks you to reload. Names sidekar keeps for itself (oauth:, internal:, duo:, auth: and the default tokens) are changed only by sidekar. Each change is recorded under Activity (kind and name, never the value).
• Memories on your own account can be edited (text, type, scope, project, tags) or deleted, after the same recent sign-in. The page re-encrypts an edit in your browser and sends only ciphertext; each machine picks up the change, or removes a deleted memory, the next time it syncs, as it would from another machine's sidekar memory command. If the memory changed elsewhere since the page loaded, nothing is saved and the page asks you to reload. Each edit and delete is recorded under Activity (which memory, never its text).
• What it does not protect against: sidekar.dev holds your account key (it is what lets a new machine sign in and read its secrets), so anyone in control of the server or its database could decrypt your records. A linked account's secrets are not stored on sidekar.dev: revealing one asks the owner's machine through the relay, and the value passes through sidekar.dev and the relay in memory only. HOTP codes are taken with sidekar totp get, since each one advances a counter.

System

sidekar daemon status
sidekar config
sidekar event list --level=error 100
sidekar report --area=calendar "create has no location option"
sidekar skill
sidekar install
sidekar update

The daemon holds the CDP pool, extension bridge, and a local web portal on 127.0.0.1:21517 (or the next free port) for SQLite browsing, proxy traces, prompts, KV and TOTP. Open it with sidekar daemon web, which prints a one-time sign-in code to type into the page (it never goes in the URL, so no other process can read it from a command line). Only your OS user can use the portal: every API call needs the daemon's access token, regenerated at each start in ~/.sidekar/portal.token (mode 0600), and requests naming any host but 127.0.0.1 or localhost are refused.