Skip to content
Python

One command on the path: openworker

Rohit C Prasad9671e7294c54
diff --git a/README.md b/README.md
index f096d35e..e6d95ff9 100644
--- a/README.md
+++ b/README.md
@@ -100,8 +100,8 @@ cd openworker
bash packaging/setup_dev_env.sh
# 2. Start the local agent server
-.venv/bin/openworker-server --cwd ~/some/project --port 8765
-# (Windows: .venv\Scripts\openworker-server.exe)
+.venv/bin/python -m coworker.server.run --cwd ~/some/project --port 8765
+# (Windows: .venv\Scripts\python -m coworker.server.run ...)
# 3. In a second terminal, start the UI
cd surfaces/gui
diff --git a/coworker/connectors/cli.py b/coworker/connectors/cli.py
index 9217d2ca..7de8194e 100644
--- a/coworker/connectors/cli.py
+++ b/coworker/connectors/cli.py
@@ -81,7 +81,7 @@ def _cmd_send(target: str, text: str) -> int:
def main(argv: list[str] | None = None) -> int:
- parser = argparse.ArgumentParser(prog="openworker-connectors")
+ parser = argparse.ArgumentParser(prog="python -m coworker.connectors.cli")
sub = parser.add_subparsers(dest="cmd", required=True)
sub.add_parser("status")
diff --git a/coworker/remote/service.py b/coworker/remote/service.py
index 44c3d65e..91bbbe29 100644
--- a/coworker/remote/service.py
+++ b/coworker/remote/service.py
@@ -155,7 +155,7 @@ def create_cloud_app(data_dir: str | Path) -> FastAPI:
def main(argv=None) -> None:
parser = argparse.ArgumentParser(
- prog="openworker-acceptor",
+ prog="python -m coworker.remote.service",
description="Acceptor-only cloud service: machines join it; the SPA runs against it in cloud mode.",
)
parser.add_argument("--data-dir", default="~/.config/openworker-cloud")
diff --git a/coworker/server/app.py b/coworker/server/app.py
index a80c8a83..095c47b5 100644
--- a/coworker/server/app.py
+++ b/coworker/server/app.py
@@ -909,7 +909,7 @@ def create_app(manager: SessionManager) -> FastAPI:
if actor is None:
return JSONResponse(
{"error": "board token required (Authorization: Bearer …) — mint"
- " one with `ocw board token` on the serving machine"},
+ " one with `python -m coworker.teams.cli board token` on the serving machine"},
status_code=401,
)
try:
diff --git a/coworker/server/run.py b/coworker/server/run.py
index 5738a886..56ea9912 100644
--- a/coworker/server/run.py
+++ b/coworker/server/run.py
@@ -163,7 +163,10 @@ def main(argv=None) -> None:
maybe_run_runner(list(sys.argv[1:] if argv is None else argv)) # `sandbox-runner ...`
_ensure_ca_bundle()
cfg = load_config() # global config supplies defaults
- parser = argparse.ArgumentParser(prog="openworker-server")
+ # The desktop app's bundled sidecar is a program named openworker-server (packaging/
+ # cli_entry.py); from a checkout the server is run as a module.
+ prog = "openworker-server" if os.path.basename(sys.argv[0]).startswith("openworker-server") else "python -m coworker.server.run"
+ parser = argparse.ArgumentParser(prog=prog)
parser.add_argument("--cwd", default=None, help="optional seed/default workspace")
parser.add_argument("--model", default=cfg.model)
parser.add_argument(
diff --git a/coworker/teams/cli.py b/coworker/teams/cli.py
index 7fd7930c..5b54ca4f 100644
--- a/coworker/teams/cli.py
+++ b/coworker/teams/cli.py
@@ -1,4 +1,4 @@
-"""`ocw` — the board and journal from any shell, for any harness.
+"""The board and journal from any shell, for any harness (`python -m coworker.teams.cli`).
The board is an open surface (OPE-100): the same role-scoped verbs the in-app
agents get, usable by an external agent CLI, a script, or a human. Point it at a
@@ -12,9 +12,9 @@ Backing resolution, in order:
whenever a server is up: two processes must never write one board file.
4. Direct SQLite on the default state dir (nothing else is running).
-`ocw board mcp` serves the same surface as an MCP server on stdio — the way to
+`board mcp` serves the same surface as an MCP server on stdio — the way to
hand a board to an external coding agent: point the agent's MCP config at
-`ocw board mcp --url … --token … --space …` and ask it to claim a work item.
+`python -m coworker.teams.cli board mcp --url … --token … --space …` and ask it to claim a work item.
"""
from __future__ import annotations
@@ -47,7 +47,7 @@ def main(argv: Optional[list[str]] = None) -> int:
def _parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
- prog="ocw", description="OpenWorker team board + journal CLI."
+ prog="python -m coworker.teams.cli", description="OpenWorker team board + journal CLI."
)
sub = parser.add_subparsers(dest="group")
diff --git a/coworker/teams/dialect.py b/coworker/teams/dialect.py
index efbc7519..76ef418d 100644
--- a/coworker/teams/dialect.py
+++ b/coworker/teams/dialect.py
@@ -351,7 +351,7 @@ class RemoteDialect:
def _unwrap(response: Any) -> Any:
if response.status_code == 401:
raise BoardError("board token was not accepted (401) — mint one with"
- " `ocw board token` on the serving machine")
+ " `python -m coworker.teams.cli board token` on the serving machine")
try:
data = response.json()
except ValueError:
diff --git a/coworker/teams/mcp_server.py b/coworker/teams/mcp_server.py
index da746517..9b88915b 100644
--- a/coworker/teams/mcp_server.py
+++ b/coworker/teams/mcp_server.py
@@ -1,7 +1,7 @@
"""`team-board` — the board and journal as an MCP server on stdio.
The way an external coding agent joins a team: its MCP config runs
-`ocw board mcp --url … --token … --space …` (or `--db …` headless), it sees the
+`python -m coworker.teams.cli board mcp --url … --token … --space …` (or `--db …` headless), it sees the
role-scoped board tools, and the user asks it to claim an item and work. Identity
and authority never live here: the dialect is already bound to one actor (token or
local flags), and every write is judged by the store/server — this file is a thin
diff --git a/pyproject.toml b/pyproject.toml
index 89927c9d..91a05f16 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -57,14 +57,10 @@ bedrock = ["boto3>=1.34"]
# OpenShell sandbox provider: the runner's stream is a gRPC call to the OpenShell gateway.
openshell = ["grpcio>=1.60"]
+# One command on the path. The server, the connectors tool, the acceptor and the team
+# board stay runnable as modules (`python -m coworker.server.run`, …) for development.
[project.scripts]
openworker = "coworker.cli:main"
-openworker-server = "coworker.server.run:main"
-openworker-connectors = "coworker.connectors.cli:main"
-openworker-acceptor = "coworker.remote.service:main"
-# The board as an open surface (OPE-100): `ocw board …` / `ocw journal …`,
-# including `ocw board mcp` — the stdio MCP server external harnesses attach to.
-ocw = "coworker.teams.cli:main"
[tool.setuptools.packages.find]
where = ["."]
diff --git a/tests/test_console_scripts.py b/tests/test_console_scripts.py
new file mode 100644
index 00000000..eae28edb
--- /dev/null
+++ b/tests/test_console_scripts.py
@@ -0,0 +1,17 @@
+"""The package puts one command on the path: `openworker`. The server, the connectors
+tool, the acceptor and the team board are run as modules while they are not products."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+ import tomllib
+else: # pragma: no cover
+ import tomli as tomllib
+
+
+def test_only_openworker_is_a_console_script() -> None:
+ pyproject = tomllib.loads((Path(__file__).resolve().parents[1] / "pyproject.toml").read_text(encoding="utf-8"))
+ assert pyproject["project"]["scripts"] == {"openworker": "coworker.cli:main"}