A desktop workspace for organizing and working with AI employees.
Build a team of AI roles, give each role instructions and a budget, and work with them from one place. RoleWeave brings your organization chart, conversations, role documents, and activity reports into a local desktop app.
Its organizing principle is simple: the file tree is the org chart. Roles live in folders, and nested folders define reporting relationships. Your team structure stays visible and inspectable on disk.
Download · Get started · For AI assistants and integrations · Develop from source · Report an issue
- Organize an AI team. Create roles with explicit token budgets, change reporting relationships, and archive or restore roles.
- Work with individual roles. Start conversations, revisit local history, and start a fresh session when the task changes.
- Keep instructions close to the work. Read role documents alongside the workspace and connect shared organization documents.
- Understand what happened. Review recorded activity, organization changes, turn outcomes, and available budget usage in the reporting center.
- Connect knowledge sources. Add optional document, file, and context services when your workflow needs them.
For example, an open-source maintenance team can have a repository owner with three supporting roles: an issue researcher, a community operator, and a release engineer. The repository includes an example workspace with this structure and role budgets.
The v0.3.0 source adds native phone shells for iOS, Android, and HarmonyOS, editable employee profiles with permission management, persistent per-employee Agent bindings, an encrypted host-credential settings surface, semantic color theming, and a bundled WorkBuddy engine host, on top of the goal-centered collaboration spine, the Windows WSL runtime for projects and Agent hosts, and local doc/mem service surfaces shipped in v0.2.0. See continuing work with an AI team for usage and limits. Older v0.2.0 installers do not include these features.
Workspace auto-open diagnostics remain best-effort: an unavailable stderr stream does not turn a diagnostic write into a failed startup. The current source restores an accessible workspace you previously opened and honors explicit workspace overrides. Otherwise, it starts without a workspace; it does not create or open a demo automatically. This empty first-launch behavior ships with v0.2.0.
RoleWeave is an early preview. This source targets v0.3.0. The versioned downloads below become available when the release is published; use the latest published release until then.
| Platform | Download |
|---|---|
| macOS, Apple Silicon | DMG installer · ZIP archive |
| Windows, x64 | EXE installer |
See the v0.3.0 release notes for this candidate's changes and all releases for published packages. Intel Mac and Linux installers are not included in this release target.
Installation notes: macOS packages are not Apple Developer ID-signed or notarized, and the Windows installer is not Authenticode-signed. Your operating system may show a security prompt on installation or first launch. The macOS update manifest has a separate cryptographic signature; this does not provide Apple code-signing trust. Users of older Org Workbench development builds need to install RoleWeave manually once.
- Install and open RoleWeave. Choose the package for your platform above. The interface supports English and Simplified Chinese; open Preferences in the top-right title bar, then choose Language to switch to English.
- Create or open a workspace. Use the project menu to create a project or open an existing
digital-employeeworkspace. To explore a prepared team, download or clone this repository and open itsexamples/oss-maintainerfolder. If you choose a source folder that has no RoleWeave files yet, the app explains why it cannot be opened and offers Initialize this folder; that action keeps your existing files and adds a project owner plus the workspace metadata. - Choose a role. Inspect its instructions and budget, or create a role for the work you want it to do.
- Prepare an AI host. The default desktop adapter uses a locally installed Qoder CLI 1.x, version 1.1.0 or newer, and checks the headless command options required for employee conversations. Install the native CLI with
npm install -g @qoder-ai/qodercliand sign in withqodercli login; the Qoder editor'sqoderlauncher is not the CLI. RoleWeave checks the CLI's reported login status before enabling Qoder conversations. It does not include a model subscription, and local readiness does not establish model entitlement or a successful model request. - Send a small first task. Select the role's conversation and send a prompt such as: “Summarize your role instructions and suggest a first task.” Review the recorded result and return to its history when needed.
If the host is unavailable, follow the engine status guidance. For a custom Qoder installation, the server-side ORG_WORKBENCH_QODER_BIN environment variable can point to its executable. Restart the app after changing its launch environment.
The current source can keep the Windows interface while running the project backend and Agents in a local WSL distribution. This ships with the v0.2.0 release. Linux Node.js 22 or newer and the chosen Agent CLI must already be installed in that distribution.
To make WSL the default on one machine, place runtime-settings.json in RoleWeave's Electron user-data directory (normally %APPDATA%\RoleWeave):
{
"mode": "wsl",
"distro": "Ubuntu-22.04",
"homePath": "/home/your-user"
}Use your actual distribution and Linux home directory. An optional nodePath pins an absolute Linux Node executable; otherwise the launcher checks the WSL login PATH and local nvm installation. The launcher uses the Linux account's Bash or Zsh login configuration; other shells fall back to Bash with an explicit diagnostic. Configure PATH, proxy and certificates in Bash's login configuration if your account uses another shell. Explicit launch-environment overrides, including ROLEWEAVE_WSL_NODE_PATH, take precedence over this machine preference. Machines without the file keep the native backend.
After fully restarting RoleWeave, project pickers start in the selected WSL home. Both \\wsl.localhost\<distribution>\... and \\wsl$\<distribution>\... are supported; another distribution is rejected. Windows drive paths still map to /mnt/<drive>/.... The backend uses the WSL user's CLI installations, login files, proxy and certificate settings.
For environment-based provider, document or memory connections, keep each endpoint and its credentials together in one environment. A Windows override replaces that connection's Linux environment values as a group; missing credentials are never borrowed from Linux. Connections without a Windows override keep their Linux environment configuration.
Choose an Agent when creating a project or hiring an employee. Each employee keeps its own saved runtime binding across restarts and health changes; conversations do not share a global Host selector. Claude Code and Codex prefer an available local configuration for new bindings. A ready status does not prove model entitlement or a successful model request. Settings shows which environment supplies the project and Agents alongside the document and memory service connections. Closing the desktop also closes its WSL backend.
A workspace is a local project folder. A role is an AI employee's position, with its own instructions and budget. A session groups local conversation turns for that role.
Opening a directory does not infer a workspace from arbitrary files. A valid workspace has workspace.json, organization.v1alpha1.json, and positions/, and its organization must contain at least one employee. For an existing source tree without those markers, use the explicit initialize action in the project dialog. Initialization is additive: it preserves the source files and creates a read-only project owner so the directory is immediately usable.
The included example uses this layout:
positions/
└── repo-owner/
├── SKILL.md
├── budget.json
├── issue-researcher/
├── community-operator/
└── release-engineer/
Moving a role changes its reporting relationship. Archiving through the app preserves the role in the workspace's backup area for explicit restoration. Starting a fresh session preserves earlier local history; it does not grant new permissions or imply that the underlying AI host resumes a previous session.
For a packaged install, open Settings → Agent Host credentials to save Qoder, Claude or Codex credentials with operating-system encryption. Finish active work, then fully quit and reopen RoleWeave to apply saved changes. Launch-environment connections take precedence. See Host credential settings for the supported fields, precedence and storage boundaries.
Workspace files and conversation records are stored locally. Local storage does not mean offline AI: prompts and task context may be sent to the AI provider used by your configured host. Connected services have their own storage and access policies.
These integrations are optional. In the desktop app, open Preferences → Document and memory services to connect doc or mem by API URL and token. Tokens are encrypted with the operating system credential facility; the full upstream editor or drive opens in its own sandboxed window. Server-only deployments can keep using environment variables:
| Service | Purpose | Configuration |
|---|---|---|
| bytefolk/doc | Read shared documents through its v1 API; open the upstream collaborative editor | Preferences, or ORG_WORKBENCH_DOC_URL, ORG_WORKBENCH_DOC_TOKEN |
| bytefolk/mem | Read the shared file index; open the upstream drive and memory interface | Preferences, or ORG_WORKBENCH_MEM_URL, ORG_WORKBENCH_MEM_TOKEN |
| bytefolk/context | Export completed session turns into scoped context records | ORG_WORKBENCH_CONTEXT_CLI, CONTEXT_VAULT, CONTEXT_RUNTIME_TOKEN |
Unconfigured document and file services display a disconnected or unconfigured state. Context export requires an operator to establish the appropriate scope grant first. Keep service tokens in the encrypted desktop connection store or server environment, outside role documents, prompts, and committed files. See the API reference and context boundary for details.
Manage both local Docker deployments with npm run local-services -- init, up, status, logs, and stop (each also accepts doc or mem). Configuration and data volumes persist across source upgrades. Enable Docker Desktop WSL integration when running from WSL.
doc and mem run independently: use local services by default, or a team HTTPS endpoint. Their Web interfaces update with their deployments; API compatibility is checked through authenticated requests. RoleWeave does not bundle their source or database. Use npm run services -- plan doc (or mem) to inspect upstream source candidates, then prepare an explicit commit for a separate deployment. The independent services guide covers local setup, source updates, persistent data, and compatibility limits.
RoleWeave is an Electron desktop application with a local Node.js HTTP service, built around digital-employee workspaces. Use the following entry points when helping a user, inspecting the repository, or building an integration:
| Goal | Start here |
|---|---|
| Install a published build | Releases and version-specific notes |
| Understand HTTP requests, authentication, errors, and events | Local API contract |
| Inspect request and response types | packages/shared |
| Understand role instructions and folder structure | examples/oss-maintainer |
| Inspect server behavior and adapters | apps/server |
| Inspect the desktop UI and application shell | apps/desktop |
| Understand design decisions | Architecture decisions |
The local service binds to 127.0.0.1. Only GET /health is unauthenticated; other endpoints require a fresh per-launch Bearer token. API responses use JSON, and /events provides server-sent events. The server can run independently of Electron with npm run dev:server after the source setup below. Standalone mode also needs a compatible engine configured through ORG_WORKBENCH_DIGITAL_EMPLOYEE_CLI; the desktop launcher supplies its bundled adapter by default.
For read-only inspection, use the port and token printed by your local server at startup:
# Replace the placeholders with values from your own local server.
export ROLEWEAVE_PORT='<port>'
export ROLEWEAVE_TOKEN='<boot-token>'
curl "http://127.0.0.1:${ROLEWEAVE_PORT}/health"
curl -H "Authorization: Bearer ${ROLEWEAVE_TOKEN}" \
"http://127.0.0.1:${ROLEWEAVE_PORT}/workspace"
curl -H "Authorization: Bearer ${ROLEWEAVE_TOKEN}" \
"http://127.0.0.1:${ROLEWEAVE_PORT}/org/tree"Read the API contract before issuing mutations. Reporting relationships do not grant tool permissions. A completed local turn does not prove delegation, long-term memory, or access to an external service. When describing capabilities, distinguish the installed release from newer source changes. Some detailed engineering documents are currently in Chinese; the paths and code identifiers above provide direct navigation.
Use Node.js 24 for parity with CI, plus npm and Git. Keep the two repositories side by side: RoleWeave currently uses a local file dependency on the ByteFolk design system. The commit below matches the design-system revision pinned by RoleWeave CI.
git clone https://github.com/bytefolk/design-system.git
git clone https://github.com/bytefolk/roleweave.git
cd design-system
git checkout 910456901dda74da4d5b0320cd03d36ad18650b0
npm ci
npm run build:package
cd ../roleweave
npm ci
npm run doctor
npm run dev:desktopnpm run doctor performs a read-only development environment check. Starting the desktop app does not configure your AI host account or optional services.
Useful commands from the repository root:
| Command | Purpose |
|---|---|
npm run dev:desktop |
Build and launch the desktop app |
npm run dev:server |
Build and run the standalone local HTTP service |
npm run check |
Run the repository's build, tests, type checks, and dependency audit |
npm run preview:quick |
Print a dry-run launch plan without starting services |
- Real Qoder execution has been verified on a macOS machine. Claude Code live execution, full delegation chains, and end-to-end long-term context workflows are not yet part of the verified baseline.
- macOS has a signed-manifest update mechanism. Windows can check the existing Electron update channel, but unsigned builds require manual installation; in-app download and install remain disabled without a publisher identity. Publishing a release exposes its metadata to clients checking these channels.
- Native builds, packaged launch and layout checks, and asset integrity are covered by CI. Installation, uninstallation, and cross-version automatic updates on user machines are not claimed as fully verified end to end.
See the latest published release notes for the downloaded build's exact scope.
Open an issue for bugs, questions, or feature requests. For a bug report, include your RoleWeave version, operating system, steps to reproduce, and expected versus actual behavior. Remove credentials and private workspace content from logs before sharing.
For contributions, use a focused branch and pull request, run the relevant checks, and describe how you verified the change. See the changelog for development history.