openrune 0.3.22 → 0.4.0

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 (2) hide show
  1. package/README.md +107 -178
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -5,8 +5,8 @@
5
5
  <h1 align="center">Rune</h1>
6
6
 
7
7
  <p align="center">
8
- <strong>File-based AI Agent Harness for Claude Code</strong><br/>
9
- Drop a <code>.rune</code> file in any folder. Run it headlessly, chain agents, or open the desktop UI.
8
+ <strong>The simplest agent harness for Claude Code</strong><br/>
9
+ One file per agent. Run headlessly, chain them together, automate with triggers, or chat in the desktop UI.
10
10
  </p>
11
11
 
12
12
  <p align="center">
@@ -17,32 +17,20 @@
17
17
 
18
18
  ---
19
19
 
20
- ## What is Rune?
21
-
22
- Rune is a file-based agent harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Each `.rune` file is an independent AI agent with its own role, memory, and context. Run it from the CLI, chain agents together, automate with triggers, or open the desktop UI.
23
-
24
- - **File-based** — One `.rune` file = one agent. Move it, share it, version it with git.
25
- - **Headless execution** — Run agents from the CLI or scripts. No GUI needed.
26
- - **Agent chaining** — Pipe agents together in a pipeline. Output → input, automatically.
27
- - **Automated triggers** — Run agents on file changes, git commits, or a cron schedule.
28
- - **Node.js API** — Use agents programmatically with `require('openrune')`.
29
- - **Desktop UI** — Chat interface with real-time activity monitoring and built-in terminal.
30
-
31
- ---
32
-
33
20
  ## Why Rune?
34
21
 
35
- Building a Claude Code harness usually means wiring up process management, I/O parsing, state handling, and a UI from scratch. Rune lets you skip all of that — just drop a file and go.
22
+ Building a Claude Code harness usually means wiring up process management, I/O parsing, state handling, and a UI from scratch.
36
23
 
37
- **No harness boilerplate** — No SDK wiring, no process management, no custom I/O parsing. One `.rune` file gives you a fully working agent you can run from CLI, scripts, or the desktop UI.
24
+ Rune replaces all of that with a single file.
38
25
 
39
- **Persistent context** — Role, memory, and chat history live in the `.rune` file. Close the app, reopen it next week — the agent picks up right where you left off.
40
-
41
- **Portable & shareable** — The `.rune` file is just JSON. Commit it to git, share it with teammates, or move it to another machine. The agent goes wherever the file goes.
26
+ ```bash
27
+ npm install -g openrune
42
28
 
43
- **Multiple agents per project** — A reviewer, a backend dev, a designer — each with its own role and history, working side by side in the same folder.
29
+ rune new reviewer --role "Code reviewer, security focused"
30
+ rune run reviewer.rune "Review the latest commit"
31
+ ```
44
32
 
45
- **Scriptable** — Chain agents, set up triggers, or call agents from your own code via the Node.js API. One file format, multiple ways to use it.
33
+ That's it. No SDK, no boilerplate, no config.
46
34
 
47
35
  ---
48
36
 
@@ -53,131 +41,140 @@ Building a Claude Code harness usually means wiring up process management, I/O p
53
41
  - **Node.js** 18+
54
42
  - **Claude Code CLI** — `npm install -g @anthropic-ai/claude-code`
55
43
 
56
- ### 1. Install
44
+ ### Install
57
45
 
58
46
  ```bash
59
47
  npm install -g openrune
60
48
  ```
61
49
 
62
- ### 2. Create an agent
50
+ ### Create and run agents
63
51
 
64
52
  ```bash
65
- cd ~/my-project
66
- rune new reviewer --role "Code reviewer, security focused"
67
- ```
53
+ # Create agents
54
+ rune new architect --role "Software architect"
55
+ rune new coder --role "Backend developer"
56
+ rune new reviewer --role "Code reviewer"
68
57
 
69
- ### 3. Run it
70
-
71
- ```bash
72
- # Headless — run from CLI, get results in your terminal
58
+ # Run headlessly
73
59
  rune run reviewer.rune "Review the latest commit"
74
60
 
75
- # Pipe input from other commands
61
+ # Pipe input
76
62
  git diff | rune run reviewer.rune "Review this diff"
77
63
 
78
- # Desktop UI — open the chat interface
64
+ # Agent pipeline — architect designs, coder builds (with file creation)
65
+ rune pipe architect.rune coder.rune "Build a REST API with Express" --auto
66
+
67
+ # Open desktop UI
79
68
  rune open reviewer.rune
80
69
  ```
81
70
 
82
71
  ---
83
72
 
84
- ## Use Cases
73
+ ## How It Works
85
74
 
86
- **Solo dev workflow** — Create `reviewer.rune` and `coder.rune` in your project. Use one to write code, the other to review it. Each agent keeps its own context and history.
75
+ Each `.rune` file is an independent AI agent:
87
76
 
88
- **Automated code review** — Set up a trigger to review every commit automatically:
89
- ```bash
90
- rune watch reviewer.rune --on git-commit --prompt "Review this commit for bugs and security issues"
77
+ ```json
78
+ {
79
+ "name": "reviewer",
80
+ "role": "Code reviewer, security focused",
81
+ "history": [],
82
+ "memory": []
83
+ }
91
84
  ```
92
85
 
93
- **CI/CD integration** — Run agents headlessly in your pipeline:
94
- ```bash
95
- rune run qa.rune "Run tests and report any failures" --output json
96
- ```
86
+ - **Portable** — It's just JSON. Commit to git, share with teammates, move between machines.
87
+ - **Persistent** — Role, memory, and chat history live in the file. The agent picks up where it left off.
88
+ - **Independent** — Multiple agents in the same folder, each with their own context.
89
+
90
+ ---
91
+
92
+ ## Agent Pipeline
93
+
94
+ Chain agents together. Each agent's output feeds into the next:
97
95
 
98
- **Agent pipeline** — Chain specialized agents for complex tasks:
99
96
  ```bash
100
97
  rune pipe architect.rune coder.rune reviewer.rune "Add OAuth2 login flow"
101
98
  ```
102
99
 
103
- **Team collaboration** — Commit `.rune` files to git. Your teammates get the same agent with the same role and memory — no setup needed.
100
+ architect designs → coder implements → reviewer checks.
101
+
102
+ With `--auto`, the last agent can write files and run commands:
104
103
 
105
- **Monitoring** — Schedule an agent to check things periodically:
106
104
  ```bash
107
- rune watch ops.rune --on cron --interval 10m --prompt "Check if the API is healthy"
105
+ rune pipe architect.rune coder.rune "Build a REST API with Express" --auto
108
106
  ```
109
107
 
110
108
  ---
111
109
 
112
- ## Harness
113
-
114
- ### Headless execution
110
+ ## Autonomous Mode
115
111
 
116
- Run any `.rune` agent from the command line without opening the GUI:
112
+ `--auto` lets agents write files, run commands, and fix errors on their own:
117
113
 
118
114
  ```bash
119
- rune run reviewer.rune "Review the latest commit"
120
-
121
- # Pipe input from other commands
122
- git diff | rune run reviewer.rune "Review this diff"
123
-
124
- # JSON output for scripting
125
- rune run reviewer.rune "Review src/auth.ts" --output json
115
+ rune run coder.rune "Create a server.js with Express, run npm init and npm install" --auto
126
116
  ```
127
117
 
128
- ### Agent chaining
118
+ You see every action in real-time:
119
+ ```
120
+ 🔮 [auto] coder is working on: Create a server.js...
129
121
 
130
- Chain multiple agents into a pipeline. The output of each agent becomes the input for the next:
122
+ ▶ Write: /path/to/server.js
123
+ ▶ Bash: npm init -y
124
+ ▶ Bash: npm install express
125
+ 💬 Server created and dependencies installed.
131
126
 
132
- ```bash
133
- rune pipe coder.rune reviewer.rune tester.rune "Implement a login page"
127
+ ✓ coder finished
134
128
  ```
135
129
 
136
- This runs: coder writes the code → reviewer reviews it → tester writes tests.
130
+ ---
137
131
 
138
- ### Automated triggers
132
+ ## Automated Triggers
139
133
 
140
- Set agents to run automatically on events:
134
+ Run agents automatically on events:
141
135
 
142
136
  ```bash
143
- # Run on every git commit
137
+ # On every git commit
144
138
  rune watch reviewer.rune --on git-commit --prompt "Review this commit"
145
139
 
146
- # Watch for file changes
140
+ # On file changes
147
141
  rune watch linter.rune --on file-change --glob "src/**/*.ts" --prompt "Check for issues"
148
142
 
149
- # Run on a schedule
143
+ # On a schedule
150
144
  rune watch monitor.rune --on cron --interval 5m --prompt "Check server health"
151
145
  ```
152
146
 
153
- ### Node.js API
147
+ ---
148
+
149
+ ## Node.js API
154
150
 
155
- Use Rune agents programmatically in your own code:
151
+ Use agents in your own code:
156
152
 
157
153
  ```js
158
154
  const rune = require('openrune')
159
155
 
156
+ // Single agent
160
157
  const reviewer = rune.load('reviewer.rune')
161
158
  const result = await reviewer.send('Review the latest commit')
162
- console.log(result)
163
159
 
164
- // Agent chaining via API
160
+ // Pipeline
165
161
  const { finalOutput } = await rune.pipe(
166
- ['coder.rune', 'reviewer.rune'],
167
- 'Implement a login page'
162
+ ['architect.rune', 'coder.rune'],
163
+ 'Build a REST API'
168
164
  )
169
165
  ```
170
166
 
167
+ Works in Express servers, scripts, CI/CD — anywhere Node.js runs.
168
+
171
169
  ---
172
170
 
173
171
  ## Desktop UI
174
172
 
175
- Rune also includes a desktop app for interactive use. Double-click a `.rune` file or run `rune open`.
173
+ Double-click a `.rune` file or run `rune open` for an interactive chat interface.
176
174
 
177
- - **Chat interface** — Markdown rendering, file attachment, stream cancellation.
178
- - **Real-time activity** — See every tool call, result, and permission request as it happens via [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks).
179
- - **Built-in terminal** — Raw Claude Code output and your own commands, side by side.
180
- - **Right-click to create** — macOS Quick Action lets you create agents from Finder.
175
+ - **Real-time activity** — See every tool call, result, and permission request via [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks).
176
+ - **Built-in terminal** — Claude Code output and your own commands, side by side.
177
+ - **Right-click to create** — macOS Quick Action for creating agents from Finder.
181
178
 
182
179
  <p align="center">
183
180
  <img src="demo.gif" width="100%" alt="Rune demo" />
@@ -185,139 +182,71 @@ Rune also includes a desktop app for interactive use. Double-click a `.rune` fil
185
182
 
186
183
  ---
187
184
 
188
- ## The `.rune` File
189
-
190
- A `.rune` file is just JSON:
191
-
192
- ```json
193
- {
194
- "name": "reviewer",
195
- "role": "Code reviewer, security focused",
196
- "createdAt": "2025-01-01T00:00:00Z",
197
- "history": [],
198
- "memory": []
199
- }
200
- ```
185
+ ## Use Cases
201
186
 
202
- Edit the `role` field anytime to change the agent's behavior. History and memory persist across sessions automatically.
187
+ | Scenario | Example |
188
+ |----------|---------|
189
+ | **Code review** | `rune run reviewer.rune "Review the latest commit"` |
190
+ | **Auto review on commit** | `rune watch reviewer.rune --on git-commit --prompt "Review this"` |
191
+ | **Agent pipeline** | `rune pipe architect.rune coder.rune "Build a login page" --auto` |
192
+ | **CI/CD** | `rune run qa.rune "Run tests and report failures" --output json` |
193
+ | **Monitoring** | `rune watch ops.rune --on cron --interval 10m --prompt "Check health"` |
194
+ | **Team sharing** | Commit `.rune` files to git — teammates get the same agents |
195
+ | **Node.js server** | `const rune = require('openrune'); rune.load('agent.rune').send(...)` |
203
196
 
204
197
  ---
205
198
 
206
- ## CLI Commands
199
+ ## CLI Reference
207
200
 
208
201
  | Command | Description |
209
202
  |---------|-------------|
210
- | `rune new <name>` | Create a `.rune` file in the current directory |
211
- | `rune new <name> --role "..."` | Create with a custom role |
212
- | `rune run <file.rune> "prompt"` | Run agent headlessly (no GUI) |
213
- | `rune pipe <a.rune> <b.rune> "prompt"` | Chain agents in a pipeline |
214
- | `rune watch <file.rune> --on <event>` | Set up automated triggers |
215
- | `rune open <file.rune>` | Open a `.rune` file (desktop GUI) |
216
- | `rune list` | List `.rune` files in the current directory |
217
- | `rune install` | Build app, register file association, install Quick Action |
218
- | `rune uninstall` | Remove Rune integration (keeps your `.rune` files) |
203
+ | `rune new <name> [--role "..."]` | Create agent |
204
+ | `rune run <file> "prompt" [--auto] [--output json]` | Run headlessly |
205
+ | `rune pipe <a> <b> [...] "prompt" [--auto]` | Chain agents |
206
+ | `rune watch <file> --on <event> --prompt "..."` | Automated triggers |
207
+ | `rune open <file>` | Desktop UI |
208
+ | `rune list` | List agents in current directory |
209
+ | `rune install` | Set up file associations & Quick Action |
210
+
211
+ **Watch events:** `git-commit`, `git-push`, `file-change` (with `--glob`), `cron` (with `--interval`)
219
212
 
220
213
  ---
221
214
 
222
215
  ## Architecture
223
216
 
224
217
  ```
225
- ┌─────────────────────────┐
226
- │ Desktop UI Mode │
227
- │ User ↔ Chat UI (React) │
228
- │ ↕ IPC │
229
- │ Electron Main Process │
230
- │ ↕ HTTP + SSE │
231
- └────────────┬────────────┘
232
- │
233
- ┌────────────┴────────────┐
234
- │ MCP Channel │ Claude Code Hooks
235
- │ (rune-channel) │ ↕ HTTP POST
236
- │ ↕ MCP │←──── rune-channel /hook
237
- └────────────┬────────────┘
238
- │
239
- ┌────────────┴────────────┐
240
- │ Claude Code CLI │
241
- └─────────────────────────┘
242
-
243
- Harness Mode (rune run / pipe / watch):
244
- CLI → Claude Code CLI (-p) → stdout
245
- No MCP channel, no Electron — direct execution
246
- ```
247
-
248
- **Two modes of operation:**
218
+ Harness Mode (rune run / pipe / watch):
219
+ CLI → Claude Code (-p) → stdout
220
+ No GUI, no MCP — direct execution with .rune context
249
221
 
250
- 1. **Harness** — Direct CLI execution via `claude -p`. Agents run headlessly with context from the `.rune` file.
251
- 2. **Desktop UI** — Chat input → MCP channel → Claude Code, with hooks for real-time activity monitoring.
222
+ Desktop UI Mode (rune open / double-click):
223
+ Chat UI (React) ↔ Electron ↔ MCP Channel ↔ Claude Code CLI
224
+ Real-time hooks for activity monitoring
225
+ ```
252
226
 
253
227
  ---
254
228
 
255
229
  ## Development
256
230
 
257
- ### Setup
258
-
259
231
  ```bash
260
232
  git clone https://github.com/gilhyun/Rune.git
261
233
  cd Rune
262
234
  npm install
263
- ```
264
-
265
- ### Build & Run
266
-
267
- ```bash
268
- # Build and launch
269
235
  npm start
270
-
271
- # Build only
272
- npm run build
273
236
  ```
274
237
 
275
238
  ### Project Structure
276
239
 
277
240
  ```
278
- Rune/
279
- bin/rune.js # CLI (install, new, open, run, pipe, watch, list)
280
- lib/index.js # Node.js API (require('openrune'))
281
- src/
282
- main.ts # Electron main process
283
- preload.ts # Preload bridge (IPC security)
284
- channel/
285
- rune-channel.ts # MCP channel + hooks HTTP endpoint
286
- renderer/
287
- src/
288
- App.tsx # Root React component
289
- features/
290
- chat/ # Chat UI (input, messages, activity blocks)
291
- terminal/ # Built-in terminal (xterm.js + node-pty)
292
- hooks/ # IPC hooks
293
- lib/ # Utilities
241
+ bin/rune.js CLI (new, run, pipe, watch, open, list)
242
+ lib/index.js Node.js API
243
+ channel/rune-channel.ts MCP channel + hooks endpoint
244
+ src/main.ts Electron main process
245
+ renderer/src/ React chat UI + terminal
294
246
  ```
295
247
 
296
248
  ---
297
249
 
298
- ## Important Notice
299
-
300
- > **Rune is currently in early development.** The MCP channel (`rune-channel`) loads via Claude Code's `--dangerously-load-development-channels` flag. This is a development-only feature and may change in future Claude Code releases. Use at your own discretion.
301
-
302
- ---
303
-
304
- ## Troubleshooting
305
-
306
- ### "Channel disconnected"
307
-
308
- The Claude Code CLI isn't running. It should start automatically via the terminal. If not:
309
-
310
- ```bash
311
- cd /your/project/folder
312
- RUNE_CHANNEL_PORT=<port> claude --permission-mode auto --enable-auto-mode
313
- ```
314
-
315
- ### Quick Action doesn't appear
316
-
317
- Open **System Settings** → **Privacy & Security** → **Extensions** → **Finder** and enable **New Rune**.
318
-
319
- ---
320
-
321
250
  ## Platform Support
322
251
 
323
252
  | Platform | Status |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openrune",
3
- "version": "0.3.22",
3
+ "version": "0.4.0",
4
4
  "description": "Rune — File-based AI Agent Harness for Claude Code",
5
5
  "keywords": ["ai", "agent", "claude", "desktop", "electron", "mcp", "claude-code", "harness", "automation"],
6
6
  "repository": {