orc-ai 0.1.60 → 0.1.61
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +68 -1069
- package/dist/index.js +886 -816
- package/dist/skills/orc-platform/references/execution.md +2 -2
- package/dist/skills/orc-platform/references/knowledge.md +2 -2
- package/dist/skills/orc-platform/references/packages.md +2 -2
- package/dist/skills/orc-platform/references/rules.md +1 -1
- package/dist/skills/orc-platform/references/setup.md +4 -4
- package/dist/skills/orc-platform/references/work.md +2 -2
- package/dist/web/assets/Agents-Cbd4OtTh.js +34 -0
- package/dist/web/assets/Audit-BE6gJGJ2.js +1 -0
- package/dist/web/assets/ChatUiRenderer-nPW9cPY0.js +4 -0
- package/dist/web/assets/{ConfirmDialog-DOSTWblx.js → ConfirmDialog-B2AoOb7K.js} +1 -1
- package/dist/web/assets/Dashboard-D7Eo8L7f.js +1 -0
- package/dist/web/assets/{DocumentWorkspace-DVnU3uMP.js → DocumentWorkspace--nA1W_JJ.js} +1 -1
- package/dist/web/assets/{ErrorState-DprXzfow.js → ErrorState-DB0nWfcc.js} +1 -1
- package/dist/web/assets/FileEditor-DQShHKIA.js +1 -0
- package/dist/web/assets/IntegrationCallback-CQ-5tFDS.js +1 -0
- package/dist/web/assets/JobWebhooks-vnINFwVc.js +1 -0
- package/dist/web/assets/Jobs-DNJ6n04q.js +1 -0
- package/dist/web/assets/Knowledge-tjN4eGKT.js +1 -0
- package/dist/web/assets/Markdown-Dd63lfhh.js +2 -0
- package/dist/web/assets/MarkdownEditor-CsNy7jLm.js +2 -0
- package/dist/web/assets/{MarkdownRenderer-B6SKIKVL.js → MarkdownRenderer-BknAyZea.js} +4 -4
- package/dist/web/assets/{NativeFolderField-DwXF9tJW.js → NativeFolderField-BGEeFzlL.js} +1 -1
- package/dist/web/assets/PackageCatalog-B9oCbPsz.js +8 -0
- package/dist/web/assets/{PackageRunDialog-HoczGux2.js → PackageRunDialog-uzw-JgW8.js} +2 -2
- package/dist/web/assets/{Pager-D-y150yZ.js → Pager-LiuxU9XN.js} +1 -1
- package/dist/web/assets/{PriorityBadge-D263N3pH.js → PriorityBadge-DOfXvpzs.js} +1 -1
- package/dist/web/assets/Projects-CQD5qz53.js +3 -0
- package/dist/web/assets/{ResponsiveFilters-CQ42T3S8.js → ResponsiveFilters-BqJByGHN.js} +1 -1
- package/dist/web/assets/ResumeActions-CbJ-Cbk3.js +1 -0
- package/dist/web/assets/Rules-U6hnHFB5.js +18 -0
- package/dist/web/assets/{ScratchpadDiagramEditor-Dcfngku2.js → ScratchpadDiagramEditor-B4U8Nurj.js} +1 -1
- package/dist/web/assets/Scratchpads-DxUCf7R6.js +10 -0
- package/dist/web/assets/SessionHomeLink-DEnym_Kp.js +1 -0
- package/dist/web/assets/Sessions-Q0f4LxgT.js +4 -0
- package/dist/web/assets/Settings-Dpl5JNsM.js +14 -0
- package/dist/web/assets/Skills-oUtF9ajd.js +3 -0
- package/dist/web/assets/{SourceEditor-DNHVu9ux.js → SourceEditor-F7ig908r.js} +3 -3
- package/dist/web/assets/{StatusBadge-BUGpPpcH.js → StatusBadge-CKL0hTFN.js} +1 -1
- package/dist/web/assets/{TagInput-BmRYPN4B.js → TagInput-IRNFWgaL.js} +1 -1
- package/dist/web/assets/TaskDetailSheet-DqgRaZIm.js +1 -0
- package/dist/web/assets/Tasks-DYe7ju-6.js +22 -0
- package/dist/web/assets/Terminals-BgJxLXJj.js +2 -0
- package/dist/web/assets/Terminals-D-D3Ovm0.css +1 -0
- package/dist/web/assets/ViewHeader-CxFP-m6y.js +1 -0
- package/dist/web/assets/{Webhooks-CP-m_Dos.js → Webhooks-DcuNI8FK.js} +1 -1
- package/dist/web/assets/{badge-CpU0J4qt.js → badge-DAr2seta.js} +1 -1
- package/dist/web/assets/{button-C91mbQEU.js → button-By-NN7c7.js} +1 -1
- package/dist/web/assets/check-END_yWNt.js +1 -0
- package/dist/web/assets/chevron-down-Bbc7HWYe.js +1 -0
- package/dist/web/assets/client-Bc0rY81o.js +1 -0
- package/dist/web/assets/{dialog-D86vkhdt.js → dialog-DCEKcvjh.js} +1 -1
- package/dist/web/assets/{dist-BKxzy3T8.js → dist-DScw4RwC.js} +1 -1
- package/dist/web/assets/{download-6d5_Jyox.js → download-FH1W-e9Z.js} +1 -1
- package/dist/web/assets/{highlighted-body-JLMTFACH-C0zXH1C-.js → highlighted-body-JLMTFACH-B8I4Gdpk.js} +1 -1
- package/dist/web/assets/index-CEyJTk82.css +1 -0
- package/dist/web/assets/index-D5goDDAB.js +133 -0
- package/dist/web/assets/{label-BdnRgBbz.js → label-Bm_d0NKL.js} +1 -1
- package/dist/web/assets/live-sessions-B9U-96Jq.js +1 -0
- package/dist/web/assets/{maximize-2-Daih3Vv7.js → maximize-2-CJeuZEOw.js} +1 -1
- package/dist/web/assets/mermaid-WFAXDIZX-COoUW0ok.js +1 -0
- package/dist/web/assets/{save-CnCcteVb.js → save-CUaOLP-Y.js} +1 -1
- package/dist/web/assets/schemas-BQZhekae.js +55 -0
- package/dist/web/assets/{scratchpad-kinds-vQJshqz1.js → scratchpad-kinds-DKq-cPq3.js} +1 -1
- package/dist/web/assets/{scratchpad-routes-D8SCEha7.js → scratchpad-routes-CsZsw51j.js} +1 -1
- package/dist/web/assets/{scroll-area-Cmb_s_kX.js → scroll-area-BhajWBGy.js} +1 -1
- package/dist/web/assets/select-CllJZCPs.js +1 -0
- package/dist/web/assets/{table-Q26Vm3R3.js → table-COm8Aml-.js} +1 -1
- package/dist/web/assets/{tabs-DpKnjRll.js → tabs-bEwJLtA0.js} +1 -1
- package/dist/web/assets/{textarea-BRdsUa6B.js → textarea-CovStda2.js} +1 -1
- package/dist/web/assets/{upload-BLDr7Cwk.js → upload-D-P6hPWY.js} +1 -1
- package/dist/web/assets/useFolderPickerSession-BrGcm1V7.js +1 -0
- package/dist/web/assets/{useIntegrations-CkfXwYNs.js → useIntegrations-CfcITS7V.js} +1 -1
- package/dist/web/assets/{useJobs-BNj4dd9l.js → useJobs-X366wdF7.js} +1 -1
- package/dist/web/assets/{useListSelection-DLQYrJX-.js → useListSelection-BnMxiGpC.js} +1 -1
- package/dist/web/assets/{useMemories-BpfvcV2g.js → useMemories-B8by0Dez.js} +1 -1
- package/dist/web/assets/useMutation-CRAWY7v2.js +1 -0
- package/dist/web/assets/{useSessions-n-bp8ic5.js → useSessions-DsGibmJW.js} +1 -1
- package/dist/web/assets/{x-CIaAKXRo.js → x-DrjbksZi.js} +1 -1
- package/dist/web/index.html +20 -18
- package/dist/web/manifest.webmanifest +2 -2
- package/package.json +1 -1
- package/dist/web/assets/Agents-DBN_IKhQ.js +0 -34
- package/dist/web/assets/Attention-Col9bpvb.js +0 -2
- package/dist/web/assets/Audit-DDhPMP5V.js +0 -1
- package/dist/web/assets/ChatUiRenderer-Bflvv2nP.js +0 -4
- package/dist/web/assets/Dashboard-CXREcWFQ.js +0 -1
- package/dist/web/assets/FileEditor-YLZReqhf.js +0 -1
- package/dist/web/assets/FormDialog-CelnA8hT.js +0 -1
- package/dist/web/assets/IntegrationCallback-elv3Aqfs.js +0 -1
- package/dist/web/assets/JobWebhooks-BvKIhaAK.js +0 -1
- package/dist/web/assets/Jobs-TFiqlEzO.js +0 -1
- package/dist/web/assets/Knowledge-Dz9v7lfr.js +0 -1
- package/dist/web/assets/Markdown-CtVGTUZH.js +0 -2
- package/dist/web/assets/MarkdownEditor-CSloDLyL.js +0 -2
- package/dist/web/assets/PackageCatalog-DSwcvJsN.js +0 -8
- package/dist/web/assets/Projects-D5da4x_q.js +0 -3
- package/dist/web/assets/ResumeActions-DYiHEYFy.js +0 -1
- package/dist/web/assets/Rules-CYG1JoBH.js +0 -18
- package/dist/web/assets/Scratchpads-uSMao0H4.js +0 -10
- package/dist/web/assets/Sessions-BWh81qh3.js +0 -3
- package/dist/web/assets/Settings-w_H15X7M.js +0 -14
- package/dist/web/assets/Skills-CmcTt8ye.js +0 -8
- package/dist/web/assets/TaskDetailSheet-DfK_DtzG.js +0 -1
- package/dist/web/assets/Tasks-CbOw64sI.js +0 -22
- package/dist/web/assets/Terminals-C0aoP7ar.css +0 -1
- package/dist/web/assets/Terminals-DP3MyIBo.js +0 -3
- package/dist/web/assets/ViewHeader-BtTaSrXy.js +0 -1
- package/dist/web/assets/check-N8fVGVDO.js +0 -1
- package/dist/web/assets/chevron-down-wgh-M0zj.js +0 -1
- package/dist/web/assets/circle-alert-OZ-kwnCD.js +0 -1
- package/dist/web/assets/circle-check-DQM5o2QS.js +0 -1
- package/dist/web/assets/claude-DyzolaFc.svg +0 -3
- package/dist/web/assets/client-BnTXPI20.js +0 -1
- package/dist/web/assets/codex-BNO0LSlX.svg +0 -1
- package/dist/web/assets/copilot-BALWjOlU.svg +0 -1
- package/dist/web/assets/cursor-DdfUZ9gB.svg +0 -12
- package/dist/web/assets/index-D5qFuDmc.js +0 -160
- package/dist/web/assets/index-z4BVJQry.css +0 -1
- package/dist/web/assets/link-2-Ced5Jr2w.js +0 -1
- package/dist/web/assets/list-OJI1AaZs.js +0 -1
- package/dist/web/assets/live-sessions-D07BClP7.js +0 -1
- package/dist/web/assets/mermaid-WFAXDIZX-BTh2e4d1.js +0 -1
- package/dist/web/assets/terminal-links-B3ce99i1.js +0 -1
- package/dist/web/assets/useMutation-HX90wI4L.js +0 -1
package/README.md
CHANGED
|
@@ -1,1115 +1,114 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
**Multi-agent orchestrator with human-in-the-loop review**
|
|
6
|
-
|
|
7
|
-
[](https://www.npmjs.com/package/orc-ai)
|
|
8
|
-
[](LICENSE)
|
|
9
|
-

|
|
10
|
-

|
|
11
|
-
|
|
12
|
-
One SQLite file. One CLI. Any agent.<br>
|
|
13
|
-
ORC coordinates Claude Code, Cursor, Codex, Gemini, and remote A2A agents through a shared task board, persistent memory, and a review flow that keeps you in control.
|
|
14
|
-
|
|
15
|
-
<img src="assets/Architecture.gif" alt="ORC Architecture" width="700" />
|
|
16
|
-
|
|
17
|
-
</div>
|
|
18
|
-
|
|
19
|
-
## Overview
|
|
20
|
-
|
|
21
|
-
Every AI agent session is an island. Start a new session and it knows nothing about the last one. Run two in parallel and they can't coordinate. Switch agents and you start from zero.
|
|
22
|
-
|
|
23
|
-
ORC fixes this. Shared memory across every session. A task board where agents submit work and you approve it. A scheduler that runs agents on a cron. All backed by a single SQLite file - no cloud, no account, no subscription.
|
|
3
|
+
<img src="docs/public/logo.svg" alt="orc" width="88" />
|
|
24
4
|
|
|
25
|
-
|
|
5
|
+
# orc
|
|
26
6
|
|
|
27
|
-
|
|
28
|
-
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
29
|
-
| **Agent orchestration** | Task loop spawns workers across backends (Claude Code, Codex, Gemini, Copilot, A2A), manages concurrency and review cycles |
|
|
30
|
-
| **Human-in-the-loop** | Agents submit work for your approval via CLI, Telegram, or Slack before anything lands |
|
|
31
|
-
| **Shared memory** | Short project facts (ports, conventions, gotchas, decisions), ranked by priority and loaded into every session's context |
|
|
32
|
-
| **Task board** | `todo → queued → doing → review → done` with dependency tracking, priority, and automatic unblocking |
|
|
33
|
-
| **Multi-backend routing** | Route to Claude (in-process, nothing to install), ACPX (14+ agents), agentapi, or remote A2A endpoints — with `orc doctor` reporting which are usable |
|
|
34
|
-
| **Job runner** | Cron, file-watch, webhook, or manual triggers with full run history |
|
|
35
|
-
| **MCP server** | 54 tools connect any [Model Context Protocol](https://modelcontextprotocol.io) (MCP) compatible agent — stdio or Streamable HTTP |
|
|
36
|
-
| **Session continuity** | Snapshots survive context compaction so agents resume where they left off |
|
|
37
|
-
| **Gateway** | Approve work, search memory, and chat with live agents from Telegram or Slack |
|
|
38
|
-
| **Knowledge bases** | Upload PDFs, Office files and Markdown or copy in local folders; hybrid full-text + vector search with cited passages |
|
|
39
|
-
| **Skill library** | Discoverable workflow templates (coder, reviewer, planner, bugfix) that encode your standards |
|
|
40
|
-
| **Task flows** | Per-task graphs: conditional edges, bounded loops, parallel fan-out with joins, and human gates — with hard termination rails |
|
|
7
|
+
**One hub for every coding agent.**
|
|
41
8
|
|
|
42
|
-
|
|
9
|
+
Tasks, live sessions, memory and knowledge shared across Claude Code, Codex and Cursor, on your laptop or your own server.
|
|
43
10
|
|
|
44
|
-
|
|
11
|
+
[](https://github.com/niradler/orc/releases/latest)
|
|
12
|
+
[](https://www.npmjs.com/package/orc-ai)
|
|
13
|
+
[](https://niradler.github.io/orc/)
|
|
14
|
+
[](LICENSE)
|
|
45
15
|
|
|
46
|
-
|
|
16
|
+
[Documentation](https://niradler.github.io/orc/) · [Install](#install) · [Quick start](#quick-start) · [Releases](https://github.com/niradler/orc/releases)
|
|
47
17
|
|
|
48
|
-
|
|
49
|
-
| --------------------- | -------------------------------------------------------- |
|
|
50
|
-
| macOS (Apple Silicon) | `orc-<version>-mac-arm64.dmg` |
|
|
51
|
-
| macOS (Intel) | `orc-<version>-mac-x64.dmg` |
|
|
52
|
-
| Windows (x64) | `orc-<version>-windows-x64-setup.exe` |
|
|
53
|
-
| Linux (x64) | `orc-<version>-linux-x64.AppImage` (`chmod +x`, then run) |
|
|
18
|
+
<img src="docs/public/screens/orc-tour.gif" alt="A tour of the ORC dashboard: activity, task board, task flow, agent sessions and the terminal" width="820" />
|
|
54
19
|
|
|
55
|
-
|
|
20
|
+
</div>
|
|
56
21
|
|
|
57
|
-
|
|
58
|
-
- when it starts the daemon, generates an API secret, saves it to `~/.orc/config.json`, and sends it for you - Terminals work with nothing to configure
|
|
59
|
-
- installs the `orc` CLI to `~/.orc/bin` and adds that folder to your `PATH` (a marked block in your login shell's startup file on macOS and Linux, the user `PATH` on Windows) - open a new terminal and run `orc`
|
|
60
|
-
- registers start at login (hidden) and keeps the daemon running from the tray / menu bar when the window is closed; toggle it from the tray menu, quit from there to stop the daemon
|
|
22
|
+
## Why ORC
|
|
61
23
|
|
|
62
|
-
|
|
24
|
+
Every agent session is an island. A new session forgets the last one, two sessions in parallel can't coordinate, and switching from Claude Code to Codex starts from zero. ORC is the shared layer underneath them:
|
|
63
25
|
|
|
64
|
-
|
|
26
|
+
- **See every session.** Claude Code, Codex and Cursor sessions appear on their own, with status, tokens and transcript. Resume any of them from the browser or your phone.
|
|
27
|
+
- **Track the work, not the windows.** A task board of PR-sized goals that many sessions can serve, with flow graphs, review loops and human approval.
|
|
28
|
+
- **Stop re-explaining your codebase.** Memories and knowledge bases that every agent reads through MCP, plus a daily digest that turns sessions into documents.
|
|
29
|
+
- **Run agents for you.** Hand a task to a backend, schedule jobs, take webhooks, and answer agent questions from Telegram or Slack.
|
|
30
|
+
- **Local first, cloud when you want it.** One SQLite file on your laptop, plus a self-hosted ORC on your server to hand sessions off to and keep work running.
|
|
65
31
|
|
|
66
|
-
|
|
67
|
-
<summary>Headless / CLI-only install (servers, Docker, CI)</summary>
|
|
32
|
+
## Install
|
|
68
33
|
|
|
69
|
-
|
|
34
|
+
**The desktop app is the recommended install.** It starts the daemon, sets an API secret, installs the `orc` CLI on your `PATH`, and adds a tray icon. Download it from [GitHub Releases](https://github.com/niradler/orc/releases/latest):
|
|
70
35
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
36
|
+
| OS | Installer |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| macOS (Apple Silicon) | `orc-<version>-mac-arm64.dmg` |
|
|
39
|
+
| Windows (x64) | `orc-<version>-win-x64.exe` |
|
|
40
|
+
| Linux (x64 / ARM64) | `orc-<version>-linux-x86_64.AppImage` / `orc-<version>-linux-arm64.AppImage` |
|
|
76
41
|
|
|
77
|
-
|
|
42
|
+
Prefer a headless install? Use a single binary, npm or Docker:
|
|
78
43
|
|
|
79
44
|
```bash
|
|
80
|
-
# macOS
|
|
45
|
+
# Binary (macOS Apple Silicon shown; mac-x64, linux-x64 and linux-arm64 also published)
|
|
81
46
|
curl -L https://github.com/niradler/orc/releases/latest/download/orc-mac-arm64 -o /usr/local/bin/orc && chmod +x /usr/local/bin/orc
|
|
82
47
|
|
|
83
|
-
#
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
# Linux (x64)
|
|
87
|
-
curl -L https://github.com/niradler/orc/releases/latest/download/orc-linux-x64 -o /usr/local/bin/orc && chmod +x /usr/local/bin/orc
|
|
88
|
-
|
|
89
|
-
# Linux (ARM64)
|
|
90
|
-
curl -L https://github.com/niradler/orc/releases/latest/download/orc-linux-arm64 -o /usr/local/bin/orc && chmod +x /usr/local/bin/orc
|
|
91
|
-
|
|
92
|
-
# Windows - download orc-windows-x64.exe from the release page and add to PATH
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
#### From source
|
|
48
|
+
# npm (needs Bun >= 1.4.4)
|
|
49
|
+
npm install -g orc-ai
|
|
96
50
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
51
|
+
# Docker
|
|
52
|
+
docker run -d --name orc -p 127.0.0.1:7700:7700 \
|
|
53
|
+
-v orc-data:/data -v orc-home:/home/bun \
|
|
54
|
+
-e ORC_API_SECRET=$(openssl rand -hex 32) niradler/orc:latest
|
|
100
55
|
```
|
|
101
56
|
|
|
102
|
-
|
|
57
|
+
> [!TIP]
|
|
58
|
+
> Without the desktop app, run `orc daemon install` to start ORC now and at every login. Full options are in the [install guide](https://niradler.github.io/orc/docs/install).
|
|
103
59
|
|
|
104
|
-
|
|
60
|
+
## Quick start
|
|
105
61
|
|
|
106
62
|
```bash
|
|
107
|
-
#
|
|
108
|
-
# (skip this if you installed the desktop app: it is already running)
|
|
109
|
-
orc daemon start
|
|
110
|
-
|
|
111
|
-
# 2. Create a project
|
|
63
|
+
orc status # daemon is up on :7700
|
|
112
64
|
orc project add my-app -d "My application"
|
|
113
65
|
orc project use my-app
|
|
114
|
-
|
|
115
|
-
# 3. Add tasks and memories - everything auto-scopes to my-app
|
|
116
66
|
orc task add "Fix the auth bug" --priority high
|
|
117
|
-
orc mem add token-refresh-lock -d "Check before touching token refresh" -c "Use RWMutex for token refresh"
|
|
118
|
-
orc job add nightly --command "bun run test" --trigger cron --cron "0 22 * * *"
|
|
119
|
-
|
|
120
|
-
# 4. See everything
|
|
121
|
-
orc status
|
|
122
|
-
orc task list
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
Open `http://localhost:7700` to use the web dashboard - task board, kanban, flow runs, jobs, memories, sessions, knowledge, and a live chat panel. The same server hosts both the REST API and the prebuilt React SPA, so there is no separate command to run for the UI.
|
|
126
|
-
|
|
127
|
-
Chat uses the shared agent runtime: Claude through its SDK, Codex through its native
|
|
128
|
-
CLI App Server, and other agents through ACPX. Choose a model beside the agent
|
|
129
|
-
at the top of chat; configure model choices, conversation instructions, tools and permission
|
|
130
|
-
actions in **Settings → Chat**. Defaults are stored in `preferences.chat` in ORC's
|
|
131
|
-
JSON configuration and apply to new conversations on every device. Conversation
|
|
132
|
-
settings show the current conversation's setup. Claude appends the instructions
|
|
133
|
-
to its coding system prompt; Codex and ACPX receive them as turn instructions.
|
|
134
|
-
Agent and workspace instructions may also apply.
|
|
135
|
-
|
|
136
|
-
Choose **Ask in chat**, **Allow workspace edits**, or **Full access / bypass permissions**
|
|
137
|
-
for Claude and Codex. Codex's Ask mode uses a read-only sandbox with native approval
|
|
138
|
-
and question responses in chat. Full access disables Codex's sandbox and permission
|
|
139
|
-
prompts; workspace and ORC rules still apply. Change permissions for the next message
|
|
140
|
-
in conversation settings, or save defaults under Settings → Chat. ACPX follows its
|
|
141
|
-
agent's native permission policy. Existing automatic-action settings remain compatible.
|
|
142
|
-
The ORC MCP option adds an authenticated
|
|
143
|
-
connection for Claude and Codex without exposing credentials to the browser.
|
|
144
|
-
Host configuration can include additional MCP servers; choosing host configuration
|
|
145
|
-
does not disable those servers. Other ACPX agents require host configuration.
|
|
146
|
-
|
|
147
|
-
**Conversation settings → Advanced launch options** accepts SDK options for
|
|
148
|
-
Claude or a JSON argument array for ACPX and Codex. For example, Claude accepts
|
|
149
|
-
`{"permissionMode":"bypassPermissions","maxTurns":20,"effort":"high"}`;
|
|
150
|
-
ACPX accepts `["--approve-all","--timeout","120"]`; Codex accepts
|
|
151
|
-
`["-c","model_reasoning_effort=\"high\""]`. Apply saves existing conversations
|
|
152
|
-
immediately and affects the next message. Each agent keeps its own options.
|
|
153
|
-
ORC validates supported options and retains control of the session identity,
|
|
154
|
-
working folder, response transport and hooks. Credentials stay in host configuration;
|
|
155
|
-
available native flags depend on the installed agent version.
|
|
156
|
-
|
|
157
|
-
Use the history icon to continue a saved chat or an ended Claude/Codex coding
|
|
158
|
-
session. The terminal's speech-bubble icon continues in chat; chat's terminal icon
|
|
159
|
-
continues in a terminal using the same existing resume flow. On phones the terminal
|
|
160
|
-
action is in Terminal options. Synced sessions use the existing verified repository/commit handoff;
|
|
161
|
-
provide missing checkout details before importing. Native history stays with the
|
|
162
|
-
agent, while chat pages through imported history in batches of 500 messages. An active source session
|
|
163
|
-
must end before chat resumes it. Resume failures never trigger a fresh session.
|
|
164
|
-
New chats use the API working directory locally or the selected SSH host's home;
|
|
165
|
-
resumed chats retain their execution host and folder. New conversation keeps the
|
|
166
|
-
previous chat in history.
|
|
167
|
-
|
|
168
|
-
Responses show provider-supplied text, collapsible thinking summaries and tool
|
|
169
|
-
input/results as they arrive, with a responding indicator during quiet periods.
|
|
170
|
-
Some providers emit complete blocks rather than individual tokens. Conversation
|
|
171
|
-
messages and activity are saved in the ORC database. Full-screen mode preserves
|
|
172
|
-
the conversation; phones and tablets use a full-screen chat sheet automatically.
|
|
173
|
-
|
|
174
|
-
> [!TIP]
|
|
175
|
-
> The database is created automatically at `~/.orc/orc.db` on first run. No setup needed.
|
|
176
|
-
|
|
177
|
-
### Web dashboard
|
|
178
|
-
|
|
179
|
-
The web dashboard ships inside the `orc` binary and is served by the API process at the root path. REST routes live under `/api/<route>` - the SDK, CLI and MCP clients add that prefix themselves - which leaves the root path free for the SPA.
|
|
180
|
-
|
|
181
|
-
| Route | Served from |
|
|
182
|
-
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
183
|
-
| `GET /` | `index.html` (web SPA shell) |
|
|
184
|
-
| `GET /assets/*` | Built JS/CSS bundles |
|
|
185
|
-
| `GET /api/*` | All REST routes |
|
|
186
|
-
| `GET /openapi.json`, `GET /docs` | Swagger UI |
|
|
187
|
-
| `GET /mcp` | MCP server (streamable HTTP) |
|
|
188
|
-
| `GET /tasks/<id>`, `/knowledge`, … | `index.html` again - a navigation request matching no static file falls back to the SPA shell, so dashboard links are shareable |
|
|
189
|
-
|
|
190
|
-
`/mcp` serves three meta-tools by default (`tool_search`, `tool_describe`, `tool_invoke`) instead of the full tool list, which keeps client context small; the model finds a tool, reads its schema, then calls it through `tool_invoke` with the same validation as a direct call. Stdio `orc mcp` also defaults to meta mode. Use HTTP `/mcp?mode=full` or stdio `--mode full` for the whole tool list. Any other `mode` value returns HTTP 400.
|
|
191
|
-
|
|
192
|
-
Use `/mcp?project=orc` to set connection-wide defaults for project-aware tools,
|
|
193
|
-
including context, tasks, jobs, memories, knowledge and archived-session search.
|
|
194
|
-
Use `/mcp?projects=orc,project2` to select several projects in priority order;
|
|
195
|
-
combine it with `&mode=meta` if desired. Lists/searches combine the selected
|
|
196
|
-
projects before limiting or paginating, and shared global skills/KBs appear once.
|
|
197
|
-
Memories remain project-only. New resources default to the first project; an
|
|
198
|
-
explicit tool `project` (or supported `project_id`) can select another project
|
|
199
|
-
from the connection. ID-targeted operations keep the resource's existing owner.
|
|
200
|
-
Global-only reads remain available where the tool supports `scope: "global"`.
|
|
201
|
-
Unbound connections keep the existing activeProject/config behavior.
|
|
202
|
-
|
|
203
|
-
Select at most 50 projects. Names are trimmed, validated and deduplicated
|
|
204
|
-
case-insensitively while preserving order; unknown projects reject the request.
|
|
205
|
-
Pass either `project` or `projects`, not both. Explicit tool overrides cannot
|
|
206
|
-
select projects outside the URL. This is resource scoping, not tenant authorization.
|
|
207
|
-
|
|
208
|
-
Override the served dist directory with `ORC_WEB_DIST=/path/to/web/dist` if you want to host a custom build (e.g. a fork). If no dist is found, the server runs in pure-API mode.
|
|
209
|
-
|
|
210
|
-
### Desktop app
|
|
211
|
-
|
|
212
|
-
`packages/desktop` is the Electron app described under [Install](#install). It attaches to a daemon already answering `/api/health` on the configured port (`api.port`, default 7700) or starts the bundled `orc` binary, and stops only a daemon it started. Its daemon output goes to `~/.orc/desktop-daemon.log`. Launching the app executable with `--quit` quits the running instance (and the daemon it started), which is what installers and scripts should use; `--hidden` starts it without opening a window.
|
|
213
|
-
|
|
214
|
-
Hardening: sandboxed renderer with context isolation and no Node integration, permission requests denied except clipboard, `<webview>` blocked, navigation locked to the daemon origin (everything else opens in the system browser), Electron fuses that disable `ELECTRON_RUN_AS_NODE` and Node CLI/env options.
|
|
215
|
-
|
|
216
|
-
`orc daemon start` merges the login shell's `PATH` into its own on macOS and Linux, so `claude`, `codex` and `cursor-agent` are found when the daemon is started by launchd, systemd or a Finder-launched app.
|
|
217
|
-
|
|
218
|
-
```bash
|
|
219
|
-
bun run --filter @orc/desktop bin --only host # build the orc binary for this machine
|
|
220
|
-
bun run --filter @orc/desktop dev # run the app from source
|
|
221
|
-
bun run --filter @orc/desktop dist # installer for this machine -> packages/desktop/release
|
|
222
|
-
bun run --filter @orc/desktop dist:mac # also dist:win, dist:linux
|
|
223
|
-
bun packages/desktop/scripts/smoke.ts # end-to-end check of the packaged app
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
Builds are unsigned and there is no auto-update yet. Building binaries needs `bun >= 1.4.2` on `PATH` ahead of any `node_modules/.bin/bun`.
|
|
227
|
-
|
|
228
|
-
## Docker
|
|
229
|
-
|
|
230
|
-
Run ORC in a container with the published image:
|
|
231
|
-
|
|
232
|
-
```bash
|
|
233
|
-
docker run -d --name orc \
|
|
234
|
-
-p 7700:7700 \
|
|
235
|
-
-v orc-data:/data \
|
|
236
|
-
-e ORC_API_SECRET=$(openssl rand -hex 32) \
|
|
237
|
-
-e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
|
|
238
|
-
niradler/orc:latest
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
> The container binds `0.0.0.0`. Set a strong `ORC_API_SECRET` before exposing the
|
|
242
|
-
> mapped port beyond localhost — without it, every endpoint (including job execution,
|
|
243
|
-
> which runs arbitrary shell commands) is open to anyone who can reach the port.
|
|
244
|
-
|
|
245
|
-
Or with [docker-compose.yml](docker-compose.yml):
|
|
246
|
-
|
|
247
|
-
```bash
|
|
248
|
-
docker compose up -d
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
The source Docker image includes Node, ACPX, Claude Code and Codex CLI, with versions pinned in the Dockerfile. Its default backend is `claude` through the Anthropic SDK. Tool installation alone does not supply authentication: provide `ANTHROPIC_API_KEY` for Claude, `OPENAI_API_KEY` or a container-local Codex login for `codex-cli`, and the credentials required by whichever agent ACPX launches. Mount your repository and use its **container path** as the project folder. Agent configuration/session files can persist in the Compose `orc-home` volume. Existing ORC policies still apply; native Codex rule interception is not certified by CLI/tool availability. These source changes do not update an already published image.
|
|
252
|
-
|
|
253
|
-
To delegate to an agent running on the host instead, set `ORC_AGENT_LOOP_DEFAULT_BACKEND=agentapi` and run [coder/agentapi](https://github.com/coder/agentapi) on the host:
|
|
254
|
-
|
|
255
|
-
```bash
|
|
256
|
-
agentapi server --allowed-hosts '*' -- \
|
|
257
|
-
claude --allowedTools all \
|
|
258
|
-
--mcp-config '{"mcpServers":{"orc":{"type":"http","url":"http://localhost:7700/mcp"}}}'
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
The `--mcp-config` flag wires the host agent back to ORC's [HTTP MCP endpoint](#mcp-tools) so it can call `task_update`, `memory_*`, `knowledge_*`, etc. `host.docker.internal` lets the container reach agentapi on the host.
|
|
262
|
-
|
|
263
|
-
## Connect your agent
|
|
264
|
-
|
|
265
|
-
For coding-agent access, check the installed `spec` CLI bridge first (`spec --help`,
|
|
266
|
-
`spec specs`). It can call ORC's MCP server without configuring MCP separately in
|
|
267
|
-
each agent. Use an existing ORC registration or an inline endpoint for your selected
|
|
268
|
-
installation:
|
|
269
|
-
|
|
270
|
-
```sh
|
|
271
|
-
spec call --mcp-http http://127.0.0.1:7700/mcp context --data '{"project":"my-app"}'
|
|
272
|
-
spec call --mcp-http http://127.0.0.1:7700/mcp skill_read --data '{"name":"orc-sdlc","project":"my-app"}'
|
|
273
|
-
```
|
|
274
|
-
|
|
275
|
-
For authenticated servers, use existing secure secret references in spec configuration;
|
|
276
|
-
do not put secrets in command arguments. Use `SPEC_NO_CACHE=1` when refreshing live
|
|
277
|
-
context and effective skills. Direct MCP connections below remain supported when
|
|
278
|
-
already configured. Check the CLI bridge before reporting ORC unavailable.
|
|
279
|
-
|
|
280
|
-
Lifecycle hooks and MCP registration are separate. The hook examples below record
|
|
281
|
-
session activity; also register ORC in the client's supported MCP configuration
|
|
282
|
-
using `orc mcp` (stdio) or `<origin>/mcp` (HTTP). Preserve existing servers and
|
|
283
|
-
configure authentication privately. Verify tool discovery and a project-scoped
|
|
284
|
-
`context` call in each client; installed hooks alone do not establish MCP access.
|
|
285
|
-
|
|
286
|
-
### Claude Code
|
|
287
|
-
|
|
288
|
-
Add to `~/.claude/settings.json`:
|
|
289
|
-
|
|
290
|
-
```json
|
|
291
|
-
{
|
|
292
|
-
"hooks": {
|
|
293
|
-
"PostToolUse": [
|
|
294
|
-
{
|
|
295
|
-
"matcher": "Write|Edit|MultiEdit|StrReplace|EditNotebook|Bash|Shell|Agent|EnterPlanMode|ExitPlanMode|mcp__orc__task_|mcp__orc__memory_create|mcp__orc__memory_delete|mcp__orc__job_run|mcp__orc__job_create|mcp__orc__job_update",
|
|
296
|
-
"hooks": [
|
|
297
|
-
{
|
|
298
|
-
"type": "command",
|
|
299
|
-
"command": "bun /path/to/orc/hooks/post-tool-use.ts"
|
|
300
|
-
}
|
|
301
|
-
]
|
|
302
|
-
}
|
|
303
|
-
],
|
|
304
|
-
"PreCompact": [
|
|
305
|
-
{
|
|
306
|
-
"matcher": "",
|
|
307
|
-
"hooks": [
|
|
308
|
-
{
|
|
309
|
-
"type": "command",
|
|
310
|
-
"command": "bun /path/to/orc/hooks/pre-compact.ts"
|
|
311
|
-
}
|
|
312
|
-
]
|
|
313
|
-
}
|
|
314
|
-
],
|
|
315
|
-
"SessionStart": [
|
|
316
|
-
{
|
|
317
|
-
"matcher": "",
|
|
318
|
-
"hooks": [
|
|
319
|
-
{
|
|
320
|
-
"type": "command",
|
|
321
|
-
"command": "bun /path/to/orc/hooks/session-start.ts"
|
|
322
|
-
}
|
|
323
|
-
]
|
|
324
|
-
}
|
|
325
|
-
]
|
|
326
|
-
},
|
|
327
|
-
"env": { "ORC_API_BASE": "http://127.0.0.1:7700", "ORC_PROJECT": "" }
|
|
328
|
-
}
|
|
329
|
-
```
|
|
330
|
-
|
|
331
|
-
> [!NOTE]
|
|
332
|
-
> Replace `/path/to/orc/` with the path to your ORC clone or the installed package location (run `npm root -g` to find global installs). Hooks handle session events and snapshots automatically.
|
|
333
|
-
|
|
334
|
-
### Cursor
|
|
335
|
-
|
|
336
|
-
Add to `.cursor/mcp.json`:
|
|
337
|
-
|
|
338
|
-
```json
|
|
339
|
-
{
|
|
340
|
-
"mcpServers": {
|
|
341
|
-
"orc": {
|
|
342
|
-
"command": "orc",
|
|
343
|
-
"args": ["mcp"],
|
|
344
|
-
"env": {
|
|
345
|
-
"ORC_API_BASE": "http://127.0.0.1:7700",
|
|
346
|
-
"ORC_SESSION_ID": "cursor"
|
|
347
|
-
}
|
|
348
|
-
}
|
|
349
|
-
}
|
|
350
|
-
}
|
|
351
|
-
```
|
|
352
|
-
|
|
353
|
-
<details>
|
|
354
|
-
<summary>Codex, Gemini CLI, and other MCP agents</summary>
|
|
355
|
-
|
|
356
|
-
**Codex** - Copy `hooks/codex/settings.json` to `~/.codex/settings.json` and update the path.
|
|
357
|
-
|
|
358
|
-
**Gemini CLI / any MCP agent** - Add to your MCP config:
|
|
359
|
-
|
|
360
|
-
```json
|
|
361
|
-
{
|
|
362
|
-
"mcpServers": {
|
|
363
|
-
"orc": {
|
|
364
|
-
"command": "orc",
|
|
365
|
-
"args": ["mcp"],
|
|
366
|
-
"env": {
|
|
367
|
-
"ORC_API_BASE": "http://127.0.0.1:7700",
|
|
368
|
-
"ORC_SESSION_ID": "gemini"
|
|
369
|
-
}
|
|
370
|
-
}
|
|
371
|
-
}
|
|
372
|
-
}
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
</details>
|
|
376
|
-
|
|
377
|
-
## Usage
|
|
378
|
-
|
|
379
|
-
### How agents use ORC
|
|
380
|
-
|
|
381
|
-
```
|
|
382
|
-
1. Agent starts → context() returns active tasks + key memories
|
|
383
|
-
2. Agent works → creates tasks, stores decisions, records events
|
|
384
|
-
3. Agent submits work → task_update(status: "review", comment: "summary")
|
|
385
|
-
4. You review → approve or request changes via CLI / Telegram / Slack
|
|
386
|
-
5. Agent continues → picks up next task or resumes with feedback
|
|
387
|
-
6. Session ends → session_log() records what happened
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
When a context window fills up, `session_snapshot` captures current state into a compact 2KB blob that `session_restore` injects back after compaction - the agent picks up where it left off.
|
|
391
|
-
|
|
392
|
-
### Agent orchestration
|
|
393
|
-
|
|
394
|
-
The task loop automatically picks up queued tasks and spawns worker agents:
|
|
395
|
-
|
|
396
|
-
```bash
|
|
397
|
-
# Create a task with a workflow and backend
|
|
398
|
-
orc task add "Implement user auth" --skill orc-sdlc --backend claude --priority high
|
|
399
|
-
|
|
400
|
-
# Or batch-create with dependencies via MCP
|
|
401
|
-
task_batch_create({ tasks: [
|
|
402
|
-
{ ref: "design", title: "Design schema", skill_name: "orc-sdlc" },
|
|
403
|
-
{ ref: "api", title: "Implement API", skill_name: "orc-sdlc", depends_on: ["design"] },
|
|
404
|
-
{ ref: "tests", title: "Verify API integration", skill_name: "orc-sdlc", depends_on: ["api"] }
|
|
405
|
-
]})
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
The loop handles concurrency, session resume on feedback, review round limits, stale claim cleanup, and backend routing.
|
|
409
|
-
Each task's configured flow handles its review; a separate review task is unnecessary.
|
|
410
|
-
|
|
411
|
-
Every task runs a **flow graph** (see [Task flows](#task-flows)); `orc-default` is the build → review → done pipeline described above.
|
|
412
|
-
|
|
413
|
-
#### Agent backends
|
|
414
|
-
|
|
415
|
-
| Backend | Needs |
|
|
416
|
-
| --------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
417
|
-
| `claude` | Nothing to install: runs **in-process** via [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk), which ships with orc. Uses the Claude Code CLI's stored credentials, or `ANTHROPIC_API_KEY`. The default. |
|
|
418
|
-
| `acpx` | The [ACP CLI](https://github.com/openclaw/acpx) — 14+ agents (Codex, Gemini, Copilot, Kiro, Cursor, …). Installed as an optional dependency, so a normal `npm i -g orc-ai` gets it. ORC prefers that bundled version, then falls back to `PATH`. Point `ORC_ACPX_PATH` at a specific copy to override. |
|
|
419
|
-
| `agentapi` | A [coder/agentapi](https://github.com/coder/agentapi) server on the host (HTTP+SSE), wrapping any local coding agent. `AGENTAPI_URL` if it is not on the default port. |
|
|
420
|
-
| `a2a` | A remote [A2A](https://github.com/google/A2A) endpoint, supplied per task/session — nothing local. |
|
|
421
|
-
| `claude-cli` | The `claude` binary on `PATH`. The pre-SDK path, kept for when driving the real CLI matters. |
|
|
422
|
-
| `codex-cli` | The `codex` binary on `PATH`, driven natively instead of through acpx. |
|
|
423
|
-
| _anything else_ | Passed to acpx as its agent name, so `--agent-backend gemini` means "acpx driving gemini". |
|
|
424
|
-
|
|
425
|
-
Which of these actually work on a given machine depends on what is installed, so orc probes them rather than making you guess:
|
|
426
|
-
|
|
427
|
-
```bash
|
|
428
|
-
orc doctor # per backend: usable or not, what it resolved to, what a missing one needs
|
|
429
|
-
orc doctor --json # same, machine-readable
|
|
430
|
-
```
|
|
431
|
-
|
|
432
|
-
The dashboard shows the same probe: the agent-backend field on a task is a picker that marks each backend ready or unavailable, and names the one a task with no backend of its own will use. `GET /api/backends` is the endpoint behind both.
|
|
433
|
-
|
|
434
|
-
Standalone executables embed the SDK adapter, but its native Claude executable is
|
|
435
|
-
external. Install Claude Code on `PATH` to use `claude` in a standalone build; an
|
|
436
|
-
API key alone does not supply that executable. The npm distribution uses the SDK's
|
|
437
|
-
installed optional executable. Windows npm shims require their `cli.js` and Node
|
|
438
|
-
or Bun; missing executable prerequisites are reported before launching a session.
|
|
439
|
-
|
|
440
|
-
Enable the task loop in `~/.orc/config.json`:
|
|
441
|
-
|
|
442
|
-
```json
|
|
443
|
-
{
|
|
444
|
-
"agent_loop": {
|
|
445
|
-
"enabled": true,
|
|
446
|
-
"poll_interval_minutes": 5,
|
|
447
|
-
"max_workers": 1,
|
|
448
|
-
"default_backend": "claude",
|
|
449
|
-
"session_idle_timeout_minutes": 20,
|
|
450
|
-
"worker_auto_approve": true,
|
|
451
|
-
"default_flow": "orc-default",
|
|
452
|
-
"review_flow": "orc-review-only"
|
|
453
|
-
}
|
|
454
|
-
}
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
### Projects
|
|
458
|
-
|
|
459
|
-
Projects group tasks, memories, and jobs. Set an active project and all commands auto-scope:
|
|
460
|
-
|
|
461
|
-
Projects can also store an optional Git remote URL in the create/edit dialog or through `--git-remote-url`. HTTPS and SSH addresses are supported without embedded credentials. The address is project metadata; setting it does not clone a repository or change a checkout's remote. Clear it in the editor, send `git_remote_url: null` through the API, or use `orc project update my-app --clear-git-remote-url`.
|
|
462
|
-
|
|
463
|
-
```bash
|
|
464
|
-
orc project add my-app -d "Main application"
|
|
465
|
-
orc project use my-app # set active
|
|
466
|
-
|
|
467
|
-
orc task list # scoped to my-app
|
|
468
|
-
orc mem list -q auth # scoped to my-app
|
|
469
|
-
orc task list -p infra # override to different project
|
|
470
|
-
orc task list --no-project # see everything
|
|
471
|
-
```
|
|
472
|
-
|
|
473
|
-
**Resolution order:** explicit `-p <name>` > `activeProject` from config > error
|
|
474
|
-
|
|
475
|
-
MCP tools follow the same logic - pass `project: "name"` to scope, or omit to use the active project.
|
|
476
|
-
|
|
477
|
-
### Memory
|
|
478
|
-
|
|
479
|
-
A memory is a short project fact worth knowing next session: ports, conventions, gotchas,
|
|
480
|
-
decisions, pointers. Each has a lowercase-hyphenated `name` (unique per project), a
|
|
481
|
-
`description` saying when it matters, `content` (up to 800 characters by default) and an
|
|
482
|
-
optional `priority` from 0 to 100. `context` loads the top 30 memories by priority; agents
|
|
483
|
-
then read the ones they need. Procedures and long guidance belong in skills.
|
|
484
|
-
|
|
485
|
-
```bash
|
|
486
|
-
orc mem add ulid-ids -d "Check before adding a table or ID field" -c "All IDs are ULIDs" --priority 90
|
|
487
|
-
orc mem list -q ids # search names and descriptions
|
|
488
|
-
orc mem show ulid-ids
|
|
489
|
-
orc mem edit ulid-ids --priority 80 -r "Narrower than we thought"
|
|
490
|
-
orc mem history ulid-ids # every change, with before/after
|
|
491
|
-
orc mem revert ulid-ids <change-id> --expected-change-id <latest-change-id> -r "Undo mistaken edit"
|
|
492
|
-
```
|
|
493
|
-
|
|
494
|
-
Memories move both ways between ORC and native agent memory. **Memories → Import / export** (with a project selected) or `orc mem import|export` reads and writes Claude Code memory files (`~/.claude/projects/<project>/memory/*.md` with `name`/`description` frontmatter and a `MEMORY.md` index), Codex notes (`$CODEX_HOME/memories/extensions/ad_hoc/notes`, which Codex consolidates into its generated memory; plain notes import with their leading heading, or else their first sentence, as the description; generated Codex summaries are never touched), or any folder of memory files. The project's Claude memory folder is the default. Dedup ignores whitespace and case, and treats a near copy (a few characters different) as the same memory: it is never imported or exported as new, and the dialog names the match. Similar items are flagged with their match and score. An existing memory or file is replaced only when you select it; imports keep memory history, and exports keep a backup.
|
|
495
|
-
|
|
496
|
-
```bash
|
|
497
|
-
orc mem sources # Claude and Codex memory folders; * marks this project's
|
|
498
|
-
orc mem import # preview this project's Claude memory folder
|
|
499
|
-
orc mem import --all # import every new memory
|
|
500
|
-
orc mem import ./notes --replace api-port
|
|
501
|
-
orc mem export --dry-run # compare with the folder
|
|
502
|
-
orc mem export ./memory -n ulid-ids --overwrite ulid-ids
|
|
503
|
-
```
|
|
504
|
-
|
|
505
|
-
### Knowledge bases
|
|
506
|
-
|
|
507
|
-
Knowledge bases hold human reference documents for agents to search and cite. A knowledge base belongs to a project or is global. Add documents by uploading files (PDF, Word, PowerPoint, Excel, HTML, CSV, Markdown, text), writing Markdown in the dashboard, or registering a folder whose files are copied in. ORC never writes the folder: a copy follows its file on each scan until it is edited in ORC, and a file deleted from the folder keeps its copy. Documents have folders, labels and `[[links]]` with backlinks.
|
|
508
|
-
|
|
509
|
-
```bash
|
|
510
|
-
orc kb create Runbooks --project my-app
|
|
511
|
-
orc kb add Runbooks ./docs/*.pdf # upload and parse
|
|
512
|
-
orc kb sources add Runbooks ./handbook # copy a folder in, rescanned periodically
|
|
513
|
-
orc kb editable-by Runbooks ui,cli,api # agents (mcp) may read but not edit
|
|
514
|
-
orc kb search "rollback procedure" # cited passages
|
|
515
|
-
orc kb evidence "how do we rotate keys" # budgeted evidence pack
|
|
516
|
-
orc kb usage Runbooks # reads by source (mcp, api, cli, ui)
|
|
517
|
-
```
|
|
518
|
-
|
|
519
|
-
Comments on a knowledge base or one of its documents ask for a change: a correction, a source to digest, a lesson to record. Each has an author and source, a status (open, resolved, dismissed) and one closing reply.
|
|
520
|
-
|
|
521
|
-
Any knowledge base can have a digest: an agent (Claude, Codex, ...) that follows the knowledge base's own instructions on a schedule, handling open comments first and then reading memories, session summaries and audit records to add, correct and clean up documents. The schedule is an ordinary ORC job (cron or manual) with run history. In the dashboard choose **Add digest** on a knowledge base; it starts from a generic template. Scheduled runs are skipped when nothing new happened. Each active project gets a starter **Learnings** knowledge base with a daily 03:00 digest.
|
|
522
|
-
|
|
523
|
-
```bash
|
|
524
|
-
orc kb comment add Learnings "Digest https://example.com/postmortem"
|
|
525
|
-
orc kb digest template > digest.md # edit, then:
|
|
526
|
-
orc kb digest set Runbooks -b codex --cron "0 3 * * *" -i digest.md
|
|
527
|
-
orc kb digest run Runbooks
|
|
528
|
-
```
|
|
529
|
-
|
|
530
|
-
Search combines title/path matches, SQLite full-text search and, when embeddings are configured (Ollama or an OpenAI-compatible API), vectors stored with sqlite-vec. Set the embedding URL, model and API key or token in Settings or with `orc kb settings`; the key is stored encrypted and never returned by the API. Results cite passages as `kb:<doc>@<rev>#<n>`. Every read is counted per document and source.
|
|
531
|
-
|
|
532
|
-
The built-in parser handles all formats without extra installs. For better PDF layout, tables and OCR, install the optional [Docling](https://github.com/docling-project/docling) parser from Settings or with `orc kb docling install` (about 2 GB); in `auto` mode it is then used for PDFs and images. Each knowledge base can override the parser.
|
|
533
|
-
|
|
534
|
-
Each knowledge base lists the call sources that may change its documents (`editable_by`: `ui`, `cli`, `api`, `mcp`; all four by default). Agents write with `kb_write` and `kb_document` (partial edits by exact text or line range) where `mcp` is allowed; every change is a revision recording its source and session. Knowledge base settings and knowledge settings cannot be changed over MCP, so an agent cannot widen its own access. Rendered Markdown shows remote images as links instead of loading them.
|
|
535
|
-
|
|
536
|
-
To back up knowledge bases, stop ORC and copy `~/.orc/orc.db` (with its `-wal` and `-shm` files) and `~/.orc/knowledge/originals/`, plus `~/.orc/secret.key`, without which a saved embedding API key cannot be decrypted and must be entered again. The search index, parse results and Markdown copies are rebuilt on the next start.
|
|
537
|
-
|
|
538
|
-
**MCP tools:** `kb_list`, `kb_search`, `kb_evidence`, `kb_read`, `kb_documents`, `kb_write`, `kb_document`, `kb_comment`, `kb_manage`, `kb_digest`, `kb_maintenance`
|
|
539
|
-
|
|
540
|
-
### Task status flow
|
|
541
|
-
|
|
67
|
+
orc mem add token-refresh-lock -d "Check before touching token refresh" -c "Use RWMutex for token refresh"
|
|
542
68
|
```
|
|
543
|
-
todo → queued → doing → review → done
|
|
544
|
-
│ │
|
|
545
|
-
v v
|
|
546
|
-
blocked changes_requested → doing
|
|
547
|
-
│
|
|
548
|
-
v
|
|
549
|
-
paused
|
|
550
|
-
```
|
|
551
|
-
|
|
552
|
-
Tasks with `required_review: true` (default) need your approval before moving to `done`. Set `max_review_rounds` to auto-pause tasks that cycle through too many revision rounds.
|
|
553
69
|
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
<img src="assets/TaskFlow.gif" alt="Task Flow" width="600" />
|
|
557
|
-
|
|
558
|
-
### Task flows
|
|
559
|
-
|
|
560
|
-
That pipeline is not hardcoded — it is a **flow graph** named `orc-default`. A flow is nodes joined by conditional edges that may cycle, so a task can run whatever shape its work actually needs: a plan → build → verify loop, a bug-fix-then-confirm loop, an executor with an independent supervisor, or three reviewers in parallel joined before a decision.
|
|
561
|
-
|
|
562
|
-
The graph itself is deterministic; only the nodes are agents. That means loops, branches, and fan-out behave predictably and are fully unit-testable, while the agents just do the work and report a verdict.
|
|
70
|
+
Open the dashboard at **http://localhost:7700** (or the desktop app), then connect your agent:
|
|
563
71
|
|
|
564
72
|
```bash
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
orc task add "Fix the flaky test" --flow orc-default --skill orc-sdlc
|
|
568
|
-
orc flow status <taskId> # active nodes + the ledger of outcomes
|
|
569
|
-
orc flow resume <taskId> --outcome approved # resolve a human gate
|
|
570
|
-
orc flow halt <taskId> # stop it and kill live nodes
|
|
571
|
-
```
|
|
572
|
-
|
|
573
|
-
| Built-in workflow | Use it for |
|
|
574
|
-
| --- | --- |
|
|
575
|
-
| `orc-default` | Development: understand, plan as needed, implement, verify and independently review; bounded rework. `required_review: false` explicitly skips agent review. |
|
|
576
|
-
| `orc-human-review` | The same development process plus human sign-off. Agent review and human approval are always required, even if `required_review` is false. |
|
|
577
|
-
| `orc-review-only` | Review existing work; approve, request changes, or pause when evidence is insufficient. |
|
|
578
|
-
|
|
579
|
-
**Nodes** are `agent` (runs a session with a skill), `gate` (deterministic branching, fan-out, join points), `human` (waits for you), or `terminal` (ends the run and sets the task's final status). **Edges** carry declarative conditions — `outcome`, `visits`, `var`, `elapsed_secs`, composed with `all`/`any`/`not` — which are data, never evaluated code.
|
|
580
|
-
|
|
581
|
-
Loops always terminate. Per-node `max_visits`, a per-run node-execution budget, a wall clock, plus deadlock and stall detection each halt the run and hand the task back to you with an explanation of which rail tripped.
|
|
582
|
-
|
|
583
|
-
#### Custom graphs per task
|
|
584
|
-
|
|
585
|
-
For work no named flow fits, attach a bespoke graph to a single task:
|
|
586
|
-
|
|
587
|
-
```bash
|
|
588
|
-
orc flow validate --file ./my-graph.json # catch mistakes before running anything
|
|
589
|
-
orc flow attach <taskId> --file ./my-graph.json --start
|
|
590
|
-
```
|
|
591
|
-
|
|
592
|
-
Definitions are JSON, validated on load: unknown edge targets, unreachable nodes, a graph that can never finish, or an edge shadowed by an earlier catch-all are all rejected up front rather than discovered mid-run. Reusable flows go in `~/.orc/flows/<name>/flow.json` (or `./.orc/flows/` to pin one per repo), and a user flow shadows a built-in of the same name — that is how you customise `orc-default` without patching orc.
|
|
593
|
-
|
|
594
|
-
Agents can do all of this themselves via the `flow_list`, `flow_read`, `flow_create`, `flow_attach`, `flow_status`, and `flow_report` MCP tools, so a planner can design the pipeline for the work it just decomposed.
|
|
595
|
-
|
|
596
|
-
#### In the web dashboard
|
|
597
|
-
|
|
598
|
-
A task's **Flow** section draws the graph the run froze at start next to its ledger: which node is active, the verdict each visit produced, how many visits a node has spent of its budget, per-node timings and errors, a link to each node's agent transcript, and — when a rail tripped — which one and why. Loopbacks are drawn as edges that go backwards, so a rework cycle looks like one.
|
|
599
|
-
|
|
600
|
-
When a run parks on a human gate, that panel is where you answer it: pick one of the outcomes the node's own edges can route, add a comment, and the flow continues. `Halt` stops a run and kills its live sessions. The **Flows** page lists every graph available with its source, marks the one a task with no flow of its own will run, shows any definition, and reports flows that failed validation along with the errors — so a broken graph is visible before a task tries to run it.
|
|
601
|
-
|
|
602
|
-
### Jobs
|
|
603
|
-
|
|
604
|
-
```bash
|
|
605
|
-
orc job add deploy --command "bun run deploy" --trigger manual
|
|
606
|
-
orc job add nightly --command "bun run test" --trigger cron --cron "0 22 * * *"
|
|
607
|
-
orc job add on-change --command "bun run lint" --trigger watch --watch "./src"
|
|
608
|
-
orc job add on-push --command "bun run ci" --trigger webhook
|
|
609
|
-
```
|
|
610
|
-
|
|
611
|
-
Jobs separate **what runs** from **when it runs**. Choose **Run command**,
|
|
612
|
-
**Run agent**, or **Create task** in the dashboard. Command is required only for
|
|
613
|
-
Run command. Agent jobs save instructions, backend, optional model and explicit
|
|
614
|
-
tool approval; each run links to its tracked session. Task jobs save a task title
|
|
615
|
-
and instructions and link to the created task. **Start the task flow automatically**
|
|
616
|
-
is off by default, so generated tasks wait for a manual flow start.
|
|
617
|
-
The CLI accepts typed actions through `--action-config <json>`.
|
|
618
|
-
|
|
619
|
-
New jobs are disabled by default. Select **Enable this job immediately** during
|
|
620
|
-
creation or pass `orc job add ... --enable` to opt in. Jobs supports enable/disable
|
|
621
|
-
directly in the list and for selected rows. Projects shares the selection toolbar
|
|
622
|
-
for activate, pause and archive actions; select-all applies only to displayed rows.
|
|
623
|
-
Failed bulk updates remain selected so you can retry them.
|
|
624
|
-
|
|
625
|
-
### Webhooks
|
|
626
|
-
|
|
627
|
-
Open **Activity → Webhooks** to see all configured event sources and their connected
|
|
628
|
-
jobs. Create a source without a job, copy its URL and one-time signing secret, then
|
|
629
|
-
register them with the provider. Sources belong to the selected project, or are
|
|
630
|
-
shared across projects when created in All projects.
|
|
631
|
-
|
|
632
|
-
In **Jobs → New job** (or Edit), choose **Webhook** as the trigger, select an
|
|
633
|
-
existing source or create one inline, and set this job's event/action filters.
|
|
634
|
-
One source can trigger multiple enabled jobs, each with its own filters and action.
|
|
635
|
-
The Webhooks page shows source enablement, connected jobs and recent deliveries,
|
|
636
|
-
including individual run results and links to generated tasks or agent sessions.
|
|
637
|
-
Deleting a job disconnects it while preserving the reusable source.
|
|
638
|
-
|
|
639
|
-
For command jobs, accepted JSON is passed unchanged on stdin; bounded metadata is
|
|
640
|
-
also available as `ORC_WEBHOOK_*` environment variables. Agent and task jobs receive
|
|
641
|
-
up to 50,000 characters of event data, explicitly marked as untrusted input, alongside
|
|
642
|
-
the configured instructions. Delivery history stores event metadata and a payload
|
|
643
|
-
hash, not the payload body or signing secret; generated tasks and agent prompts can
|
|
644
|
-
contain the supplied event data.
|
|
645
|
-
|
|
646
|
-
Generic endpoints verify `X-Orc-Signature-256: sha256=<HMAC-SHA256 of the raw body>`.
|
|
647
|
-
Use `X-Orc-Event` for event filtering and `X-Orc-Delivery` (or
|
|
648
|
-
`Idempotency-Key`) for deduplication. GitHub endpoints use
|
|
649
|
-
`X-Hub-Signature-256`, `X-GitHub-Event` and `X-GitHub-Delivery` directly.
|
|
650
|
-
Event names and payload `action` values are configurable, so PR lifecycle,
|
|
651
|
-
reviews, workflow runs, releases, or later providers use the same job trigger.
|
|
652
|
-
|
|
653
|
-
Signing secrets are encrypted at rest and shown only when an endpoint is created or
|
|
654
|
-
rotated. The receiver is intentionally outside normal ORC bearer authentication;
|
|
655
|
-
the per-endpoint HMAC is its authentication boundary. Management remains under the
|
|
656
|
-
authenticated API.
|
|
657
|
-
|
|
658
|
-
### Channels (Telegram / Slack)
|
|
659
|
-
|
|
660
|
-
Use **Settings → Channels** to configure connections, verify bot/workspace identity,
|
|
661
|
-
pair approved recipients, and define ordered inbound rules that invoke agents.
|
|
662
|
-
Rules support simple predicates and nested AND/OR/NOT groups; authorization runs
|
|
663
|
-
before routing, and the first matching rule wins. Agent replies return to the
|
|
664
|
-
original conversation. Agents can also send independently through `channel_send`
|
|
665
|
-
over MCP or `POST /api/channels/messages`.
|
|
666
|
-
|
|
667
|
-
Common Markdown renders automatically. Optional `overrides` accepts the provider's
|
|
668
|
-
native JSON message options, including Slack Block Kit and Telegram HTML/keyboards.
|
|
669
|
-
Connections, recipients and routes live in SQLite; credentials are encrypted or
|
|
670
|
-
referenced through server environment variables. Pairing grants messaging access
|
|
671
|
-
only; inbound invocation and Attention notifications are separate opt-ins.
|
|
672
|
-
|
|
673
|
-
See the [channel setup, routing, API/MCP and native payload reference](skills/orc-platform/references/channels.md).
|
|
674
|
-
|
|
675
|
-
In Telegram, `/start`, `/help` and `/status` show native chat-control buttons.
|
|
676
|
-
Tap **New session**, **Sessions**, **Project**, **Agent** or **Model** to operate
|
|
677
|
-
the conversation; long pickers have Previous/Next buttons. `/session_new` and
|
|
678
|
-
`/session_list` also appear in Telegram's command menu (Telegram command names
|
|
679
|
-
allow underscores, not hyphens). Agent turns show an updating preview with a
|
|
680
|
-
**Stop** button bound to that turn; the complete reply retains chat controls.
|
|
681
|
-
Existing argument-based commands remain available for compatibility.
|
|
682
|
-
|
|
683
|
-
### Legacy gateway (Telegram / Slack)
|
|
684
|
-
|
|
685
|
-
Approve agent work from your phone, search memory, or start a live AI session.
|
|
686
|
-
|
|
687
|
-
```json
|
|
688
|
-
{
|
|
689
|
-
"gateway": {
|
|
690
|
-
"telegram": {
|
|
691
|
-
"enabled": true,
|
|
692
|
-
"token": "7123456789:AAF...",
|
|
693
|
-
"authorized_users": [123456789]
|
|
694
|
-
}
|
|
695
|
-
}
|
|
696
|
-
}
|
|
697
|
-
```
|
|
698
|
-
|
|
699
|
-
**Commands:** `/status`, `/tasks`, `/approve <id>`, `/reject <id>`, `/jobs`, `/run <name>`, `/mem <query>`, `/agent <claude|codex>`
|
|
700
|
-
|
|
701
|
-
> [!TIP]
|
|
702
|
-
> Create a Telegram bot via [@BotFather](https://t.me/BotFather) and find your user ID via [@userinfobot](https://t.me/userinfobot).
|
|
703
|
-
|
|
704
|
-
<details>
|
|
705
|
-
<summary>Slack setup</summary>
|
|
706
|
-
|
|
707
|
-
```json
|
|
708
|
-
{
|
|
709
|
-
"gateway": {
|
|
710
|
-
"slack": {
|
|
711
|
-
"enabled": true,
|
|
712
|
-
"bot_token": "xoxb-...",
|
|
713
|
-
"app_token": "xapp-...",
|
|
714
|
-
"authorized_users": ["U01ABCDEF"]
|
|
715
|
-
}
|
|
716
|
-
}
|
|
717
|
-
}
|
|
718
|
-
```
|
|
719
|
-
|
|
720
|
-
Same commands as Telegram. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps) with Socket Mode enabled.
|
|
721
|
-
|
|
722
|
-
</details>
|
|
723
|
-
|
|
724
|
-
## Skills
|
|
725
|
-
|
|
726
|
-
ORC ships two entry-point skills. Their supporting references load only when needed; custom skills and packages remain supported.
|
|
727
|
-
|
|
728
|
-
### Install skills
|
|
729
|
-
|
|
730
|
-
```bash
|
|
731
|
-
# Install all ORC skills into your agent
|
|
73
|
+
claude mcp add --transport http orc 'http://127.0.0.1:7700/mcp' \
|
|
74
|
+
--header 'Authorization: Bearer ${ORC_API_SECRET}'
|
|
732
75
|
npx skills add niradler/orc --all
|
|
733
|
-
|
|
734
|
-
# Or pick specific ones
|
|
735
|
-
npx skills add niradler/orc --skill orc-platform orc-sdlc
|
|
736
|
-
|
|
737
|
-
# Global install
|
|
738
|
-
npx skills add niradler/orc --all -g
|
|
739
|
-
```
|
|
740
|
-
|
|
741
|
-
### Entry-point skills
|
|
742
|
-
|
|
743
|
-
| Skill | Purpose |
|
|
744
|
-
| --- | --- |
|
|
745
|
-
| `orc-platform` | Operate ORC domains: setup/interfaces/auth, memory and maintained KBs/digests/embeddings, work/operations, sessions/SSH/Git/chat, rules and agent packages |
|
|
746
|
-
| `orc-sdlc` | Requirements → risk/complexity classification → direct work or plan → implementation → tests/completeness → review/rework → authorized Git delivery, with shared learning throughout |
|
|
747
|
-
|
|
748
|
-
Start with the relevant entry point and read only its selected reference. Platform
|
|
749
|
-
guidance groups related domains while keeping memory, execution and rules independently
|
|
750
|
-
loadable; SDLC has planning, development and review/delivery references. Clear low-risk
|
|
751
|
-
work can execute directly; assigned managed nodes preserve roles and flow contracts.
|
|
752
|
-
|
|
753
|
-
### Built-in skill templates
|
|
754
|
-
|
|
755
|
-
Skill templates live in `skills/*/SKILL.md` (built-in) and `~/.orc/skills/` (user-defined). Agents discover them via `skill_list` and load with `skill_read`.
|
|
756
|
-
|
|
757
|
-
Skills can be assigned to several projects; no assignments means global. Connect
|
|
758
|
-
to `/mcp?project=orc` or `/mcp?projects=orc,project2` to discover and read only
|
|
759
|
-
the selected projects' skills plus global skills. Add `&mode=meta` for meta mode.
|
|
760
|
-
Project names are case-insensitive; unknown projects are rejected. Tool arguments
|
|
761
|
-
can narrow the selection to one project from the URL. Shared skills appear once;
|
|
762
|
-
project-specific instructions use the first applicable override in URL order,
|
|
763
|
-
then global instructions. An explicit tool `project` selects that project's version.
|
|
764
|
-
Named reads, supporting files, compatibility aliases and downloads follow the same
|
|
765
|
-
assignment rule. Project-specific instruction overrides remain independent of assignments.
|
|
766
|
-
MCP `skill_create` inherits the selected project; unscoped creation is global.
|
|
767
|
-
|
|
768
|
-
Manage assignments with `orc skill projects <name> --set <project-id> <project-id>`;
|
|
769
|
-
use `--global` to clear assignments, or omit flags to inspect them. The API exposes
|
|
770
|
-
authenticated `GET`/`PUT /api/skills/{name}/projects` with `{ "project_ids": [] }`.
|
|
771
|
-
Existing skills remain global until assigned. Reassign skills before deleting a project.
|
|
772
|
-
The project selector controls discovery, not API authentication or tenant authorization.
|
|
773
|
-
|
|
774
|
-
`skill_list({ q: "code review", limit: 30, offset: 0 })` searches names and
|
|
775
|
-
descriptions with weighted BM25, prefixes, English stemming, phrase matches,
|
|
776
|
-
substrings and bounded typo tolerance. Every term must match; results are sorted
|
|
777
|
-
by descending relevance score, with names breaking ties. Scores are relative
|
|
778
|
-
relevance, not probabilities; no embedding service is required. Without `q`,
|
|
779
|
-
the existing reads/recent sorting applies. MCP responses show `total`, `offset`,
|
|
780
|
-
`limit` and `next_offset`; pass the next offset to fetch another page. API
|
|
781
|
-
`GET /api/skills?q=...&limit=30&offset=0` returns `skills` plus those fields;
|
|
782
|
-
`next_offset: null` means the end. Default page size is 30, maximum 500.
|
|
783
|
-
CLI equivalents are `orc skill list -q "code review" --project-id <id> --limit 30 --offset 0`.
|
|
784
|
-
|
|
785
|
-
On the **Skills** page, every skill has an **Agent discovery** toggle, including
|
|
786
|
-
built-in, user/imported and modified skills. Visibility applies across the installation
|
|
787
|
-
and defaults to visible. Hidden skills stay on the Skills page for management and
|
|
788
|
-
remain readable by name, including supporting files; existing task flows continue to
|
|
789
|
-
use them. **Modified** means its instructions have an authored global/project edit.
|
|
790
|
-
|
|
791
|
-
The policy is saved under `skills.hidden_skills` in `~/.orc/config.json` and
|
|
792
|
-
read afresh for discovery, including by existing MCP processes. `GET /api/skills`
|
|
793
|
-
omits hidden skills; `include_hidden=true` returns the management catalog with
|
|
794
|
-
`discovery_hidden` metadata. `GET /api/skills/settings/visibility` reads the policy and
|
|
795
|
-
`PUT /api/skills/settings/visibility` replaces its `hidden_skills` array using the usual
|
|
796
|
-
API authentication. This installation-wide preference ignores project config.
|
|
797
|
-
New skills default to visible until hidden explicitly. Legacy `hidden_builtins` settings
|
|
798
|
-
remain supported with their original built-in-only behavior; modified instructions
|
|
799
|
-
remain discoverable under that legacy setting unless explicitly hidden via `hidden_skills`.
|
|
800
|
-
|
|
801
|
-
Retired built-in names (such as `orc-coder` and `orc-reviewer`) remain readable
|
|
802
|
-
as compatibility routes for saved tasks, authored overrides and frozen flows, but
|
|
803
|
-
are not additional discovery entries. New tasks and built-in flows use
|
|
804
|
-
`orc-sdlc`; the node role selects implementation versus independent review.
|
|
805
|
-
Applicable authored legacy worker/coder/reviewer/knowledge instructions remain
|
|
806
|
-
role-scoped supplements with revision provenance, including on resume. Other authored
|
|
807
|
-
legacy domain guidance is indexed from the canonical effective read and loads by name
|
|
808
|
-
when relevant. Conflicts are surfaced rather than silently rewriting stored overlays.
|
|
809
|
-
|
|
810
|
-
Add custom skills by creating a `SKILL.md` in `~/.orc/skills/my-workflow/SKILL.md`.
|
|
811
|
-
|
|
812
|
-
Skills are complete folders, following the [Agent Skills format](https://agentskills.io/specification). Keep the entry instructions in `SKILL.md` and reference supporting files with paths relative to the skill root:
|
|
813
|
-
|
|
814
|
-
```text
|
|
815
|
-
my-workflow/
|
|
816
|
-
SKILL.md
|
|
817
|
-
references/guide.md
|
|
818
|
-
references/topics/details.md
|
|
819
|
-
scripts/check.py
|
|
820
|
-
assets/template.json
|
|
821
|
-
```
|
|
822
|
-
|
|
823
|
-
`skill_list` loads metadata only. `skill_read` returns the entry instructions plus a recursive `files` inventory; supporting content loads on demand. For example, `skill_read({ name: "my-workflow", ref: "scripts/check.py" })` reads a script without executing it. Bare reference filenames such as `ref: "guide.md"` remain supported. Binary assets are transported as base64 with `encoding: "base64"`.
|
|
824
|
-
|
|
825
|
-
```bash
|
|
826
|
-
# Import the whole folder through the API
|
|
827
|
-
orc skill create my-workflow --directory ./my-workflow
|
|
828
|
-
orc skill read my-workflow --ref references/topics/details.md
|
|
829
|
-
orc skill validate ./my-workflow
|
|
830
|
-
orc skill export my-workflow ./exported/my-workflow
|
|
831
76
|
```
|
|
832
77
|
|
|
833
|
-
|
|
78
|
+
Codex, Cursor, Gemini and other MCP clients are covered in [Connect your agents](https://niradler.github.io/orc/docs/connect-agents).
|
|
834
79
|
|
|
835
|
-
|
|
836
|
-
orc skill import vercel-labs/agent-skills --list
|
|
837
|
-
orc skill import vercel-labs/agent-skills --skill web-design-guidelines
|
|
838
|
-
orc skill sync web-design-guidelines
|
|
839
|
-
```
|
|
80
|
+
## Five ways in
|
|
840
81
|
|
|
841
|
-
|
|
82
|
+
The same data sits behind every interface.
|
|
842
83
|
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
orc
|
|
848
|
-
|
|
849
|
-
orc
|
|
850
|
-
orc skill export-to claude my-workflow --project orc # <repo>/.claude/skills
|
|
851
|
-
orc skill local agents --project orc --all # <repo>/.agents/skills
|
|
852
|
-
```
|
|
853
|
-
|
|
854
|
-
Imported skills remain editable: open the skill, choose `SKILL.md` or a supporting text file, then **Edit** and **Save changes**. **Sync from GitHub** fetches the source again and compares each file against its last imported version. Local edits are kept when upstream has not changed that file. If both sides changed the same file, the whole sync pauses and lists conflicts. **Review override → Replace listed files** requires confirmation and replaces only those conflicts with upstream versions; unrelated local edits remain. If the local files or upstream commit changed since review, ORC requires a new sync check. Sync retains the previous folder under `~/.orc/skill-sync-backups/`; import provenance and upstream baselines live under `~/.orc/skill-imports/`. These backups are retained until manually removed. Private repositories and non-GitHub sources are not supported by this importer.
|
|
855
|
-
|
|
856
|
-
The dashboard can import a skill folder or add supporting files individually, then open each file from the detail sheet. API `POST /api/skills` and MCP `skill_create` accept optional `files: [{ path, content, encoding? }]` alongside `name` and the full `SKILL.md` `content`. Encoding defaults to `utf8`. Bundles allow 512 supporting files, 8 MiB per file and 16 MiB total. To change a supporting text file of an existing user skill, or add one, use MCP `skill_file_write`, API `PUT /api/skills/{name}/file` or `orc skill file <name> <path> -f <local-file> [--new]`: pass the current file text as the expected content (null / `--new` to add a file) so stale edits are rejected; every write is audited. These write the installed file for every scope; `SKILL.md` instructions change through `skill_update` / `orc skill update`. Paths must stay inside the skill folder; symlinks are excluded and cannot be read. The legacy `references` inventory is retained for existing clients. Worker prompts include the skill's entry path and file inventory so relative links resolve from the skill directory.
|
|
857
|
-
|
|
858
|
-
### Shared agents and portable packages
|
|
859
|
-
|
|
860
|
-
ORC shares authored definitions across coding agents through one library. An agent profile describes the specialist; a backend selects the coding agent that runs it. Profiles use [APM's `.agent.md` format](https://microsoft.github.io/apm/producer/author-primitives/instructions-and-agents/): YAML frontmatter with a required `description`, optional `name`, `model`, `tools`, `color`, and `handoffs`, followed by Markdown instructions. Unknown agent fields are preserved. Standalone profiles live in `~/.orc/agents/`; project profiles in `.apm/agents/` override matching shared IDs.
|
|
861
|
-
|
|
862
|
-
An imported package keeps its entire directory under `~/.orc/packages/<name>/`, including `apm.yml`, `.apm/agents/`, `.apm/skills/<name>/SKILL.md`, `.apm/instructions/`, scripts, references, and binary assets. Root `SKILL.md` packages are supported too. Manifest validation uses Microsoft's pinned OpenAPM v0.1 schema; the v0.1.41 schema is supported when explicitly selected with `$schema`. Import/export preserves dependency declarations, scripts, and extension fields. Import does not resolve dependencies or execute lifecycle scripts; use APM for those operations before importing the resulting package.
|
|
863
|
-
|
|
864
|
-
```bash
|
|
865
|
-
orc agent-package import ./team-agents
|
|
866
|
-
orc agent list
|
|
867
|
-
orc agent read team-agents/reviewer
|
|
868
|
-
orc agent-package export team-agents ./exported/team-agents
|
|
869
|
-
orc agent create reviewer --file ./reviewer.agent.md
|
|
870
|
-
orc agent export reviewer ./exported/reviewer.agent.md
|
|
871
|
-
```
|
|
84
|
+
| Interface | Use it for | Docs |
|
|
85
|
+
| --- | --- | --- |
|
|
86
|
+
| **Desktop app** | Daily driver: tray, start at login, bundled daemon and CLI | [Desktop and web](https://niradler.github.io/orc/docs/desktop-and-web) |
|
|
87
|
+
| **Web dashboard** | Board, sessions, terminals, knowledge, jobs, settings, from any browser or phone | [Desktop and web](https://niradler.github.io/orc/docs/desktop-and-web) |
|
|
88
|
+
| **CLI** | `orc task`, `orc mem`, `orc kb`, `orc job`, `orc flow`, `orc session` and more | [CLI](https://niradler.github.io/orc/docs/cli) |
|
|
89
|
+
| **MCP** | Agents read and write tasks, memory, knowledge and sessions at `/mcp` | [MCP](https://niradler.github.io/orc/docs/mcp) |
|
|
90
|
+
| **REST API + SDK** | Scripts and integrations, OpenAPI at `/openapi.json`, typed `@orc/sdk` client | [REST API](https://niradler.github.io/orc/docs/api) |
|
|
872
91
|
|
|
873
|
-
|
|
92
|
+
<table>
|
|
93
|
+
<tr>
|
|
94
|
+
<td><img src="docs/public/screens/tasks.png" alt="Task board" /></td>
|
|
95
|
+
<td><img src="docs/public/screens/sessions.png" alt="Agent sessions" /></td>
|
|
96
|
+
</tr>
|
|
97
|
+
<tr>
|
|
98
|
+
<td><img src="docs/public/screens/task-flow.png" alt="Task flow graph" /></td>
|
|
99
|
+
<td><img src="docs/public/screens/terminals.png" alt="Terminal workspace running the orc CLI" /></td>
|
|
100
|
+
</tr>
|
|
101
|
+
</table>
|
|
874
102
|
|
|
875
|
-
|
|
876
|
-
{ "kind": "agent", "agent": "team-agents/reviewer", "backend": "codex-cli", "outcomes": ["pass", "fail"] }
|
|
877
|
-
```
|
|
878
|
-
|
|
879
|
-
The same profile instructions and relative file locations reach every backend. Pinned models are supported by Claude SDK, Claude CLI, Codex CLI, and ACPX. Tool allowlists are enforced by Claude SDK and Claude CLI; other adapters reject profiles declaring tool restrictions. Unsupported model/tool settings fail before launch. Tool names and model IDs must be valid for the selected coding agent. Explicit session/flow model choices override the profile's model. Handoffs remain authored declarations; ORC flow edges control execution. Package instructions without `applyTo` are included automatically; scoped instructions retain their original glob strings or arrays in an on-demand index, which the coding agent applies when working on matching files.
|
|
880
|
-
|
|
881
|
-
The dashboard's **Packages** page imports OpenAPM and portable Agent Plugins v1.0.0 folders, inspects/exports their files, and saves reusable agent setups. **Run with → Open in ORC terminal** prepares the selected packages through Microsoft APM or Vercel skills, then opens the coding agent. Deployment persists in the chosen project; normal upstream trust and authentication prompts remain. Whole portable plugins activate through APM/Copilot; skills-only plugins can use Vercel with Claude, Codex or Copilot. See [Reusable agent packages](docs/agent-packages.md) for requirements and supported combinations.
|
|
882
|
-
|
|
883
|
-
The **Agents** page creates/reads specialist profiles. API `/api/agents` and `/api/agent-packages`, SDK clients, CLI, and MCP all access the same files. MCP tools are `agent_list`, `agent_read`, `agent_create`, `agent_update`, `agent_delete`, `agent_package_list`, `agent_package_read`, `agent_package_import`, `agent_package_update`, and `agent_package_delete`; updates and deletes require the raw content or package revision you last read. Package agent IDs are namespaced as `<package>/<file-stem>`.
|
|
884
|
-
|
|
885
|
-
## MCP tools
|
|
886
|
-
|
|
887
|
-
Agents can fetch original skill scripts/assets with
|
|
888
|
-
`skill_read({name: "orc-platform", ref: "scripts/upload-session.py", download: true, project: "my-app"})`.
|
|
889
|
-
It returns a signed ten-minute `download_url`, `sha256`, `size_bytes` and expiry
|
|
890
|
-
instead of the file body. Download to a local file and verify the hash; do not
|
|
891
|
-
reconstruct scripts from tool text. The URL authorizes only that file version and
|
|
892
|
-
does not contain the API secret. Keep it private. Expiry, API restart or file changes
|
|
893
|
-
require a new URL. Downloading never executes scripts. The authenticated REST mint
|
|
894
|
-
endpoint is `POST /api/skills/<name>/download` with `ref` and optional scope.
|
|
895
|
-
|
|
896
|
-
Tools are available to any connected agent. Start every session with `context`.
|
|
897
|
-
|
|
898
|
-
| Category | Tools |
|
|
899
|
-
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
900
|
-
| **Project** | `project_list` |
|
|
901
|
-
| **Memory** | `context`, `memory_list`, `memory_read`, `memory_create`, `memory_update`, `memory_delete`, `memory_history`, `memory_revert` |
|
|
902
|
-
| **Task** | `task_list`, `task_get`, `task_create`, `task_update`, `task_batch_create`, `task_link` |
|
|
903
|
-
| **Skill** | `skill_list`, `skill_read`, `skill_create` |
|
|
904
|
-
| **Agent** | `agent_list`, `agent_read`, `agent_create`, `agent_update`, `agent_delete`, `agent_package_list`, `agent_package_read`, `agent_package_import`, `agent_package_update`, `agent_package_delete` |
|
|
905
|
-
| **Flow** | `flow_report`, `flow_status`, `flow_list`, `flow_read`, `flow_create`, `flow_attach` |
|
|
906
|
-
| **Knowledge** | `kb_list`, `kb_search`, `kb_evidence`, `kb_read`, `kb_documents`, `kb_write`, `kb_maintenance` |
|
|
907
|
-
| **Search** | `search` |
|
|
908
|
-
| **Job** | `job_list`, `job_run`, `job_status` |
|
|
909
|
-
| **Session** | `session_event`, `session_snapshot`, `session_restore`, `session_log` |
|
|
910
|
-
|
|
911
|
-
## REST API
|
|
912
|
-
|
|
913
|
-
Runs on port 7700 with auto-generated OpenAPI spec.
|
|
914
|
-
|
|
915
|
-
- **Swagger UI:** `GET /docs`
|
|
916
|
-
- **OpenAPI spec:** `GET /openapi.json`
|
|
917
|
-
|
|
918
|
-
`GET /api/projects` and `GET /api/jobs` return bounded pages (`limit` defaults to 50, maximum 100;
|
|
919
|
-
`offset` defaults to 0), ordered by name and ID. Follow `next_offset` until it is
|
|
920
|
-
`null`. Project `status`/`tag` and job `enabled`/`project_id` filters apply to every
|
|
921
|
-
page. Dashboard lists and pickers load all pages, so later records remain searchable
|
|
922
|
-
and selectable.
|
|
923
|
-
|
|
924
|
-
<details>
|
|
925
|
-
<summary>Full endpoint list</summary>
|
|
926
|
-
|
|
927
|
-
| Method | Path | Description |
|
|
928
|
-
| ----------------------- | ------------------------------ | ------------------------------ |
|
|
929
|
-
| `GET` | `/health` | Health check |
|
|
930
|
-
| `GET/POST/PATCH/DELETE` | `/projects` | CRUD projects |
|
|
931
|
-
| `GET` | `/projects/by-name/{name}` | Lookup by name |
|
|
932
|
-
| `GET` | `/projects/{id}/summary` | Task/memory/job counts |
|
|
933
|
-
| `GET/POST/PATCH/DELETE` | `/tasks` | CRUD tasks |
|
|
934
|
-
| `GET/POST` | `/tasks/{id}/notes` | Task notes |
|
|
935
|
-
| `GET/POST/DELETE` | `/tasks/{id}/links` | Task dependencies |
|
|
936
|
-
| `GET/POST` | `/memories` | List (`q`, `sort`) / create |
|
|
937
|
-
| `GET/PATCH/DELETE` | `/memories/{name}` | Read / update / delete by name |
|
|
938
|
-
| `GET` | `/memories/{name}/history` | Change history |
|
|
939
|
-
| `POST` | `/memories/{name}/revert` | Revert a change |
|
|
940
|
-
| `GET` | `/knowledge/search` | Search documents (BM25/hybrid) |
|
|
941
|
-
| `GET` | `/knowledge/documents/{id}` | Get document by docid |
|
|
942
|
-
| `GET/POST/DELETE` | `/knowledge/collections` | CRUD collections |
|
|
943
|
-
| `POST` | `/knowledge/update` | Re-index collections |
|
|
944
|
-
| `GET` | `/knowledge/status` | Index status |
|
|
945
|
-
| `GET/POST` | `/jobs` | CRUD jobs |
|
|
946
|
-
| `POST` | `/jobs/{id}/trigger` | Trigger a job; `?sync=true` waits and returns output |
|
|
947
|
-
| `GET` | `/jobs/{id}/runs` | Run history |
|
|
948
|
-
| `GET` | `/jobs/{id}/runs/{runId}/logs` | Run logs |
|
|
949
|
-
| `GET` | `/skills` | Skill templates |
|
|
950
|
-
| `GET` | `/backends` | Agent backends + usability |
|
|
951
|
-
| `GET/POST` | `/flows` | List/create flow graphs |
|
|
952
|
-
| `GET` | `/flows/{name}` | Read a flow definition |
|
|
953
|
-
| `POST` | `/flows/validate` | Validate without saving |
|
|
954
|
-
| `GET/POST` | `/tasks/{id}/flow` | Get a task's run / attach one |
|
|
955
|
-
| `POST` | `/tasks/{id}/flow/resume` | Resolve a human node |
|
|
956
|
-
| `POST` | `/tasks/{id}/flow/halt` | Stop a running flow |
|
|
957
|
-
| `GET` | `/sessions` | Agent session logs |
|
|
958
|
-
| `POST` | `/mcp/tool` | Execute any MCP tool via HTTP |
|
|
959
|
-
|
|
960
|
-
</details>
|
|
961
|
-
|
|
962
|
-
## CLI reference
|
|
963
|
-
|
|
964
|
-
```
|
|
965
|
-
orc daemon start|stop|status Manage the daemon (API + scheduler + gateway)
|
|
966
|
-
orc daemon install|uninstall Register/remove auto-start on login/boot
|
|
967
|
-
orc api Start the API server only
|
|
968
|
-
orc mcp [--mode meta|full] Start the MCP server (stdio, meta by default)
|
|
969
|
-
orc home Show ~/.orc directory and config
|
|
970
|
-
orc status Show API health and counts
|
|
971
|
-
orc doctor Check which agent backends are usable here
|
|
972
|
-
|
|
973
|
-
orc project list|add|show|use|update|archive
|
|
974
|
-
orc task list|add|show|update|done|review|approve|reject|delete
|
|
975
|
-
orc mem list|show|add|edit|delete|history|revert|sources|import|export
|
|
976
|
-
orc job list|add|run|runs
|
|
977
|
-
orc session list|show|log
|
|
978
|
-
orc skill list|show|local|export-to
|
|
979
|
-
orc flow list|show|validate|create|attach|status|resume|halt
|
|
980
|
-
orc kb search|get|collections|add|remove|update|status
|
|
981
|
-
```
|
|
982
|
-
|
|
983
|
-
> [!NOTE]
|
|
984
|
-
> All task/mem/job/kb commands default to the active project. Use `-p <name>` to override or `--no-project` to see everything. Add `--json` for machine-readable output.
|
|
985
|
-
|
|
986
|
-
## Configuration
|
|
987
|
-
|
|
988
|
-
ORC merges config in priority order (later wins):
|
|
989
|
-
|
|
990
|
-
1. `~/.orc/config.json` - user global
|
|
991
|
-
2. `./.orc/config.json` - project-local
|
|
992
|
-
3. Environment variables
|
|
993
|
-
|
|
994
|
-
<details>
|
|
995
|
-
<summary>Environment variables</summary>
|
|
996
|
-
|
|
997
|
-
| Variable | Default | Description |
|
|
998
|
-
| -------------------------------- | --------------------- | ------------------------------------------------- |
|
|
999
|
-
| `ORC_DB_PATH` | `~/.orc/orc.db` | SQLite database path |
|
|
1000
|
-
| `ORC_API_HOST` | `127.0.0.1` | API listen host (set to `0.0.0.0` in Docker) |
|
|
1001
|
-
| `ORC_API_PORT` | `7700` | API listen port |
|
|
1002
|
-
| `ORC_API_SECRET` | - | Bearer token for auth |
|
|
1003
|
-
| `ORC_TERMINALS_ALLOW_WITHOUT_SECRET` | `false` | Legacy option; no longer needed. Terminals follow API open/authenticated mode |
|
|
1004
|
-
| `ORC_TELEGRAM_TOKEN` | - | Enables the Telegram gateway when set |
|
|
1005
|
-
| `AGENTAPI_URL` | `http://127.0.0.1:3284` | URL of host agentapi server (for `agentapi` backend) |
|
|
1006
|
-
| `ANTHROPIC_API_KEY` | - | Required for the `claude` backend (Anthropic SDK) |
|
|
1007
|
-
| `ORC_SESSION_ID` | `default` | Per-agent session identifier |
|
|
1008
|
-
| `ORC_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
|
|
1009
|
-
| `ORC_LOG_DIR` | `~/.orc/logs` | Log file directory |
|
|
1010
|
-
| `ORC_LOG_FILE` | `1` | Set to `0` to disable file logging |
|
|
1011
|
-
| `ORC_RUNNER_TIMEOUT` | `300` | Default job timeout (seconds) |
|
|
1012
|
-
| `ORC_AGENT_LOOP_ENABLED` | `false` | Enable the agent task loop |
|
|
1013
|
-
| `ORC_AGENT_LOOP_POLL_INTERVAL` | `5` | Task loop poll interval (minutes) |
|
|
1014
|
-
| `ORC_AGENT_LOOP_MAX_WORKERS` | `1` | Max concurrent worker agents |
|
|
1015
|
-
| `ORC_AGENT_LOOP_DEFAULT_BACKEND` | `claude` | Default agent backend |
|
|
1016
|
-
| `ORC_AGENT_LOOP_IDLE_TIMEOUT` | `20` | Session idle timeout (minutes) |
|
|
1017
|
-
| `ORC_AGENT_LOOP_AUTO_APPROVE` | `true` | Auto-approve worker tool permissions |
|
|
1018
|
-
| `ORC_KNOWLEDGE_ROOT` | beside `orc.db` | Knowledge base storage (files, index) |
|
|
1019
|
-
| `ORC_KNOWLEDGE_PARSER` | `auto` | `auto`, `basic` or `docling` |
|
|
1020
|
-
| `ORC_KNOWLEDGE_EMBEDDING_PROVIDER` | `none` | `none`, `ollama` or `openai` |
|
|
1021
|
-
| `ORC_KNOWLEDGE_EMBEDDING_URL` | provider default | Embedding endpoint |
|
|
1022
|
-
| `ORC_KNOWLEDGE_EMBEDDING_MODEL` | provider default | Embedding model |
|
|
1023
|
-
| `ORC_KNOWLEDGE_EMBEDDING_API_KEY` | - | API key for OpenAI-compatible embeddings |
|
|
1024
|
-
| `ORC_SQLITE_VEC_PATH` | bundled | Path to a sqlite-vec `vec0` library |
|
|
1025
|
-
|
|
1026
|
-
</details>
|
|
1027
|
-
|
|
1028
|
-
### Logs
|
|
1029
|
-
|
|
1030
|
-
All output goes to **stderr** (colored, human-readable) and **`~/.orc/logs/orc.log`** (JSON lines, machine-readable). Log files rotate at 10 MB with 3 rotated backups (30 MB total).
|
|
1031
|
-
|
|
1032
|
-
```bash
|
|
1033
|
-
# Tail recent errors
|
|
1034
|
-
grep '"level":"error"' ~/.orc/logs/orc.log | tail -20
|
|
1035
|
-
|
|
1036
|
-
# Watch live
|
|
1037
|
-
tail -f ~/.orc/logs/orc.log | jq .
|
|
1038
|
-
```
|
|
1039
|
-
|
|
1040
|
-
### Running as a background service
|
|
1041
|
-
|
|
1042
|
-
The daemon runs the API server, job scheduler, file watchers, and gateway in one process. To start it automatically on login/boot:
|
|
1043
|
-
|
|
1044
|
-
```bash
|
|
1045
|
-
orc daemon install # register auto-start for your OS
|
|
1046
|
-
orc daemon uninstall # remove auto-start registration
|
|
1047
|
-
```
|
|
1048
|
-
|
|
1049
|
-
| Platform | Mechanism | Auto-restart on crash |
|
|
1050
|
-
| ----------- | ------------------------------------------------------------------ | --------------------- |
|
|
1051
|
-
| **Windows** | Registry Run key (`HKCU\...\Run`) | No |
|
|
1052
|
-
| **macOS** | launchd (`~/Library/LaunchAgents/com.orc.daemon.plist`) | Yes |
|
|
1053
|
-
| **Linux** | systemd user service (`~/.config/systemd/user/orc-daemon.service`) | Yes |
|
|
1054
|
-
|
|
1055
|
-
No admin/root privileges required on any platform.
|
|
1056
|
-
|
|
1057
|
-
```bash
|
|
1058
|
-
# Manual control
|
|
1059
|
-
orc daemon start # start in foreground (API + scheduler + gateway)
|
|
1060
|
-
orc daemon stop # stop a running daemon
|
|
1061
|
-
orc daemon status # show scheduled jobs
|
|
1062
|
-
orc api # start the API server only (no scheduler/gateway)
|
|
1063
|
-
|
|
1064
|
-
# Check daemon health
|
|
1065
|
-
curl http://localhost:7700/health
|
|
1066
|
-
```
|
|
1067
|
-
|
|
1068
|
-
Logs go to `~/.orc/daemon.log`. Config is read from `~/.orc/config.json`.
|
|
1069
|
-
|
|
1070
|
-
## Architecture
|
|
1071
|
-
|
|
1072
|
-
```
|
|
1073
|
-
packages/
|
|
1074
|
-
core/ Config (Zod), types, logger, ULID IDs
|
|
1075
|
-
db/ Drizzle ORM + SQLite (~/.orc/orc.db)
|
|
1076
|
-
api/ Hono REST API + OpenAPI spec (:7700)
|
|
1077
|
-
sdk/ Typed HTTP client from OpenAPI
|
|
1078
|
-
cli/ Commander CLI (the `orc` binary)
|
|
1079
|
-
mcp/ MCP server (stdio + Streamable HTTP at /mcp)
|
|
1080
|
-
runner/ Job executor + cron/watch scheduler + task loop
|
|
1081
|
-
gateway/ Telegram + Slack bridge + agent sessions
|
|
1082
|
-
channels/ Provider transport, rendering, pairing and channel delivery
|
|
1083
|
-
agent-runtime/ Agent backend registry (claude, acpx, a2a)
|
|
1084
|
-
task-service/ Task status transitions + side-effects
|
|
1085
|
-
web/ React dashboard (Vite + Tailwind + shadcn + React Query)
|
|
1086
|
-
```
|
|
1087
|
-
|
|
1088
|
-
Data flow: `Agent → MCP → API → DB` / `CLI → SDK → API → DB`
|
|
1089
|
-
|
|
1090
|
-
## Development
|
|
1091
|
-
|
|
1092
|
-
```bash
|
|
1093
|
-
bun install # install all workspace deps
|
|
1094
|
-
bun dev # API + CLI + web in watch mode
|
|
1095
|
-
bun typecheck # typecheck all packages
|
|
1096
|
-
bun check # biome lint + format
|
|
1097
|
-
bun test # run all tests
|
|
1098
|
-
bun build # build all packages
|
|
1099
|
-
```
|
|
103
|
+
## Local and cloud
|
|
1100
104
|
|
|
1101
|
-
|
|
105
|
+
Run ORC on your laptop and a second ORC on your own server, side by side. Point the CLI and your agents at either one, hand a running session off to the server so it keeps going there, run tasks on the server's runner, and copy scratchpads, skills, agents and packages between the two. The two installations stay independent: nothing replicates on its own. See [Self-hosted ORC](https://niradler.github.io/orc/docs/self-hosted).
|
|
1102
106
|
|
|
1103
|
-
##
|
|
107
|
+
## Documentation
|
|
1104
108
|
|
|
1105
|
-
|
|
1106
|
-
- [Agent Rules](./docs/agent-rules.md) - opt-in tool protection, revision history, deterministic job actions, and evidence-based skill evaluation
|
|
1107
|
-
- [Usage Guide](./docs/usage-guide.md) - best practices for memory, tasks, multi-agent workflows, and configuration
|
|
1108
|
-
- [Vision](./docs/vision.md) - why ORC exists and the problem it solves
|
|
1109
|
-
- [Roadmap](./docs/roadmap.md) - what shipped and what's next
|
|
1110
|
-
- [Agent Orchestration Design](./docs/agent-orchestration-design.md) - architecture spec for the task loop and multi-agent workflow
|
|
1111
|
-
- [Task Flows](./docs/task-flows.md) - flow graphs: nodes, conditional edges, bounded loops, fan-out and joins, and how to author your own
|
|
109
|
+
Everything else lives on the docs site, **[niradler.github.io/orc](https://niradler.github.io/orc/)**:
|
|
1112
110
|
|
|
1113
|
-
|
|
111
|
+
- **Usage**: [what ORC is](https://niradler.github.io/orc/docs/what-is-orc), [concepts](https://niradler.github.io/orc/docs/concepts), [task flows](https://niradler.github.io/orc/docs/task-flows), [live sessions](https://niradler.github.io/orc/docs/live-sessions), [configuration](https://niradler.github.io/orc/docs/configuration)
|
|
112
|
+
- **Contributing**: [how to contribute](https://niradler.github.io/orc/development/), [run locally](https://niradler.github.io/orc/development/setup), [build and test](https://niradler.github.io/orc/development/build-and-test)
|
|
1114
113
|
|
|
1115
|
-
|
|
114
|
+
The same pages are in [`docs/`](docs) as plain Markdown.
|