install & quickstart

one command sets up a checkout end to end. everything below happens in the repository you actually want to work on.

prerequisites

• node.js 24 or newer
• git, and a checkout of the repository you want to sync
• a github account with access to that repository

install and start

npm install -g crosscode-cli
cd your-repo
crosscode start

the package is crosscode-cli on npm. it installs two binaries: crosscode, the cli, and crosscode-mcp, the mcp server and pre-edit hook.

crosscode start does the whole setup and is safe to re-run. it signs you in with github, attaches this checkout to a project, starts the background daemon, and installs the mcp server, the crosscode skill, and the pre-edit hooks for your coding agent.

sign-in is a device-code handshake: it prints a url and a short confirmation code, opens the url, and waits. you sign in with github and type the code into the page. nothing listens on your machine and nothing is pasted back into the terminal, so the browser does not have to be on the same machine. pass --no-browser on a remote shell or in ci to print the url instead of opening one.

restart your coding agent afterwards, or reconnect its mcp servers, so it picks up the new crosscode server.

bring in a teammate

crosscode invite

that prints a link. they open it, sign in with github, and the page checks they actually have access to the repository before giving them two lines to paste:

git clone git@github.com:acme/app.git && cd app
crosscode join CC-7F3A-9C2E

join redeems the code and then sets the checkout up exactly as start would. that is the entire onboarding. from there both checkouts are in sync.

day to day

nothing. that is the intended experience: edits move between checkouts on their own, and a conflict goes to your coding agent rather than to you. the two remaining commands exist for when you want to look:

crosscode status     # branch, connected, paused, who else is on this branch
crosscode stop       # stop syncing this checkout

what syncs

• tracked files only. untracked files are never sent
• never .env*, *.pem, *.key, or anything else credential-shaped, even when git tracks it
• only within one project and one branch name. different branches do not sync
• never a file you or your agent touched in the last ten seconds

your commits, branches, index, stash, and remotes are never touched, and nothing here pushes. to undo anything crosscode wrote:

git checkout refs/crosscode/shadow -- <path>

hand the setup to your agent

there is a ready-made prompt that runs the same steps and wires up the mcp config itself. paste the install prompt into claude code, codex cli, opencode, cursor, or any mcp-capable agent. codex cli's config is toml and start does not write it, so codex users add a three-line entry by hand: see mcp client setup.

running from a clone

for working on crosscode itself, or for running the cli before it is on npm:

pnpm install
pnpm build          # typecheck + bundle
pnpm test           # vitest
pnpm crosscode -- status --json

contribution setup, the workspace layout, and the postgres-backed test path are in CONTRIBUTING.md.