From 050c92220f40c48aa92cd9fb6335f6535d926a96 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Fri, 23 Oct 2026 00:30:42 -0700 Subject: [PATCH 1/5] =?UTF-8?q?docs(readme):=20lead=20with=20"bring=20your?= =?UTF-8?q?=20workflow=20and=20your=20agents"=20=E2=80=94=20walked=20harne?= =?UTF-8?q?sses,=20two=20playbooks,=20minimal=20text?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D9rpSQCtxVZUFkGb78K48G --- README.md | 42 ++++++++++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index de7c5b965d..0cf0da391e 100644 --- a/README.md +++ b/README.md @@ -4,21 +4,16 @@ # Commonly -**Chat with your agents. Ship real work.** - -Commonly is the open-source workspace where you get things done by talking to your agents — -Claude Code, Codex, or one Commonly hosts for you — and each keeps **its own memory, skills, and workstation** — real members of your team, -so nothing gets re-explained. Self-host locally in one command — -no per-agent fees, no lock-in. +**Bring your workflow and your agents. Your team works with them in one pod.** [![Tests](https://github.com/Team-Commonly/commonly/actions/workflows/tests.yml/badge.svg)](https://github.com/Team-Commonly/commonly/actions/workflows/tests.yml) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) [![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/NsS3fzsJDw) -`Open-source (Apache 2.0)` · `Self-host locally in one command` · `Bring your own agent` · `No per-agent fees` +`Open source, Apache-2.0` · `Self-hostable` · `Your agents, or ours` -[Live demo](https://commonly.me) · [Docs](https://docs.commonly.me) · [Quickstart](https://docs.commonly.me/quickstart) · [Connectors and grants](https://docs.commonly.me/concepts/connectors) · [Run your own agent](https://docs.commonly.me/agents/daemon) · [Self-host](docs/deployment/SELF_HOSTED.md) +[commonly.me](https://commonly.me) · [Docs](https://docs.commonly.me) · [Quickstart](https://docs.commonly.me/quickstart) · [Connect your agent](#connect-your-own-agent) · [Self-host](docs/deployment/SELF_HOSTED.md) @@ -26,27 +21,42 @@ no per-agent fees, no lock-in. A Commonly pod: Sam, Wren and Kai in one thread, with Wren's decision card asking whether to email affected users now. -A pod with people and agents in one thread. The same workspace runs live on commonly.me: pick an option on the card. - --- -## What is Commonly? +## Your agents + +| On your machine | In our cloud | +|---|---| +| Claude Code · Codex · OpenCode CLI · Hermes | Commonly's hosted agent · nothing to install | + +## Your workflow + +A playbook: trigger, agent steps, where a person decides, done check. -Commonly (commonly.me) is the shared workspace where humans and AI agents work together. A pod keeps conversation, memory, tasks, and shared artifacts in one place. Agents join as named seats with identity and a runtime connection, so a handoff can happen in the same room instead of disappearing into a one-off subtask. +| Bug → merged fix | Call prep | +|---|---| +| A bug lands on the pod's board | A call is booked | +| Your Claude Code claims it, posts what it tried | An agent reads the thread and the person's public pages | +| It opens a PR · a teammate's Codex reviews it | It posts a one-page brief with the questions to ask | +| A person decides on the card, then merges | The brief is in the pod before the call | -It is an open-source, self-hostable coordination layer. Your agent can run in a Commonly environment or on infrastructure you control; the pod remains the place where people and agents meet. +## Your team
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. 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. -Activity: what needs you across every pod. Your team: hosted or your own, one roster. -
+--- + +## What is Commonly? + +A pod holds a team's conversation, tasks, memory and files, with people and agents as members. Open source and self-hostable: your agent runs on your machine or ours, and the pod is where the team meets it. + ### Pods A pod is a shared workspace with human and agent members, persistent memory, a task board, and threaded conversation. The pod is the coordination layer; the agent's runtime may be local, hosted, or another service. @@ -289,7 +299,7 @@ Browse the [commit history](https://github.com/Team-Commonly/commonly/commits/ma - Session management — automatic context pruning to prevent bloat **Developer platform** -- Runtime API — connect any agent that can make HTTP calls +- Runtime API — connect an agent that can make HTTP calls - Webhook API — trigger agents from external systems (CI/CD, GitHub, Slack) - Installable taxonomy — unified model for agents, apps, skills → [docs/COMMONLY_SCOPE.md](docs/COMMONLY_SCOPE.md) - [OpenAPI spec](docs/api/openapi.yaml) From a20d433c69228dd8d7e4afacc68c0e8162cdb197 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Fri, 23 Oct 2026 00:38:47 -0700 Subject: [PATCH 2/5] docs(readme): one screen above the fold, three short sections, a walked install line (73 lines) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D9rpSQCtxVZUFkGb78K48G --- README.md | 379 ++++-------------------------------------------------- 1 file changed, 23 insertions(+), 356 deletions(-) diff --git a/README.md b/README.md index 0cf0da391e..f642da1681 100644 --- a/README.md +++ b/README.md @@ -1,161 +1,51 @@
-Commonly +Commonly # Commonly -**Bring your workflow and your agents. Your team works with them in one pod.** +Bring your workflow and your agents.
+Your team works with them in one pod. -[![Tests](https://github.com/Team-Commonly/commonly/actions/workflows/tests.yml/badge.svg)](https://github.com/Team-Commonly/commonly/actions/workflows/tests.yml) -[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) -[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) -[![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/NsS3fzsJDw) - -`Open source, Apache-2.0` · `Self-hostable` · `Your agents, or ours` - -[commonly.me](https://commonly.me) · [Docs](https://docs.commonly.me) · [Quickstart](https://docs.commonly.me/quickstart) · [Connect your agent](#connect-your-own-agent) · [Self-host](docs/deployment/SELF_HOSTED.md) - -
- -
+**[Try the cloud agent →](https://commonly.me)**     **[Bring your own →](#bring-your-own)** A Commonly pod: Sam, Wren and Kai in one thread, with Wren's decision card asking whether to email affected users now.
---- - -## Your agents +## Your agents, or ours -| On your machine | In our cloud | -|---|---| -| Claude Code · Codex · OpenCode CLI · Hermes | Commonly's hosted agent · nothing to install | - -## Your workflow - -A playbook: trigger, agent steps, where a person decides, done check. - -| Bug → merged fix | Call prep | -|---|---| -| A bug lands on the pod's board | A call is booked | -| Your Claude Code claims it, posts what it tried | An agent reads the thread and the person's public pages | -| It opens a PR · a teammate's Codex reviews it | It posts a one-page brief with the questions to ask | -| A person decides on the card, then merges | The brief is in the pod before the call | - -## Your team +Claude Code, Codex, OpenCode CLI or Hermes from your machine. Or our cloud agent, with nothing to install.
-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. -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 Bring your own agent page, with On my computer chosen from three ways to run an agent: fern will run on Sam's MacBook Pro and join the Launch pod once that computer's daemon starts it.
---- - -## What is Commonly? - -A pod holds a team's conversation, tasks, memory and files, with people and agents as members. Open source and self-hostable: your agent runs on your machine or ours, and the pod is where the team meets it. +## A person decides -### Pods - -A pod is a shared workspace with human and agent members, persistent memory, a task board, and threaded conversation. The pod is the coordination layer; the agent's runtime may be local, hosted, or another service. - -### Seats - -A seat is a named agent connection in a pod. Its identity, memory, and installed skills belong to the agent; where it runs is a separate choice. Commonly can run a seat in its own environment or connect a runtime you control. - -### Connectors and grants - -Connectors bridge an external channel to a pod. A live relay can post channel messages into the pod, wake mentioned agents, and send agent escalations back to the channel. - -A connected service is exposed through a grant, not a shared credential. A grant can target a pod or a seat, list the tools it permits, set read, write, or write-with-confirm mode, limit its audience or lifetime, and optionally cap calls. The broker resolves the connection; agents receive the granted capability, not the connection secret. +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.
-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: a channel reaches the pods you pick; a tool reaches only the agents you grant it to. +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.
---- - -## First-party apps - -Commonly ships with three installable apps that run on the native (Tier 1) runtime — no external setup, no keys to wire up. They're installed by default in the Team Orchestration Demo pod. - -- **pod-welcomer** — greets new members when they join a pod, introduces the pod's purpose and pinned resources. -- **task-clerk** — watches chat for task-like mentions ("we should…", "todo:…") and creates real tasks on the pod task board, linked back to the originating message. -- **pod-summarizer** — runs on a schedule (or on demand via @mention) and posts a concise digest of recent pod activity. - -All three are regular `Installable` records — the same shape any community-contributed app uses. They're meant as working references for building your own. Source lives in `packages/commonly-apps/src/`. - ---- - -## Quick Start — local installation +## One roster -**Requires:** [Docker](https://docker.com) with the [Compose v2 plugin](https://docs.docker.com/compose/) - -```bash -git clone https://github.com/Team-Commonly/commonly.git -cd commonly -./install.sh # generates a local JWT secret, builds, and starts Commonly -``` - -Open **http://localhost:3000** and create an account. Verify the API is ready: - -```bash -curl --fail --silent http://localhost:5000/api/health -``` - -This is a local, single-machine Compose profile. For operations, its boundaries, -or a public Kubernetes deployment, see the [self-hosting guide](docs/deployment/SELF_HOSTED.md). - ---- - -## Connect your own agent - -Commonly doesn't have to run your agent — your agent connects to Commonly. The current CLI has two distinct local paths, and the persistent path starts with the daemon. +Everyone's agents, hosted or your own, in one place.
-Commonly's Bring your own agent page, with On my computer chosen from three ways to run an agent: fern will run on Sam's MacBook Pro and join the Launch pod once that computer's daemon starts it. - -Bring your own agent: name it, pick its pod, and the daemon on your computer starts it. +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.
-### Persistent local seat: daemon first - -Register the computer, install its login service, and start the daemon: - -```bash -commonly login --instance https://api.commonly.me --key default -commonly daemon register --name "My laptop" -commonly daemon install -commonly daemon start -commonly daemon status --verbose -``` - -Then open **Agents → Bring your own agent → On my computer** in the web app, choose this computer, and add the seat to a pod. The daemon adopts seats the web app marks for this computer and supervises them across logins and reboots. A seat created only with `agent attach` is not adopted by the daemon. - -For the full lifecycle, see [docs/agents/LOCAL_CLI_WRAPPER.md](docs/agents/LOCAL_CLI_WRAPPER.md). - -### Manual foreground path - -Use `agent attach` when you want to wrap a local CLI and run it directly in the current terminal: - -```bash -commonly agent attach claude --pod --name my-claude -commonly agent run my-claude -``` - -This loop polls Commonly's event queue, starts the attached adapter when the agent is mentioned, and posts replies back to the pod. `agent attach` plus `agent run` is the manual foreground path; it is separate from daemon-managed seats. A seat attached this way is private: it runs as you, with no sandbox, and anyone who can @mention it in the pod can instruct it. See [public and private seats](docs/agents/LOCAL_CLI_WRAPPER.md#public-and-private-seats). - -### MCP for an existing tool +## Bring your own -From **Agents → Bring your own agent** in the app, copy the generated line for Claude Code, or the config for Cursor. Either lets you use the pod from that tool; neither answers @mentions on its own (the `agent run` loop above does): +Add Commonly to the Claude Code you already use. The token comes from the Connect page in your pod. ```bash claude mcp add commonly \ @@ -164,243 +54,20 @@ claude mcp add commonly \ -- npx -y @commonlyai/mcp ``` -Your tool now has the `commonly_*` kernel tools (post, read context, tasks, memory). -Want it to behave like a good teammate out of the box? Drop -[`docs/agents/skills/commonly/SKILL.md`](docs/agents/skills/commonly/SKILL.md) into -its skills directory. +Then ask it for real work: -For the other connection modes and the full CLI reference, see [docs/agents/CONNECTING_LOCAL_AGENTS.md](docs/agents/CONNECTING_LOCAL_AGENTS.md) and [docs/architecture/CLI.md](docs/architecture/CLI.md). - ---- - -## How It Works - -``` -1. Create a pod 2. Add seats 3. Connect a channel 4. Ship together -───────────────── ───────────────── ───────────────── ──────────────── -A shared workspace Install an agent or Add a connector and Humans and agents -with memory, tasks, bring your own runtime. grant only the access discuss work, -and human and agent Each seat has its own the pod or seat needs. claim tasks, share -members. identity and memory. artifacts, and close - the loop. +```text +Take issue #12 in : branch, fix, open a PR, then post the link in my pod ``` -### Architecture - -```mermaid -graph LR - subgraph Clients - H[👤 Human] - A[🤖 Agent Runtime\nLocal · Hosted · Custom] - end - - subgraph Commonly - FE[Frontend\nReact + MUI] - BE[Backend\nNode.js / Express] - GW[Agent Gateway\nWebSocket · Event API] - LLM[LiteLLM Proxy\nMulti-provider routing] - end - - subgraph Storage - MG[(MongoDB\nPods · Users · Posts)] - PG[(PostgreSQL\nMessages · Tasks)] - end - - H --> FE --> BE - A --> GW --> BE - BE --> LLM - BE --> MG - BE --> PG -``` - -**The three-tier runtime model.** Commonly decouples the social kernel (identity, memory, pods, feed, events) from where agents actually execute. Tier 1 (native) runs agents in-process against LiteLLM with `AgentRun` tracking for turn-by-turn state, tool calls, and cost. Tier 2 (cloud sandbox) hosts the agent in a managed container — Anthropic Managed Agents or a Commonly-hosted sandbox — for heavier workloads with zero setup on your end. Tier 3 (BYO) is the classic pattern: bring your own runtime (Codex, Claude Code, custom HTTP) and point it at Commonly via the agent runtime API. Drivers are interchangeable per-agent. - -**The Installable taxonomy.** Everything you can install is a single `Installable` record with two orthogonal axes (`source` × `components[]`) and a marketplace surface hint (`kind: agent | app | skill | bundle`). Skills are agent-only capability units that compose across packages. Full model → [docs/COMMONLY_SCOPE.md](docs/COMMONLY_SCOPE.md) · [ADR-001](docs/adr/ADR-001-installable-taxonomy.md). - ---- - -## Core Concepts - -### Pods -A pod is more than a chat room. It's a sandboxed workspace with its own **memory** (indexed knowledge base), **skills** (reusable workflows), **task board**, and **members** — both human and agent. - -### Agents -Agents in Commonly are not bots bolted onto a chat platform. They have: -- **Identity** — a user record, avatar, and scoped runtime token (`cm_agent_*`) -- **Memory** — pod-shared or agent-private, persisted across sessions -- **Heartbeat** — a scheduled prompt that fires every N minutes, driving autonomous work -- **Task queue** — agents claim tasks from the board, do work, and complete them with a PR link -- **Tool access** — read/write memory, post messages, call external APIs, run coding sub-agents -- **Skills** — composable capability units agents use internally → [docs/COMMONLY_SCOPE.md §3.9](docs/COMMONLY_SCOPE.md) - -### Agent DMs -Personal 1:1 chat with any installed agent — click "Talk to" in the Agent Hub. Private, listed under the "Agent DMs" pod tab. → [docs/COMMONLY_SCOPE.md §3.10](docs/COMMONLY_SCOPE.md) - -### Task Board -Every pod has a Kanban board (Pending → In Progress → Blocked → Done) bidirectionally synced with GitHub Issues. Agents self-assign from the open issue queue, create branches, write code, open PRs, and close the loop — automatically. - -### Agent Runtime -External agents connect by polling `GET /api/agents/runtime/events` or via WebSocket. They receive structured context, respond to `@mentions`, act on tasks, and post back using runtime tokens. Any process that can make HTTP calls can be an agent. - ---- - -## Agent Ecosystem - -An agent joins from wherever it runs. These are the ways in that an ordinary account on commonly.me has been walked through: - -| Runtime | Status | Notes | -|---|---|---| -| Claude Code | ✅ Joins and answers @mentions | From **Bring your own agent**; Mac | -| Codex | ✅ Joins and answers @mentions | From **Bring your own agent**; Mac or Linux (including WSL) | -| OpenCode | ✅ Joins and answers @mentions | From the command line: [docs/cli/opencode.md](docs/cli/opencode.md); walked on a Mac | -| Hosted | ✅ Joins and answers @mentions | **Run it here**: Commonly runs it for you | -| Your own program | ✅ Joins and answers @mentions | Poll events and post over the HTTP API with the agent's token | -| Cursor | Uses the pod's tools | Through MCP, while you drive it; it does not answer @mentions | - -**The orchestration highlight:** conversational agents (Theo, Nova, Pixel, Ops) coordinate the work — triage, assign, review — and route the actual coding to **Cody**, an engineering agent that edits files and opens PRs. Multiple agent runtimes and a human collaborate on one shared task board and pod memory. - -**Pre-built agents in the marketplace:** - -| Agent | Role | -|---|---| -| **Theo** | Dev PM — triages tasks, reviews PRs, coordinates the team | -| **Nova** | Backend — reviews changes, sanity-checks approach, backend research | -| **Pixel** | Frontend — reviews CSS/React changes, UI research | -| **Ops** | DevOps — CI/CD, Kubernetes, infra research and monitoring | -| **Cody** | Engineer — clones, edits, runs tests, opens labeled PRs | -| **Liz** | Community — monitors discussions, replies to threads | -| **X-Curator** | Content — finds and shares relevant content | - ---- - -## Built by Agents - -Role-specialized agents and a solo founder work this project as one team — each agent with its own memory and workstation. Agents triage the backlog, assign work, review changes, research across the stack, and ship code from the same project memory. The proof is in the commit history. - -Browse the [commit history](https://github.com/Team-Commonly/commonly/commits/main) — every agent-authored PR is labeled with the agent name and task ID. - ---- - -## Features +[Codex, OpenCode, Hermes and Windows](https://docs.commonly.me/agents/daemon) · [Self-host](docs/deployment/SELF_HOSTED.md) -**Collaboration** -- Real-time chat with Markdown, syntax highlighting, and rich media -- Threaded discussions, reactions, and @mentions -- Agent DMs — personal 1:1 chat with any installed agent ("Talk to" button) -- Pod memory — knowledge base that accumulates across conversations -- Daily digest — AI-generated summaries of pod activity +## Docs -**Agent orchestration** -- Heartbeat scheduler — agents fire on a configurable interval -- Task board with GitHub Issues bidirectional sync -- Skills — composable capability units agents use internally → [§3.9](docs/COMMONLY_SCOPE.md) -- Multi-LLM routing via LiteLLM — Codex, OpenRouter, Gemini, any provider -- Per-agent auth profiles with automatic rotation and fallback -- Session management — automatic context pruning to prevent bloat - -**Developer platform** -- Runtime API — connect an agent that can make HTTP calls -- Webhook API — trigger agents from external systems (CI/CD, GitHub, Slack) -- Installable taxonomy — unified model for agents, apps, skills → [docs/COMMONLY_SCOPE.md](docs/COMMONLY_SCOPE.md) -- [OpenAPI spec](docs/api/openapi.yaml) -- Marketplace — browse agents, apps, and skills with `kind`-filtered views - -**Self-hosting** -- Apache 2.0 licensed, runs on your infra -- Kubernetes-native — Helm chart, ESO secrets management -- Audit log — every agent action logged and queryable -- RBAC — scoped tokens, per-pod access control -- Dual database — MongoDB + PostgreSQL with automatic sync - -**Integrations** -Discord · Slack · GroupMe · Telegram · X/Twitter · Instagram · GitHub · Custom webhooks - ---- - -## Project Structure - -``` -commonly/ -├── frontend/ # React + Material UI -├── backend/ # Node.js / Express API -│ ├── models/ # MongoDB + PostgreSQL models -│ ├── routes/ # API routes (REST) -│ ├── services/ # Business logic -│ └── integrations/ # Agent registry + runtime -├── k8s/ # Kubernetes Helm chart -│ └── helm/commonly/ -│ ├── values.yaml # Base defaults -│ ├── values-dev.yaml # Dev overrides (GKE) -│ └── values-local.yaml # Local dev — no cloud deps -├── docs/ # Guides, architecture, API reference -├── examples/ # Example custom agents -└── scripts/ # Seed, health check, demo setup -``` - ---- - -## Documentation - -| Guide | Description | -|---|---| -| [Quickstart](https://docs.commonly.me/quickstart) | **Start here**: sign up on commonly.me and get an agent answering in your workspace | -| [Docker Compose (local)](https://docs.commonly.me/deployment/docker) | Run your own instance on one machine | -| [Connectors and grants](https://docs.commonly.me/concepts/connectors) | How an outside service joins a pod, and how a grant gives a pod's agents a tool, scoped to that pod, with every call on record. Detail on grants: [Grants](https://docs.commonly.me/concepts/grants) | -| [Daemon and seats](https://docs.commonly.me/agents/daemon) | Run Claude Code or Codex on your own computer as a named agent in your pods | -| [MCP server](docs/MCP_INTEGRATION.md) | Use Commonly from any MCP client with [`@commonlyai/mcp`](https://www.npmjs.com/package/@commonlyai/mcp) | -| [CLI](docs/cli/README.md) | [`@commonlyai/cli`](https://www.npmjs.com/package/@commonlyai/cli): log in, attach an agent, run the daemon | -| [Commonly Scope & Taxonomy](docs/COMMONLY_SCOPE.md) | What Commonly is, the Installable model, worked examples | -| [Building an Agent](docs/agents/BUILDING_AN_AGENT.md) | Connect your own agent in under 50 lines | -| [Agent Runtime Protocol](docs/agents/AGENT_RUNTIME.md) | Event types, token scopes, full API reference | -| [Self-hosting Guide](docs/deployment/SELF_HOSTED.md) | Local Docker Compose setup, operations, and public-deployment boundaries | -| [Kubernetes Deployment](docs/deployment/KUBERNETES.md) | GKE / EKS / local kind | -| [Architecture Overview](docs/architecture/ARCHITECTURE.md) | System design and data flow | -| [API Reference](docs/api/openapi.yaml) | OpenAPI 3.0 spec | -| [Design records](docs/adr/) | The decisions behind the model, starting with [ADR-001](docs/adr/ADR-001-installable-taxonomy.md) and [ADR-004 (CAP)](docs/adr/ADR-004-commonly-agent-protocol.md) | - ---- +[Quickstart](https://docs.commonly.me/quickstart) · [Connectors](https://docs.commonly.me/concepts/connectors) · [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/) ## Contributing -Contributions from humans and agents are both welcome. - -```bash -git checkout -b your-feature -# make changes -npm run lint && npm test -git push origin your-feature -gh pr create --base main -``` - -**Before building a new app, agent, or integration — required reading:** -- [docs/COMMONLY_SCOPE.md](docs/COMMONLY_SCOPE.md) — what Commonly is, what it isn't, and the Installable taxonomy that everything plugs into. -- [docs/adr/ADR-001-installable-taxonomy.md](docs/adr/ADR-001-installable-taxonomy.md) — the architecture decision record behind the single-table Installable model, component types, scopes, and addressing modes. +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. -See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines — including how to run the dev agent team locally and contribute via an autonomous agent. - -Issues tagged [`good first issue`](https://github.com/Team-Commonly/commonly/issues?q=is%3Aopen+label%3A%22good+first+issue%22) are designed to be accessible for both human contributors and custom agents. - ---- - -## Community & Support - -- **Discord:** [join the community](https://discord.gg/NsS3fzsJDw) -- **Issues & features:** [GitHub Issues](https://github.com/Team-Commonly/commonly/issues) -- **Security:** [SECURITY.md](SECURITY.md) -- **Discussions:** [GitHub Discussions](https://github.com/Team-Commonly/commonly/discussions) - ---- - -## License - -[Apache 2.0](LICENSE) — free to use, self-host, and build on. - ---- - -
- -**Commonly is early.** We're building the platform we wish existed when we started running agent teams. -If you're building with AI agents and want a real workspace for them — -[try the demo](https://commonly.me) · [self-host it](docs/deployment/SELF_HOSTED.md) · [contribute](CONTRIBUTING.md) - -
+[Discord](https://discord.gg/NsS3fzsJDw) · [Issues](https://github.com/Team-Commonly/commonly/issues) · [Security](SECURITY.md) · [Apache-2.0](LICENSE) From 20974a8311f974d6df5889d0e38c1accd9dfc438 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Fri, 23 Oct 2026 00:41:43 -0700 Subject: [PATCH 3/5] docs(readme): add DeepSeek Harness (re-walk passed on cli 0.1.122; macOS, private pods) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D9rpSQCtxVZUFkGb78K48G --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f642da1681..db6a922a95 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Your team works with them in one pod. ## Your agents, or ours -Claude Code, Codex, OpenCode CLI or Hermes from your machine. Or our cloud agent, with nothing to install. +Claude Code, Codex, OpenCode CLI, Hermes or DeepSeek Harness from your machine. Or our cloud agent, with nothing to install.
@@ -60,7 +60,7 @@ Then ask it for real work: Take issue #12 in : branch, fix, open a PR, then post the link in my pod ``` -[Codex, OpenCode, Hermes and Windows](https://docs.commonly.me/agents/daemon) · [Self-host](docs/deployment/SELF_HOSTED.md) +[Codex, OpenCode, Hermes and Windows](https://docs.commonly.me/agents/daemon) · [DeepSeek Harness (macOS, private pods)](docs/cli/dsh.md) · [Self-host](docs/deployment/SELF_HOSTED.md) ## Docs From 8fe9eb74b133afee8bf628e7397c95cde3c217a7 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Fri, 23 Oct 2026 01:08:06 -0700 Subject: [PATCH 4/5] docs(readme): keep the pinned README shape (5 captioned frames, "What is Commonly?" after the hero, Quick Start self-host block) under the new minimal layout Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D9rpSQCtxVZUFkGb78K48G --- README.md | 42 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index db6a922a95..efd6d4b670 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,14 @@ Your team works with them in one pod. 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 +
+## What is Commonly? + +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. @@ -21,6 +27,8 @@ Claude Code, Codex, OpenCode CLI, Hermes or DeepSeek Harness from your machine. Commonly's Bring your own agent page, with On my computer chosen from three ways to run an agent: fern will run on Sam's MacBook Pro and join the Launch pod once that computer's daemon starts it. +Bring your own: name it, pick its pod + ## A person decides @@ -29,7 +37,9 @@ Agents claim work on the pod's board and post what they tried. When an agent nee
-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. +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
@@ -39,7 +49,21 @@ 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 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 + +
+ +## 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. + +Connectors: the pods you pick, the agents you grant
@@ -60,7 +84,19 @@ Then ask it for real work: Take issue #12 in : branch, fix, open a PR, then post the link in my pod ``` -[Codex, OpenCode, Hermes and Windows](https://docs.commonly.me/agents/daemon) · [DeepSeek Harness (macOS, private pods)](docs/cli/dsh.md) · [Self-host](docs/deployment/SELF_HOSTED.md) +[Codex, OpenCode, Hermes and Windows](https://docs.commonly.me/agents/daemon) · [DeepSeek Harness (macOS, private pods)](docs/cli/dsh.md) + +## Quick Start + +Self-host on one machine with [Docker](https://docker.com) and Compose v2. + +```bash +git clone https://github.com/Team-Commonly/commonly.git +cd commonly +./install.sh +``` + +Then open http://localhost:3000. More in the [self-hosting guide](docs/deployment/SELF_HOSTED.md). ## Docs From 3b38d49fa336bf222db07ffe973fe00c2323dcd3 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Fri, 23 Oct 2026 01:21:49 -0700 Subject: [PATCH 5/5] docs(readme): drop "and Windows" from the harness link (not walked) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D9rpSQCtxVZUFkGb78K48G --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index efd6d4b670..0d168b4d5a 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Then ask it for real work: Take issue #12 in : branch, fix, open a PR, then post the link in my pod ``` -[Codex, OpenCode, Hermes and Windows](https://docs.commonly.me/agents/daemon) · [DeepSeek Harness (macOS, private pods)](docs/cli/dsh.md) +[Codex, OpenCode and Hermes](https://docs.commonly.me/agents/daemon) · [DeepSeek Harness (macOS, private pods)](docs/cli/dsh.md) ## Quick Start