Skip to content

Commit bf27c6b

Browse files
author
Petrus Pennanen
committed
Merge branch 'feat/openclaw-skill'
2 parents 8879f9c + e1acbb6 commit bf27c6b

1 file changed

Lines changed: 164 additions & 0 deletions

File tree

‎SKILL.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
name: ide-agent-kit
3+
version: 0.2.0
4+
description: Filesystem message bus and webhook relay for cross-IDE agent coordination
5+
requires:
6+
bins: [node]
7+
env: []
8+
install:
9+
- kind: node
10+
package: ide-agent-kit
11+
bins: [ide-agent-kit]
12+
env:
13+
- name: OPENCLAW_TOKEN
14+
description: OpenClaw gateway auth token. Required only for gateway/sessions commands.
15+
required: false
16+
- name: GITHUB_WEBHOOK_SECRET
17+
description: HMAC secret for verifying inbound GitHub webhooks. Required only when using serve with GitHub.
18+
required: false
19+
- name: ANTFARM_API_KEY
20+
description: Ant Farm API key for room polling. Required only for the poll command.
21+
required: false
22+
---
23+
24+
# IDE Agent Kit
25+
26+
Filesystem-based message bus for cross-IDE agent coordination. Zero dependencies.
27+
28+
## Security Model
29+
30+
This skill operates in two tiers:
31+
32+
**Core (local-only, no credentials needed):**
33+
- Local filesystem queue and receipt log — agents read/write files in the working directory
34+
- `init`, `receipt tail`, `memory` (local backend), `keepalive` — no network, no secrets
35+
- `serve` binds to `127.0.0.1` only by default — receives webhooks, writes to local queue
36+
37+
**Advanced (requires explicit opt-in and credentials):**
38+
- `sessions`, `gateway` — talk to an OpenClaw gateway (requires `openclaw.token` in config)
39+
- `poll` — connects to Ant Farm rooms (requires `--api-key` flag)
40+
- `emit`, `hooks create` — POST data to external URLs you specify
41+
- `tmux run`, `exec` — execute shell commands (restricted to an allowlist in config)
42+
43+
No advanced features activate without explicit configuration. The default `init` config has empty credential fields and a minimal command allowlist.
44+
45+
### Network behavior
46+
47+
| Command | Outbound connections | Inbound connections |
48+
|---------|---------------------|---------------------|
49+
| `init`, `receipt tail`, `memory` (local), `keepalive` | None | None |
50+
| `serve` | None | localhost:8787 only (configurable) |
51+
| `poll` | Ant Farm API (HTTPS) | None |
52+
| `sessions`, `gateway` | OpenClaw gateway (localhost by default) | None |
53+
| `emit` | User-specified URL | None |
54+
| `hooks create` | User-specified webhook URL | None |
55+
56+
### Command execution
57+
58+
`tmux run` and `exec` only run commands listed in `tmux.allow` in your config. Default allowlist: `npm test`, `npm run build`, `pytest`, `git status`, `git diff`. Commands not on the list are rejected.
59+
60+
`exec` adds an approval flow: commands go through `exec request` → human/agent `exec resolve` before running.
61+
62+
## Quick Start
63+
64+
```bash
65+
npm install -g ide-agent-kit
66+
ide-agent-kit init --ide claude-code
67+
```
68+
69+
Creates a local `ide-agent-kit.json` config. All credential fields are blank. Nothing connects to any server until you configure it.
70+
71+
## Connectivity Modes
72+
73+
Four modes that compose freely. Only mode 1 is active by default.
74+
75+
### 1. Local Filesystem Bus (default)
76+
77+
Agents on the same machine communicate through a shared queue directory and receipt log. No network, no server, no API keys.
78+
79+
- Queue: `./ide-agent-queue.jsonl`
80+
- Receipts: `./ide-agent-receipts.jsonl`
81+
82+
### 2. Webhook Relay Server (optional)
83+
84+
Receives inbound webhooks from GitHub/GitLab and writes them to the local event queue.
85+
86+
```bash
87+
ide-agent-kit serve [--config <path>]
88+
```
89+
90+
Binds to `127.0.0.1:8787` by default. Set `github.webhook_secret` in config to verify signatures. Does not make outbound connections.
91+
92+
### 3. Ant Farm Room Polling (optional)
93+
94+
Connects to Ant Farm rooms for cross-machine coordination.
95+
96+
```bash
97+
ide-agent-kit poll --rooms <room1,room2> --api-key <key> --handle <@handle> [--interval <sec>]
98+
```
99+
100+
**Requires:** `--api-key` flag (Ant Farm API key). Rate-limited, default 120s interval.
101+
102+
### 4. GitHub Events (optional)
103+
104+
When `serve` is running, point a GitHub webhook at your relay URL. Translates PR/issue/CI events into local queue events.
105+
106+
**Requires:** `github.webhook_secret` in config to verify inbound signatures.
107+
108+
## Commands
109+
110+
### Core (local-only, no credentials)
111+
112+
| Command | Description |
113+
|---------|-------------|
114+
| `init [--ide <name>] [--profile <balanced\|low-friction>]` | Generate starter config |
115+
| `receipt tail [--n <count>]` | Print last N receipts |
116+
| `watch [--config <path>]` | Watch event queue, nudge IDE session on new events |
117+
| `serve [--config <path>]` | Start webhook relay server (localhost only) |
118+
| `memory list\|get\|set\|search` | Manage agent memory (local file backend) |
119+
| `keepalive start\|stop\|status` | Prevent macOS sleep for remote sessions |
120+
121+
### Advanced (requires credentials or explicit config)
122+
123+
| Command | Requires | Description |
124+
|---------|----------|-------------|
125+
| `sessions send --agent <id> --message <text>` | `openclaw.token` | Send message to agent via gateway |
126+
| `sessions spawn --task <text>` | `openclaw.token` | Spawn a new agent session |
127+
| `sessions list\|history\|status` | `openclaw.token` | Query sessions |
128+
| `gateway trigger\|health\|agents` | `openclaw.token` | Gateway operations |
129+
| `poll --rooms <r> --api-key <k> --handle <h>` | Ant Farm API key | Poll rooms for messages |
130+
| `emit --to <url> --json <file>` | None (user specifies target) | POST event JSON to a URL |
131+
| `hooks create --webhook-url <url>` | None (user specifies target) | Create webhook forwarder |
132+
| `tmux run --cmd <command>` | Allowlisted commands only | Run command in tmux, capture receipt |
133+
| `exec request\|resolve\|list` | Allowlisted commands only | Execution approval workflow |
134+
| `cron add\|list\|remove\|run\|status` | `openclaw.token` | Scheduled task management |
135+
136+
## Configuration
137+
138+
Generated by `ide-agent-kit init`. All credential fields default to empty.
139+
140+
| Field | Purpose | Default |
141+
|-------|---------|---------|
142+
| `listen.host` | Webhook server bind address | `127.0.0.1` |
143+
| `listen.port` | Webhook server port | `8787` |
144+
| `tmux.allow` | Allowlisted shell commands | `[npm test, npm run build, pytest, git status, git diff]` |
145+
| `openclaw.token` | Gateway auth (advanced commands) | empty |
146+
| `github.webhook_secret` | Verify GitHub webhooks | empty |
147+
148+
## Data Access
149+
150+
| Path | Access | Purpose |
151+
|------|--------|---------|
152+
| `ide-agent-receipts.jsonl` | append | Audit log of all agent actions |
153+
| `ide-agent-queue.jsonl` | read/write | Event queue |
154+
| `ide-agent-kit.json` | read | Runtime configuration (may contain secrets) |
155+
| `memory/` | read/write | Local agent memory files |
156+
157+
## Source & Verification
158+
159+
- **npm:** https://www.npmjs.com/package/ide-agent-kit
160+
- **Source:** https://github.com/ThinkOffApp/ide-agent-kit
161+
- **Maintainer:** petruspennanen (npm), ThinkOffApp (GitHub)
162+
- **License:** AGPL-3.0-only
163+
164+
The npm package contains no install scripts (`preinstall`/`postinstall`). All code is plain ESM JavaScript. Verify with `npm pack --dry-run` before installing.

0 commit comments

Comments
 (0)