openrune 0.3.22 → 0.4.1

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 +102 -198
  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
+ No SDK. No boilerplate. Just one file per agent.
10
10
  </p>
11
11
 
12
12
  <p align="center">
@@ -17,304 +17,208 @@
17
17
 
18
18
  ---
19
19
 
20
- ## What is Rune?
20
+ ## Install
21
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.
22
+ ```bash
23
+ npm install -g @anthropic-ai/claude-code # prerequisite
24
+ npm install -g openrune
25
+ ```
30
26
 
31
27
  ---
32
28
 
33
- ## Why Rune?
34
-
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.
36
-
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.
29
+ ## 30-Second Harness
38
30
 
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.
42
-
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.
31
+ ```bash
32
+ rune new reviewer --role "Code reviewer, security focused"
33
+ rune run reviewer.rune "Review the latest commit"
34
+ ```
44
35
 
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.
36
+ That's it. You just built an agent harness.
46
37
 
47
38
  ---
48
39
 
49
- ## Quick Start
40
+ ## Core Concepts
50
41
 
51
- ### Prerequisites
52
-
53
- - **Node.js** 18+
54
- - **Claude Code CLI** — `npm install -g @anthropic-ai/claude-code`
55
-
56
- ### 1. Install
42
+ ### One file = one agent
57
43
 
58
44
  ```bash
59
- npm install -g openrune
45
+ rune new architect --role "Software architect"
46
+ rune new coder --role "Backend developer"
47
+ rune new reviewer --role "Code reviewer"
60
48
  ```
61
49
 
62
- ### 2. Create an agent
50
+ Each `.rune` file is just JSON — portable, shareable, version-controllable:
63
51
 
64
- ```bash
65
- cd ~/my-project
66
- rune new reviewer --role "Code reviewer, security focused"
52
+ ```json
53
+ {
54
+ "name": "reviewer",
55
+ "role": "Code reviewer, security focused",
56
+ "history": [],
57
+ "memory": []
58
+ }
67
59
  ```
68
60
 
69
- ### 3. Run it
61
+ ### Headless execution
62
+
63
+ Run agents from the terminal. No GUI needed:
70
64
 
71
65
  ```bash
72
- # Headless — run from CLI, get results in your terminal
73
66
  rune run reviewer.rune "Review the latest commit"
74
67
 
75
68
  # Pipe input from other commands
76
69
  git diff | rune run reviewer.rune "Review this diff"
77
70
 
78
- # Desktop UI — open the chat interface
79
- rune open reviewer.rune
71
+ # JSON output for scripting
72
+ rune run reviewer.rune "Check for security issues" --output json
80
73
  ```
81
74
 
82
- ---
83
-
84
- ## Use Cases
75
+ ### Autonomous mode
85
76
 
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.
77
+ With `--auto`, agents write files, run commands, and fix errors on their own:
87
78
 
88
- **Automated code review** — Set up a trigger to review every commit automatically:
89
79
  ```bash
90
- rune watch reviewer.rune --on git-commit --prompt "Review this commit for bugs and security issues"
80
+ rune run coder.rune "Create an Express server with a /health endpoint. Run npm init and npm install." --auto
91
81
  ```
92
82
 
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
- ```
97
-
98
- **Agent pipeline** — Chain specialized agents for complex tasks:
99
- ```bash
100
- rune pipe architect.rune coder.rune reviewer.rune "Add OAuth2 login flow"
101
83
  ```
84
+ 🔮 [auto] coder is working on: Create an Express server...
102
85
 
103
- **Team collaboration** — Commit `.rune` files to git. Your teammates get the same agent with the same role and memory — no setup needed.
86
+ ▶ Write: /path/to/server.js
87
+ ▶ Bash: npm init -y
88
+ ▶ Bash: npm install express
89
+ 💬 Server created and dependencies installed.
104
90
 
105
- **Monitoring** — Schedule an agent to check things periodically:
106
- ```bash
107
- rune watch ops.rune --on cron --interval 10m --prompt "Check if the API is healthy"
91
+ ✓ coder finished
108
92
  ```
109
93
 
110
- ---
94
+ ### Agent pipeline
111
95
 
112
- ## Harness
113
-
114
- ### Headless execution
115
-
116
- Run any `.rune` agent from the command line without opening the GUI:
96
+ Chain agents. Each agent's output feeds into the next:
117
97
 
118
98
  ```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
99
+ rune pipe architect.rune coder.rune "Build a REST API with Express"
126
100
  ```
127
101
 
128
- ### Agent chaining
129
-
130
- Chain multiple agents into a pipeline. The output of each agent becomes the input for the next:
102
+ With `--auto`, the last agent executes the plan:
131
103
 
132
104
  ```bash
133
- rune pipe coder.rune reviewer.rune tester.rune "Implement a login page"
105
+ rune pipe architect.rune coder.rune "Build a REST API with Express" --auto
134
106
  ```
135
107
 
136
- This runs: coder writes the code → reviewer reviews it → tester writes tests.
108
+ architect designs → coder implements (writes files, installs deps).
137
109
 
138
110
  ### Automated triggers
139
111
 
140
- Set agents to run automatically on events:
141
-
142
112
  ```bash
143
- # Run on every git commit
113
+ # On every git commit
144
114
  rune watch reviewer.rune --on git-commit --prompt "Review this commit"
145
115
 
146
- # Watch for file changes
116
+ # On file changes
147
117
  rune watch linter.rune --on file-change --glob "src/**/*.ts" --prompt "Check for issues"
148
118
 
149
- # Run on a schedule
119
+ # On a schedule
150
120
  rune watch monitor.rune --on cron --interval 5m --prompt "Check server health"
151
121
  ```
152
122
 
153
123
  ### Node.js API
154
124
 
155
- Use Rune agents programmatically in your own code:
125
+ Use agents in your own code:
156
126
 
157
127
  ```js
158
128
  const rune = require('openrune')
159
129
 
160
130
  const reviewer = rune.load('reviewer.rune')
161
131
  const result = await reviewer.send('Review the latest commit')
162
- console.log(result)
163
132
 
164
- // Agent chaining via API
133
+ // Pipeline
165
134
  const { finalOutput } = await rune.pipe(
166
- ['coder.rune', 'reviewer.rune'],
167
- 'Implement a login page'
135
+ ['architect.rune', 'coder.rune'],
136
+ 'Build a REST API'
168
137
  )
169
138
  ```
170
139
 
171
140
  ---
172
141
 
173
- ## Desktop UI
174
-
175
- Rune also includes a desktop app for interactive use. Double-click a `.rune` file or run `rune open`.
176
-
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.
181
-
182
- <p align="center">
183
- <img src="demo.gif" width="100%" alt="Rune demo" />
184
- </p>
142
+ ## Example: Agent-Powered API Server
185
143
 
186
- ---
144
+ A full walkthrough — from zero to a running server built by agents.
187
145
 
188
- ## The `.rune` File
146
+ ### 1. Install and create agents
189
147
 
190
- A `.rune` file is just JSON:
148
+ ```bash
149
+ npm install -g openrune
150
+ mkdir my-project && cd my-project
191
151
 
192
- ```json
193
- {
194
- "name": "reviewer",
195
- "role": "Code reviewer, security focused",
196
- "createdAt": "2025-01-01T00:00:00Z",
197
- "history": [],
198
- "memory": []
199
- }
152
+ rune new architect --role "Software architect. Design system architecture concisely."
153
+ rune new coder --role "Backend developer. Implement code based on the given plan."
154
+ rune new reviewer --role "Code reviewer. Review for bugs and security issues."
200
155
  ```
201
156
 
202
- Edit the `role` field anytime to change the agent's behavior. History and memory persist across sessions automatically.
203
-
204
- ---
205
-
206
- ## CLI Commands
207
-
208
- | Command | Description |
209
- |---------|-------------|
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) |
219
-
220
- ---
157
+ ### 2. Agents collaborate to build a server
221
158
 
222
- ## Architecture
223
-
224
- ```
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
159
+ ```bash
160
+ rune pipe architect.rune coder.rune "Design and build an Express server with POST /review endpoint that uses require('openrune') to load reviewer.rune and send the prompt. Run npm init -y and npm install express openrune." --auto
246
161
  ```
247
162
 
248
- **Two modes of operation:**
249
-
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.
252
-
253
- ---
254
-
255
- ## Development
163
+ architect designs the architecture → coder writes `server.js`, runs `npm init`, installs dependencies.
256
164
 
257
- ### Setup
165
+ ### 3. Start the server
258
166
 
259
167
  ```bash
260
- git clone https://github.com/gilhyun/Rune.git
261
- cd Rune
262
- npm install
168
+ node server.js
263
169
  ```
264
170
 
265
- ### Build & Run
171
+ ### 4. Call the agent via API
266
172
 
267
173
  ```bash
268
- # Build and launch
269
- npm start
270
-
271
- # Build only
272
- npm run build
174
+ curl -X POST http://localhost:3000/review \
175
+ -H "Content-Type: application/json" \
176
+ -d '{"prompt": "Review this project"}'
273
177
  ```
274
178
 
275
- ### Project Structure
179
+ The reviewer agent analyzes your project and returns a full code review.
276
180
 
277
- ```
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
181
+ ### 5. Open the desktop UI
182
+
183
+ ```bash
184
+ rune open reviewer.rune
294
185
  ```
295
186
 
187
+ The conversation history from the API call is already there — context persists across CLI, API, and GUI.
188
+
296
189
  ---
297
190
 
298
- ## Important Notice
191
+ ## Desktop UI
299
192
 
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.
193
+ Rune includes an optional desktop app for interactive chat.
301
194
 
302
- ---
195
+ ```bash
196
+ rune open reviewer.rune
197
+ ```
303
198
 
304
- ## Troubleshooting
199
+ Or double-click any `.rune` file in Finder.
305
200
 
306
- ### "Channel disconnected"
201
+ - **Real-time activity** — See tool calls, results, and permission requests as they happen.
202
+ - **Built-in terminal** — Claude Code output and your own commands, side by side.
203
+ - **Right-click to create** — macOS Quick Action for creating agents from Finder.
307
204
 
308
- The Claude Code CLI isn't running. It should start automatically via the terminal. If not:
205
+ > If double-click doesn't work, run `rune install` once to register the file association.
309
206
 
310
- ```bash
311
- cd /your/project/folder
312
- RUNE_CHANNEL_PORT=<port> claude --permission-mode auto --enable-auto-mode
313
- ```
207
+ ---
314
208
 
315
- ### Quick Action doesn't appear
209
+ ## CLI Reference
316
210
 
317
- Open **System Settings** → **Privacy & Security** → **Extensions** → **Finder** and enable **New Rune**.
211
+ | Command | Description |
212
+ |---------|-------------|
213
+ | `rune new <name> [--role "..."]` | Create agent |
214
+ | `rune run <file> "prompt" [--auto] [--output json]` | Run headlessly |
215
+ | `rune pipe <a> <b> [...] "prompt" [--auto]` | Chain agents |
216
+ | `rune watch <file> --on <event> --prompt "..."` | Automated triggers |
217
+ | `rune open <file>` | Desktop UI |
218
+ | `rune list` | List agents in current directory |
219
+ | `rune install` | Set up file associations & Quick Action |
220
+
221
+ **Watch events:** `git-commit`, `git-push`, `file-change` (with `--glob`), `cron` (with `--interval`)
318
222
 
319
223
  ---
320
224
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openrune",
3
- "version": "0.3.22",
3
+ "version": "0.4.1",
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": {