company-os

Host-agnostic multi-agent company framework. Install into any repo; it compiles a neutral .company-os/ source into the host(s) you enable (Cursor today; Claude/Codex later).

Extracted from a production consumer application with git history preserved.

Releases: v0.31.0 (latest) · see CHANGELOG.md · Publishing · Releasing

Documentation: docs/README.md · Company OS handbook (full project guide)

New repo? Adopt in 5 commands · Migrating? Consumer adoption · Hosting? Hosted dashboard playbook

Install (pinned)

pip install company-os==0.31.0

Or from git tag:

pip install "git+https://github.com/mohitmeena144/company-os@v0.31.0"

For local editable installs on the framework repo:

pip install -e ".[dev]"

Virtual environment (auto)

From any consumer repo with a .venv (or venv) at the project root, you can run company-os or cos without manually activating the venv first. The CLI walks up from your current directory, finds the project venv, and re-runs itself with that Python (works on macOS/Linux and Windows).

Manual activation (optional):

Set COMPANY_OS_NO_VENV_BOOTSTRAP=1 to disable auto-venv (CI, tests).

Commands

cos is an alias for company-os (same entrypoint). Full reference: Company OS handbook § CLI.

Top-level commands: init · update · status · doctor · version · migrate-legacy · link · unlink · sprint · todos · flows · qa · run · budget · metrics · dashboard · reports · hub · agent-run · scheduler · agent · agents · pods · hosting · remote · plugin · linear · docs · sheets · release

Edit workflow content in .company-os/ (rules, skills, agents, overlays) — then company-os update. Do not edit generated .cursor/ or AGENTS.md directly.

Core

company-os init --name myproject --host cursor          # scaffold .company-os/ + compile
company-os update [--force]                             # recompile host files
company-os status                                     # version, hosts, plugins, drift
company-os doctor --check                             # validate config; exit 1 on problems
company-os doctor --check-hub --check-metrics         # hub registry + metrics health
company-os version
company-os migrate-legacy [--dry-run]                 # copy legacy .claude/company/ state
company-os link [--name slug]                         # register repo in ~/.company-os/registry.json
company-os unlink

Sprint, todos, flows, QA

company-os sprint board                               # kanban (add --json for machines)
company-os sprint ref --id N                          # task detail / Linear link
company-os sprint advance --id N --by developer --note "…"
company-os sprint set-task-status --id N --to in-progress
company-os todos list
company-os todos add --title "…" --assignee ceo
company-os flows status                               # modes + kill switch
company-os flows arm nightly-ceo --cap 3
company-os flows allowed email-campaign --agent sales # budget/cap gate (exit 0 = ok)
company-os flows run email-campaign                   # one-shot autonomous validation
company-os qa run --branch S12T42/fix-login           # Playwright sprint QA

Observability (runs, budget, dashboard, hub)

company-os run list [--limit 20]                      # agent run audit trail
company-os run start developer --host cursor --task-id N
company-os run finish run-abc --status succeeded --learn "…"   # LEARNED → MEMORIES.md
company-os budget status                              # monthly spend vs caps
company-os budget set-cap --usd 50                    # cap override (v0.30+)
company-os budget hub-status                          # aggregate linked repos
company-os metrics record developer --json '{"tasksCompleted":3}'
company-os dashboard [--port 8787] [--all]            # local board; --all = hub rollup
company-os dashboard --mode edit-syncback             # writable + sync-outbox intents
company-os reports read analytics                     # latest agent report
company-os hub status [--verbose]

Agent execution (API runner, scheduler, scaffolding)

company-os agent-run providers                        # anthropic / openai / cursor / ollama
company-os agent-run config                           # resolved runner.yaml
company-os agent-run agent developer --task "…" --provider openai --model gpt-4o --tools
company-os agent-run flow email-campaign --task "…" --branch dev --campaign my-campaign
company-os scheduler run [--dry-run]                  # due schedule-triggered agents
company-os scheduler status
company-os agents list
company-os agents new --name weekly-ceo --pod oversight --trigger schedule:weekly
company-os pods list                                  # per-consumer pod gating
company-os pods enable sales

Hosting and remote mirror

company-os hosting doctor                             # hosting.yaml + sync health
company-os hosting sync --pull                        # git pull on hosted mirror
company-os hosting sync --push                      # push state to hosted dashboard
company-os hosting tenant list                        # multi-tenant registry
company-os hosting provision --slug feedback-ai --repo-url https://…
company-os remote auth-status
company-os remote serve --host 0.0.0.0 --port 8790    # record + sync-state + webhooks
company-os remote push --state                        # push runs/state to hosted mirror
company-os remote pull --outbox --loop --reconcile    # replay hosted write-back

Integrations (plugins, Linear, docs, sheets, release)

company-os plugin list                                # sales, social, media, seo
company-os plugin enable sales
company-os plugin doctor
company-os plugin sales pipeline board              # run packaged plugin scripts
company-os linear status                              # dry-run sync counts
company-os linear sync                                # incremental Linear push
company-os linear migrate                             # one-time local → Linear
company-os docs generate                              # company reference tables
company-os docs check
company-os sheets sync                                # export sprint/todos (needs [google])
company-os release check --build --tag v0.31.0        # version pins + wheel build

Adopting in another repo: docs/adopt-in-5-commands.md (new) or docs/consumer-adoption.md (migrate).

Legacy (retired in v0.14+)

• .claude/company/scripts/ — removed; use company-os / cos CLI only
• One-off utilities quarantined in tools/legacy-scripts/

Development

pytest -q
company-os version

Requires Python 3.10+.