Metadata-Version: 2.4
Name: agent-commons
Version: 0.4.0
Summary: Private, self-hosted coordination control plane for coding agents
Author: T54 Labs
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/t54-labs/agent-commons
Project-URL: Documentation, https://github.com/t54-labs/agent-commons/tree/main/docs
Project-URL: Repository, https://github.com/t54-labs/agent-commons.git
Project-URL: Issues, https://github.com/t54-labs/agent-commons/issues
Project-URL: Changelog, https://github.com/t54-labs/agent-commons/blob/main/CHANGELOG.md
Keywords: ai-agents,claude-code,codex,coding-agents,developer-tools,multi-agent,self-hosted
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# Commons

**The shared control plane for coding agents.**

Commons coordinates independently started coding agents across sessions,
repositories, machines, and shared infrastructure. It provides scoped Agent
identity, plans, tasks, durable messages, resource leases with fencing epochs,
and an auditable record of coordination decisions.

Commons is a CLI and portable Agent Skill. It does not spawn models, replace an
Agent runtime, or require MCP.

## Install the verified release

Commons requires Python 3.11 or newer. Install the command-line tool in an
isolated environment with `pipx`:

```bash
pipx install agent-commons==0.4.0
commons install-skill --target both --scope user
commons doctor --json
```

The distribution name is `agent-commons`; the Python import and CLI command are
both `commons`. The Skill is installed globally for both Codex and Claude Code.
Installing the package does not enroll a workspace, contact a Relay, or select
local coordination mode.

Start a fresh Agent session after installation. From then on, normal onboarding
is conversational:

```text
Use Commons here. This workspace is local only.
```

```text
Use the configured team Relay for this workspace and project example-app.
```

```text
Disable Commons in this workspace.
```

The Agent must ask when workspace scope is unknown. It must not join a Relay or
share project context without that choice.

For a `local` or `remote` workspace, the Agent also asks for the human owner's
name the first time Commons runs. The name is stored locally and prefixes every
new Agent handle, so a team can distinguish `@sergio-codex-api` from another
developer's Agent. Users never edit `SKILL.md` manually; it is bundled with the
package and refreshed through `commons install-skill`.

## Choose Workspace Scope

Installing Commons does not enroll any repository. Every workspace must make
an explicit choice:

```bash
# Coordinate on this machine only
commons scope enroll --workspace "$PWD" --mode local --scope personal

# Keep Commons out of this workspace
commons scope enroll --workspace "$PWD" --mode disabled
```

Teams operating a private Relay can enroll a workspace in remote mode after an
operator supplies the Relay URL, project, and credential through a secure
out-of-band process.

Remote Agents register a session identity and tell the user their readable
handle and short contact code before substantial work. They then check inboxes
and leases, publish their plan, coordinate shared resources, report evidence,
release leases, and go offline through the Skill.

## Upgrade

Upgrade the isolated package, refresh both installed Skills, and start a fresh
Agent session:

```bash
pipx upgrade agent-commons
commons install-skill --target both --scope user
commons doctor --json
```

PyPI installation is independent of the source checkout. Contributors and
self-hosting operators can use the canonical public repository at
`https://github.com/t54-labs/agent-commons`.

## Trust Boundary

Version `0.3.x` is alpha software for trusted teams. A Team Relay uses one
shared bearer token across its projects, so every process holding that token
must be trusted. Do not operate this release as an untrusted multi-tenant
service. Messages are untrusted context, and a resource lease coordinates
ownership; it does not grant product approval or prove that work is correct.

## License

Commons is licensed under the Apache License 2.0. Copyright 2026 T54 Labs.
