# CommonGrounds

> 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, because a history that confidently mislabels a careful human edit as
> AI output is worse than one that admits it does not know.

CommonGrounds is a desktop client plus a server. You install one file, sign
in, and choose a folder. That folder syncs continuously to the people it is
shared with, every synced state is a snapshot you can go back to, and every
change carries who made it and how the system knows.

The part that is unusual: it works at the filesystem level, so any agent that
edits files in the folder takes part with no integration written for it. An
agent that announces itself through the local MCP server is credited exactly;
one that does not is recorded as inferred, never as the person.

## What an agent working in one of these folders should know

- The folder changes under you. Somebody else may be editing it right now.
- Never write back a whole file you read earlier. Re-read immediately before
  writing, and prefer a targeted edit to replacing the contents.
- Nothing is lost. Every version is kept: `cg log --files` shows what each
  change did, `cg cat --revision <id> <path>` prints old contents back.
- `.cg/generated/TEAM_MEMORY.md` is what the people and agents here have
  already learned about the workspace. Read it before starting. Add to it with
  `cg memory add "..."` - facts about the workspace, not about your task.
- `cg agent setup` in the folder writes the MCP server and hooks for the
  agents already used there. Through `cg_write` and `cg_edit` a change is
  recorded as certainly yours, and a write to a file that moved since you read
  it is refused rather than performed.
- Your session may be on a branch rather than on the folder's main line. Where
  the policy says so - the default in an organisation's folder - your session
  opens a proposal branch, your edits go there, and the people in the folder
  approve or reject them afterwards. `cg status` says which branch the folder
  is following and whether a proposal is open. Nothing about how you edit
  changes; do not try to merge or switch branches yourself.
- The folder's `.cg/policy.toml` may make you read-only, or limit you to part
  of the tree. A refusal with a reason is the policy, not a bug: say so
  instead of working around it.
- Some files are held back rather than synced - a private key, a token, a
  `.env`. The person is asked once and can send it anyway. An unsynced file is
  not a lost file.

## Clients

- Desktop app: Windows, macOS, Linux. Syncs in the background, starts at
  login, and serves the local socket agents connect to. On Windows it also
  adds two entries to Explorer's right-click menu: sync this folder, and make
  a download link for this file or folder.
- Command line: the same single file. `cg status`, `cg log`, `cg folders`,
  `cg share`, `cg memory`, `cg branch`, `cg review`, `cg fetch`.
- Claude Code, Codex CLI, Cursor: MCP server and hooks, written by
  `cg agent setup`.
- Claude Desktop and Gemini CLI: MCP server only.
- Web app: the same workspaces in a browser - files, history, diffs, sharing,
  branches and reviews - at the address below.
- Anything else: no setup at all. Edits are versioned, synced, and recorded
  as found on disk with nobody claiming them.

## What it does besides syncing

- **Attribution with a confidence level.** `declared` when an agent claimed
  the change through its tools, `inferred` when it was running in the folder
  at the time, `human` for a person's own edit, `unknown` when nothing is
  known. Never a guess dressed as a fact.
- **Sharing by email address.** The person invited accepts or declines, and
  their work is charged to the owner's quota, not theirs. Roles: owner,
  editor, viewer.
- **Organisations and teams.** A folder can belong to an organisation;
  administrators manage members, and a team is a group invited at once.
- **Proposal branches and reviews.** An agent session can be routed to a
  branch instead of the main line, with the merge reviewed, commented on and
  approved by a person. The policy is per folder and keyed by the member's
  role; organisation folders default to it.
- **Links into a folder.** A share link lets somebody with an account join a
  folder without being invited by address.
- **Download links.** A folder, or one path in it, handed to somebody with no
  account as a zip written while it is sent. Always expires - a week by
  default, ninety days at most - and can need a passphrase or be limited to a
  number of downloads. `cg fetch <address>` does the same from a terminal.
- **Shared memory.** Facts the people and agents in a folder have learned,
  kept in the folder; and personal memory that follows the account to every
  machine it signs in on.
- **Merge drivers, git export and import.** Line-level merges for text, union
  merges for logs, and a git repository in or out when a project needs one.
- **An audit ledger.** What each agent session was allowed to do, and what it
  did.

## Links

- [Home](https://usecommongrounds.com/): what it is, how it works, and the download.
- [Pricing](https://usecommongrounds.com/pricing): free while it is early; Pro is coming; Enterprise
  is a conversation.
- [Privacy](https://usecommongrounds.com/privacy): what is kept, what is not, and how to have it
  deleted.
- [For language models, in full](https://usecommongrounds.com/llms-full.txt): the same in detail -
  how the sync works, what is stored, the commands, the limits.
- [Downloads](https://usecommongrounds.com/v1/downloads): the current builds as JSON, with sizes and
  SHA-256 checksums for each platform.

## Notes

- One account per person; 100 MiB of storage to begin with, and 1 GiB once the
  address is confirmed, counted deduplicated across every version. Free at that
  allowance, with no card and no trial clock; a paid tier is not for sale yet.
- A folder is charged to whoever owns it, not to the people they share it with.
- The source is not published and there is no self-hosted edition.
- Written in Rust. One binary is the desktop app, the command line and the
  server.