• 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.

Workspace And Setup. Choose or create a project, start New Chat, then select Company or Task plus the matching organization or agent. In Company Mode, pick role employees and execution agents, or let OpenOPC auto-recruit. Execution Progress. Track every role's state, then click a role or work item to inspect detailed execution records, tool activity, handoffs, reviews, and runtime metadata. Kanban. Supervise each agent's concrete tasks and work items as they move through planning, execution, review, blockers, and completion. Org Control. Tune existing organizations, adjust roles and reporting lines, review runtime policy, or create a new organization. Talent Market. Browse talent templates, inspect candidate details, and recruit employees into vacant roles when the company needs more capability. Office View. Watch the organization as an animated office, with each role/agent showing status, current task, active tool, seat, and runtime activity.

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

OpenOPC exposes two choices in both Task and Company modes:

• JiuwenSwarm-single is a single external agent, like Codex or Claude Code. It handles only the selected task or role. Its compatible OpenOPC agent ID is jiuwen.
• JiuwenSwarm-team is one opaque external Team. OpenOPC works with the Team as a whole and does not manage its internal agents. Its compatible OpenOPC agent ID is jiuwenswarm.

Setup

JiuwenSwarm reads ~/.jiuwenswarm/config/.env; it does not automatically read OpenOPC's .opc/config/llm_config.yaml. You may reuse the same provider credentials, but the model name must support JiuwenSwarm agent requests. For example, Volcengine Ark Agent Plan uses:

API_BASE="https://ark.cn-beijing.volces.com/api/plan/v3"
API_KEY="<your API key>"
MODEL_NAME="ark-code-latest"
MODEL_PROVIDER="OpenAI"

JiuwenSwarm requires Python 3.11–3.13. Install the verified JiuwenSwarm 0.2.4b4 / openJiuwen 0.1.16 combination and the OpenOPC Gateway adapter from the OpenOPC repository root.

macOS / Linux:

python -m pip install -e ".[jiuwen]"
uv tool install --force --python 3.12 \
  --overrides docs/jiuwen-openjiuwen-overrides.txt \
  "https://github.com/openJiuwen-ai/jiuwenswarm/archive/ec305b70bf4a82f3603ea1a7b3ddc212386662df.tar.gz"
jiuwenswarm-init
chmod 600 ~/.jiuwenswarm/config/.env
jiuwenswarm-start app
opc agents preflight jiuwen
opc agents preflight jiuwenswarm
opc exec --mode task --agent jiuwen "Handle this task"
opc exec --mode task --agent jiuwenswarm "Have one Team handle this task"

Windows PowerShell / Command Prompt (no chmod step):

py -3.12 -m pip install -e ".[jiuwen]"
uv tool install --force --python 3.12 `
  --overrides docs/jiuwen-openjiuwen-overrides.txt `
  "https://github.com/openJiuwen-ai/jiuwenswarm/archive/ec305b70bf4a82f3603ea1a7b3ddc212386662df.tar.gz"
jiuwenswarm-init
jiuwenswarm-start app
opc agents preflight jiuwen
opc agents preflight jiuwenswarm

jiuwenswarm-start app stays in the foreground; keep that terminal open while using OpenOPC.

On Windows the Jiuwen configuration is normally stored under %USERPROFILE%\.jiuwenswarm\config\.env; on macOS/Linux it is under ~/.jiuwenswarm/config/.env. OpenOPC reads Jiuwen's persisted custom Gateway port, so both sides continue to use the same endpoint. Set JIUWENSWARM_GATEWAY_URL or a non-default gateway_url in .opc/config/agent_config.yaml only for an intentional remote/custom endpoint.

OpenOPC supports JiuwenSwarm-single and JiuwenSwarm-team in both Task and Company modes on Windows, macOS, and Linux. Company communication uses the same protected workspace boundary on every platform: POSIX directory handles on macOS/Linux and native handle-relative, reparse-point-safe access on Windows. Windows workspaces must be local; UNC/network-share workspaces fail closed because they cannot provide the same boundary guarantees.

Role selection in Company Mode

Choose the execution agent in Staffing / Recruitment Review, or under Company → Org → role → Runtime.

• Select JiuwenSwarm-single on CTO: only CTO uses JiuwenSwarm-single. CTO's subordinates remain separate OpenOPC roles and keep their own staffing and agent choices.
• Select JiuwenSwarm-team on CTO: CTO and every role below CTO become one Team. The roles remain visible in the org chart, but descendant controls are locked and OpenOPC does not recruit or assign employees inside that subtree. CEO delegates to the CTO Team boundary and receives one Team result.
• Select JiuwenSwarm-team on CEO: CEO and the entire company subtree become one Team. Descendants cannot select separate agents or create nested Teams.
• Select Teams on several peer managers, such as COO, CTO, and CMO: they become separate Teams coordinated and reviewed by their parent manager.
• Select no Team: normal Company staffing and per-role execution continue unchanged.

The parent manager receives a capability summary compiled from the covered roles, skills, tools, and deliverables. JiuwenSwarm-team decides how work is divided internally.

Team Activity (read-only)

When JiuwenSwarm-team emits its official Team events, Execution Progress still shows one organizational node and one OpenOPC WorkItem executor. Its second line summarizes the observed internal run, for example 3 members · 2 active · Leader synthesizing. Select that node to open Team Activity:

• Overview shows the leader and only the internal members Jiuwen actually created. OpenOPC covered roles are listed separately and never become inferred members.
• Tasks is a read-only internal Kanban; Timeline shows official member, task, message, retry, completion, and error events; Output keeps member outputs separate from the leader synthesis.
• todo_create, task_tool, covered_role_ids, and natural-language claims never create Team rows. Team telemetry never creates an OpenOPC Agent, Session, WorkItem, or main Kanban card, and never changes WorkItem progress, review, permissions, or scheduling.
• Task and Company modes use the same view. Stored telemetry survives refresh/reconnect and is isolated by project, OpenOPC task, and concrete external invocation. Older runs without structured events say that internal telemetry is unavailable instead of guessing.

This view observes Jiuwen's existing /tui stream only. It does not modify the Jiuwen harness or open another control connection.

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

OpenOPC Native has three permission levels. Set the default copied into each new session in .opc/config/system_config.yaml:

autonomy:
  native_approval_level: auto   # read-only | auto | full-access

Use the Permissions selector beside Mode/Agent in the UI, including while a session is running. Changes take effect at the next tool call; already-open approval requests are not replayed or auto-approved. The same setting is available from the CLI:

opc permissions
opc permissions set auto
opc chat --approval-level read-only
opc exec --approval-level full-access "Run the task"
opc session config <task-id> --approval-level auto

Interactive chat supports /permissions and /permissions read-only|auto|full-access; opc status and /status show the effective level and sandbox. A new session freezes the current default. Native subagents and all Native Company roles inherit the root session level, while different projects and sessions remain isolated.

Changing the default through the UI or opc permissions set atomically refreshes the trust fingerprint of an already trusted workspace. If you edit .opc/config/*.yaml by hand, review the change and run opc trust add <workspace> as usual.

When a call asks, approval cards retain once/session/project/global scopes; no grant can override an explicit deny. Default in the UI changes only future sessions.

full-access bypasses only Native tool permission prompts. Organization reviews, hiring decisions, user questions, Company WorkItem gates, controller ownership, durable effect fences, and explicit deny rules remain active. This setting does not control Codex, Claude Code, JiuwenSwarm-single, JiuwenSwarm-team, or any other external harness; their approval and sandbox settings remain independent. Legacy Native risk settings are read once for migration, then native_approval_level is authoritative.

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, opencode, jiuwen (JiuwenSwarm-single), and jiuwenswarm (JiuwenSwarm-team). See JiuwenSwarm setup and role behavior.

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