openrune 0.2.0 → 0.2.2

package/README.md

@@ -19,13 +19,14 @@
 
 ## What is Rune?
 
-Rune turns any folder into an AI workspace. Each `.rune` file is an independent AI agent with its own chat history, role, and context — all powered by [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+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.
 
 - **File-based** — One `.rune` file = one agent. Move it, share it, version it with git.
-- **Folder-aware** — The agent knows your project. It can read files, run commands, and write code.
-- **Real-time activity** — See every tool call, permission request, and agent action as it happens via Claude Code hooks.
-- **Desktop-native** — Lightweight Electron app with built-in terminal. No browser needed.
-- **Right-click to create** — macOS Quick Action lets you create agents from Finder.
+- **Headless execution** — Run agents from the CLI or scripts. No GUI needed.
+- **Agent chaining** — Pipe agents together in a pipeline. Output → input, automatically.
+- **Automated triggers** — Run agents on file changes, git commits, or a cron schedule.
+- **Node.js API** — Use agents programmatically with `require('openrune')`.
+- **Desktop UI** — Chat interface with real-time activity monitoring and built-in terminal.
 
 ---
 
@@ -33,19 +34,15 @@ Rune turns any folder into an AI workspace. Each `.rune` file is an independent
 
 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.
 
-**No harness boilerplate** — No SDK wiring, no process management, no custom I/O parsing. One `.rune` file gives you a fully working Claude Code agent with a desktop UI.
-
-**Persistent context** — Your agent remembers everything. Close the app, reopen it next week — the conversation and context are right where you left off.
+**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.
 
-**Portable** — The `.rune` file is just a JSON file. Copy it to another machine, share it with a teammate, or check it into git. Your agent goes wherever the file goes.
+**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.
 
-**Multiple agents per folder** — Need a code reviewer AND a backend developer in the same project? Create two `.rune` files. Each agent has its own role, history, and expertise — working side by side in the same folder.
+**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.
 
-**No setup per project** — No config files, no extensions, no workspace settings. Drop a `.rune` file and you're ready.
+**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.
 
-<p align="center">
-  <img src="demo.gif" width="100%" alt="Rune demo" />
-</p>
+**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.
 
 ---
 
@@ -62,102 +59,57 @@ Building a Claude Code harness usually means wiring up process management, I/O p
 npm install -g openrune
 ```
 
-### 2. Create your first agent
+### 2. Create an agent
 
 ```bash
 cd ~/my-project
-rune new myagent
+rune new reviewer --role "Code reviewer, security focused"
 ```
 
-Or right-click any folder in Finder → Quick Actions → **New Rune**
-
-<p align="center">
-  <img src="Screenshot.png" width="500" alt="Right-click to create a Rune agent" />
-</p>
+### 3. Run it
 
-### 3. Open and chat
+```bash
+# Headless — run from CLI, get results in your terminal
+rune run reviewer.rune "Review the latest commit"
 
-**Double-click** the `.rune` file, or:
+# Pipe input from other commands
+git diff | rune run reviewer.rune "Review this diff"
 
-```bash
-rune open myagent.rune
+# Desktop UI — open the chat interface
+rune open reviewer.rune
 ```
 
 ---
 
-## Features
-
-### Chat UI
-
-- **Markdown rendering** — Code blocks, tables, lists with syntax highlighting.
-- **File attachment** — Drag and drop files or click to attach. The agent reads them from your filesystem.
-- **Stream cancellation** — Stop a response mid-stream.
-- **Chat history** — Persisted in the `.rune` file. Clear anytime.
-
-### Real-time Activity Monitoring
-
-Rune uses [Claude Code hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) to capture all agent activity in real-time:
-
-- **Tool calls** — See when the agent reads files, edits code, runs commands.
-- **Tool results** — See the output of each action.
-- **Permission requests** — Get notified when the agent needs approval.
-- **Session events** — Track when sessions start, stop, or encounter errors.
+## Use Cases
 
-No more guessing what the agent is doing — everything is visible in the chat panel.
-
-### Built-in Terminal
-
-Toggle the terminal panel to see raw Claude Code output or run your own commands alongside the agent.
-
-### Agent Roles
+**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.
 
+**Automated code review** — Set up a trigger to review every commit automatically:
 ```bash
-# General assistant
-rune new assistant
-
-# Specialized agents
-rune new designer --role "UI/UX design expert"
-rune new backend --role "Backend developer, Node.js specialist"
-rune new reviewer --role "Code reviewer, focused on security and performance"
+rune watch reviewer.rune --on git-commit --prompt "Review this commit for bugs and security issues"
 ```
 
-### The `.rune` File
-
-A `.rune` file is just JSON:
-
-```json
-{
-  "name": "myagent",
-  "role": "General assistant",
-  "icon": "bot",
-  "createdAt": "2025-01-01T00:00:00Z",
-  "history": []
-}
+**CI/CD integration** — Run agents headlessly in your pipeline:
+```bash
+rune run qa.rune "Run tests and report any failures" --output json
 ```
 
-Edit the `role` field anytime to change the agent's behavior.
-
----
+**Agent pipeline** — Chain specialized agents for complex tasks:
+```bash
+rune pipe architect.rune coder.rune reviewer.rune "Add OAuth2 login flow"
+```
 
-## CLI Commands
+**Team collaboration** — Commit `.rune` files to git. Your teammates get the same agent with the same role and memory — no setup needed.
 
-| Command | Description |
-|---------|-------------|
-| `rune install` | Build app, register file association, install Quick Action |
-| `rune new <name>` | Create a `.rune` file in the current directory |
-| `rune new <name> --role "..."` | Create with a custom role |
-| `rune open <file.rune>` | Open a `.rune` file (desktop GUI) |
-| `rune run <file.rune> "prompt"` | Run agent headlessly (no GUI) |
-| `rune pipe <a.rune> <b.rune> "prompt"` | Chain agents in a pipeline |
-| `rune watch <file.rune> --on <event>` | Set up automated triggers |
-| `rune list` | List `.rune` files in the current directory |
-| `rune uninstall` | Remove Rune integration (keeps your `.rune` files) |
+**Monitoring** — Schedule an agent to check things periodically:
+```bash
+rune watch ops.rune --on cron --interval 10m --prompt "Check if the API is healthy"
+```
 
 ---
 
-## Harness Mode
-
-Rune isn't just a desktop app — it's a full agent harness. Use it from scripts, CI/CD, or your own tools.
+## Harness
 
 ### Headless execution
 
@@ -218,24 +170,85 @@ const { finalOutput } = await rune.pipe(
 
 ---
 
+## Desktop UI
+
+Rune also includes a desktop app for interactive use. Double-click a `.rune` file or run `rune open`.
+
+- **Chat interface** — Markdown rendering, file attachment, stream cancellation.
+- **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).
+- **Built-in terminal** — Raw Claude Code output and your own commands, side by side.
+- **Right-click to create** — macOS Quick Action lets you create agents from Finder.
+
+<p align="center">
+  <img src="demo.gif" width="100%" alt="Rune demo" />
+</p>
+
+---
+
+## The `.rune` File
+
+A `.rune` file is just JSON:
+
+```json
+{
+  "name": "reviewer",
+  "role": "Code reviewer, security focused",
+  "createdAt": "2025-01-01T00:00:00Z",
+  "history": [],
+  "memory": []
+}
+```
+
+Edit the `role` field anytime to change the agent's behavior. History and memory persist across sessions automatically.
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `rune new <name>` | Create a `.rune` file in the current directory |
+| `rune new <name> --role "..."` | Create with a custom role |
+| `rune run <file.rune> "prompt"` | Run agent headlessly (no GUI) |
+| `rune pipe <a.rune> <b.rune> "prompt"` | Chain agents in a pipeline |
+| `rune watch <file.rune> --on <event>` | Set up automated triggers |
+| `rune open <file.rune>` | Open a `.rune` file (desktop GUI) |
+| `rune list` | List `.rune` files in the current directory |
+| `rune install` | Build app, register file association, install Quick Action |
+| `rune uninstall` | Remove Rune integration (keeps your `.rune` files) |
+
+---
+
 ## Architecture
 
 ```
-User ↔ Chat UI (React)
-         ↕ IPC
-       Electron Main Process
-         ↕ HTTP + SSE
-       MCP Channel (rune-channel)         Claude Code Hooks
-         ↕ MCP                              ↕ HTTP POST
-       Claude Code CLI  ──────────────→  rune-channel /hook
+                    ┌─────────────────────────┐
+                    │      Desktop UI Mode     │
+                    │   User ↔ Chat UI (React) │
+                    │         ↕ IPC            │
+                    │   Electron Main Process  │
+                    │         ↕ HTTP + SSE     │
+                    └────────────┬────────────┘
+                                 │
+                    ┌────────────┴────────────┐
+                    │  MCP Channel             │     Claude Code Hooks
+                    │  (rune-channel)          │      ↕ HTTP POST
+                    │         ↕ MCP            │←──── rune-channel /hook
+                    └────────────┬────────────┘
+                                 │
+                    ┌────────────┴────────────┐
+                    │     Claude Code CLI      │
+                    └─────────────────────────┘
+
+   Harness Mode (rune run / pipe / watch):
+     CLI → Claude Code CLI (-p) → stdout
+     No MCP channel, no Electron — direct execution
 ```
 
-**Two paths for data:**
-
-1. **Chat input** → MCP channel → Claude Code (user messages)
-2. **Claude Code hooks** → rune-channel → SSE → Chat UI (activity monitoring)
+**Two modes of operation:**
 
-The hooks approach ensures Rune sees everything Claude does, without relying on the agent to self-report.
+1. **Harness** — Direct CLI execution via `claude -p`. Agents run headlessly with context from the `.rune` file.
+2. **Desktop UI** — Chat input → MCP channel → Claude Code, with hooks for real-time activity monitoring.
 
 ---
 
@@ -263,7 +276,8 @@ npm run build
 
 ```
 Rune/
-  bin/rune.js              # CLI tool (install, new, open, list)
+  bin/rune.js              # CLI (install, new, open, run, pipe, watch, list)
+  lib/index.js             # Node.js API (require('openrune'))
   src/
     main.ts                # Electron main process
     preload.ts             # Preload bridge (IPC security)
@@ -279,12 +293,6 @@ Rune/
       lib/                 # Utilities
 ```
 
-### Hooks Configuration
-
-Rune automatically sets up Claude Code hooks in `~/.claude/settings.json`. The hooks only fire when `RUNE_CHANNEL_PORT` is set, so they don't affect standalone Claude Code usage.
-
-Captured events: `PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `Notification`, `SessionStart`, `SessionEnd`.
-
 ---
 
 ## Important Notice

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openrune",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Rune — File-based AI Agent Harness for Claude Code",
   "keywords": ["ai", "agent", "claude", "desktop", "electron", "mcp", "claude-code", "harness", "automation"],
   "repository": {