sidecar

Sidecar is a child repo — not a submodule — for your repo. Gitignored, shared, auto-synced, and never a merge conflict: give your agents a scratchpad that's always up to date.

your-repo/
  |-- .sidecar        # committed config (points at the sidecar remote)
  |-- sidecar/        # gitignored, shared, auto-synced, no merge conflicts

Your agents' planning docs, research notes, and context files don't belong in your code's history. They shouldn't reset when you switch branches or worktrees, and the latest version is the only one that matters. sidecar keeps them in a separate git repo that lives inside your working tree, while a background daemon keeps every clone in sync.

• It's just git. The scratchpad is a normal repo you own — clone it, grep it, read it on GitHub, build your own extensions with git hooks.
• Zero merge conflicts. Each machine writes to its own inbox branch; sidecar merges them so a sync never stops you to resolve anything.
• Zero ceremony. The daemon watches for changes and syncs automatically. You never commit, pull, or push it by hand.
• Found by default. It lives inside your working tree, so agents and tools pick it up with no configuration at all.
• Secrets stay home. Pasted API keys and tokens are redacted from pushes while your local files stay untouched; PII redaction is one flag away — how redaction works.

Quickstart

Requires Node.js 20+ and git, on macOS or Linux. (Windows is coming soon.)

npm install -g sidecarsync
cd ~/dev/your-repo
sidecar init

That's it. If the repo already has a committed .sidecar file, init joins the existing sidecar. If not, init walks you through it — pick where the checkout lives, then paste a remote URL, or leave it blank and init creates a private repo for you with the GitHub CLI (gh).

The daemon takes it from here. sidecar status shows what's happening; sidecar sync forces a sync right now. Once a second machine joins, sidecar health shows whether all of them are still syncing — a sync can fail on one laptop for reasons the others would otherwise never hear about.

Standalone repos

Some repos have no parent — a dotfiles or machine-setup repo you keep on every machine, that wants auto-sync for its own sake. Answer . when init asks for the checkout path (or pass --path .) and the repo becomes its own sidecar, syncing to its own remote:

cd ~/dev/setup
sidecar init --path .

Sidecar takes over branch management there — how standalone works.

Peers

A repo can carry more than one sidecar. .sidecar is the default; every .sidecar.<name> beside it is another, with its own remote and checkout, and the two never interact — so one can be committed for the team while another is gitignored and yours alone:

sidecar init [email protected]:you/your-repo-private.git --peer private --ignored

Every command acts on all peers unless --peer names one — how peers work.

Learn more

• Agent guide and Sidecar skill — peer selection, handoffs, sync, and environment variables
• How syncing works — the daemon, inbox branches, conflict-free merging
• Standalone repos — a repo that is its own sidecar
• Peers — several sidecars in one repo, one committed and one ignored
• Per-file rules — glob-based merge and redaction policy for each peer
• Redaction — what's stripped from pushes and how to review it
• Editor search visibility — making gitignored files searchable
• Global vs local installs — the newest install wins
• All commands
• Uninstall & troubleshooting — removing the daemon, service, and state

Inspiration

• hunk
• plannotator
• jujutsu