• Org -> Team edits the company architecture and roles.
• Org -> Employees hires talent into vacant roles.
• Team Roster -> Deploy turns a hired employee into a visible office agent.
• The Workspace composer selects the Task Mode execution agent.
• The role inspector can set runtime policy and preferred external agent for Company Mode roles.
• During execution, Workspace Agents and the Execution Progress panel show which role is active, which work item it owns, and which execution agent is doing the concrete work.

macOS

# Install uv with Homebrew, or use the official standalone installer.
brew install uv
# curl -LsSf https://astral.sh/uv/install.sh | sh

cd /path/to/OpenOPC
uv python install 3.12
uv venv --python 3.12
source .venv/bin/activate

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"

cd /path/to/OpenOPC
uv python install 3.12
uv venv --python 3.12
source .venv/bin/activate

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

cd C:\path\to\OpenOPC
uv python install 3.12
uv venv --python 3.12
.\.venv\Scripts\Activate.ps1

Windows Command Prompt

winget install --id=astral-sh.uv -e
:: Or run the standalone installer from cmd:
:: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

cd C:\path\to\OpenOPC
uv python install 3.12
uv venv --python 3.12
.venv\Scripts\activate.bat

• Python: >=3.10. Current required dependencies do not all publish Python 3.9-compatible releases.
• uv is recommended for local development and release testing. If you prefer classic pip, create and activate a Python >=3.10 virtualenv, then run python -m pip install -e ..
• If virtualenv activation is blocked, stay unactivated and run commands with uv run ....
• See the official uv installation and Python management docs for alternative package managers and managed Python details.
• Node.js: >=18 is needed when the Office UI frontend must be built.
• opc ui auto-installs missing aiohttp / aiosqlite and auto-builds the frontend if needed.
• If you have not installed external agent CLIs yet, run opc init --no-external-agent-preflight to skip the first-run external-agent checks.
• Browser tools are native Playwright tools. Install Chromium with python -m playwright install chromium before asking agents to browse pages.

python -m pip install -e .
python -m pytest

cd opc/plugins/office_ui/frontend_src
npm install
npm run typecheck
npm run build

The frontend build output is served from opc/plugins/office_ui/frontend_dist/.

Start it with:

opc ui
opc ui --port 9000 --project demo
opc ui --rebuild

Visual Tour

Scroll horizontally to browse the Office UI walkthrough. Each screenshot keeps its short guide text attached.

The Office UI has three primary pages:

Workspace

The Workspace page is the default screen.

Start Work From The UI

1. Create or select a project from the top project selector.
2. In Workspace, click New Chat.
3. In the composer, choose Task or Company.
4. For Task Mode, choose the agent: OpenOPC Native, Codex, Claude Code, Cursor, or OpenCode.
5. For Company Mode, choose Corporate or a saved org architecture.
6. Send the brief.

Once the first message is sent, the mode and task agent are locked for that chat. Use the locked-mode popover to continue in a new chat with a different mode.

Company Mode In The UI

Company Mode turns one brief into a runtime session plus role-owned work items.

To inspect the detailed workflow for a role, open a company-mode session and click a role/work item in the Chat progress card or Agents tab. The Execution Progress panel shows each work item, its status, activity sections, tool progress, handoffs, review targets, and execution turn metadata.

Kanban

• Task Mode: the kanban is a project-level board. You can quick-create tasks in Todo, start them, and inspect each task from the right panel.
• Company Mode: the active board follows the selected runtime session. Cards represent company work items and move from planning/execution/review/done according to backend runtime state.
• Manual drag between status columns is intentionally restricted when runtime owns the state. Same-column reorder is supported where applicable.

Office

Use the Office page when you want a visual view of the running team.

• Click an agent character or row to inspect status, current tool, current task, role, office, and seat.
• Use the office/seat controls to move an agent.
• Sub-agents can be shown or hidden.
• Agents created from employees or templates appear in the office and are persisted in .opc/ui_state.db.

Org

The Org page is where company structure becomes runnable.

To create a new company: open Org, click New organization, enter a name, add at least two members with responsibilities and reporting lines, review, and create. OpenOPC saves it automatically and switches the composer to Company / <your org>.

To recruit: import talent templates first, then open Org -> Employees, search a template, click Hire, choose a vacant role, and deploy the employee from Team Roster if you want it visible in the Office page.

opc talent import /path/to/agency-agents

OpenOPC exposes both high-level natural-language commands and lower-level UI/service commands.

Conceptually OpenOPC has two execution modes: task and company. Some lower-level CLI/service commands still expose org as a compatibility selector for Company Mode with a saved organization architecture; in the UI this appears as Company plus an architecture choice.

Common Commands

# Chat
opc chat
opc chat -p demo --mode task --agent native "Inspect the failing tests"
opc chat -p demo --mode company --company-profile corporate "Ship this change with review"

# Scriptable execution
opc exec -p demo --mode task --agent codex --stream-json "Run the migration check"
opc exec -p demo --mode company --company-profile corporate "Draft the research report"

# Project lifecycle
opc project list
opc project create demo
opc project switch demo

# Sessions
opc session list -p demo
opc session create "New feature" -p demo --mode company
opc session send <task_id> "Continue with implementation" -p demo
opc session stop <task_id> -p demo
opc session continue <task_id> "Proceed after review" -p demo

# Runtime inspection
opc runtime status -p demo
opc runtime logs <task_id> -p demo
opc work-item list -p demo
opc work-item show <work_item_id> -p demo
opc comms state <task_id> -p demo

# Recruitment
opc talent import /path/to/agency-agents
opc talent hire <template_id> <role_id> -p demo

Interactive Slash Commands

Run opc chat, then use slash commands:

/status
/mode task
/mode company corporate
/agent codex
/project switch demo
/session list
/runtime --full
/logs <task_id> --full
/comms <task_id> --full
/org
/talent list
/market list

See docs/cli-chat-slash.md for the full command table.

opc exec -p demo --mode org --org hku_research_lab "Draft the research report"
opc session create "Research sprint" -p demo --mode org --org hku_research_lab

LLM Keys

After opc init, edit .opc/config/llm_config.yaml in the repo-local OPC home. If you set OPC_HOME, edit $OPC_HOME/config/llm_config.yaml instead.

The template leaves secrets empty. Write your key directly into the file:

llm:
  default_model: "openai/gpt-5.4"
  api_base: "https://openrouter.ai/api/v1"
  api_key: "sk-or-v1-..."   # your OpenRouter (or other provider) API key

  max_tokens: 32768         # max output tokens per request; lower it if your
                            # model's output cap is smaller
  # context_window: 128000  # total input window. Usually auto-detected via
                            # litellm; unmapped models fall back to 128000.
                            # Uncomment and set only when the fallback is
                            # wrong for your model.

Then verify with opc status.

If you prefer not to store the key in the file, leave api_key empty and set api_key_env to the name of an environment variable that holds it (e.g. api_key_env: "OPENROUTER_API_KEY").

Approval & Agent Permissions

The autonomy section of .opc/config/system_config.yaml controls how much an agent can do without asking. The key knob is max_auto_approve_risk — the highest risk level that can be auto-approved:

autonomy:
  max_auto_approve_risk: medium   # low | medium | high | critical
  allow_native_tool_auto_approval: true
  tool_first_use_approval: true   # first use of each tool always asks

Every native tool call is risk-classified before it runs: known destructive commands (rm -rf, drop table, force-push, …) and sensitive keywords (credentials, deploys, …) are high/critical and always escalate to a human; allowlisted safe prefixes (ls, git status, …) are low; everything else is medium and goes through an LLM review before auto-approval.

• medium (default): balanced — ordinary commands run without prompts; dangerous ones escalate.
• low: strict — anything not on the safe allowlist asks for approval. Recommended for shared or production machines.
• high/critical: permissive — only for throwaway sandboxes.

The first time a tool is used you are always prompted (unless the tool is in tool_approval_exemptions), and your “Always allow” choices accumulate in a per-project allowlist.

External Agents

Task Mode can explicitly select an execution agent:

opc chat -p demo --mode task --agent codex "Implement the change"

Available values are native, codex, claude_code, cursor, and opencode. Configure command names, flags, timeouts, session reuse, and approval behavior in .opc/config/agent_config.yaml.

In Company Mode, roles can prefer external agents through their role config or the Org role inspector. A role can use auto, native, or external execution strategy, with an optional preferred external agent.

Feishu Connection

pip install -e .[channels-feishu]
opc init
opc channels login feishu

Edit .opc/config/channel_config.yaml:

channels:
  feishu:
    enabled: true
    app_id: "cli_xxx"
    app_secret: "..."
    encrypt_key: ""
    verification_token: ""
    react_emoji: THUMBSUP
    allow_from:
      - "ou_xxx"

Then:

opc channels status
opc channels start -p demo
# or run the long-lived engine + channel runtime:
opc run -p demo

Feishu uses the lark-oapi WebSocket client. app_id and app_secret are required; encrypt_key and verification_token are optional unless your tenant/app configuration requires them. Keep allow_from explicit; an empty list denies all inbound messages.

opc channels login slack
opc channels status
opc channels start -p demo
opc channels stop
opc run -p demo

python -m playwright install chromium

system:
  browser:
    mode: embedded   # embedded | chrome | auto
    headless: true
    chrome_channel: chrome
    user_data_dir: ""

Troubleshooting

opc ui --rebuild

python scripts/reset_stuck_task.py --project <project> --session <session_id> --apply
python scripts/reset_stuck_task.py --all --apply

opc status