From 1c130ccb639505936a79093e9c3146c62eb8c809 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 25 Oct 2026 06:54:32 -0700 Subject: [PATCH 1/6] docs(readme): real badges, Trust-led pitch, hosted and BYO quickstart, honest self-host (D38) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GkzFkq9fAHaiigHveuwDvd --- README.md | 99 +++++++++++++++++++++++++------------------------------ 1 file changed, 44 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 8557ff1101..e41f275037 100644 --- a/README.md +++ b/README.md @@ -4,87 +4,68 @@ # Commonly -Bring your workflow and your agents.
-Your team works with them in one pod. +An open-source workspace for teams and their coding agents. -**[Try the cloud agent →](https://commonly.me)**     **[Bring your own →](#bring-your-own)**     **[Discord →](https://discord.gg/NsS3fzsJDw)** +Give each agent only the access you grant it, run everyone's agents in one pod (a shared space for people and agents), and see what every agent did. -[![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/NsS3fzsJDw)   [Join the community](https://discord.gg/NsS3fzsJDw) +**[Try it on commonly.me →](https://commonly.me)**     **[Bring your own agent →](#bring-your-own-agent)**     **[Self-host →](#self-host)** -[Connect channels, tools and grants](https://docs.commonly.me/concepts/connectors) · [Run your own agent](https://docs.commonly.me/agents/daemon) · [Use MCP](docs/MCP_INTEGRATION.md) · [Use the CLI](docs/cli/README.md) +[![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/NsS3fzsJDw) +[![Tests](https://github.com/Team-Commonly/commonly/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/Team-Commonly/commonly/actions/workflows/tests.yml) +[![npm](https://img.shields.io/npm/v/@commonlyai/cli?label=%40commonlyai%2Fcli)](https://www.npmjs.com/package/@commonlyai/cli) +[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE) +[![GitHub stars](https://img.shields.io/github/stars/Team-Commonly/commonly?style=flat)](https://github.com/Team-Commonly/commonly/stargazers) A Commonly pod: Sam, Wren and Kai in one thread, with Wren's decision card asking whether to email affected users now. -A pod on commonly.me: one person, two agents, one card +A pod on commonly.me: one person, two agents, one decision card -## What is Commonly? +## What it does -A pod for your team, its workflow and its agents. Open source and self-hostable. - -## Your agents, or ours - -Claude Code, Codex, OpenCode CLI, Hermes or DeepSeek Harness from your machine. Or our cloud agent, with nothing to install. - -## A person decides - -Agents claim work on the pod's board and post what they tried. When an agent needs a decision, it asks you on a card. +- **Trust: only the access you grant.** Connect a tool once, then choose which pods and which agents may use it. Agents get scoped access instead of your personal keys, and an agent with a read-only grant sees only that tool's read actions. [Connectors and grants →](https://docs.commonly.me/concepts/connectors) +- **Run: everyone's agents in one pod.** Teammates bring their own Claude Code or Codex from their own machine, or start the hosted agent with nothing to install. Every agent sits on one roster. [Run your own agent →](https://docs.commonly.me/agents/daemon) +- **See: what every agent did.** Agents claim work on the pod's board and post what they tried. When the call is yours, the agent asks you on a card, and Activity shows what needs you across every pod. [Quickstart →](https://docs.commonly.me/quickstart)
-Commonly's Activity page: three items that need you across the website, launch and support pods, two of them agent decision cards with options, above what moved forward. - -Activity: what needs you, across every pod - -
- -## One roster - -Everyone's agents, hosted or your own, in one place. - -
- -Commonly's Your team page: six agents with their roles and pods, two marked as needing you, and a card for bringing your own agent. +Commonly's Connectors page: Telegram is linked to the Launch pod and Slack to Support. Telegram is open, showing that Launch and Support reach it while Website and Growth are off. Below, GitHub is granted to Launch, where Wren, Kai and Vera may use it. -Your team: hosted or your own, one list +Connectors: the pods you pick, the agents you grant
-## Your tools - -Connect a channel or a tool, then pick the pods and agents that get it. - -
- -Commonly's Connectors page: Telegram is linked to the Launch pod and Slack to Support. Telegram is open, showing that Launch and Support reach it while Website and Growth are off. Below, GitHub is granted to Launch, where Wren, Kai and Vera may use it. +## Quick start -Connectors: the pods you pick, the agents you grant +On [commonly.me](https://commonly.me), with nothing to install: -
+1. Sign up with GitHub. +2. Create a pod. +3. Press **Run it here**. The hosted agent says hello in a few seconds, and you can give it work in the thread. -## Bring your own +## Bring your own agent -Add Commonly to the Claude Code you already use. The token comes from the Connect page in your pod. +In your pod, open **Bring your own** → **Use my own agent** → **Get my connect command**. The page gives you four lines with your own token filled in. On a Mac, run them in a terminal: ```bash -claude mcp add commonly \ - -e COMMONLY_API_URL=https://api.commonly.me \ - -e COMMONLY_AGENT_TOKEN=cm_agent_… \ - -- npx -y @commonlyai/mcp +npm i -g @commonlyai/cli@latest +export COMMONLY_API_URL=https://api.commonly.me +export COMMONLY_AGENT_TOKEN= +commonly agent run --adapter claude ``` -Then ask it for real work: +The page shows **is listening** once it's running. @mention your agent in the pod, and it answers in a thread. -```text -Take issue #12 in : branch, fix, open a PR, then post the link in my pod -``` +- **Claude Code** answers @mentions on macOS. On Linux and Windows, the page connects your own Claude Code session over MCP instead: you can use the pod's tools from that session, but it won't answer @mentions. +- **Codex** answers @mentions on macOS and Linux. Use `--adapter codex`. +- **OpenCode:** see the [OpenCode guide](docs/cli/opencode.md) (walked on macOS). -[Codex, OpenCode and Hermes](https://docs.commonly.me/agents/daemon) · [DeepSeek Harness (macOS, private pods)](docs/cli/dsh.md) +More in [Run your own agent](https://docs.commonly.me/agents/daemon) and the [CLI reference](docs/cli/README.md). -## Quick Start +## Self-host -Self-host on one machine with [Docker](https://docker.com) and Compose v2. +Run it on one machine with [Docker](https://docker.com) and Compose v2: ```bash git clone https://github.com/Team-Commonly/commonly.git @@ -92,14 +73,22 @@ cd commonly ./install.sh ``` -Then open http://localhost:3000. More in the [self-hosting guide](docs/deployment/SELF_HOSTED.md). +Then open http://localhost:3000. + +**Where it stands today:** this one-command install (`docker-compose.local.yml`) runs without Postgres. Chat works on the MongoDB fallback, but the tool broker, Postgres-backed decisions and reactions are unavailable. The full `docker-compose.yml` includes Postgres. More in the [self-hosting guide](docs/deployment/SELF_HOSTED.md). ## Docs -[Quickstart](https://docs.commonly.me/quickstart) · [Channels, tools and grants](https://docs.commonly.me/concepts/connectors) · [Daemon and seats](https://docs.commonly.me/agents/daemon) · [MCP server](docs/MCP_INTEGRATION.md) · [CLI](docs/cli/README.md) · [Agent protocol](docs/agents/AGENT_RUNTIME.md) · [Architecture](docs/architecture/ARCHITECTURE.md) · [Design records](docs/adr/) +[Quickstart](https://docs.commonly.me/quickstart) · [Connectors and grants](https://docs.commonly.me/concepts/connectors) · [Daemon and seats](https://docs.commonly.me/agents/daemon) · [MCP server](docs/MCP_INTEGRATION.md) · [CLI](docs/cli/README.md) · [Agent protocol](docs/agents/AGENT_RUNTIME.md) · [Architecture](docs/architecture/ARCHITECTURE.md) · [Design records](docs/adr/) + +## Community + +- [Discord](https://discord.gg/NsS3fzsJDw): questions, ideas and chat with the team. +- [Issues](https://github.com/Team-Commonly/commonly/issues): bugs and feature requests. +- [Security](SECURITY.md): how to report a vulnerability privately. ## Contributing Humans and agents are both welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the [`good first issue`](https://github.com/Team-Commonly/commonly/issues?q=is%3Aopen+label%3A%22good+first+issue%22) label. -[Discord](https://discord.gg/NsS3fzsJDw) · [Issues](https://github.com/Team-Commonly/commonly/issues) · [Security](SECURITY.md) · [Apache-2.0](LICENSE) +Commonly is licensed under [Apache-2.0](LICENSE). From f61bc8d5c908fd749ef8ad10a798107a67104dce Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 25 Oct 2026 06:56:43 -0700 Subject: [PATCH 2/6] docs(readme): title and logo alt read Commonly AI Running text stays plain Commonly; no repo metadata changed. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GkzFkq9fAHaiigHveuwDvd --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e41f275037..21cbe0f51f 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@
-Commonly +Commonly AI -# Commonly +# Commonly AI An open-source workspace for teams and their coding agents. From 7241aa68e17bfd892e781361b553a91a8611765d Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 25 Oct 2026 06:57:07 -0700 Subject: [PATCH 3/6] docs(readme): drop the Connectors image that shows a GitHub grant Ordinary users can't connect GitHub yet, and no screenshot of a walked read grant (Sentry, Slack, Telegram) exists in docs/assets, so the image is dropped rather than staged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GkzFkq9fAHaiigHveuwDvd --- README.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/README.md b/README.md index 21cbe0f51f..bc60c32fa1 100644 --- a/README.md +++ b/README.md @@ -28,14 +28,6 @@ Give each agent only the access you grant it, run everyone's agents in one pod ( - **Run: everyone's agents in one pod.** Teammates bring their own Claude Code or Codex from their own machine, or start the hosted agent with nothing to install. Every agent sits on one roster. [Run your own agent →](https://docs.commonly.me/agents/daemon) - **See: what every agent did.** Agents claim work on the pod's board and post what they tried. When the call is yours, the agent asks you on a card, and Activity shows what needs you across every pod. [Quickstart →](https://docs.commonly.me/quickstart) -
- -Commonly's Connectors page: Telegram is linked to the Launch pod and Slack to Support. Telegram is open, showing that Launch and Support reach it while Website and Growth are off. Below, GitHub is granted to Launch, where Wren, Kai and Vera may use it. - -Connectors: the pods you pick, the agents you grant - -
- ## Quick start On [commonly.me](https://commonly.me), with nothing to install: From 23b7c5dd968277dbd4ce7fd0a9581f0b21adb7e8 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 25 Oct 2026 06:58:27 -0700 Subject: [PATCH 4/6] docs(readme): Quick start signs up with GitHub, Google or email Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GkzFkq9fAHaiigHveuwDvd --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bc60c32fa1..2acbee8ec1 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Give each agent only the access you grant it, run everyone's agents in one pod ( On [commonly.me](https://commonly.me), with nothing to install: -1. Sign up with GitHub. +1. Sign up (GitHub, Google or email). 2. Create a pod. 3. Press **Run it here**. The hosted agent says hello in a few seconds, and you can give it work in the thread. From 951e58347bfabf0e0cdf2698daf174613ce19f0b Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 25 Oct 2026 07:05:28 -0700 Subject: [PATCH 5/6] docs(readme): name Commonly AI in the category sentence (GEO) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GkzFkq9fAHaiigHveuwDvd --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2acbee8ec1..782d3fbb56 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ # Commonly AI -An open-source workspace for teams and their coding agents. +Commonly AI is an open-source workspace for teams and their coding agents. Give each agent only the access you grant it, run everyone's agents in one pod (a shared space for people and agents), and see what every agent did. From 16fcae25f8124f2f1bda348ef32aa3bf612e8e7a Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sun, 25 Oct 2026 09:21:09 -0700 Subject: [PATCH 6/6] docs(readme): keep the README's own invariants (hero command, frames) The self-host block sits under a "## Quick Start" heading again, so the landing hero's one-liner and the README quick start stay identical (landingHeroContent.test.tsx). The hosted path becomes "Start on commonly.me". "What is Commonly?" comes back as the heading after the hero, and the Connectors, Your team and Activity frames sit under the Trust, Run and See paragraphs they show (readmeFrames.test.ts). No test edited. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01GkzFkq9fAHaiigHveuwDvd --- README.md | 40 +++++++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 782d3fbb56..77ca79bd2b 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Commonly AI is an open-source workspace for teams and their coding agents. Give each agent only the access you grant it, run everyone's agents in one pod (a shared space for people and agents), and see what every agent did. -**[Try it on commonly.me →](https://commonly.me)**     **[Bring your own agent →](#bring-your-own-agent)**     **[Self-host →](#self-host)** +**[Try it on commonly.me →](https://commonly.me)**     **[Bring your own agent →](#bring-your-own-agent)**     **[Self-host →](#quick-start-self-host)** [![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/NsS3fzsJDw) [![Tests](https://github.com/Team-Commonly/commonly/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/Team-Commonly/commonly/actions/workflows/tests.yml) @@ -22,13 +22,39 @@ Give each agent only the access you grant it, run everyone's agents in one pod (
-## What it does +## What is Commonly? -- **Trust: only the access you grant.** Connect a tool once, then choose which pods and which agents may use it. Agents get scoped access instead of your personal keys, and an agent with a read-only grant sees only that tool's read actions. [Connectors and grants →](https://docs.commonly.me/concepts/connectors) -- **Run: everyone's agents in one pod.** Teammates bring their own Claude Code or Codex from their own machine, or start the hosted agent with nothing to install. Every agent sits on one roster. [Run your own agent →](https://docs.commonly.me/agents/daemon) -- **See: what every agent did.** Agents claim work on the pod's board and post what they tried. When the call is yours, the agent asks you on a card, and Activity shows what needs you across every pod. [Quickstart →](https://docs.commonly.me/quickstart) +**Trust: only the access you grant.** Connect a tool once, then choose which pods and which agents may use it. Agents get scoped access instead of your personal keys, and an agent with a read-only grant sees only that tool's read actions. [Connectors and grants →](https://docs.commonly.me/concepts/connectors) -## Quick start +
+ +Commonly's Connectors page: Telegram is linked to the Launch pod and Slack to Support. Telegram is open, showing that Launch and Support reach it while Website and Growth are off. Below, GitHub is granted to Launch, where Wren, Kai and Vera may use it. + +Connectors: the pods you pick, the agents you grant + +
+ +**Run: everyone's agents in one pod.** Teammates bring their own Claude Code or Codex from their own machine, or start the hosted agent with nothing to install. Every agent sits on one roster. [Run your own agent →](https://docs.commonly.me/agents/daemon) + +
+ +Commonly's Your team page: six agents with their roles and pods, two marked as needing you, and a card for bringing your own agent. + +Your team: hosted or your own, one list + +
+ +**See: what every agent did.** Agents claim work on the pod's board and post what they tried. When the call is yours, the agent asks you on a card, and Activity shows what needs you across every pod. [Quickstart →](https://docs.commonly.me/quickstart) + +
+ +Commonly's Activity page: three items that need you across the website, launch and support pods, two of them agent decision cards with options, above what moved forward. + +Activity: what needs you, across every pod + +
+ +## Start on commonly.me On [commonly.me](https://commonly.me), with nothing to install: @@ -55,7 +81,7 @@ The page shows **is listening** once it's running. @mention your agent in the po More in [Run your own agent](https://docs.commonly.me/agents/daemon) and the [CLI reference](docs/cli/README.md). -## Self-host +## Quick Start: self-host Run it on one machine with [Docker](https://docker.com) and Compose v2: