orc-ai 0.1.48 → 0.1.49

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 (121) hide show
  1. package/README.md +1059 -0
  2. package/dist/index.js +514 -494
  3. package/dist/web/assets/{Agents-jr4tBoaK.js → Agents-C8dJX8px.js} +3 -3
  4. package/dist/web/assets/{Attention-C1CBdN6r.js → Attention-BHYo8Lwr.js} +2 -2
  5. package/dist/web/assets/{Audit-CHGMGiUH.js → Audit-CS_DZkbJ.js} +1 -1
  6. package/dist/web/assets/ConfirmDialog-CrSa87VF.js +1 -0
  7. package/dist/web/assets/Dashboard-V813oIhq.js +1 -0
  8. package/dist/web/assets/{DocumentWorkspace-Bw6NaR0Q.js → DocumentWorkspace-CNyVQTjg.js} +1 -1
  9. package/dist/web/assets/EmptyState-Ctm7L70B.js +1 -0
  10. package/dist/web/assets/ErrorState-BPTepwiG.js +1 -0
  11. package/dist/web/assets/{FileEditor-BWeo_YzB.js → FileEditor-Dh29_xCL.js} +1 -1
  12. package/dist/web/assets/JobWebhooks-TvAY8p1V.js +1 -0
  13. package/dist/web/assets/{Jobs-BYlPCj8c.js → Jobs-C5ggSs2T.js} +3 -3
  14. package/dist/web/assets/{Knowledge-DsOJpZd5.js → Knowledge-BpiN3iVE.js} +3 -3
  15. package/dist/web/assets/{PackageCatalog-CnsavTBo.js → PackageCatalog-B1U3vfhW.js} +5 -5
  16. package/dist/web/assets/{Pager-DCsiS5yC.js → Pager-ClYYU9et.js} +1 -1
  17. package/dist/web/assets/PriorityBadge-BW-A50LE.js +1 -0
  18. package/dist/web/assets/Projects-DRao5Qpk.js +3 -0
  19. package/dist/web/assets/ResumeActions-DHTOr6GQ.js +11 -0
  20. package/dist/web/assets/{Rules-K9XzeBoM.js → Rules-DGKsAbTf.js} +2 -2
  21. package/dist/web/assets/{Sessions-DVFKv-nY.js → Sessions-CWHU6sYy.js} +3 -3
  22. package/dist/web/assets/{Settings-DRFRwAzC.js → Settings-yW1S2q4F.js} +5 -5
  23. package/dist/web/assets/{Skills-794QsmRr.js → Skills-BwdXE5nT.js} +4 -4
  24. package/dist/web/assets/SourceEditor-ft02z20v.js +43 -0
  25. package/dist/web/assets/StatusBadge-C5G1fdZh.js +1 -0
  26. package/dist/web/assets/TaskDetailSheet-fUSHPFB-.js +11 -0
  27. package/dist/web/assets/{Tasks-DPjDT6DJ.js → Tasks-uRqvmLz7.js} +9 -9
  28. package/dist/web/assets/{Terminals-BAT8w5fU.js → Terminals-W5nszLI1.js} +6 -6
  29. package/dist/web/assets/ViewHeader-DXR0ZaMO.js +1 -0
  30. package/dist/web/assets/Webhooks-lXLoKWdt.js +1 -0
  31. package/dist/web/assets/{abnfDiagram-VCTEODGH-CU33f3k1.js → abnfDiagram-VCTEODGH-K8P_VxLi.js} +1 -1
  32. package/dist/web/assets/{arc-Cvg6JGGh.js → arc-BOl9BKfD.js} +1 -1
  33. package/dist/web/assets/{architectureDiagram-5GKGNRK7-CCrBayxl.js → architectureDiagram-5GKGNRK7-DIZ15fO5.js} +2 -2
  34. package/dist/web/assets/{blockDiagram-I7D4REHJ-UciymbQJ.js → blockDiagram-I7D4REHJ-DMrufypV.js} +1 -1
  35. package/dist/web/assets/{c4Diagram-7LVT6UL2-z2xI2mL_.js → c4Diagram-7LVT6UL2-BUUxjwvU.js} +1 -1
  36. package/dist/web/assets/channel-CQFNQIhG.js +1 -0
  37. package/dist/web/assets/{chunk-2Q5K7J3B-BKGKI1uz.js → chunk-2Q5K7J3B-wRIxA2_q.js} +1 -1
  38. package/dist/web/assets/{chunk-5VM5RSS4-CLAy5Pjy.js → chunk-5VM5RSS4-B6lAVcgQ.js} +1 -1
  39. package/dist/web/assets/{chunk-F27PBJKO-Ch--IqBe.js → chunk-F27PBJKO-DVuei-Pl.js} +1 -1
  40. package/dist/web/assets/{chunk-IMKFNOWR-Rlkt_DmX.js → chunk-IMKFNOWR-CwyogA-y.js} +1 -1
  41. package/dist/web/assets/{chunk-JWPE2WC7-DaeLNYk7.js → chunk-JWPE2WC7-zdsOarNZ.js} +1 -1
  42. package/dist/web/assets/{chunk-POPQ4Y6H-BnuI44n3.js → chunk-POPQ4Y6H-D3ieeKih.js} +1 -1
  43. package/dist/web/assets/{chunk-SVP7TREG-DvZSQ5NI.js → chunk-SVP7TREG-CmiQdvOH.js} +1 -1
  44. package/dist/web/assets/{chunk-TICWLB2K-DVsqEZRj.js → chunk-TICWLB2K-CieIpfOy.js} +1 -1
  45. package/dist/web/assets/{chunk-XXDRQBXY-DnIZuVZV.js → chunk-XXDRQBXY-BoTHwisB.js} +1 -1
  46. package/dist/web/assets/classDiagram-ZZMXUADV-B5yD90Df.js +1 -0
  47. package/dist/web/assets/classDiagram-v2-VYDZK3BY-B5yD90Df.js +1 -0
  48. package/dist/web/assets/{cose-bilkent-JH36ORCC-Cn03pIS1.js → cose-bilkent-JH36ORCC-CtGsuuTW.js} +1 -1
  49. package/dist/web/assets/{cynefin-OW5HDTMX-Ce0_rfcJ.js → cynefin-OW5HDTMX-vMXgcpgg.js} +1 -1
  50. package/dist/web/assets/{cynefinDiagram-5FMLGOSQ-BmvPd2DO.js → cynefinDiagram-5FMLGOSQ-kMbm5D7e.js} +1 -1
  51. package/dist/web/assets/{dagre-GXQ25YYZ-BI_iESjX.js → dagre-GXQ25YYZ-xmoviGlr.js} +1 -1
  52. package/dist/web/assets/{diagram-S7CK7UJ4-DCkANt02.js → diagram-S7CK7UJ4-CguQzzXs.js} +1 -1
  53. package/dist/web/assets/{diagram-UQ7AKVKN-CJbIrhc6.js → diagram-UQ7AKVKN-CMX0u7Gf.js} +1 -1
  54. package/dist/web/assets/{diagram-VSXAHHWV-BS3wAm8f.js → diagram-VSXAHHWV-cuhv3Fvj.js} +1 -1
  55. package/dist/web/assets/{diagram-VX7I27RA-Bf6ouJud.js → diagram-VX7I27RA-Bp_JbX0e.js} +1 -1
  56. package/dist/web/assets/{diagram-Z3DM3KII-BR7YnYjD.js → diagram-Z3DM3KII-oZ6jRSCd.js} +1 -1
  57. package/dist/web/assets/{download-BvcsHVh_.js → download-UgMvjBjR.js} +1 -1
  58. package/dist/web/assets/{ebnfDiagram-PWID7BFC-BB_duVb2.js → ebnfDiagram-PWID7BFC-DbxnEjb0.js} +1 -1
  59. package/dist/web/assets/{erDiagram-RLTQ6QDP-DVpvqADj.js → erDiagram-RLTQ6QDP-Cl5kXPho.js} +1 -1
  60. package/dist/web/assets/{flowDiagram-HODETNUW-CYCG8Khy.js → flowDiagram-HODETNUW-DueO0Ju6.js} +1 -1
  61. package/dist/web/assets/{folder-open-FLHAqscD.js → folder-open-DojCP5NP.js} +1 -1
  62. package/dist/web/assets/{ganttDiagram-EL5Y4UJY-BXeyk_i8.js → ganttDiagram-EL5Y4UJY-DNjT4iVH.js} +4 -4
  63. package/dist/web/assets/{gitGraphDiagram-WWUBYQGX-KGCo-QoM.js → gitGraphDiagram-WWUBYQGX-B4aUQ9gY.js} +1 -1
  64. package/dist/web/assets/{highlighted-body-KPVGNVTW-_lM_4hwr.js → highlighted-body-KPVGNVTW-gt1u8RcC.js} +1 -1
  65. package/dist/web/assets/index-C_jtMgr7.js +412 -0
  66. package/dist/web/assets/{infoDiagram-27XIBGKW-BXbLlnR-.js → infoDiagram-27XIBGKW-CWcOvNAB.js} +1 -1
  67. package/dist/web/assets/{ishikawaDiagram-5VMMS53U-Bgfr65z9.js → ishikawaDiagram-5VMMS53U-ccIPCUs4.js} +1 -1
  68. package/dist/web/assets/{journeyDiagram-3NMN7TZE-Cceeqsmt.js → journeyDiagram-3NMN7TZE-rRe3uTLu.js} +1 -1
  69. package/dist/web/assets/{kanban-definition-UXKFOSKX-BWdymhtd.js → kanban-definition-UXKFOSKX-tAKCWntJ.js} +1 -1
  70. package/dist/web/assets/{layout-VQYaf5Px.js → layout-7xCiQ5Mn.js} +1 -1
  71. package/dist/web/assets/{linear-C_UKR9_Y.js → linear-WCNhc07o.js} +1 -1
  72. package/dist/web/assets/{list-DZ7tVJxe.js → list-BL4eRkIg.js} +1 -1
  73. package/dist/web/assets/{mermaid-HWGCJPDP-CUN0Fzkf.js → mermaid-HWGCJPDP-C8QwWdo5.js} +6 -6
  74. package/dist/web/assets/{mindmap-definition-YA3MSWOX-skKDKZay.js → mindmap-definition-YA3MSWOX-Cj5-j6a7.js} +1 -1
  75. package/dist/web/assets/{pegDiagram-XKGWAZYB-BBVgKimF.js → pegDiagram-XKGWAZYB-BYB3oVZ_.js} +1 -1
  76. package/dist/web/assets/{pencil-864Hty9z.js → pencil-gxvh59uO.js} +1 -1
  77. package/dist/web/assets/{pieDiagram-E7YTZNPT-DbTfOeVM.js → pieDiagram-E7YTZNPT-CSbpzXas.js} +1 -1
  78. package/dist/web/assets/{quadrantDiagram-AXDQQJYC-GB57kGMj.js → quadrantDiagram-AXDQQJYC-DKTP6jS5.js} +1 -1
  79. package/dist/web/assets/{railroadDiagram-O6MQD6OU-BaWEAljp.js → railroadDiagram-O6MQD6OU-Ct8aPeLX.js} +1 -1
  80. package/dist/web/assets/{refresh-cw-CDVBz6mR.js → refresh-cw-BQRdbjy6.js} +1 -1
  81. package/dist/web/assets/{requirementDiagram-BXWQKSXE-1FhQiz9k.js → requirementDiagram-BXWQKSXE-B9hH69zu.js} +1 -1
  82. package/dist/web/assets/{sankeyDiagram-P5KCCOFB-tQhcHMdz.js → sankeyDiagram-P5KCCOFB-CDqNONxU.js} +1 -1
  83. package/dist/web/assets/{save-cYQVut42.js → save-CYoz3QKB.js} +1 -1
  84. package/dist/web/assets/scroll-area-CU4DGUBA.js +1 -0
  85. package/dist/web/assets/{sequenceDiagram-WJ2MYXX4-CC3gj2gv.js → sequenceDiagram-WJ2MYXX4-BF77J63J.js} +1 -1
  86. package/dist/web/assets/{sizeCapture-INFHLROL-CQ9O8ZCT.js → sizeCapture-INFHLROL-Dpubco_U.js} +1 -1
  87. package/dist/web/assets/{stateDiagram-D77RDMKH-DYKy0trf.js → stateDiagram-D77RDMKH-CzslKEYw.js} +1 -1
  88. package/dist/web/assets/stateDiagram-v2-MP3YSRHH-DKbNjyV-.js +1 -0
  89. package/dist/web/assets/{swimlanes-42K2YHIH-glbk0TBg.js → swimlanes-42K2YHIH-bD_tUjo6.js} +1 -1
  90. package/dist/web/assets/swimlanesDiagram-VR7AAH4N-0wAluWQF.js +8 -0
  91. package/dist/web/assets/table-D3N_5Wee.js +1 -0
  92. package/dist/web/assets/tabs-CSlEXoxD.js +1 -0
  93. package/dist/web/assets/{timeline-definition-24CTP7MA-f6rViR3x.js → timeline-definition-24CTP7MA-owGoHn8z.js} +1 -1
  94. package/dist/web/assets/trash-2-D3Ey4I09.js +6 -0
  95. package/dist/web/assets/{upload-CVOr0xxD.js → upload-DhVOCWST.js} +1 -1
  96. package/dist/web/assets/useDetailRoute-j9nlwack.js +1 -0
  97. package/dist/web/assets/{useJobs-D6xj3XjG.js → useJobs-Dcl-Vim3.js} +1 -1
  98. package/dist/web/assets/{useKnowledge-qKVT26ZM.js → useKnowledge-gIjk0_I1.js} +1 -1
  99. package/dist/web/assets/useListSelection-CSQd_Hmx.js +1 -0
  100. package/dist/web/assets/{useMemories-Cd7-k-Iq.js → useMemories-B8Zpz0Qz.js} +1 -1
  101. package/dist/web/assets/useProjectScope-Dk0mjyHf.js +1 -0
  102. package/dist/web/assets/useSessions-BrdK-12R.js +1 -0
  103. package/dist/web/assets/{vennDiagram-4TSXK5OY-CxG3VgNS.js → vennDiagram-4TSXK5OY-D0_6bldW.js} +1 -1
  104. package/dist/web/assets/view-params-Bm1Qf6KC.js +1 -0
  105. package/dist/web/assets/{wardleyDiagram-VM6X3IG4-ByyivCzx.js → wardleyDiagram-VM6X3IG4-D9GbTBKy.js} +1 -1
  106. package/dist/web/assets/{xychartDiagram-S5SC5T6Z-BVm2sRFs.js → xychartDiagram-S5SC5T6Z-BFqPF2Hl.js} +1 -1
  107. package/dist/web/index.html +1 -1
  108. package/package.json +1 -1
  109. package/dist/checksums.txt +0 -5
  110. package/dist/web/assets/Dashboard-DTwx4Oce.js +0 -1
  111. package/dist/web/assets/JobWebhooks-DjkbxUMt.js +0 -1
  112. package/dist/web/assets/SourceEditor-Bbm17thv.js +0 -14
  113. package/dist/web/assets/Webhooks-CDzbzurB.js +0 -1
  114. package/dist/web/assets/channel-DfI_NPkS.js +0 -1
  115. package/dist/web/assets/classDiagram-ZZMXUADV-BMn0P_qW.js +0 -1
  116. package/dist/web/assets/classDiagram-v2-VYDZK3BY-BMn0P_qW.js +0 -1
  117. package/dist/web/assets/index-CS_oHx6f.js +0 -468
  118. package/dist/web/assets/scroll-area-DQvJ9JpU.js +0 -1
  119. package/dist/web/assets/stateDiagram-v2-MP3YSRHH-BKFrUA7i.js +0 -1
  120. package/dist/web/assets/swimlanesDiagram-VR7AAH4N-C6lvE7xF.js +0 -8
  121. package/dist/web/assets/useProjectScope-Duh5p4ZM.js +0 -1
package/README.md ADDED
@@ -0,0 +1,1059 @@
1
+ <div align="center">
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.
24
+
25
+ ### Key features
26
+
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 |
41
+
42
+ ## Getting started
43
+
44
+ ### Install
45
+
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).
47
+
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) |
54
+
55
+ On first launch the app sets everything up:
56
+
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
61
+
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".
63
+
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.
65
+
66
+ <details>
67
+ <summary>Headless / CLI-only install (servers, Docker, CI)</summary>
68
+
69
+ Needs [Bun](https://bun.sh) >= 1.4.2 for the npm install.
70
+
71
+ ```bash
72
+ npm install -g orc-ai
73
+ ```
74
+
75
+ #### Pre-built binaries
76
+
77
+ Download from [GitHub Releases](https://github.com/niradler/orc/releases):
78
+
79
+ ```bash
80
+ # macOS (Apple Silicon)
81
+ 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
+
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
96
+
97
+ ```bash
98
+ git clone https://github.com/niradler/orc
99
+ cd orc && bun install && bun build
100
+ ```
101
+
102
+ </details>
103
+
104
+ ### Quick start
105
+
106
+ ```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
112
+ orc project add my-app -d "My application"
113
+ orc project use my-app
114
+
115
+ # 3. Add tasks and memories - everything auto-scopes to my-app
116
+ 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?mode=meta` serves three meta-tools (`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` serves meta mode by default; pass `--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
+ ### Knowledge bases
495
+
496
+ 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.
497
+
498
+ ```bash
499
+ orc kb create Runbooks --project my-app
500
+ orc kb add Runbooks ./docs/*.pdf # upload and parse
501
+ orc kb sources add Runbooks ./handbook # copy a folder in, rescanned periodically
502
+ orc kb editable-by Runbooks ui,cli,api # agents (mcp) may read but not edit
503
+ orc kb search "rollback procedure" # cited passages
504
+ orc kb evidence "how do we rotate keys" # budgeted evidence pack
505
+ orc kb usage Runbooks # reads by source (mcp, api, cli, ui)
506
+ ```
507
+
508
+ 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.
509
+
510
+ 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.
511
+
512
+ ```bash
513
+ orc kb comment add Learnings "Digest https://example.com/postmortem"
514
+ orc kb digest template > digest.md # edit, then:
515
+ orc kb digest set Runbooks -b codex --cron "0 3 * * *" -i digest.md
516
+ orc kb digest run Runbooks
517
+ ```
518
+
519
+ 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.
520
+
521
+ 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.
522
+
523
+ 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.
524
+
525
+ 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.
526
+
527
+ **MCP tools:** `kb_list`, `kb_search`, `kb_evidence`, `kb_read`, `kb_documents`, `kb_write`, `kb_document`, `kb_comment`, `kb_manage`, `kb_digest`, `kb_maintenance`
528
+
529
+ ### Task status flow
530
+
531
+ ```
532
+ todo → queued → doing → review → done
533
+ │ │
534
+ v v
535
+ blocked changes_requested → doing
536
+ │
537
+ v
538
+ paused
539
+ ```
540
+
541
+ 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.
542
+
543
+ `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.
544
+
545
+ <img src="assets/TaskFlow.gif" alt="Task Flow" width="600" />
546
+
547
+ ### Task flows
548
+
549
+ 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.
550
+
551
+ 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.
552
+
553
+ ```bash
554
+ orc flow list # what graphs are available
555
+ orc flow show orc-default # nodes, edges, limits
556
+ orc task add "Fix the flaky test" --flow orc-default --skill orc-sdlc
557
+ orc flow status <taskId> # active nodes + the ledger of outcomes
558
+ orc flow resume <taskId> --outcome approved # resolve a human gate
559
+ orc flow halt <taskId> # stop it and kill live nodes
560
+ ```
561
+
562
+ | Built-in workflow | Use it for |
563
+ | --- | --- |
564
+ | `orc-default` | Development: understand, plan as needed, implement, verify and independently review; bounded rework. `required_review: false` explicitly skips agent review. |
565
+ | `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. |
566
+ | `orc-review-only` | Review existing work; approve, request changes, or pause when evidence is insufficient. |
567
+
568
+ **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.
569
+
570
+ 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.
571
+
572
+ #### Custom graphs per task
573
+
574
+ For work no named flow fits, attach a bespoke graph to a single task:
575
+
576
+ ```bash
577
+ orc flow validate --file ./my-graph.json # catch mistakes before running anything
578
+ orc flow attach <taskId> --file ./my-graph.json --start
579
+ ```
580
+
581
+ 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.
582
+
583
+ 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.
584
+
585
+ #### In the web dashboard
586
+
587
+ 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.
588
+
589
+ 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.
590
+
591
+ ### Jobs
592
+
593
+ ```bash
594
+ orc job add deploy --command "bun run deploy" --trigger manual
595
+ orc job add nightly --command "bun run test" --trigger cron --cron "0 22 * * *"
596
+ orc job add on-change --command "bun run lint" --trigger watch --watch "./src"
597
+ orc job add on-push --command "bun run ci" --trigger webhook
598
+ ```
599
+
600
+ Jobs separate **what runs** from **when it runs**. Choose **Run command**,
601
+ **Run agent**, or **Create task** in the dashboard. Command is required only for
602
+ Run command. Agent jobs save instructions, backend, optional model and explicit
603
+ tool approval; each run links to its tracked session. Task jobs save a task title
604
+ and instructions and link to the created task. **Start the task flow automatically**
605
+ is off by default, so generated tasks wait for a manual flow start.
606
+ The CLI accepts typed actions through `--action-config <json>`.
607
+
608
+ New jobs are disabled by default. Select **Enable this job immediately** during
609
+ creation or pass `orc job add ... --enable` to opt in. Jobs supports enable/disable
610
+ directly in the list and for selected rows. Projects shares the selection toolbar
611
+ for activate, pause and archive actions; select-all applies only to displayed rows.
612
+ Failed bulk updates remain selected so you can retry them.
613
+
614
+ ### Webhooks
615
+
616
+ Open **Activity → Webhooks** to see all configured event sources and their connected
617
+ jobs. Create a source without a job, copy its URL and one-time signing secret, then
618
+ register them with the provider. Sources belong to the selected project, or are
619
+ shared across projects when created in All projects.
620
+
621
+ In **Jobs → New job** (or Edit), choose **Webhook** as the trigger, select an
622
+ existing source or create one inline, and set this job's event/action filters.
623
+ One source can trigger multiple enabled jobs, each with its own filters and action.
624
+ The Webhooks page shows source enablement, connected jobs and recent deliveries,
625
+ including individual run results and links to generated tasks or agent sessions.
626
+ Deleting a job disconnects it while preserving the reusable source.
627
+
628
+ For command jobs, accepted JSON is passed unchanged on stdin; bounded metadata is
629
+ also available as `ORC_WEBHOOK_*` environment variables. Agent and task jobs receive
630
+ up to 50,000 characters of event data, explicitly marked as untrusted input, alongside
631
+ the configured instructions. Delivery history stores event metadata and a payload
632
+ hash, not the payload body or signing secret; generated tasks and agent prompts can
633
+ contain the supplied event data.
634
+
635
+ Generic endpoints verify `X-Orc-Signature-256: sha256=<HMAC-SHA256 of the raw body>`.
636
+ Use `X-Orc-Event` for event filtering and `X-Orc-Delivery` (or
637
+ `Idempotency-Key`) for deduplication. GitHub endpoints use
638
+ `X-Hub-Signature-256`, `X-GitHub-Event` and `X-GitHub-Delivery` directly.
639
+ Event names and payload `action` values are configurable, so PR lifecycle,
640
+ reviews, workflow runs, releases, or later providers use the same job trigger.
641
+
642
+ Signing secrets are encrypted at rest and shown only when an endpoint is created or
643
+ rotated. The receiver is intentionally outside normal ORC bearer authentication;
644
+ the per-endpoint HMAC is its authentication boundary. Management remains under the
645
+ authenticated API.
646
+
647
+ ### Gateway (Telegram / Slack)
648
+
649
+ Approve agent work from your phone, search memory, or start a live AI session.
650
+
651
+ ```json
652
+ {
653
+ "gateway": {
654
+ "telegram": {
655
+ "enabled": true,
656
+ "token": "7123456789:AAF...",
657
+ "authorized_users": [123456789]
658
+ }
659
+ }
660
+ }
661
+ ```
662
+
663
+ **Commands:** `/status`, `/tasks`, `/approve <id>`, `/reject <id>`, `/jobs`, `/run <name>`, `/mem <query>`, `/agent <claude|codex>`
664
+
665
+ > [!TIP]
666
+ > Create a Telegram bot via [@BotFather](https://t.me/BotFather) and find your user ID via [@userinfobot](https://t.me/userinfobot).
667
+
668
+ <details>
669
+ <summary>Slack setup</summary>
670
+
671
+ ```json
672
+ {
673
+ "gateway": {
674
+ "slack": {
675
+ "enabled": true,
676
+ "bot_token": "xoxb-...",
677
+ "app_token": "xapp-...",
678
+ "authorized_users": ["U01ABCDEF"]
679
+ }
680
+ }
681
+ }
682
+ ```
683
+
684
+ Same commands as Telegram. Create a Slack app at [api.slack.com/apps](https://api.slack.com/apps) with Socket Mode enabled.
685
+
686
+ </details>
687
+
688
+ ## Skills
689
+
690
+ ORC ships two entry-point skills. Their supporting references load only when needed; custom skills and packages remain supported.
691
+
692
+ ### Install skills
693
+
694
+ ```bash
695
+ # Install all ORC skills into your agent
696
+ npx skills add niradler/orc --all
697
+
698
+ # Or pick specific ones
699
+ npx skills add niradler/orc --skill orc-platform orc-sdlc
700
+
701
+ # Global install
702
+ npx skills add niradler/orc --all -g
703
+ ```
704
+
705
+ ### Entry-point skills
706
+
707
+ | Skill | Purpose |
708
+ | --- | --- |
709
+ | `orc-platform` | Operate ORC domains: setup/interfaces/auth, memory and maintained KBs/digests/embeddings, work/operations, sessions/SSH/Git/chat, rules and agent packages |
710
+ | `orc-sdlc` | Requirements → risk/complexity classification → direct work or plan → implementation → tests/completeness → review/rework → authorized Git delivery, with shared learning throughout |
711
+
712
+ Start with the relevant entry point and read only its selected reference. Platform
713
+ guidance groups related domains while keeping memory, execution and rules independently
714
+ loadable; SDLC has planning, development and review/delivery references. Clear low-risk
715
+ work can execute directly; assigned managed nodes preserve roles and flow contracts.
716
+
717
+ ### Built-in skill templates
718
+
719
+ 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`.
720
+
721
+ Skills can be assigned to several projects; no assignments means global. Connect
722
+ to `/mcp?project=orc` or `/mcp?projects=orc,project2` to discover and read only
723
+ the selected projects' skills plus global skills. Add `&mode=meta` for meta mode.
724
+ Project names are case-insensitive; unknown projects are rejected. Tool arguments
725
+ can narrow the selection to one project from the URL. Shared skills appear once;
726
+ project-specific instructions use the first applicable override in URL order,
727
+ then global instructions. An explicit tool `project` selects that project's version.
728
+ Named reads, supporting files, compatibility aliases and downloads follow the same
729
+ assignment rule. Project-specific instruction overrides remain independent of assignments.
730
+ MCP `skill_create` inherits the selected project; unscoped creation is global.
731
+
732
+ Manage assignments with `orc skill projects <name> --set <project-id> <project-id>`;
733
+ use `--global` to clear assignments, or omit flags to inspect them. The API exposes
734
+ authenticated `GET`/`PUT /api/skills/{name}/projects` with `{ "project_ids": [] }`.
735
+ Existing skills remain global until assigned. Reassign skills before deleting a project.
736
+ The project selector controls discovery, not API authentication or tenant authorization.
737
+
738
+ `skill_list({ q: "code review", limit: 30, offset: 0 })` searches names and
739
+ descriptions with weighted BM25, prefixes, English stemming, phrase matches,
740
+ substrings and bounded typo tolerance. Every term must match; results are sorted
741
+ by descending relevance score, with names breaking ties. Scores are relative
742
+ relevance, not probabilities; no embedding service is required. Without `q`,
743
+ the existing reads/recent sorting applies. MCP responses show `total`, `offset`,
744
+ `limit` and `next_offset`; pass the next offset to fetch another page. API
745
+ `GET /api/skills?q=...&limit=30&offset=0` returns `skills` plus those fields;
746
+ `next_offset: null` means the end. Default page size is 30, maximum 500.
747
+ CLI equivalents are `orc skill list -q "code review" --project-id <id> --limit 30 --offset 0`.
748
+
749
+ On the **Skills** page, every skill has an **Agent discovery** toggle, including
750
+ built-in, user/imported and modified skills. Visibility applies across the installation
751
+ and defaults to visible. Hidden skills stay on the Skills page for management and
752
+ remain readable by name, including supporting files; existing task flows continue to
753
+ use them. **Modified** means its instructions have an authored global/project edit.
754
+
755
+ The policy is saved under `skills.hidden_skills` in `~/.orc/config.json` and
756
+ read afresh for discovery, including by existing MCP processes. `GET /api/skills`
757
+ omits hidden skills; `include_hidden=true` returns the management catalog with
758
+ `discovery_hidden` metadata. `GET /api/skills/settings/visibility` reads the policy and
759
+ `PUT /api/skills/settings/visibility` replaces its `hidden_skills` array using the usual
760
+ API authentication. This installation-wide preference ignores project config.
761
+ New skills default to visible until hidden explicitly. Legacy `hidden_builtins` settings
762
+ remain supported with their original built-in-only behavior; modified instructions
763
+ remain discoverable under that legacy setting unless explicitly hidden via `hidden_skills`.
764
+
765
+ Retired built-in names (such as `orc-coder` and `orc-reviewer`) remain readable
766
+ as compatibility routes for saved tasks, authored overrides and frozen flows, but
767
+ are not additional discovery entries. New tasks and built-in flows use
768
+ `orc-sdlc`; the node role selects implementation versus independent review.
769
+ Applicable authored legacy worker/coder/reviewer/knowledge instructions remain
770
+ role-scoped supplements with revision provenance, including on resume. Other authored
771
+ legacy domain guidance is indexed from the canonical effective read and loads by name
772
+ when relevant. Conflicts are surfaced rather than silently rewriting stored overlays.
773
+
774
+ Add custom skills by creating a `SKILL.md` in `~/.orc/skills/my-workflow/SKILL.md`.
775
+
776
+ 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:
777
+
778
+ ```text
779
+ my-workflow/
780
+ SKILL.md
781
+ references/guide.md
782
+ references/topics/details.md
783
+ scripts/check.py
784
+ assets/template.json
785
+ ```
786
+
787
+ `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"`.
788
+
789
+ ```bash
790
+ # Import the whole folder through the API
791
+ orc skill create my-workflow --directory ./my-workflow
792
+ orc skill read my-workflow --ref references/topics/details.md
793
+ orc skill validate ./my-workflow
794
+ orc skill export my-workflow ./exported/my-workflow
795
+ ```
796
+
797
+ 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).
798
+
799
+ ```bash
800
+ orc skill import vercel-labs/agent-skills --list
801
+ orc skill import vercel-labs/agent-skills --skill web-design-guidelines
802
+ orc skill sync web-design-guidelines
803
+ ```
804
+
805
+ 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.
806
+
807
+ 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. 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.
808
+
809
+ ### Shared agents and portable packages
810
+
811
+ 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.
812
+
813
+ 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.
814
+
815
+ ```bash
816
+ orc agent-package import ./team-agents
817
+ orc agent list
818
+ orc agent read team-agents/reviewer
819
+ orc agent-package export team-agents ./exported/team-agents
820
+ orc agent create reviewer --file ./reviewer.agent.md
821
+ orc agent export reviewer ./exported/reviewer.agent.md
822
+ ```
823
+
824
+ Select a shared profile independently of its backend in an ORC flow:
825
+
826
+ ```json
827
+ { "kind": "agent", "agent": "team-agents/reviewer", "backend": "codex-cli", "outcomes": ["pass", "fail"] }
828
+ ```
829
+
830
+ 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.
831
+
832
+ 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.
833
+
834
+ 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_package_list`, `agent_package_read`, and `agent_package_import`. Package agent IDs are namespaced as `<package>/<file-stem>`.
835
+
836
+ ## MCP tools
837
+
838
+ Agents can fetch original skill scripts/assets with
839
+ `skill_read({name: "orc-platform", ref: "scripts/upload-session.py", download: true, project: "my-app"})`.
840
+ It returns a signed ten-minute `download_url`, `sha256`, `size_bytes` and expiry
841
+ instead of the file body. Download to a local file and verify the hash; do not
842
+ reconstruct scripts from tool text. The URL authorizes only that file version and
843
+ does not contain the API secret. Keep it private. Expiry, API restart or file changes
844
+ require a new URL. Downloading never executes scripts. The authenticated REST mint
845
+ endpoint is `POST /api/skills/<name>/download` with `ref` and optional scope.
846
+
847
+ Tools are available to any connected agent. Start every session with `context`.
848
+
849
+ | Category | Tools |
850
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
851
+ | **Project** | `project_list` |
852
+ | **Memory** | `context`, `memory_list`, `memory_read`, `memory_create`, `memory_update`, `memory_delete`, `memory_history`, `memory_revert` |
853
+ | **Task** | `task_list`, `task_get`, `task_create`, `task_update`, `task_batch_create` |
854
+ | **Skill** | `skill_list`, `skill_read`, `skill_create` |
855
+ | **Agent** | `agent_list`, `agent_read`, `agent_create`, `agent_package_list`, `agent_package_read`, `agent_package_import` |
856
+ | **Flow** | `flow_report`, `flow_status`, `flow_list`, `flow_read`, `flow_create`, `flow_attach` |
857
+ | **Knowledge** | `kb_list`, `kb_search`, `kb_evidence`, `kb_read`, `kb_documents`, `kb_write`, `kb_maintenance` |
858
+ | **Search** | `search` |
859
+ | **Job** | `job_list`, `job_run`, `job_status` |
860
+ | **Session** | `session_event`, `session_snapshot`, `session_restore`, `session_log` |
861
+
862
+ ## REST API
863
+
864
+ Runs on port 7700 with auto-generated OpenAPI spec.
865
+
866
+ - **Swagger UI:** `GET /docs`
867
+ - **OpenAPI spec:** `GET /openapi.json`
868
+
869
+ <details>
870
+ <summary>Full endpoint list</summary>
871
+
872
+ | Method | Path | Description |
873
+ | ----------------------- | ------------------------------ | ------------------------------ |
874
+ | `GET` | `/health` | Health check |
875
+ | `GET/POST/PATCH/DELETE` | `/projects` | CRUD projects |
876
+ | `GET` | `/projects/by-name/{name}` | Lookup by name |
877
+ | `GET` | `/projects/{id}/summary` | Task/memory/job counts |
878
+ | `GET/POST/PATCH/DELETE` | `/tasks` | CRUD tasks |
879
+ | `GET/POST` | `/tasks/{id}/notes` | Task notes |
880
+ | `GET/POST/DELETE` | `/tasks/{id}/links` | Task dependencies |
881
+ | `GET/POST` | `/memories` | List (`q`, `sort`) / create |
882
+ | `GET/PATCH/DELETE` | `/memories/{name}` | Read / update / delete by name |
883
+ | `GET` | `/memories/{name}/history` | Change history |
884
+ | `POST` | `/memories/{name}/revert` | Revert a change |
885
+ | `GET` | `/knowledge/search` | Search documents (BM25/hybrid) |
886
+ | `GET` | `/knowledge/documents/{id}` | Get document by docid |
887
+ | `GET/POST/DELETE` | `/knowledge/collections` | CRUD collections |
888
+ | `POST` | `/knowledge/update` | Re-index collections |
889
+ | `GET` | `/knowledge/status` | Index status |
890
+ | `GET/POST` | `/jobs` | CRUD jobs |
891
+ | `POST` | `/jobs/{id}/trigger` | Trigger a job |
892
+ | `GET` | `/jobs/{id}/runs` | Run history |
893
+ | `GET` | `/jobs/{id}/runs/{runId}/logs` | Run logs |
894
+ | `GET` | `/skills` | Skill templates |
895
+ | `GET` | `/backends` | Agent backends + usability |
896
+ | `GET/POST` | `/flows` | List/create flow graphs |
897
+ | `GET` | `/flows/{name}` | Read a flow definition |
898
+ | `POST` | `/flows/validate` | Validate without saving |
899
+ | `GET/POST` | `/tasks/{id}/flow` | Get a task's run / attach one |
900
+ | `POST` | `/tasks/{id}/flow/resume` | Resolve a human node |
901
+ | `POST` | `/tasks/{id}/flow/halt` | Stop a running flow |
902
+ | `GET` | `/sessions` | Agent session logs |
903
+ | `POST` | `/mcp/tool` | Execute any MCP tool via HTTP |
904
+
905
+ </details>
906
+
907
+ ## CLI reference
908
+
909
+ ```
910
+ orc daemon start|stop|status Manage the daemon (API + scheduler + gateway)
911
+ orc daemon install|uninstall Register/remove auto-start on login/boot
912
+ orc api Start the API server only
913
+ orc mcp [--mode meta|full] Start the MCP server (stdio, meta by default)
914
+ orc home Show ~/.orc directory and config
915
+ orc status Show API health and counts
916
+ orc doctor Check which agent backends are usable here
917
+
918
+ orc project list|add|show|use|update|archive
919
+ orc task list|add|show|update|done|review|approve|reject|delete
920
+ orc mem list|show|add|edit|delete|history|revert
921
+ orc job list|add|run|runs
922
+ orc session list|show|log
923
+ orc skill list|show
924
+ orc flow list|show|validate|create|attach|status|resume|halt
925
+ orc kb search|get|collections|add|remove|update|status
926
+ ```
927
+
928
+ > [!NOTE]
929
+ > 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.
930
+
931
+ ## Configuration
932
+
933
+ ORC merges config in priority order (later wins):
934
+
935
+ 1. `~/.orc/config.json` - user global
936
+ 2. `./.orc/config.json` - project-local
937
+ 3. Environment variables
938
+
939
+ <details>
940
+ <summary>Environment variables</summary>
941
+
942
+ | Variable | Default | Description |
943
+ | -------------------------------- | --------------------- | ------------------------------------------------- |
944
+ | `ORC_DB_PATH` | `~/.orc/orc.db` | SQLite database path |
945
+ | `ORC_API_HOST` | `127.0.0.1` | API listen host (set to `0.0.0.0` in Docker) |
946
+ | `ORC_API_PORT` | `7700` | API listen port |
947
+ | `ORC_API_SECRET` | - | Bearer token for auth |
948
+ | `ORC_TERMINALS_ALLOW_WITHOUT_SECRET` | `false` | Legacy option; no longer needed. Terminals follow API open/authenticated mode |
949
+ | `ORC_TELEGRAM_TOKEN` | - | Enables the Telegram gateway when set |
950
+ | `AGENTAPI_URL` | `http://127.0.0.1:3284` | URL of host agentapi server (for `agentapi` backend) |
951
+ | `ANTHROPIC_API_KEY` | - | Required for the `claude` backend (Anthropic SDK) |
952
+ | `ORC_SESSION_ID` | `default` | Per-agent session identifier |
953
+ | `ORC_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
954
+ | `ORC_LOG_DIR` | `~/.orc/logs` | Log file directory |
955
+ | `ORC_LOG_FILE` | `1` | Set to `0` to disable file logging |
956
+ | `ORC_RUNNER_TIMEOUT` | `300` | Default job timeout (seconds) |
957
+ | `ORC_AGENT_LOOP_ENABLED` | `false` | Enable the agent task loop |
958
+ | `ORC_AGENT_LOOP_POLL_INTERVAL` | `5` | Task loop poll interval (minutes) |
959
+ | `ORC_AGENT_LOOP_MAX_WORKERS` | `1` | Max concurrent worker agents |
960
+ | `ORC_AGENT_LOOP_DEFAULT_BACKEND` | `claude` | Default agent backend |
961
+ | `ORC_AGENT_LOOP_IDLE_TIMEOUT` | `20` | Session idle timeout (minutes) |
962
+ | `ORC_AGENT_LOOP_AUTO_APPROVE` | `true` | Auto-approve worker tool permissions |
963
+ | `ORC_KNOWLEDGE_ROOT` | beside `orc.db` | Knowledge base storage (files, index) |
964
+ | `ORC_KNOWLEDGE_PARSER` | `auto` | `auto`, `basic` or `docling` |
965
+ | `ORC_KNOWLEDGE_EMBEDDING_PROVIDER` | `none` | `none`, `ollama` or `openai` |
966
+ | `ORC_KNOWLEDGE_EMBEDDING_URL` | provider default | Embedding endpoint |
967
+ | `ORC_KNOWLEDGE_EMBEDDING_MODEL` | provider default | Embedding model |
968
+ | `ORC_KNOWLEDGE_EMBEDDING_API_KEY` | - | API key for OpenAI-compatible embeddings |
969
+ | `ORC_SQLITE_VEC_PATH` | bundled | Path to a sqlite-vec `vec0` library |
970
+
971
+ </details>
972
+
973
+ ### Logs
974
+
975
+ 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).
976
+
977
+ ```bash
978
+ # Tail recent errors
979
+ grep '"level":"error"' ~/.orc/logs/orc.log | tail -20
980
+
981
+ # Watch live
982
+ tail -f ~/.orc/logs/orc.log | jq .
983
+ ```
984
+
985
+ ### Running as a background service
986
+
987
+ The daemon runs the API server, job scheduler, file watchers, and gateway in one process. To start it automatically on login/boot:
988
+
989
+ ```bash
990
+ orc daemon install # register auto-start for your OS
991
+ orc daemon uninstall # remove auto-start registration
992
+ ```
993
+
994
+ | Platform | Mechanism | Auto-restart on crash |
995
+ | ----------- | ------------------------------------------------------------------ | --------------------- |
996
+ | **Windows** | Registry Run key (`HKCU\...\Run`) | No |
997
+ | **macOS** | launchd (`~/Library/LaunchAgents/com.orc.daemon.plist`) | Yes |
998
+ | **Linux** | systemd user service (`~/.config/systemd/user/orc-daemon.service`) | Yes |
999
+
1000
+ No admin/root privileges required on any platform.
1001
+
1002
+ ```bash
1003
+ # Manual control
1004
+ orc daemon start # start in foreground (API + scheduler + gateway)
1005
+ orc daemon stop # stop a running daemon
1006
+ orc daemon status # show scheduled jobs
1007
+ orc api # start the API server only (no scheduler/gateway)
1008
+
1009
+ # Check daemon health
1010
+ curl http://localhost:7700/health
1011
+ ```
1012
+
1013
+ Logs go to `~/.orc/daemon.log`. Config is read from `~/.orc/config.json`.
1014
+
1015
+ ## Architecture
1016
+
1017
+ ```
1018
+ packages/
1019
+ core/ Config (Zod), types, logger, ULID IDs
1020
+ db/ Drizzle ORM + SQLite (~/.orc/orc.db)
1021
+ api/ Hono REST API + OpenAPI spec (:7700)
1022
+ sdk/ Typed HTTP client from OpenAPI
1023
+ cli/ Commander CLI (the `orc` binary)
1024
+ mcp/ MCP server (stdio + Streamable HTTP at /mcp)
1025
+ runner/ Job executor + cron/watch scheduler + task loop
1026
+ gateway/ Telegram + Slack bridge + agent sessions
1027
+ agent-runtime/ Agent backend registry (claude, acpx, a2a)
1028
+ task-service/ Task status transitions + side-effects
1029
+ web/ React dashboard (Vite + Tailwind + shadcn + React Query)
1030
+ ```
1031
+
1032
+ Data flow: `Agent → MCP → API → DB` / `CLI → SDK → API → DB`
1033
+
1034
+ ## Development
1035
+
1036
+ ```bash
1037
+ bun install # install all workspace deps
1038
+ bun dev # API + CLI in watch mode
1039
+ bun typecheck # typecheck all packages
1040
+ bun check # biome lint + format
1041
+ bun test # run all tests
1042
+ bun build # build all packages
1043
+ ```
1044
+
1045
+ See [AGENTS.md](./AGENTS.md) for the full development guide and coding conventions.
1046
+
1047
+ ## Learn more
1048
+
1049
+ - [Knowledge learning loop](./docs/knowledge-loop.md) - memories, knowledge base digests and comments, skill edits, and human revert
1050
+ - [Agent Rules](./docs/agent-rules.md) - opt-in tool protection, revision history, deterministic job actions, and evidence-based skill evaluation
1051
+ - [Usage Guide](./docs/usage-guide.md) - best practices for memory, tasks, multi-agent workflows, and configuration
1052
+ - [Vision](./docs/vision.md) - why ORC exists and the problem it solves
1053
+ - [Roadmap](./docs/roadmap.md) - what shipped and what's next
1054
+ - [Agent Orchestration Design](./docs/agent-orchestration-design.md) - architecture spec for the task loop and multi-agent workflow
1055
+ - [Task Flows](./docs/task-flows.md) - flow graphs: nodes, conditional edges, bounded loops, fan-out and joins, and how to author your own
1056
+
1057
+ ### Knowledge learning
1058
+
1059
+ 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.