@openparachute/agent 0.1.0

package/.claude/skills/add-matrix/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: add-matrix
+description: Add Matrix channel integration via Chat SDK. Works with any Matrix homeserver.
+---
+
+# Add Matrix Channel
+
+Adds Matrix support via the Chat SDK bridge.
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Matrix adapter in from the `channels` branch.
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/matrix.ts` exists
+- `src/channels/index.ts` contains `import './matrix.js';`
+- `@beeper/chat-adapter-matrix` is listed in `package.json` dependencies
+
+Otherwise continue. Every step below is safe to re-run.
+
+### 1. Fetch the channels branch
+
+```bash
+git fetch origin channels
+```
+
+### 2. Copy the adapter
+
+```bash
+git show origin/channels:src/channels/matrix.ts > src/channels/matrix.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './matrix.js';
+```
+
+### 4. Install the adapter package (pinned)
+
+```bash
+pnpm install @beeper/chat-adapter-matrix@0.2.0
+```
+
+### 5. Patch matrix-js-sdk ESM imports
+
+The adapter's published dist references `matrix-js-sdk/lib/...` without `.js`
+extensions, which fails under Node 22 strict ESM resolution. Add the missing
+extensions (idempotent — safe to re-run):
+
+```bash
+node -e '
+  const fs = require("fs"), path = require("path");
+  const root = "node_modules/.pnpm";
+  const dir = fs.readdirSync(root).find(d => d.startsWith("@beeper+chat-adapter-matrix@"));
+  if (!dir) { console.log("Matrix adapter not installed"); process.exit(0); }
+  const f = path.join(root, dir, "node_modules/@beeper/chat-adapter-matrix/dist/index.js");
+  fs.writeFileSync(f, fs.readFileSync(f, "utf8").replace(
+    /from "(matrix-js-sdk\/lib\/[^"]+?)(?<!\.js)"/g, "from \"$1.js\""
+  ));
+  console.log("Patched", f);
+'
+```
+
+Re-run this after every `pnpm install` that touches the adapter.
+
+### 6. Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+The bot needs its own Matrix account — separate from the user's account. This is required because Matrix cannot send DMs to yourself.
+
+### Create a bot account
+
+1. Open [app.element.io](https://app.element.io) in a private/incognito window (or sign out first)
+2. Register a new account for the bot (e.g. `andybot` on matrix.org)
+3. Note the bot's user ID (e.g. `@andybot:matrix.org`)
+
+### Choose an auth method
+
+**Option A: Username + Password (simpler)**
+
+No extra steps — just use the bot account's credentials directly. The adapter logs in automatically.
+
+```bash
+MATRIX_BASE_URL=https://matrix.org
+MATRIX_USERNAME=andybot
+MATRIX_PASSWORD=your-bot-password
+MATRIX_USER_ID=@andybot:matrix.org
+MATRIX_BOT_USERNAME=Andy
+```
+
+**Option B: Access Token (recommended for production)**
+
+Get an access token from Element: sign into the bot account → **Settings** > **Help & About** > **Access Token** (under Advanced). Or via API:
+
+```bash
+curl -XPOST 'https://matrix.org/_matrix/client/r0/login' \
+  -d '{"type":"m.login.password","user":"andybot","password":"..."}'
+```
+
+```bash
+MATRIX_BASE_URL=https://matrix.org
+MATRIX_ACCESS_TOKEN=your-access-token
+MATRIX_USER_ID=@andybot:matrix.org
+MATRIX_BOT_USERNAME=Andy
+```
+
+### Optional settings
+
+```bash
+MATRIX_INVITE_AUTOJOIN=true                    # Auto-accept room invites (default: true)
+MATRIX_INVITE_AUTOJOIN_ALLOWLIST=@you:matrix.org  # Only accept invites from these users
+MATRIX_RECOVERY_KEY=your-recovery-key          # Enable E2EE cross-signing
+MATRIX_DEVICE_ID=NANOCLAW01                    # Stable device ID across restarts
+```
+
+### Configure environment
+
+Add the chosen env vars to `.env`, then sync:
+
+```bash
+mkdir -p data/env && cp .env data/env/env
+```
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, run `/manage-channels` to wire this channel to an agent group.
+
+## Channel Info
+
+- **type**: `matrix`
+- **terminology**: Matrix has "rooms." A room can be a group chat or a direct message. Rooms have internal IDs (like `!abc123:matrix.org`) and optional aliases (like `#general:matrix.org`).
+- **how-to-find-id**: For DMs, use the bot's `openDM` to resolve the room automatically. For group rooms, in Element click the room name > Settings > Advanced — the "Internal room ID" is the platform ID (starts with `!`). Or use a room alias like `#general:matrix.org`.
+- **supports-threads**: partial (some clients support threads, but not all — treat as no for reliability)
+- **typical-use**: Interactive chat — rooms or direct messages. Requires a separate bot account (the agent cannot DM users from their own account).
+- **default-isolation**: Same agent group for rooms where you're the primary user. Separate agent group for rooms with different communities or sensitive contexts.

package/.claude/skills/add-matrix/VERIFY.md

@@ -0,0 +1,3 @@
+# Verify Matrix Channel
+
+Invite the bot to a Matrix room and send a message. The bot should respond within a few seconds.

package/.claude/skills/add-ollama-provider/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: add-ollama-provider
+description: Route a NanoClaw agent group to a local Ollama model instead of the Anthropic API. Ollama speaks the Anthropic API natively (v1/messages), so no provider code changes are needed — just env var overrides and a model setting. Use when the user wants to run their agent locally, cut API costs, or experiment with open-weight models. See docs/ollama.md for background.
+---
+
+# Add Ollama Provider
+
+Routes an agent group to a local Ollama instance instead of the Anthropic API.
+See `docs/ollama.md` for how this works and the tradeoffs involved.
+
+## Prerequisites
+
+1. **Ollama is installed and running** on the host — verify: `curl -s http://localhost:11434/api/tags`
+2. **A model is pulled** — e.g. `ollama pull gemma4` or `ollama pull qwen3-coder`
+3. **The agent group already exists** — run `/init-first-agent` first if needed
+
+## 1. Check source support
+
+The feature requires two fields in `ContainerConfig` (`env` and `blockedHosts`) and their
+corresponding wiring in `container-runner.ts`. Check if already present:
+
+```bash
+grep -c 'blockedHosts' src/container-config.ts src/container-runner.ts
+```
+
+If either count is 0, apply the changes in steps 1a and 1b. Otherwise skip to step 2.
+
+### 1a. Extend ContainerConfig
+
+In `src/container-config.ts`, add to the `ContainerConfig` interface:
+
+```typescript
+env?: Record<string, string>;
+blockedHosts?: string[];
+```
+
+And in `readContainerConfig`, add inside the returned object:
+
+```typescript
+env: raw.env,
+blockedHosts: raw.blockedHosts,
+```
+
+### 1b. Wire into container-runner
+
+In `src/container-runner.ts`, after the `NANOCLAW_MCP_SERVERS` block, add:
+
+```typescript
+// Per-agent-group env overrides — applied last to win over OneCLI values.
+if (containerConfig.env) {
+  for (const [key, value] of Object.entries(containerConfig.env)) {
+    args.push('-e', `${key}=${value}`);
+  }
+}
+
+// Blocked hosts: resolve to 0.0.0.0 so they are unreachable inside the container.
+if (containerConfig.blockedHosts) {
+  for (const host of containerConfig.blockedHosts) {
+    args.push('--add-host', `${host}:0.0.0.0`);
+  }
+}
+```
+
+### 1c. Fix home directory permissions (if not already done)
+
+The container may run as your host uid (not uid 1000). Check the Dockerfile:
+
+```bash
+grep 'chmod.*home/node' container/Dockerfile
+```
+
+If it shows `chmod 755`, change it to `chmod 777` so any uid can write there.
+Then rebuild the container image: `./container/build.sh`
+
+## 2. Identify the setup
+
+Ask the user (plain text, not AskUserQuestion):
+
+1. **Which agent group?** List available groups: `sqlite3 data/v2.db "SELECT folder, name FROM agent_groups;"`
+2. **Which Ollama model?** List available: `curl -s http://localhost:11434/api/tags | grep '"name"'`
+3. **Block Anthropic API?** Recommended yes — prevents accidental spend if config drifts.
+
+Record as `FOLDER`, `MODEL`, and `BLOCK_ANTHROPIC`.
+
+## 3. Configure container.json
+
+Read `groups/<FOLDER>/container.json`. Add (or merge into) an `env` block and optionally `blockedHosts`:
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://host.docker.internal:11434",
+    "ANTHROPIC_API_KEY": "ollama",
+    "NO_PROXY": "host.docker.internal",
+    "no_proxy": "host.docker.internal"
+  },
+  "blockedHosts": ["api.anthropic.com"]
+}
+```
+
+Omit `blockedHosts` if the user declined step 2.
+
+**Why these vars:** `ANTHROPIC_BASE_URL` redirects the Anthropic SDK to Ollama.
+`ANTHROPIC_API_KEY=ollama` satisfies the SDK's key requirement (Ollama ignores it).
+`NO_PROXY` bypasses the OneCLI HTTPS proxy for requests to `host.docker.internal`
+so they reach Ollama directly instead of going through the credential gateway.
+
+## 4. Set the model
+
+Read the agent group's shared Claude settings:
+
+```bash
+# Find the agent group ID
+AG_ID=$(sqlite3 data/v2.db "SELECT id FROM agent_groups WHERE folder='<FOLDER>';")
+SETTINGS=data/v2-sessions/$AG_ID/.claude-shared/settings.json
+```
+
+Add `"model": "<MODEL>"` to that settings file. Create the file if it doesn't exist:
+
+```json
+{
+  "model": "gemma4:latest"
+}
+```
+
+If the file already has content, merge the `model` key in — don't overwrite existing keys.
+
+**Why here and not container.json:** Claude Code reads its model from its own settings
+file, not from env vars. This file is bind-mounted into the container as `~/.claude/settings.json`.
+
+## 5. Build and restart
+
+```bash
+export PATH="/opt/homebrew/bin:$PATH"
+pnpm run build
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
+# Linux: systemctl --user restart nanoclaw
+```
+
+## 6. Verify
+
+Send a message to the agent. Then confirm:
+
+```bash
+# Ollama shows the model as active
+curl -s http://localhost:11434/api/ps | grep '"name"'
+
+# Container has the right env vars
+CTR=$(docker ps --filter "name=nanoclaw-v2-<FOLDER>" --format "{{.Names}}" | head -1)
+docker inspect "$CTR" --format '{{json .HostConfig.ExtraHosts}}'
+docker exec "$CTR" env | grep ANTHROPIC
+```
+
+Expected: `api.anthropic.com:0.0.0.0` in ExtraHosts, `ANTHROPIC_BASE_URL=http://host.docker.internal:11434`.
+
+## Reverting to Claude
+
+To switch back to the Anthropic API:
+
+1. Remove the `env` and `blockedHosts` keys from `groups/<FOLDER>/container.json`
+2. Remove `"model"` from the shared settings file
+3. Restart the service
+
+No rebuild needed — both files are read at container spawn time.
+
+## Troubleshooting
+
+**Agent hangs, no response:** Ollama may be loading the model cold (large models take 10–30s).
+Watch `curl -s http://localhost:11434/api/ps` — the model appears once loaded.
+
+**"model not found" error in container logs:** The model name in settings.json doesn't match
+what Ollama has. Run `ollama list` on the host and use the exact name shown.
+
+**Responses claim to be Claude:** The model was trained on data that includes Claude conversations.
+Add a line to `groups/<FOLDER>/CLAUDE.md` telling it what model it runs on.
+
+**Agent responds but Ollama shows no activity:** `NO_PROXY` may not have taken effect for
+`http_proxy` (lowercase). Add both `NO_PROXY` and `no_proxy` to the env block.

package/.claude/skills/add-ollama-tool/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: add-ollama-tool
+description: Add Ollama MCP server so the container agent can call local models and optionally manage the Ollama model library.
+---
+
+# Add Ollama Integration
+
+This skill adds a stdio-based MCP server that exposes local Ollama models as tools for the container agent. Claude remains the orchestrator but can offload work to local models, and can optionally manage the model library directly.
+
+Core tools (always available):
+- `ollama_list_models` — list installed Ollama models with name, size, and family
+- `ollama_generate` — send a prompt to a specified model and return the response
+
+Management tools (opt-in via `OLLAMA_ADMIN_TOOLS=true`):
+- `ollama_pull_model` — pull (download) a model from the Ollama registry
+- `ollama_delete_model` — delete a locally installed model to free disk space
+- `ollama_show_model` — show model details: modelfile, parameters, and architecture info
+- `ollama_list_running` — list models currently loaded in memory with memory usage and processor type
+
+## Phase 1: Pre-flight
+
+### Check if already applied
+
+Check if `container/agent-runner/src/ollama-mcp-stdio.ts` exists. If it does, skip to Phase 3 (Configure).
+
+### Check prerequisites
+
+Verify Ollama is installed and running on the host:
+
+```bash
+ollama list
+```
+
+If Ollama is not installed, direct the user to https://ollama.com/download.
+
+If no models are installed, suggest pulling one:
+
+> You need at least one model. I recommend:
+>
+> ```bash
+> ollama pull gemma3:1b    # Small, fast (1GB)
+> ollama pull llama3.2     # Good general purpose (2GB)
+> ollama pull qwen3-coder:30b  # Best for code tasks (18GB)
+> ```
+
+## Phase 2: Apply Code Changes
+
+### Ensure upstream remote
+
+```bash
+git remote -v
+```
+
+If `upstream` is missing, add it:
+
+```bash
+git remote add upstream https://github.com/qwibitai/nanoclaw.git
+```
+
+### Merge the skill branch
+
+```bash
+git fetch upstream skill/ollama-tool
+git merge upstream/skill/ollama-tool
+```
+
+This merges in:
+- `container/agent-runner/src/ollama-mcp-stdio.ts` (Ollama MCP server)
+- `scripts/ollama-watch.sh` (macOS notification watcher)
+- Ollama MCP config in `container/agent-runner/src/index.ts` (allowedTools + mcpServers)
+- `[OLLAMA]` log surfacing in `src/container-runner.ts`
+- `OLLAMA_HOST` in `.env.example`
+
+If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.
+
+### Copy to per-group agent-runner
+
+Existing groups have a cached copy of the agent-runner source. Copy the new files:
+
+```bash
+for dir in data/sessions/*/agent-runner-src; do
+  cp container/agent-runner/src/ollama-mcp-stdio.ts "$dir/"
+  cp container/agent-runner/src/index.ts "$dir/"
+done
+```
+
+### Validate code changes
+
+```bash
+pnpm run build
+./container/build.sh
+```
+
+Build must be clean before proceeding.
+
+## Phase 3: Configure
+
+### Enable model management tools (optional)
+
+Ask the user:
+
+> Would you like the agent to be able to **manage Ollama models** (pull, delete, inspect, list running)?
+>
+> - **Yes** — adds tools to pull new models, delete old ones, show model info, and check what's loaded in memory
+> - **No** — the agent can only list installed models and generate responses (you manage models yourself on the host)
+
+If the user wants management tools, add to `.env`:
+
+```bash
+OLLAMA_ADMIN_TOOLS=true
+```
+
+If they decline (or don't answer), do not add the variable — management tools will be disabled by default.
+
+### Set Ollama host (optional)
+
+By default, the MCP server connects to `http://host.docker.internal:11434` (Docker Desktop) with a fallback to `localhost`. To use a custom Ollama host, add to `.env`:
+
+```bash
+OLLAMA_HOST=http://your-ollama-host:11434
+```
+
+### Restart the service
+
+```bash
+launchctl kickstart -k gui/$(id -u)/com.nanoclaw  # macOS
+# Linux: systemctl --user restart nanoclaw
+```
+
+## Phase 4: Verify
+
+### Test inference
+
+Tell the user:
+
+> Send a message like: "use ollama to tell me the capital of France"
+>
+> The agent should use `ollama_list_models` to find available models, then `ollama_generate` to get a response.
+
+### Test model management (if enabled)
+
+If `OLLAMA_ADMIN_TOOLS=true` was set, tell the user:
+
+> Send a message like: "pull the gemma3:1b model" or "which ollama models are currently loaded in memory?"
+>
+> The agent should call `ollama_pull_model` or `ollama_list_running` respectively.
+
+### Monitor activity (optional)
+
+Run the watcher script for macOS notifications when Ollama is used:
+
+```bash
+./scripts/ollama-watch.sh
+```
+
+### Check logs if needed
+
+```bash
+tail -f logs/nanoclaw.log | grep -i ollama
+```
+
+Look for:
+- `[OLLAMA] >>> Generating` — generation started
+- `[OLLAMA] <<< Done` — generation completed
+- `[OLLAMA] Pulling model:` — pull in progress (management tools)
+- `[OLLAMA] Deleted:` — model removed (management tools)
+
+## Troubleshooting
+
+### Agent says "Ollama is not installed"
+
+The agent is trying to run `ollama` CLI inside the container instead of using the MCP tools. This means:
+1. The MCP server wasn't registered — check `container/agent-runner/src/index.ts` has the `ollama` entry in `mcpServers`
+2. The per-group source wasn't updated — re-copy files (see Phase 2)
+3. The container wasn't rebuilt — run `./container/build.sh`
+
+### "Failed to connect to Ollama"
+
+1. Verify Ollama is running: `ollama list`
+2. Check Docker can reach the host: `docker run --rm curlimages/curl curl -s http://host.docker.internal:11434/api/tags`
+3. If using a custom host, check `OLLAMA_HOST` in `.env`
+
+### Agent doesn't use Ollama tools
+
+The agent may not know about the tools. Try being explicit: "use the ollama_generate tool with gemma3:1b to answer: ..."
+
+### `ollama_pull_model` times out on large models
+
+Large models (7B+) can take several minutes. The tool uses `stream: false` so it blocks until complete — this is intentional. For very large pulls, use the host CLI directly: `ollama pull <model>`
+
+### Management tools not showing up
+
+Ensure `OLLAMA_ADMIN_TOOLS=true` is set in `.env` and the service was restarted after adding it.