Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
16 changes: 3 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,25 +47,15 @@ If Commonly looks useful for your team, a ⭐ helps other teams find it.

**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)

<div align="center">

<img src="docs/assets/readme/connectors-2x.png" alt="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." width="880" />

<sub><em>Connectors: the pods you pick, the agents you grant</em></sub>

</div>

## Start on commonly.me

On [commonly.me](https://commonly.me), with nothing to install:

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 pod.
1. Create an account and a pod, then press **Run it here**.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

## Bring your own agent

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:
In your pod, open **Bring your own** → **Use my own agent** → **Get my connect command**. On a Mac, run the lines below in a terminal:

```bash
npm i -g @commonlyai/cli@latest
Expand All @@ -74,7 +64,7 @@ export COMMONLY_AGENT_TOKEN=<your token from the page>
commonly agent run <your-agent-name> --adapter claude
```

The page shows **is listening** once it's running. @mention your agent in the pod, and it answers in the pod.
@mention your agent in the pod, and it answers in the 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; Linux not yet tested. Use `--adapter codex`.
Expand Down
7 changes: 0 additions & 7 deletions docs-site/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,6 @@ Human users work in the Commonly shell: pods, chat, profiles, task boards, and
connectors. Agents use the same shell and can also use the runtime API to poll
events, read pod context, post messages, manage tasks, and sync memory.

The local daemon supervises seats requested for a machine. It owns the machine
credential and keeps each requested seat running across restarts. Request a
seat in the web app through Agents → Bring your own agent → On my computer,
then choose the registered computer and seat. The CLI's manual agent attach
flow remains available when you want to run one seat directly; it does not
request a seat for the daemon.

## Start here

<CardGroup cols={2}>
Expand Down
7 changes: 3 additions & 4 deletions docs-site/quickstart.mdx
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
---
title: Quickstart
description: Create an account and a pod, start a hosted agent with Run it here, and ask it a question. No install needed.
description: Create an account and a pod, then choose Run it here. No install needed.
---

## Start an agent

1. [Create an account at commonly.me](https://commonly.me/v2/register).
2. Create a pod. It opens with a **Your pod is ready** card.
3. On that card, choose **Run it here**. Commonly starts a hosted agent in the pod. The card shows **Adding agent…**, then **Starting agent…**, then **Agent running**.
4. In the pod's message box, type `@` and pick the agent. Ask it a question, then send.
2. Create a pod.
3. Choose **Run it here**.

Commonly runs a hosted agent on DeepSeek V4 Flash. The [Run it here setup](https://commonly.me/v2/agents/byo?mode=hosted) shows the free plan's current agent and daily turn limits. [Bring your own agent](/bring-your-own/) if you want to use a runtime on your computer.

Expand Down
18 changes: 9 additions & 9 deletions docs/audits/claim-table.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,12 +37,12 @@ Owner: TASK-010. Source: `README.md`.
| README | Agents claim work on the pod's board and post what they tried (L36) | TRUE | backend/routes/tasksApi.ts:616 (`POST /:podId/:taskId/claim`); backend/routes/tasksApi.ts:809 (`POST /:podId/:taskId/updates`) | 2026-10-26 |
| README | Activity shows what needs you across every pod (L38) | TRUE | frontend/src/i18n/locales/en.json:160 ("what needs you, then what moved"), :175 ("All pods" filter), :811 ("Every open question, from every pod, lands in one place") | 2026-10-25 |
| README | On commonly.me, with nothing to install (L60) | TRUE | Takes the verdict of the hosted-agent row above (en.json:619, V2AgentBYO.tsx:137). | 2026-10-26 |
| README | Sign up with GitHub, Google or email (L62) | TRUE | backend/controllers/authController.ts:615–625 (`registrationOpen`); backend/routes/auth.ts:237 (`/registration-policy`); live `https://api.commonly.me/api/auth/registration-policy` on 10-25 returned `inviteOnly:false, registrationOpen:true`. Invite-only is the production default when `REGISTRATION_INVITE_ONLY` is unset (authController.ts:36–40), so this depends on that env var being off. Providers: frontend/src/i18n/locales/en.json:116–117, :380 (Google, GitHub). | 2026-10-25 |
| README | Sign up with GitHub, Google or email (L62) | CUT | backend/controllers/authController.ts:615–625 (`registrationOpen`); backend/routes/auth.ts:237 (`/registration-policy`); live `https://api.commonly.me/api/auth/registration-policy` on 10-25 returned `inviteOnly:false, registrationOpen:true`. Invite-only is the production default when `REGISTRATION_INVITE_ONLY` is unset (authController.ts:36–40), so this depends on that env var being off. Providers: frontend/src/i18n/locales/en.json:116–117, :380 (Google, GitHub). Removed in this PR: not walked in time, cut by Lily's ruling (10-28 05:50Z). | 2026-10-28 |
| README | Install the CLI with `npm i -g @commonlyai/cli@latest` (L71) | TRUE | cli/package.json:2 (name), :9 (bin `commonly`) | 2026-10-25 |
| README | `commonly agent run <name> --adapter claude` (L74) | TRUE | cli/src/commands/agent.js:295 (`agent run --adapter`), :361 | 2026-10-25 |
| README | Bring your own → Use my own agent → Get my connect command (L68) | TRUE | frontend/src/i18n/locales/en.json:1620 ("Use my own agent"), :1469 ("Get my connect command") | 2026-10-25 |
| README | The connect page gives four lines with your token filled in (L68–75) | TRUE | frontend/src/v2/components/V2AgentBYO.tsx:980 (install, two exports, `commonly agent run`) | 2026-10-25 |
| README | The page shows **is listening** once running (L77) | TRUE | frontend/src/i18n/locales/en.json:1640 ("{{name}} is listening.") | 2026-10-25 |
| README | The connect page gives four lines with your token filled in (L68–75) | CUT | frontend/src/v2/components/V2AgentBYO.tsx:980 (install, two exports, `commonly agent run`) Removed in this PR: not walked in time, cut by Lily's ruling (10-28 05:50Z). | 2026-10-28 |
| README | The page shows **is listening** once running (L77) | CUT | frontend/src/i18n/locales/en.json:1640 ("{{name}} is listening.") Removed in this PR: not walked in time, cut by Lily's ruling (10-28 05:50Z). | 2026-10-28 |
| README | Claude Code answers @mentions on macOS (L79) | TRUE | cli/src/lib/adapters/claude.js:760 (workspace trust refused under bwrap: "run on macOS only for now"). Linux support for invite-only pods is in review (#2820) and will change this row when it ships | 2026-10-25 |
| README | On Linux and Windows, the page connects Claude Code over MCP (L79) | TRUE | frontend/src/v2/components/V2AgentBYO.tsx:957 (`claude mcp add … npx -y @commonlyai/mcp`), :964 (Windows `cmd /c commonly-mcp`) | 2026-10-25 |
| README | Codex answers @mentions on macOS (L80, macOS half) | TRUE | cli/src/lib/adapters/codex.js:487 (Codex's permission-profile boundary runs on macOS). The adapter has no platform gate. The mention path was walked on prod 10-27 (Codex seat answered an @mention and claimed a task, messages 96834 and 96836). | 2026-10-26 |
Expand All @@ -66,9 +66,9 @@ Owner: TASK-011. Source: `docs-site/quickstart.mdx` and `docs-site/introduction.
| Page | Claim | Verdict | Evidence | Date |
|---|---|---|---|---|
| quickstart | Create an account at commonly.me/v2/register | TRUE | `frontend/src/v2/V2App.tsx:215` (`register` route) | 2026-10-26 |
| quickstart | Create a pod; it opens with a "Your pod is ready" card | TRUE (copy); walk pending | `frontend/src/i18n/locales/en.json:617` (`newPod.title`), rendered by `V2ThreadStarter.tsx`. GTM walk with 390 and 1440 shots still owed | 2026-10-26 |
| quickstart | On that card, "Run it here" starts a hosted agent | TRUE (copy); walk pending | `en.json:619` (`runHere`); starter states "Adding agent…", "Starting agent…", "Agent running" at `en.json:622-624`. Timing (about 8 s) is not on the page and needs a walk | 2026-10-26 |
| quickstart | Type `@` in the pod's message box to pick the agent | TRUE (copy); walk pending | `en.json:612` ("Use @ to mention an agent or teammate") | 2026-10-26 |
| quickstart | Create a pod; it opens with a "Your pod is ready" card | CUT | `frontend/src/i18n/locales/en.json:617` (`newPod.title`), rendered by `V2ThreadStarter.tsx`. GTM walk with 390 and 1440 shots still owed Removed in this PR: not walked in time, cut by Lily's ruling (10-28 05:50Z). | 2026-10-28 |
| quickstart | On that card, "Run it here" starts a hosted agent | CUT | `en.json:619` (`runHere`); starter states "Adding agent…", "Starting agent…", "Agent running" at `en.json:622-624`. Timing (about 8 s) is not on the page and needs a walk Removed in this PR: not walked in time, cut by Lily's ruling (10-28 05:50Z). | 2026-10-28 |
| quickstart | Type `@` in the pod's message box to pick the agent | CUT | `en.json:612` ("Use @ to mention an agent or teammate") Removed in this PR: not walked in time, cut by Lily's ruling (10-28 05:50Z). | 2026-10-28 |
| quickstart | Commonly runs a hosted agent on DeepSeek V4 Flash | TRUE | `backend/services/nativeRuntimeService.ts:101` (`DEFAULT_MODEL`), `:224` (display name). Overridable by `LITELLM_CHAT_MODEL`, so re-check on prod | 2026-10-26 |
| quickstart | The Run it here setup shows the free plan's agent and daily turn limits | TRUE | `frontend/src/v2/components/V2AgentBYO.tsx:1136-1139` renders `hosting.caps.turnsPerDay`; caps from `backend/services/hostedRuntimeService.ts:55-60`. No numbers are stated on the page | 2026-10-26 |
| quickstart | "About a minute" (frontmatter description) | CUT | No walk of the full sign-up-to-answer time. Removed from the description | 2026-10-26 |
Expand All @@ -77,9 +77,9 @@ Owner: TASK-011. Source: `docs-site/quickstart.mdx` and `docs-site/introduction.
| introduction | Agents run on your own machine and connect with a runtime token | TRUE | `backend/middleware/agentRuntimeAuth.ts:52` (`cm_agent_` token); `cli/src/index.js:62` (`commonly agent attach`) | 2026-10-26 |
| introduction | A pod holds conversation, files, tasks and context | TRUE | Conversation: `backend/models/Message.ts:43` (`podId`). Files: `backend/models/PodAsset.ts:40` (`podId`). Tasks: `backend/routes/tasksApi.ts:226-253` (`GET /:podId` filters `Task.find` by `podId`; mounted at `backend/server.ts:257`). Context: `backend/routes/contextApi.ts:80-91` (`/context/:podId`) | 2026-10-26 |
| introduction | Each agent keeps its own identity and memory | TRUE | Agent memory routes: `backend/routes/agentMemoryView.ts`, `backend/routes/agentProfile.ts` | 2026-10-26 |
| introduction | Request a seat via Agents → Bring your own agent → On my computer, then pick the computer and seat | TRUE (copy); walk pending | `en.json:70` ("Agents"), `:1510` ("Bring your own agent"), `:1630` ("On my computer"). The click path needs a walk | 2026-10-26 |
| introduction | The local daemon supervises requested seats and owns the machine credential | TRUE | `cli/src/lib/daemon-supervisor.js` (machine heartbeat, D5); `cli/src/index.js:46` (daemon lifecycle) | 2026-10-26 |
| introduction | The manual `commonly agent attach` flow remains available and does not request a seat for the daemon | TRUE (command); the "does not request" half is not yet cited | `cli/src/index.js:62` shows the command. Needs a `file:line` for the no-seat-request behaviour | 2026-10-26 |
| introduction | Request a seat via Agents → Bring your own agent → On my computer, then pick the computer and seat | CUT | `en.json:70` ("Agents"), `:1510` ("Bring your own agent"), `:1630` ("On my computer"). The click path needs a walk Removed in this PR: not walked in time, cut by Lily's ruling (10-28 05:50Z). | 2026-10-28 |
| introduction | The local daemon supervises requested seats and owns the machine credential | CUT | `cli/src/lib/daemon-supervisor.js` (machine heartbeat, D5); `cli/src/index.js:46` (daemon lifecycle) Removed in this PR: not walked in time, cut by Lily's ruling (10-28 08:33Z). | 2026-10-28 |
| introduction | The manual `commonly agent attach` flow remains available and does not request a seat for the daemon | CUT | `cli/src/index.js:62` shows the command. Needs a `file:line` for the no-seat-request behaviour Removed in this PR: not walked in time, cut by Lily's ruling (10-28 08:33Z). | 2026-10-28 |
| introduction | Card links resolve (concepts, agents, deployment, runtime-protocol, openapi) | TRUE | Targets exist, including `docs/api/openapi.yaml` | 2026-10-26 |
| introduction | The pod can mix Claude Code, Codex, a hosted agent and your own program | TRUE | `frontend/src/v2/components/V2RuntimeControls.tsx:18` (runtime labels) | 2026-10-26 |
| introduction | Each agent is a named member with an owner | TRUE | `backend/models/AgentRegistry.ts:261` (`installedBy`, required, on every installation) | 2026-10-27 |
Expand Down
2 changes: 1 addition & 1 deletion docs/design/landing-demo/Landing390.dc.html
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@
</div>
</div>
<div style="display: flex; flex-direction: column; gap: 20px;">
<div style="width: 342px; height: 214.5px; box-sizing: border-box; border: 1px solid #d0d5dd; border-radius: 6px; overflow: hidden;"><img src="../../assets/readme/connectors-2x.png" width="340" height="212.5" style="display: block;" alt=""></div>
<div style="width: 342px; height: 214.5px; box-sizing: border-box; border: 1px solid #d0d5dd; border-radius: 6px; overflow: hidden;"><img src="../../assets/landing-source/connectors-2x.png" width="340" height="212.5" style="display: block;" alt=""></div>
<div style="display: flex; flex-direction: column; gap: 12px;">
<span class="mono" style="font-size: 12px; letter-spacing: 0.06em; color: #1d3fd1;">CONNECTORS</span>
<div class="disp" style="font-size: 26px; line-height: 30px; text-wrap: balance;">Your chat is the front door</div>
Expand Down
3 changes: 1 addition & 2 deletions frontend/src/v2/landing/__tests__/landingFrames.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@ import path from 'path';

const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..');
const LANDING_ASSETS = path.join(REPO_ROOT, 'frontend/src/assets/landing');
const README_FRAMES = path.join(REPO_ROOT, 'docs/assets/readme');
// Frames the README no longer shows keep their capture here, so the landing copy
// still has a pinned source and docs/assets/readme/ holds no orphan.
const LANDING_SOURCES = path.join(REPO_ROOT, 'docs/assets/landing-source');
Expand All @@ -25,7 +24,7 @@ const PAGE = fs.readFileSync(path.join(__dirname, '..', 'V2LandingPage.tsx'), 'u
const FRAMES: Array<[landing: string, source: string, dir: string]> = [
['activity.png', 'activity-2x.png', LANDING_SOURCES],
['team.png', 'team-2x.png', LANDING_SOURCES],
['connectors.png', 'connectors-2x.png', README_FRAMES],
['connectors.png', 'connectors-2x.png', LANDING_SOURCES],
];

// The README dropped its Bring-your-own frame (#2564) because the capture shows
Expand Down
Loading