paste the install prompt into the coding agent you already have open and it does the rest. prefer to type it yourself:

npm install -g crosscode-cli

works with the agent you already run

[!IMPORTANT] crosscode-cli installs from npm, and the sync engine underneath it (the shadow ref, the three-way merge, hot-file deferral, offline catch-up) is built and tested. the pre-edit hook registers the command that runs, and the daemon notices a commit or a pull on the branch you are already on.

syncing is opt-in per checkout and covers tracked files on the branch you are sharing. those files are relayed by the hosted service rather than encrypted end to end, which docs/privacy.md spells out in full. PLAN.md tracks what is done.

how it works

you both work in ordinary git checkouts. a small background daemon per checkout notices an edit once it settles, sends that one file to whoever is on the same branch, and applies theirs to your working tree the same way. commits, branches, and pushes stay pure git. crosscode only ever touches uncommitted working-tree files, and never a file you or your agent touched in the last few seconds.

the only interruption is the case that genuinely needs a decision: you both changed the same lines of the same file. that goes to your own coding agent, with the three sides of the merge, and your agent fixes it. crosscode never judges the change, classifies risk, or reviews code. it delivers the right information at the right moment, and your agent does the work.

there is no web app, no dashboard, and no ui. five cli commands, four mcp tools, one skill, installed in two places so that whichever agent you run reads it.

features

silent by default

an edit that lands cleanly is written to your working tree with no prompt, no diff, and no notification. that is roughly 95% of real use.

conflicts go to your agent

same-line collisions arrive as ours / theirs / ancestor on your own coding agent, which merges them without being asked.

docs →

pure git underneath

one ref, refs/crosscode/shadow, holds the last agreed state. HEAD never moves, and nothing shows up in git log.

docs →

one-command undo

everything crosscode writes is reversible with git checkout refs/crosscode/shadow -- <path>.

docs →

mcp native

a standard stdio mcp server, so there is no editor extension to install. claude code and codex also get a pre-edit hook.

docs → · mcp.so →

secrets never move

dropped before capture, even when git tracks them: .env* and .envrc/.npmrc/.netrc/ .pgpass/.htpasswd/.pypirc/.dockercfg/.git-credentials; .aws/, .ssh/, .kube/, .gnupg/; id_rsa and friends; *.pem/*.key/*.p8/*.p12/*.pfx/*.jks/ *.keystore/*.keytab/*.kdbx/*.ovpn/*.gpg/*.asc; anything with credentials or secrets in a path segment, *service-account*.json, kubeconfig; *.tfvars and *.tfstate. the patterns are anchored to path segments and extensions so ordinary source keeps syncing, and the full list is SECRET_PATH_PATTERNS. untracked files are never sent.

docs →

survives the network

the daemon keeps capturing offline and catches up from its cursor. history is kept about 7 days; past that a replica resyncs from full content.

docs →

two-line onboarding

crosscode invite prints a link. the join page checks the invitee actually has repo access, then hands them a git clone and a crosscode join.

docs →

quickstart

hand the setup to the agent you already have open. paste the install prompt into claude code, codex cli, opencode, cursor, or any mcp-capable agent: it installs the cli, runs crosscode start in the checkout, and wires up its own mcp config. 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.

or run the same thing yourself:

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

the published package is crosscode-cli, which ships both 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, the matching block in AGENTS.md for agents that read that instead of a skill, and the pre-edit hooks for your coding agent. restart your agent afterwards so it picks up the new mcp server.

sign-in prints a url and a short confirmation code and waits. you open the url, sign in with github, and enter the code; there is no callback server listening on your machine and nothing to paste back into the terminal. on a remote shell, --no-browser prints the url instead of opening one.

to bring a teammate in:

crosscode invite          # prints https://www.getcrosscode.dev/join/7f3a9c2e

they open the link, sign in with github, and the page gives them two lines to paste:

git clone [email protected]:acme/app.git && cd app
crosscode join CC-7F3A-9C2E

that is the entire onboarding budget. from there, both checkouts are in sync.

the other two commands, and that is all of them:

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

mcp server configuration

crosscode start writes this for you. to add it by hand, put it in .mcp.json at the checkout root (claude code), .cursor/mcp.json (cursor), or .gemini/settings.json (gemini cli):

{
  "mcpServers": {
    "crosscode": {
      "command": "crosscode-mcp",
      "args": []
    }
  }
}

the server speaks mcp over stdio and discovers the checkout from its working directory, so launch it with cwd set to the checkout root. codex cli's config is toml, and opencode uses its own shape; both are in mcp clients and hooks.

tools

four, and there will not be a fifth.

| tool | what it does | | --- | --- | | status | sync status for this checkout: branch, connected, paused, and who else is working on what. read-only. | | conflicts | list unresolved sync conflicts, each with the ours/theirs/ancestor text for a 3-way merge. | | resolve | resolve one conflict with your merged file content, written to disk and republished to the team. | | pause | pause or resume syncing for this checkout, for a rebase, bisect, or bulk rewrite. |

every response from every tool also carries any pending conflicts, whether it was asked for them or not: a summary of each, which file and since when, with the merge text one conflicts call away. the full catalog, with input and output schemas, is in mcp clients and hooks.

what syncs, and what never does

only the files you sync ever leave the room: tracked files you edit on the branch you are sharing, minus a hard denylist. untracked files stay put, and your commits, branches, index, stash, and remotes are never touched, so nothing crosscode does pushes to a remote. if you stop crosscode or remove it, your repository is an ordinary git repository, exactly as it was.

those files are relayed by the hosted coordination service rather than encrypted end to end, so someone with production access could read them. docs/privacy.md lists exactly what the service stores and for how long, and docs/security.md has the threat model.

the apply rule

one git ref does most of the work. refs/crosscode/shadow points at a commit whose tree is the last state both sides agreed on. from that one ref come the merge base, "have i edited this since we synced?", undo, and content storage in git's own object store.

the sync unit is one file: { path, op, baseHash, contentHash, content-or-patch }. no bundles, no lifecycle, no accept or reject. for an incoming change to path P, where L is your disk and S is the shadow:

1. L == S and the sender built from S: write it, silently.
2. otherwise, 3-way merge against the sender's base. clean means write it silently. a conflict is surfaced to your agent.
3. only if that base blob is genuinely missing, catch up from the cursor and retry.

binaries are never merged, so concurrent binary edits are always a conflict. a conflicted path is quarantined, neither published nor applied, until it is resolved.

rules that keep it invisible:

• never write a file you or your agent touched in the last ~10 seconds.
• never sync during a rebase, merge, or bisect. pause, then resync.
• same branch only. different branches means you did not want to sync.
• everything is undoable with one command.

more in architecture and protocol.

pricing

everything is free, permanently. the cli is mit licensed and the hosted service costs nothing: no paid plans, no tiers, no seats, no usage limits, no trial that ends, and no payment details collected. see docs/terms.md.

what your agent sees

four mcp tools, status, conflicts, resolve, and pause, plus one skill that says how to use them and, mostly, when to leave them alone. claude code reads that skill from .claude/skills/crosscode/; codex cli, cursor, opencode, and gemini cli read the same text from the crosscode block start writes into AGENTS.md.

every response from every tool carries any pending conflicts, whether the tool was asked for them or not. that is deliberate. an agent only looks at anything when it is invoked, so a conflict that arrives while it is idle would otherwise sit unseen. this way it trips over one the next time it does anything at all. what rides along is the summary, so an unrelated call never drags whole files into the agent's context; the ours/theirs/ancestor text is one conflicts call away, at the moment the agent actually merges. claude code and codex additionally get a hook that runs before a file edit, which moves that moment earlier still: a conflict on a file is known before the agent writes over it rather than after. the hook is a bonus on top of mcp, not a requirement, and every other client relies on the piggybacked conflicts alone.

the bar this is built to: neither side's agent mentions crosscode until a real conflict, which the receiving agent then resolves without being asked. see skills/crosscode/SKILL.md for what the agent is told. that file is the only copy there is: start installs it verbatim as the skill and, with the frontmatter stripped, as the AGENTS.md block, and a test fails if the three drift apart.

what crosscode is not

no accept-or-reject step on incoming work, no tasks, claims, or handoffs, no hidden snapshot layer, no validation profiles, no risk classification, no ai reviewer, no seats, no web app, no tui. we built all of that once, which is how we learned to stop.

developing

pnpm install
pnpm build          # typecheck + bundle
pnpm test           # vitest

layout: packages/protocol (the wire contract), packages/sync (the apply rule, shadow ref, and 3-way merge), packages/git (the git plumbing it runs on), packages/core (the denylist and hashing), apps/daemon (per-checkout sync), apps/service (the hosted coordination service), apps/cli (five commands), apps/mcp-server (four tools and the pre-edit hook), skills/crosscode (the agent skill), apps/docs-site (landing page and these docs).

want to contribute? see CONTRIBUTING.md. PLAN.md is the only plan document in this repository, and spike/ holds a throwaway proof of the merge core outside the build.

docs: architecture · protocol · mcp clients and hooks · onboarding contracts · install prompt · security · privacy · observability · terms · support

community and support

• issues: missing something, or hit a bug? open an issue.
• security: report vulnerabilities privately per SECURITY.md, never in a public issue.
• privacy: docs/privacy.md lists everything the service can see.
• show support: star this repo to follow along.

license

crosscode is free and open source under the mit license.

trademark

the mit license covers the code. it does not cover the name "crosscode" or the logos in assets/. fork it, ship it, write about it. just don't present a modified version as crosscode itself. TRADEMARK.md has the details, and [email protected] handles anything it doesn't cover.