README.md

September 23, 2026 · View on GitHub

OPC-Fellows · hire occupations as members, then point them at your work
A small kernel (shell, todos, contracts) plus occupation plugins you can enable or write.

English · 中文

Wire it to your business · Occupations · Download · Write a module · Architecture · Contributing

You are a developer who also is the company: sales, content, research, invoices. This README is not a product brochure. It is how you clone the repo, hire members onto your own folders and sites, and do real work the same day.

Business data stays in on-device userData. Model keys go through Settings → Model (safeStorage). No account, no upload, no telemetry. The default product catalog is empty — fill in your sites.

Wire it to your business in 15 minutes

Needs Node.js ^22.19.0 or >=24.0.0, and pnpm 10+. The first pnpm install downloads Electron and takes a while.

git clone git@github.com:Alfred-Lau/OPC-Fellows.git
cd OPC-Fellows
pnpm install
pnpm dev

The UI is still hardcoded Chinese. Then attach your business, in this order — do not start with the architecture docs:

Key — 设置 → 模型, paste a DeepSeek API Key. Or export DEEPSEEK_API_KEY=… (env wins). Members cannot speak without a key.
Hire — the open-source roster ships Host and Social ammo only. Opening a member is their home thread. The left-rail + currently reopens Social ammo (a singleton).
Bind a folder — set the identity directory when you hire. Default is ~/OPC-Fellows/agents/{title}. Better: bind the folder you actually edit. You can rebind later; files are not moved.
Register your sites — 设置 → 工作情况 → 添加产品. Social ammo reads this list, not the sample in the repo. Shape: examples/catalog.example.json.
Talk — the composer is 问 (read-only), 计划 (propose first; reply 「按计划执行」 before writes), 动手 (write in the workspace). Ask first, then act.

Optional:

cp .env.example .env          # never commit a real .env
pnpm test
pnpm dsh                      # local DeepSeek Harness CLI

Package with pnpm run pack (unpacked dir) or pnpm dist:mac. Do not run pnpm pack — that emits an npm tarball.

Vocabulary (member / project / identity directory / composer mode): CONTEXT.md.

Which member for which job

The public roster keeps two identities. Other occupation modules stay in the tree but start disabled and do not spawn members.

Your job	Who
Read/edit the workspace, run commands, plan then act	Host (default lead on every project)
Multi-platform copy from product capabilities	Social ammo (register your sites in 工作情况 first)

Social ammo reads the Work situation catalog. Env cheat sheet:

Variable	Use
`DEEPSEEK_API_KEY`	Overrides Settings → Model; still reads legacy `~/.dsh`
`OPC_USER_DATA`	userData for the runtime

A project is one multi-member job. With no @, only the lead member hears you. Today is the global inbox, not a project.

Download a build

If you do not want source: v0.8.0 (macOS Apple Silicon only).

dmg — drag into Applications
zip

The build is signed and notarized by Apple, so it opens without any extra step. If the first launch is still blocked (for example while offline), run this once:

xattr -cr "/Applications/OPC-Fellows.app"

Then open the app. Upgrading from v0.7.3: this release builds under the name OPC-Fellows, so it starts with a fresh workspace — the previous build kept its data in ~/Library/Application Support/OPC Agent Team - Solokit and the new name does not read it. The same first-hour path applies: model key → hire → bind a folder → Work situation.

Extend the roster: add your own member

This tree ships two members, but that is the default set rather than a limit: a member is an occupation backed by a module, and nothing in the kernel is per-occupation. When a job is missing, add a member instead of patching the kernel.

If a built-in occupation does not cover your business, add an npm package. Do not grow kernel union types. The workbench reads ownworkbuddy (apply(ctx) + optional mount); the runtime reads dsh.bundle. Write both during the transition. Smallest sample: examples/hello-module.

{
  "main": "dsh-plugin.js",
  "ownworkbuddy": {
    "id": "hello",
    "title": "Hello",
    "kind": "view",
    "main": "index.js",
    "capabilities": [],
    "ui": "ui.js"
  },
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" }
  }
}

export default function apply(ctx) {
  ctx.workbench.nav({ id: 'hello', title: 'Hello', mark: 'Hi', kind: 'view', order: 200 })
  ctx.bridge.handle('hello:ping', () => ({ ok: true, at: new Date().toISOString() }))
}

Install from a local folder or Git on the Extensions page. To join the Harness stack:

pnpm dsh plugin --profile opc add ./examples/hello-module

A module may call only capabilities in its manifest. Undeclared calls are rejected. subprocess and secrets confirm at install. Modules must not reach into each other's stores; cross-module traffic goes through kernel services (for example todos.ingestAgent).

Architecture

Electron is a thin shell. Chat and tools run on DeepSeek Harness; the roster, todos, and module registry hang on the same tree. Design: ADR 0005, docs/module-architecture-design.md. Shell mental model: docs/agent-workspace-design.md.

src/kernel/     boot, IPC, storage, todos, nav, module registry, members
src/modules/    built-in occupations (reference implementations)
examples/       smallest third-party module
server/         optional self-hosted reference backend (independent package)
docs/           architecture and ADRs

server/ is an optional, self-hosted reference backend for users who want to stand up their own full-stack app. It is deliberately outside the desktop build: its own package.json, not in any pnpm workspace, and nothing here imports it — see server/README.md.

Runtime: deepseek-ai/deepseek-harness. Peer desktop hosts: github.com/topics/dsh-plugin.

The author runs this workbench against SoloKit and 榆关. That is a configuration, not the trunk defaults.

Contributing

Public trunk: Alfred-Lau/OPC-Fellows. PRs against kernel services, manifests, capabilities, samples, and docs are welcome.

Do not weld personal site catalogs, signing identities, secret defaults, or machine-absolute paths into src/shared. The default identity directory is ~/OPC-Fellows/agents/{title}. Aligning a private reference tree copies mechanisms only — ADR 0007.

CONTRIBUTING.en.md · CONTRIBUTING.md
Code of Conduct · Security policy
Good first cuts: English UI strings, an examples/ module, tests for one occupation

UI copy is still hardcoded Chinese. Plan: docs/i18n-plan.md. PRs are licensed under MIT.

Security

Business data stays in on-device userData. There is no first-party backend for it. (server/ is an optional self-hosted sample you deploy and control; it never receives desktop data.)
WeChat intel is a local read-only index. Mail triage writes local drafts and does not send.
Third-party modules run on a capability allow-list.
Report vulnerabilities in private. See SECURITY.md.

License

MIT License. Runtime depends on Cordis and DeepSeek Harness.

Site: OPC-Fellows