# CommonGrounds, in full

> A shared folder that syncs like Drive, versions like Git, and records which
> change was made by a person and which by an AI agent - with a confidence
> level. One binary is the desktop app, the command line and the server.

This is the long version of [llms.txt](https://usecommongrounds.com/llms.txt), for a reader that
wants the whole picture without clicking through a site. Everything here is
about the product as it is today, not as it is planned.

## The problem it is built for

A folder that people and AI agents both write to has two histories nobody
keeps: what changed, and who changed it. File sync tools keep neither in a
form you can go back to. Git keeps the first, but only for the changes
somebody remembered to commit, and it credits whoever's name is in the
config - so an agent's work arrives under a person's name. Neither can tell
you afterwards whether the paragraph you are reading was written by your
colleague or produced by a model.

CommonGrounds keeps both, continuously, at the filesystem level: no commits
to remember, and no integration to write for each agent.

## How the sync works

- **Any folder.** You choose it in the app; nothing about its layout changes.
  A `.cg` directory inside it holds the local state and is never synced.
- **Continuous.** A filesystem watcher notices a change, the folder is
  scanned incrementally against a local index, and only what actually changed
  is uploaded.
- **Content-defined chunking.** Files are split on content boundaries, so
  appending a megabyte to a 100 MB file uploads the chunks that changed, not
  the file. Identical content anywhere is stored once.
- **Every synced state is a snapshot.** Not a backup taken on a schedule: a
  commit-like object with a tree, a time, a device and an actor. `cg log`
  lists them; `cg cat --revision <id> <path>` prints a file as it was;
  `cg restore` puts a version back.
- **Merging, not overwriting.** Two people editing different lines of a text
  file get one merged file. Two people editing the same line get both
  versions kept side by side as a conflict copy, named after who wrote it -
  never one silently winning. `.cg/attributes` can set a merge driver per
  path: three-way for text, union for logs and changelogs, and whole-file
  for anything binary.
- **Offline is not a failure.** Edits stay on disk and go up when the
  connection is back; nothing is lost and nothing has to be retried by hand.
- **Files another program is holding** (an open Word document, a database
  file) are parked and picked up later rather than half-read.

## Attribution, and why it has a confidence level

Every change carries an actor and how the system knows:

- `declared` - an agent claimed the change through the tools CommonGrounds
  gave it (`cg_write`, `cg_edit`). The strongest statement available.
- `inferred` - the file changed while an agent session was open in the
  folder, and the agent did not claim it. Probably the agent; not certainly.
- `human` - a person's own edit, outside any session.
- `unknown` - found on disk with nothing running that would explain it.

The levels exist because the alternative is a history that says "AI" or
"you" with a certainty it does not have. A tool that guessed would eventually
credit careful human work to a machine, and that is worse than admitting the
doubt. The web app and the desktop window show the level beside every entry.

## Working with AI agents

- **`cg agent setup`**, run once inside the folder, configures the agents
  already used there and nothing else. What it writes names a command to run,
  so it stays on the machine and is not synced to anybody.
- **Claude Code, Codex CLI and Cursor** get an MCP server and hooks. The MCP
  tools are read, write, edit, delete, search, recent changes, history,
  snapshot, shared memory, and messages to and from the other sessions.
  A write to a file that moved since it was read is refused rather than
  performed, so a colleague's paragraph cannot vanish under an agent.
- **Claude Desktop and Gemini CLI** get the MCP server; hooks are
  deliberately not written for them, because a hook that half works claims
  one agent's edit for another.
- **Anything else** - Copilot, an editor, a build script, a colleague with
  none of this installed - needs no setup. Its edits are chunked, versioned
  and synced, and recorded as found on disk with nobody claiming them.
- **Sessions.** An agent session is opened by a hook and closed when the
  agent stops. `cg status` shows the open ones; the audit ledger records what
  each was allowed to do and what it did.
- **Scopes and policy.** `.cg/policy.toml` can make an agent read-only, or
  limit it to part of the tree, and can be keyed by the member's role in the
  workspace. A refused write comes back with the reason.
- **Proposal branches.** Where the policy says so - the default in an
  organisation's folder - an agent session works on a branch rather than the
  folder's main line. The folder follows that branch for the session, manual
  edits included, and says so in the window and in `cg status`. When the
  session ends a review opens: the people in the folder read the diff,
  comment, approve or reject, and the merge happens on the server with the
  fork point recorded.
- **Messages between sessions.** `cg send` and `cg inbox`: one agent can
  leave another a message in the same folder, and an idle session is woken
  to read it.
- **Shared memory.** `cg memory add "..."` keeps a fact about the workspace
  where the next session will find it, in
  `.cg/generated/TEAM_MEMORY.md`. Personal memory follows the account
  instead: the same notes on every machine it signs in on.
- **Secrets are held back.** A private key, a token or a `.env` that appears
  in the folder is not synced until the person says so, once, for that file.

## Sharing

- **By email address.** The person invited accepts or declines. Accepting
  puts the folder on their machine; their work is charged to the owner's
  quota, not theirs. Roles are owner, editor and viewer.
- **Share links.** `cg_lnk_…` in an address that opens the web app's join
  page, at viewer or editor, for a day, a week, thirty days or until
  stopped, for any number of people or a few. Signed-in only, to look and to
  join. Stopping it stops new people and changes nothing for anybody already
  in.
- **Download links.** For somebody with no account: a folder, or one path in
  it, as a zip, written while it is sent. The token is shown once and stored
  hashed, and travels in the address's fragment, so it reaches no server log.
  Always expires - a week by default, ninety days at most - and can need a
  passphrase (ten wrong answers lock it for fifteen minutes) or be limited to
  a number of downloads. By default it hands out the folder as it was when
  the link was made; it can instead follow the latest. `cg fetch <address>`
  does the same from a terminal, and plain `curl` works too.
- **Organisations and teams.** A folder can belong to an organisation, with
  administrators who manage its members; a team is a group invited at once.

## The clients

- **Desktop app** (Windows, macOS, Linux): add folders, watch them arrive,
  read the history, share, make links, see invitations. It syncs in the
  background with the window closed, starts at login, and serves the local
  socket the agents connect to. On Windows it adds two entries to Explorer's
  right-click menu: sync this folder, and make a download link for this file
  or folder. On Linux there is no window; `cg ui` opens the same page in a
  browser.
- **Command line**, the same single file: `cg status`, `cg log`, `cg folders`,
  `cg share`, `cg fetch`, `cg branch`, `cg review`, `cg checkout`,
  `cg memory`, `cg send`, `cg inbox`, `cg agent`, `cg session`, `cg snapshot`,
  `cg restore`, `cg verify`, `cg export git`, `cg import git`, `cg update`,
  `cg service`. Double-click the file and a window opens; run it from a
  terminal and it is a command-line tool.
- **Web app**: the same workspaces in a browser - file tree, contents,
  history with the confidence badges, diffs, sharing, branches, reviews,
  organisations, teams, and the account's quota.
- **Signing in a terminal without a password**: `cg account login --device`
  prints a code to confirm in the browser, for machines you do not want to
  type a password on.

## Git, when a project needs it

`cg export git` writes the history of a folder as a git repository, one
commit per snapshot, with the actor and the confidence level in the commit
message; `cg import git` brings a repository in. Neither replaces the other
tool: git stays for code review and CI, CommonGrounds keeps the continuous
history of the folder itself.

## What is stored, and where

- Content is stored as chunks, deduplicated, with a per-account quota that
  counts what the branch heads hold - what an old version alone holds costs
  nothing - plus whatever a pinned download link keeps alive while it works.
- Old history is thinned on a schedule (hourly for a month, then daily for a
  year) by a collector that never drops anything a head, a branch or a live
  link can reach.
- Passwords, tokens and link secrets are stored hashed, never in a form that
  can be read back. Traffic is HTTPS.
- Releases are signed: the client verifies the signature and the release
  marker before replacing itself, and `cg update` is the same check by hand.

## Limits and price

- One account per person. 100 MiB to begin with, and 1 GiB once the address
  is confirmed, counted deduplicated across every version.
- **Free** is the only tier on sale: everything the product does today, at
  that allowance, with no card and no trial clock. A folder is charged to
  whoever owns it, not to the people they share it with.
- **Pro** - more storage, longer history, support with a person on the other
  end - is coming and has no price to quote yet. Somebody who outgrows the
  free allowance before then has it raised by asking.
- **Enterprise** - larger teams, invoicing, a security review, or an
  installation on the company's own infrastructure - is arranged by writing
  to tugba@usecommongrounds.com.
- Going over the allowance stops new versions being accepted and says so.
  Nothing is deleted and nothing is billed.
- The source is not published, and self-hosting exists only as part of an
  enterprise arrangement.

## Questions people ask

**Is this a Dropbox or Drive replacement?** For a folder you work in with
other people and with agents, yes. It is not a consumer photo library and it
does not try to be.

**Do I need to know git?** No. There is nothing to commit, nothing to push
and no branch to think about unless a proposal branch opens by itself, which
the folder tells you about in words.

**How does it know an AI made a change?** From the agent itself, when the
agent uses the tools `cg agent setup` gave it. Otherwise from what was
running when the file changed, and it says that is what it is doing.

**Can I stop an agent from writing?** Yes: `.cg/policy.toml` makes it
read-only, or limits it to part of the tree, or routes its work to a branch
somebody has to approve.

**What happens when two people edit the same file?** Different lines merge.
The same line keeps both versions, side by side, named after who wrote them.

**Can I self-host it?** No. The source is not published either.

**What is it written in?** Rust, in nine crates: one binary is the desktop
app, the command line and the server.

## Links

- [Home](https://usecommongrounds.com/)
- [Pricing](https://usecommongrounds.com/pricing)
- [Privacy](https://usecommongrounds.com/privacy): what is kept, what is not, where it is, and how
  to have it deleted.
- [For language models, short](https://usecommongrounds.com/llms.txt)
- [Downloads as JSON](https://usecommongrounds.com/v1/downloads), with sizes and SHA-256 checksums