Skip to content

Marketing readme #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
amsultan2010 merged 1 commit into from
Aug 6, 2026
Merged

Marketing readme #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
132 changes: 132 additions & 0 deletions BRIEF.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
# Workstream A — README marketing restructure

Repo: crosscode (pnpm monorepo). You are a copy/structure pass on ONE file. No code changes.

## Files (the only files you may read or edit)

- `README.md` — the only file you edit.
- You may read (do not edit): `apps/docs-site/index.html` (for the accurate "Works with"
agent list, which is a `<ul class="chips">` around line 203), `docs/privacy.md`,
`PLAN.md`. Nothing else. Do not run repo-wide greps.

## Goal

Make the first screen of the README sell the product, without changing a single factual
claim. Everything already in the README is accurate — this is reordering and tightening,
not new claims.

## Required changes to README.md

1. **Top of file, in this order:**
- Logo + `Crosscode` h1 (keep as-is).
- Badge row. Keep the existing npm version, CI, stars, MIT, and Node 24 badges, and
ADD a shields.io weekly-downloads badge for the real package:
`https://img.shields.io/npm/dw/crosscode-cli?style=flat&color=08C&label=downloads`
linked to `https://www.npmjs.com/package/crosscode-cli`. Match the existing
`style=flat&color=08C` look. The MIT badge must link to `./LICENSE` (currently it is
an unlinked img — make it a link, keep the same shields.io URL).
- The one-line value prop as the headline sentence, in the spirit of:
"Real-time codebase sync between teammates and coding agents, so nobody overwrites
anyone else's work." Keep the existing follow-on sentences ("You edit a file, their
checkout updates within seconds..."). Do not overclaim beyond what the current text
says.
- **A demo GIF placeholder.** No GIF exists in this repo. Do NOT invent one, do not
reference a file that isn't there, and do not describe a recording as if it exists.
Insert an HTML comment placeholder, clearly marked, e.g.:
```html
<!-- TODO(abdullah): record a ~10s screen capture of a sync landing in a second
checkout (edit on the left, file updating on the right), save it as
assets/demo.gif, and replace this comment with:
<p align="center"><img src="assets/demo.gif" alt="A file edit in one checkout appearing in another within seconds" width="720" /></p>
-->
```
Nothing rendered should imply a GIF is present.
- The one-command install immediately under that placeholder — a fenced bash block with
exactly `npm install -g crosscode-cli` as the first line. It is fine that the fuller
Quickstart block later also contains it; the top one is the hook.
- The "Works with the agent you already run" section, moved up here (currently at
line ~197). Use the accurate list from the site's chips: Claude Code, Codex CLI,
OpenCode, Cursor, Gemini CLI, VS Code, Amp, Cline, Zed, Windsurf, + any MCP client.
Verify against `apps/docs-site/index.html` and match it exactly.

2. **Keep the `> [!IMPORTANT]` disclosure block** (no end-to-end encryption, the service
can read your files, PLAN.md status) — but move it BELOW the first screen, i.e. after
the install + Works-with block, rather than deleting or softening it. Not one word of
it may be weakened. It must still be prominent (keep the `[!IMPORTANT]` callout
styling), just not the first thing above the fold.

3. **Reorder the body** so it reads top-to-bottom as:
1. What it does — `How it works`, `Features`
2. How to install it — `Quickstart`
3. Why it's safe to trust — `What syncs, and what never does`, `The apply rule`
(which contains the rules-it-won't-break list), `Pricing`
4. Deeper detail for the curious — `What your agent sees`, `What Crosscode is not`,
`Developing`, `Community and support`, `License`, `Trademark`

Move whole sections. Do not rewrite section bodies except for minimal transition
fixes (e.g. a heading rename, or a sentence that now points backwards instead of
forwards). Every honest disclosure stays verbatim: the no-end-to-end-encryption
sentences, what the service stores, the free-no-paid-plans pricing status, and the
"What Crosscode is not" section.

## Out of scope — do not touch

- Any file other than `README.md`.
- Anything about GitHub OAuth, sign-in, device codes, Stripe, or billing. The sign-in
paragraph in Quickstart stays exactly as written.
- No new features, metrics, user counts, star counts, testimonials, or benchmark claims.
If a number is not already in the file, do not add it.
- Do not delete the CI badge, the stars badge, or any docs link.
- Do not commit, push, merge, rebase, or open a PR. Leave changes uncommitted in your
worktree.

## Verify (run these yourself)

```bash
# 1. The install command is in the first 60 lines, and no fake GIF is referenced.
head -60 README.md
grep -n 'demo.gif' README.md # expect: only inside the TODO comment
ls assets/ | grep -i gif || echo "no gif present (expected)"

# 2. Every disclosure survived, byte-for-byte on the key phrases:
grep -c 'no end-to-end encryption' README.md # expect 2 or more
grep -n 'The hosted service is free' README.md
grep -n 'What Crosscode is not' README.md
grep -n 'docs/privacy.md' README.md

# 3. No links were dropped. Compare the set of link targets before and after:
git stash && grep -o '](\./[^)]*)' README.md | sort -u > /tmp/cc-links-before.txt
git stash pop && grep -o '](\./[^)]*)' README.md | sort -u > /tmp/cc-links-after.txt
comm -23 /tmp/cc-links-before.txt /tmp/cc-links-after.txt # expect: EMPTY output

# 4. Badge URLs resolve (npm downloads badge is real):
curl -sS -o /dev/null -w '%{http_code}\n' 'https://img.shields.io/npm/dw/crosscode-cli'
# expect 200
```

Expected result: install command visible in the first screen, comm output empty, all
disclosure greps hit, no GIF file referenced outside the TODO comment.

## Done means

All four verify steps produce the expected output, and `git status` shows `README.md` as
the only modified file.

## Report back

The verify command output, `git diff --stat`, and anything you could not do.

## Ground rules (non-negotiable)

Read only what this brief lists. If you need a file outside that list, stop and say so
rather than exploring. Do not run repo-wide greps. Do not spawn subagents. Do not merge,
rebase, commit, push, or touch any branch but your own. Leave your work uncommitted.

This `BRIEF.md` file itself is untracked scaffolding — ignore it in your file-count check
and do not commit or delete it.

Any web/browser work uses Orca's browser (`orca tab create` / `goto` / `screenshot` /
`eval`), never claude-in-chrome and never `browse`.

Report at the end: your verify command output, `git diff --stat`, and anything you could
not do or chose not to do.
98 changes: 55 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,16 @@

<p align="center">
<a href="https://www.npmjs.com/package/crosscode-cli"><img src="https://img.shields.io/npm/v/crosscode-cli?style=flat&color=08C&label=npm" alt="crosscode-cli on npm" /></a>
<a href="https://www.npmjs.com/package/crosscode-cli"><img src="https://img.shields.io/npm/dw/crosscode-cli?style=flat&color=08C&label=downloads" alt="crosscode-cli weekly downloads" /></a>
<a href="https://github.com/amsultan2010/crosscode/actions/workflows/ci.yml"><img src="https://github.com/amsultan2010/crosscode/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://github.com/amsultan2010/crosscode"><img src="https://img.shields.io/github/stars/amsultan2010/crosscode?style=flat&label=%E2%98%85&color=08C" alt="GitHub stars" /></a>
<img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="License: MIT" />
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-08C?style=flat" alt="License: MIT" /></a>
<img src="https://img.shields.io/badge/node-24%2B-4493F8?style=flat" alt="Requires Node 24 or newer" />
</p>

<p align="center">
<strong>Real-time codebase sync between teammates.</strong><br/>
<strong>Real-time codebase sync between teammates and coding agents, so nobody overwrites
anyone else's work.</strong><br/>
You edit a file, their checkout updates within seconds. They edit, yours does.
Nobody presses anything and nobody watches anything.
</p>
Expand All @@ -20,6 +22,32 @@
<sub>Node 24 and a Git checkout. Nothing to deploy.</sub>
</p>

<!-- TODO(abdullah): record a ~10s screen capture of a sync landing in a second
checkout (edit on the left, file updating on the right), save it as
assets/demo.gif, and replace this comment with:
<p align="center"><img src="assets/demo.gif" alt="A file edit in one checkout appearing in another within seconds" width="720" /></p>
-->

```bash
npm install -g crosscode-cli
```

## Works with the agent you already run

<p>
<kbd>Claude Code</kbd> &nbsp;
<kbd>Codex CLI</kbd> &nbsp;
<kbd>OpenCode</kbd> &nbsp;
<kbd>Cursor</kbd> &nbsp;
<kbd>Gemini CLI</kbd> &nbsp;
<kbd>VS Code</kbd> &nbsp;
<kbd>Amp</kbd> &nbsp;
<kbd>Cline</kbd> &nbsp;
<kbd>Zed</kbd> &nbsp;
<kbd>Windsurf</kbd> &nbsp;
<kbd>+ any MCP client</kbd>
</p>

> [!IMPORTANT]
> [`crosscode-cli`](https://www.npmjs.com/package/crosscode-cli) installs from npm, and the
> sync engine underneath it (the shadow ref, the
Expand Down Expand Up @@ -194,38 +222,16 @@ Cursor, or any MCP-capable agent, and it runs the same commands and wires up the
itself. 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](./docs/mcp-clients.md).

## Works with the agent you already run

<p>
<kbd>Claude Code</kbd> &nbsp;
<kbd>Codex CLI</kbd> &nbsp;
<kbd>OpenCode</kbd> &nbsp;
<kbd>Cursor</kbd> &nbsp;
<kbd>Gemini CLI</kbd> &nbsp;
<kbd>VS Code</kbd> &nbsp;
<kbd>Amp</kbd> &nbsp;
<kbd>Cline</kbd> &nbsp;
<kbd>Zed</kbd> &nbsp;
<kbd>Windsurf</kbd> &nbsp;
<kbd>+ any MCP client</kbd>
</p>

## 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.
## What syncs, and what never does

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. 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.
Tracked files only, plus a hard denylist. Your commits, branches, index, stash, and remotes
are never touched, and 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.

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`](./skills/crosscode/SKILL.md) for what the agent is told.
Your files do pass through the hosted coordination service, and there is no end-to-end
encryption, so we can read them. [docs/privacy.md](./docs/privacy.md) lists exactly what the
service stores and for how long, and [docs/security.md](./docs/security.md) has the threat
model.

## The apply rule

Expand Down Expand Up @@ -254,22 +260,28 @@ Rules that keep it invisible:

More in [architecture](./docs/architecture.md) and [protocol](./docs/protocol.md).

## What syncs, and what never does

Tracked files only, plus a hard denylist. Your commits, branches, index, stash, and remotes
are never touched, and 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.

Your files do pass through the hosted coordination service, and there is no end-to-end
encryption, so we can read them. [docs/privacy.md](./docs/privacy.md) lists exactly what the
service stores and for how long, and [docs/security.md](./docs/security.md) has the threat
model.

## Pricing

The hosted service is free. There are no paid plans, no seats, and no payment details
collected. See [docs/terms.md](./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.

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. 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`](./skills/crosscode/SKILL.md) for what the agent is told.

## What Crosscode is not

No accept-or-reject step on incoming work, no tasks, claims, or handoffs, no hidden snapshot
Expand Down
Loading