orc-ai 0.1.60 → 0.1.62

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.
Files changed (129) hide show
  1. package/README.md +68 -1069
  2. package/dist/index.js +1017 -874
  3. package/dist/skills/orc-platform/SKILL.md +2 -1
  4. package/dist/skills/orc-platform/references/execution.md +2 -2
  5. package/dist/skills/orc-platform/references/knowledge.md +2 -2
  6. package/dist/skills/orc-platform/references/packages.md +2 -2
  7. package/dist/skills/orc-platform/references/rules.md +1 -1
  8. package/dist/skills/orc-platform/references/setup.md +4 -4
  9. package/dist/skills/orc-platform/references/web.md +110 -0
  10. package/dist/skills/orc-platform/references/work.md +2 -2
  11. package/dist/skills/orc-sdlc/references/development.md +14 -0
  12. package/dist/web/assets/Agents-CHrwONzQ.js +34 -0
  13. package/dist/web/assets/Audit-CImYAb-T.js +1 -0
  14. package/dist/web/assets/ChatUiRenderer-BkqPz_3-.js +4 -0
  15. package/dist/web/assets/{ConfirmDialog-DOSTWblx.js → ConfirmDialog-B5es4nUp.js} +1 -1
  16. package/dist/web/assets/Dashboard-DQC28lbV.js +1 -0
  17. package/dist/web/assets/{DocumentWorkspace-DVnU3uMP.js → DocumentWorkspace-Ba691e5k.js} +1 -1
  18. package/dist/web/assets/{ErrorState-DprXzfow.js → ErrorState-DB0nWfcc.js} +1 -1
  19. package/dist/web/assets/FileEditor-DL66rsR_.js +1 -0
  20. package/dist/web/assets/IntegrationCallback-CUZ5N-88.js +1 -0
  21. package/dist/web/assets/JobWebhooks-D6N__-Or.js +1 -0
  22. package/dist/web/assets/Jobs-ByM0xl7-.js +3 -0
  23. package/dist/web/assets/Knowledge-CPfft_nC.js +1 -0
  24. package/dist/web/assets/Markdown-C-3YfTSg.js +2 -0
  25. package/dist/web/assets/MarkdownEditor-Dv5kCc29.js +2 -0
  26. package/dist/web/assets/{MarkdownRenderer-B6SKIKVL.js → MarkdownRenderer-DFhVPrBL.js} +96 -96
  27. package/dist/web/assets/{NativeFolderField-DwXF9tJW.js → NativeFolderField-BzXvdqu3.js} +1 -1
  28. package/dist/web/assets/PackageCatalog-CkWSxsZn.js +8 -0
  29. package/dist/web/assets/{PackageRunDialog-HoczGux2.js → PackageRunDialog-9e2Ap03_.js} +2 -2
  30. package/dist/web/assets/{Pager-D-y150yZ.js → Pager-DQwUM0z7.js} +1 -1
  31. package/dist/web/assets/{PriorityBadge-D263N3pH.js → PriorityBadge-DOfXvpzs.js} +1 -1
  32. package/dist/web/assets/Projects-B7DXmjIX.js +3 -0
  33. package/dist/web/assets/{ResponsiveFilters-CQ42T3S8.js → ResponsiveFilters-HzhzzjyL.js} +1 -1
  34. package/dist/web/assets/ResumeActions-M11IqtTQ.js +1 -0
  35. package/dist/web/assets/Rules-BFW_OcW_.js +18 -0
  36. package/dist/web/assets/{ScratchpadDiagramEditor-Dcfngku2.js → ScratchpadDiagramEditor-MXUNosJN.js} +1 -1
  37. package/dist/web/assets/Scratchpads-KW5J8Ufq.js +10 -0
  38. package/dist/web/assets/SessionHomeLink-DYWKVgfX.js +1 -0
  39. package/dist/web/assets/Sessions-BrOvkZB8.js +4 -0
  40. package/dist/web/assets/Settings-CHlPiV6t.js +14 -0
  41. package/dist/web/assets/Skills-DgOnOKie.js +3 -0
  42. package/dist/web/assets/{SourceEditor-DNHVu9ux.js → SourceEditor-x5FG2Umx.js} +6 -6
  43. package/dist/web/assets/{StatusBadge-BUGpPpcH.js → StatusBadge-CKL0hTFN.js} +1 -1
  44. package/dist/web/assets/{TagInput-BmRYPN4B.js → TagInput-ChFu05vJ.js} +1 -1
  45. package/dist/web/assets/TaskDetailSheet-BVmehTN7.js +1 -0
  46. package/dist/web/assets/Tasks-D7N3FlZd.js +22 -0
  47. package/dist/web/assets/Terminals-D-D3Ovm0.css +1 -0
  48. package/dist/web/assets/Terminals-j55maqYv.js +2 -0
  49. package/dist/web/assets/ViewHeader-Bveo_NIZ.js +1 -0
  50. package/dist/web/assets/{Webhooks-CP-m_Dos.js → Webhooks-DVSb-CMh.js} +1 -1
  51. package/dist/web/assets/{badge-CpU0J4qt.js → badge-BqTVr27Z.js} +1 -1
  52. package/dist/web/assets/{button-C91mbQEU.js → button-By-NN7c7.js} +1 -1
  53. package/dist/web/assets/check-Cg2_C_4I.js +1 -0
  54. package/dist/web/assets/chevron-down-KBvm_HoX.js +1 -0
  55. package/dist/web/assets/circle-check-DWP3C_MJ.js +1 -0
  56. package/dist/web/assets/client-954dj6K2.js +1 -0
  57. package/dist/web/assets/{dialog-D86vkhdt.js → dialog-DNIYhwi4.js} +1 -1
  58. package/dist/web/assets/{dist-BKxzy3T8.js → dist-DScw4RwC.js} +1 -1
  59. package/dist/web/assets/{download-6d5_Jyox.js → download-BD7lYc4O.js} +1 -1
  60. package/dist/web/assets/{highlighted-body-JLMTFACH-C0zXH1C-.js → highlighted-body-JLMTFACH-C3KWFdwV.js} +1 -1
  61. package/dist/web/assets/index-NhGnEaeq.js +133 -0
  62. package/dist/web/assets/index-hvCYuRJb.css +1 -0
  63. package/dist/web/assets/{label-BdnRgBbz.js → label-Bm_d0NKL.js} +1 -1
  64. package/dist/web/assets/live-sessions-CGWdUdHs.js +1 -0
  65. package/dist/web/assets/{maximize-2-Daih3Vv7.js → maximize-2-BUxUwGbf.js} +1 -1
  66. package/dist/web/assets/mermaid-WFAXDIZX-Dr-vK9VQ.js +1 -0
  67. package/dist/web/assets/schemas-BQZhekae.js +55 -0
  68. package/dist/web/assets/{scratchpad-kinds-vQJshqz1.js → scratchpad-kinds-CaB1JmF7.js} +1 -1
  69. package/dist/web/assets/{scratchpad-routes-D8SCEha7.js → scratchpad-routes-BtsIfhUW.js} +1 -1
  70. package/dist/web/assets/{scroll-area-Cmb_s_kX.js → scroll-area-BhajWBGy.js} +1 -1
  71. package/dist/web/assets/select-cyLFVkkB.js +1 -0
  72. package/dist/web/assets/{table-Q26Vm3R3.js → table-COm8Aml-.js} +1 -1
  73. package/dist/web/assets/{tabs-DpKnjRll.js → tabs-bEwJLtA0.js} +1 -1
  74. package/dist/web/assets/{textarea-BRdsUa6B.js → textarea-CovStda2.js} +1 -1
  75. package/dist/web/assets/{upload-BLDr7Cwk.js → upload-CPf6QZHl.js} +1 -1
  76. package/dist/web/assets/{useIntegrations-CkfXwYNs.js → useIntegrations-C0MAVKB4.js} +1 -1
  77. package/dist/web/assets/{useJobs-BNj4dd9l.js → useJobs-BlWldKP0.js} +1 -1
  78. package/dist/web/assets/{useListSelection-DLQYrJX-.js → useListSelection-BnMxiGpC.js} +1 -1
  79. package/dist/web/assets/{useMemories-BpfvcV2g.js → useMemories-CAf8HcOI.js} +1 -1
  80. package/dist/web/assets/useMutation-CRAWY7v2.js +1 -0
  81. package/dist/web/assets/{useSessions-n-bp8ic5.js → useSessions-DiUU2FN8.js} +1 -1
  82. package/dist/web/assets/{x-CIaAKXRo.js → x-tY-z3woy.js} +1 -1
  83. package/dist/web/index.html +21 -19
  84. package/dist/web/manifest.webmanifest +2 -2
  85. package/package.json +1 -1
  86. package/dist/web/assets/Agents-DBN_IKhQ.js +0 -34
  87. package/dist/web/assets/Attention-Col9bpvb.js +0 -2
  88. package/dist/web/assets/Audit-DDhPMP5V.js +0 -1
  89. package/dist/web/assets/ChatUiRenderer-Bflvv2nP.js +0 -4
  90. package/dist/web/assets/Dashboard-CXREcWFQ.js +0 -1
  91. package/dist/web/assets/FileEditor-YLZReqhf.js +0 -1
  92. package/dist/web/assets/FormDialog-CelnA8hT.js +0 -1
  93. package/dist/web/assets/IntegrationCallback-elv3Aqfs.js +0 -1
  94. package/dist/web/assets/JobWebhooks-BvKIhaAK.js +0 -1
  95. package/dist/web/assets/Jobs-TFiqlEzO.js +0 -1
  96. package/dist/web/assets/Knowledge-Dz9v7lfr.js +0 -1
  97. package/dist/web/assets/Markdown-CtVGTUZH.js +0 -2
  98. package/dist/web/assets/MarkdownEditor-CSloDLyL.js +0 -2
  99. package/dist/web/assets/PackageCatalog-DSwcvJsN.js +0 -8
  100. package/dist/web/assets/Projects-D5da4x_q.js +0 -3
  101. package/dist/web/assets/ResumeActions-DYiHEYFy.js +0 -1
  102. package/dist/web/assets/Rules-CYG1JoBH.js +0 -18
  103. package/dist/web/assets/Scratchpads-uSMao0H4.js +0 -10
  104. package/dist/web/assets/Sessions-BWh81qh3.js +0 -3
  105. package/dist/web/assets/Settings-w_H15X7M.js +0 -14
  106. package/dist/web/assets/Skills-CmcTt8ye.js +0 -8
  107. package/dist/web/assets/TaskDetailSheet-DfK_DtzG.js +0 -1
  108. package/dist/web/assets/Tasks-CbOw64sI.js +0 -22
  109. package/dist/web/assets/Terminals-C0aoP7ar.css +0 -1
  110. package/dist/web/assets/Terminals-DP3MyIBo.js +0 -3
  111. package/dist/web/assets/ViewHeader-BtTaSrXy.js +0 -1
  112. package/dist/web/assets/check-N8fVGVDO.js +0 -1
  113. package/dist/web/assets/chevron-down-wgh-M0zj.js +0 -1
  114. package/dist/web/assets/circle-alert-OZ-kwnCD.js +0 -1
  115. package/dist/web/assets/circle-check-DQM5o2QS.js +0 -1
  116. package/dist/web/assets/claude-DyzolaFc.svg +0 -3
  117. package/dist/web/assets/client-BnTXPI20.js +0 -1
  118. package/dist/web/assets/codex-BNO0LSlX.svg +0 -1
  119. package/dist/web/assets/copilot-BALWjOlU.svg +0 -1
  120. package/dist/web/assets/cursor-DdfUZ9gB.svg +0 -12
  121. package/dist/web/assets/index-D5qFuDmc.js +0 -160
  122. package/dist/web/assets/index-z4BVJQry.css +0 -1
  123. package/dist/web/assets/link-2-Ced5Jr2w.js +0 -1
  124. package/dist/web/assets/list-OJI1AaZs.js +0 -1
  125. package/dist/web/assets/live-sessions-D07BClP7.js +0 -1
  126. package/dist/web/assets/mermaid-WFAXDIZX-BTh2e4d1.js +0 -1
  127. package/dist/web/assets/save-CnCcteVb.js +0 -1
  128. package/dist/web/assets/terminal-links-B3ce99i1.js +0 -1
  129. 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
- # orc
4
-
5
- **Multi-agent orchestrator with human-in-the-loop review**
6
-
7
- [![npm version](https://img.shields.io/npm/v/orc-ai?style=flat-square)](https://www.npmjs.com/package/orc-ai)
8
- [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
9
- ![Bun](https://img.shields.io/badge/Bun-%3E%3D1.1-f472b6?style=flat-square&logo=bun&logoColor=white)
10
- ![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)
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
- ### Key features
5
+ # orc
26
6
 
27
- | Feature | What it does |
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
- ## Getting started
9
+ Tasks, live sessions, memory and knowledge shared across Claude Code, Codex and Cursor, on your laptop or your own server.
43
10
 
44
- ### Install
11
+ [![Release](https://img.shields.io/github/v/release/niradler/orc?style=flat-square&color=242424)](https://github.com/niradler/orc/releases/latest)
12
+ [![npm](https://img.shields.io/npm/v/orc-ai?style=flat-square&color=242424)](https://www.npmjs.com/package/orc-ai)
13
+ [![Docs](https://img.shields.io/badge/docs-niradler.github.io%2Forc-242424?style=flat-square)](https://niradler.github.io/orc/)
14
+ [![License: MIT](https://img.shields.io/badge/license-MIT-242424?style=flat-square)](LICENSE)
45
15
 
46
- **Recommended: the desktop app.** Download the installer for your machine from [GitHub Releases](https://github.com/niradler/orc/releases) - no Bun, Node or npm needed. Maintainers: see the [local release command](docs/releases.md).
16
+ [Documentation](https://niradler.github.io/orc/) · [Install](#install) · [Quick start](#quick-start) · [Releases](https://github.com/niradler/orc/releases)
47
17
 
48
- | OS | Installer |
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
- On first launch the app sets everything up:
20
+ </div>
56
21
 
57
- - starts the orc daemon (API, scheduler, session watchers, gateway) and opens the dashboard in its window
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
- The builds are unsigned: on macOS right-click the app and choose Open the first time, on Windows choose "More info" then "Run anyway".
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
- The sidebar shows the saved execution host, for example `Connected (lab)` or `Connected (local)`. Switching hosts applies to new actions immediately. For a full restart, use **Settings → ORC server → Restart ORC server**; it keeps settings and reconnects the dashboard automatically. Restart closes active terminals and may interrupt running work. Host changes never trigger a restart automatically.
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
- <details>
67
- <summary>Headless / CLI-only install (servers, Docker, CI)</summary>
32
+ ## Install
68
33
 
69
- Needs [Bun](https://bun.sh) >= 1.4.4 for the npm install.
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
- ```bash
72
- npm install -g orc-ai
73
- ```
74
-
75
- #### Pre-built binaries
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
- Download from [GitHub Releases](https://github.com/niradler/orc/releases):
42
+ Prefer a headless install? Use a single binary, npm or Docker:
78
43
 
79
44
  ```bash
80
- # macOS (Apple Silicon)
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
- # macOS (Intel)
84
- curl -L https://github.com/niradler/orc/releases/latest/download/orc-mac-x64 -o /usr/local/bin/orc && chmod +x /usr/local/bin/orc
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
- ```bash
98
- git clone https://github.com/niradler/orc
99
- cd orc && bun install && bun build
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
- </details>
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
- ### Quick start
60
+ ## Quick start
105
61
 
106
62
  ```bash
107
- # 1. Start the daemon - runs the REST API on :7700, task loop, job scheduler, gateway, and web UI
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" --priority 60
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
- `queued` means a node is waiting for a worker slot — the task is claimed but nothing is running on it yet, so it counts as pending rather than in progress (the dashboard's board shows it under Todo, labelled `queued`). It becomes `doing` when a session actually starts, which is what keeps the board from showing more work in flight than `agent_loop.max_workers` allows.
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
- orc flow list # what graphs are available
566
- orc flow show orc-default # nodes, edges, limits
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
- Import GitHub skills from **Skills → Import from GitHub**. Paste a repository URL, `owner/repo`, a GitHub skill-folder URL, or a `https://skills.sh/owner/repo/skill` link, discover the skills, then select which to import. Private repositories use `gh` credentials on the configured execution host (local by default, remote when `ssh.host` is set), falling back to `ORC_GITHUB_TOKEN` / `github.token` on the ORC server; credentials need access to the repository. Without credentials, public repositories still work. ORC copies each complete folder at the displayed commit, including nested documentation, scripts and binary assets. Existing names are never overwritten by an import. Select up to 16 skills per import (64 MiB total).
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
- ```bash
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
- **Skills → Import / export** also moves skills between ORC and local agents. **Import from local agents** copies skill folders from agent folders such as `~/.claude/skills` and `~/.codex/skills`, or any folder of skill folders. **Export to agents** writes ORC skills as native skill folders (`SKILL.md` plus supporting files) into an existing agent skills folder, a project checkout or any folder. A project's checkout is its folder (scope) or the git repo of its local agent sessions, with worktrees folded into the main checkout; both dialogs list each one's repo-level skill folders (`.claude/skills`, `.agents/skills` for Codex and shared agents, `.gemini/skills`, `.cursor/skills`, `.opencode/skills`). Dedup ignores whitespace and case and compares content, not just names: a copy under another name or a near copy (a one-letter edit) is flagged with its match and is not imported or exported as new. Imports never replace an ORC skill. Exports replace an existing folder only when you select it, keep a backup, and never write through a symlinked folder.
82
+ The same data sits behind every interface.
842
83
 
843
- ```bash
844
- orc skill local # scan agent skill folders
845
- orc skill local --path ./shared-skills --all
846
- orc skill local claude -s pdf-tools
847
- orc skill export-to claude my-workflow --dry-run
848
- orc skill export-to ./exported my-workflow --overwrite my-workflow
849
- orc skill project-folders --project 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
- Select a shared profile independently of its backend in an ORC flow:
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
- ```json
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
- See the [development guide](./docs/development.md) for dev ports, servers, testing, and troubleshooting. [AGENTS.md](./AGENTS.md) contains session-wide agent instructions and coding conventions. For releases and installation upgrades, follow the [release protocol](./docs/releases.md).
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
- ## Learn more
107
+ ## Documentation
1104
108
 
1105
- - [Knowledge learning loop](./docs/knowledge-loop.md) - memories, knowledge base digests and comments, skill edits, and human revert
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
- ### Knowledge learning
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
- Session review records verified lessons, and each project's Learnings knowledge base has a daily digest that turns memories, session summaries and comments into documents. Reuse them through ordinary KB search and skill reads. The dashboard shows learning history, audit records and manual skill revert. See [Knowledge learning loop](docs/knowledge-loop.md) for scopes, scheduling and validation limits.
114
+ The same pages are in [`docs/`](docs) as plain Markdown.