@openparachute/agent 0.1.0

package/.claude/skills/add-karpathy-llm-wiki/llm-wiki.md

@@ -0,0 +1,75 @@
+# LLM Wiki
+
+> Source: [karpathy/llm-wiki.md](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+
+A pattern for building personal knowledge bases using LLMs.
+
+This is an idea file, designed to be copied to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, etc.). Its goal is to communicate the high-level idea, with your agent building out specifics through collaboration with you.
+
+## The Core Idea
+
+Most interactions with LLMs and documents follow RAG patterns: upload files, retrieve relevant chunks at query time, generate answers. The knowledge is re-derived on each question with no accumulation.
+
+The concept here differs fundamentally. Rather than just retrieving from raw documents, the LLM incrementally builds and maintains a persistent wiki — a structured, interlinked markdown collection sitting between you and raw sources. When adding new material, the LLM reads it, extracts key information, and integrates it into existing wiki pages—updating entities, revising summaries, flagging contradictions, strengthening synthesis. Knowledge compiles once and stays current rather than re-deriving on every query.
+
+The wiki becomes a persistent, compounding artifact. Cross-references already exist. Contradictions are flagged. Synthesis reflects everything read. The wiki enriches with every source added and question asked.
+
+You source material and ask questions; the LLM maintains everything—summarizing, cross-referencing, filing, and organizing. The LLM acts as programmer; Obsidian serves as IDE; the wiki functions as codebase.
+
+**Applications include:**
+- Personal: tracking goals, health, self-improvement
+- Research: deep dives over weeks/months
+- Reading: building companion wikis while progressing through books
+- Business/teams: internal wikis fed by Slack, transcripts, documents
+- Analysis: competitive research, due diligence, trip planning, hobby deep-dives
+
+## Architecture
+
+Three layers comprise the system:
+
+**Raw sources** — immutable curated documents (articles, papers, images, data). The LLM reads but never modifies these.
+
+**The wiki** — LLM-generated markdown directories containing summaries, entity pages, concept pages, comparisons, syntheses. The LLM owns this entirely, creating and updating pages while maintaining cross-references and consistency.
+
+**The schema** — configuration document (e.g., CLAUDE.md) explaining wiki structure, conventions, and workflows for ingestion, querying, and maintenance. This key file transforms the LLM into disciplined wiki maintainer rather than generic chatbot.
+
+## Operations
+
+**Ingest:** Drop new sources into the raw collection; the LLM processes them. The agent reads sources, discusses takeaways, writes summaries, updates indexes, refreshes entity and concept pages, logs entries. Single sources might touch 10-15 wiki pages. Prefer ingesting individually while staying involved, though batch ingestion with less oversight is possible.
+
+**Query:** Ask questions against the wiki. The LLM searches relevant pages, synthesizes answers with citations. Answers take various forms—markdown pages, comparison tables, slide decks, charts, canvas. Good answers can be filed back into the wiki as new pages—explorations compound in the knowledge base rather than disappearing into chat history.
+
+**Lint:** Periodically health-check the wiki. Look for contradictions, stale claims superseded by newer sources, orphan pages lacking inbound links, important concepts lacking dedicated pages, missing cross-references, data gaps. The LLM suggests investigations and sources to pursue, keeping the wiki healthy as it grows.
+
+## Indexing and Logging
+
+Two special files help navigate the growing wiki:
+
+**index.md** — content-oriented catalog of everything (each page with link, one-line summary, optional metadata like dates or source counts), organized by category. The LLM updates it on every ingest. When answering queries, read the index first to locate relevant pages before drilling deeper. This approach works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) while avoiding embedding-based RAG infrastructure needs.
+
+**log.md** — append-only chronological record of what happened and when (ingests, queries, lint passes). Each entry beginning with consistent prefix (e.g., `## [2026-04-02] ingest | Article Title`) becomes parseable with simple tools—`grep "^## \[" log.md | tail -5` yields last 5 entries. The log shows wiki evolution timeline and helps the LLM understand recent activity.
+
+## Optional: CLI Tools
+
+At scale, small tools help the LLM operate more efficiently. Search engine over wiki pages is most obvious—at small scale the index suffices, but as the wiki grows, proper search becomes necessary. qmd (https://github.com/tobi/qmd) offers local search with hybrid BM25/vector search and LLM re-ranking, entirely on-device. It includes both CLI (so LLMs can shell out) and MCP server (native tool integration). Build simpler custom search scripts as needs arise.
+
+## Tips and Tricks
+
+- **Obsidian Web Clipper** converts web articles to markdown for quick source collection
+- **Download images locally:** Set attachment folder in Obsidian Settings, bind download hotkey. All images store locally; LLM views and references directly instead of relying on potentially broken URLs
+- **Obsidian's graph view** visualizes wiki connectivity—what connects to what, hub pages, orphans
+- **Marp** provides markdown-based slide deck format with Obsidian plugin integration
+- **Dataview** plugin queries page frontmatter, generating dynamic tables/lists when LLM adds YAML frontmatter
+- The wiki is simply a git-backed markdown directory—version history, branching, collaboration included
+
+## Why This Works
+
+Knowledge base maintenance's tedious part is bookkeeping, not reading/thinking: updating cross-references, keeping summaries current, noting data contradictions, maintaining consistency across pages. Humans abandon wikis as maintenance burden outpaces value. LLMs don't bore, don't forget updates, can touch 15 files in one pass. Wiki maintenance becomes nearly free.
+
+Humans curate sources, direct analysis, ask good questions, think about meaning. LLMs handle everything else.
+
+This relates in spirit to Vannevar Bush's 1945 Memex—personal curated knowledge stores with associative document trails. Bush's vision resembled this more than what the web became: private, actively curated, with connections between documents as valuable as documents themselves. Bush couldn't solve maintenance; LLMs handle that.
+
+## Note
+
+This document intentionally remains abstract, describing the idea rather than specific implementation. Directory structure, schema conventions, page formats, tooling—all depend on domain, preferences, and LLM choice. Everything is optional and modular. Pick what's useful; ignore what isn't. Your sources might be text-only (no image handling needed). Your wiki might stay small enough that index files suffice (no search engine required). You might want different output formats entirely. Share this with your LLM agent and work collaboratively to instantiate a version fitting your needs. This document's sole purpose is communicating the pattern; your LLM figures out the rest.

package/.claude/skills/add-linear/REMOVE.md

@@ -0,0 +1,6 @@
+# Remove Linear Channel
+
+1. Comment out `import './linear.js'` in `src/channels/index.ts`
+2. Remove `LINEAR_API_KEY` and `LINEAR_WEBHOOK_SECRET` from `.env`
+3. `pnpm uninstall @chat-adapter/linear`
+4. Rebuild and restart

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

@@ -0,0 +1,168 @@
+---
+name: add-linear
+description: Add Linear channel integration via Chat SDK. Issue comment threads as conversations.
+---
+
+# Add Linear Channel
+
+Adds Linear support via the Chat SDK bridge. The agent participates in issue comment threads. Every comment on a Linear issue triggers the agent — no @-mention needed.
+
+## Prerequisites
+
+**Recommended:** Create a Linear **OAuth application** so the agent posts as an app identity, not as you. This prevents the adapter from filtering your own comments as self-messages.
+
+1. Go to [Linear Settings > API > OAuth Applications](https://linear.app/settings/api/applications/new)
+2. Create an app (e.g. "NanoClaw Bot")
+   - Developer URL: your repo URL (e.g. `https://github.com/your-org/nanoclaw`)
+   - Callback URL: `http://localhost`
+3. After creating, click the app and enable **Client credentials** under grant types
+4. Copy the **Client ID** and **Client Secret**
+
+**Alternative:** Use a Personal API Key (`LINEAR_API_KEY`) for simpler setup. The agent will post as you, and your own comments will be filtered (other team members' comments still work).
+
+## Install
+
+NanoClaw doesn't ship channels in trunk. This skill copies the Linear adapter in from the `channels` branch and patches the Chat SDK bridge to support catch-all message forwarding (Linear OAuth apps can't be @-mentioned).
+
+### Pre-flight (idempotent)
+
+Skip to **Credentials** if all of these are already in place:
+
+- `src/channels/linear.ts` exists
+- `src/channels/index.ts` contains `import './linear.js';`
+- `@chat-adapter/linear` is listed in `package.json` dependencies
+- `src/channels/chat-sdk-bridge.ts` contains `catchAll`
+
+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/linear.ts > src/channels/linear.ts
+```
+
+### 3. Append the self-registration import
+
+Append to `src/channels/index.ts` (skip if the line is already present):
+
+```typescript
+import './linear.js';
+```
+
+### 4. Patch the Chat SDK bridge for catch-all message forwarding
+
+Linear OAuth apps can't be @-mentioned, so the bridge's `onNewMention` handler never fires. Add `catchAll` support to `src/channels/chat-sdk-bridge.ts`:
+
+**4a.** Add `catchAll?: boolean` to the `ChatSdkBridgeConfig` interface:
+
+```typescript
+  /**
+   * Forward ALL messages in unsubscribed threads, not just @-mentions.
+   * Use for platforms where the bot identity can't be @-mentioned (e.g.
+   * Linear OAuth apps). The thread is auto-subscribed on first message.
+   */
+  catchAll?: boolean;
+```
+
+**4b.** Add this handler block right after the `chat.onNewMention(...)` block (before the DMs block):
+
+```typescript
+      // Catch-all for platforms where @-mention isn't possible (e.g. Linear
+      // OAuth apps). Forward every unsubscribed message and auto-subscribe.
+      if (config.catchAll) {
+        chat.onNewMessage(/.*/, async (thread, message) => {
+          const channelId = adapter.channelIdFromThreadId(thread.id);
+          await setupConfig.onInbound(channelId, thread.id, await messageToInbound(message));
+          await thread.subscribe();
+        });
+      }
+```
+
+### 5. Install the adapter package (pinned)
+
+```bash
+pnpm install @chat-adapter/linear@4.26.0
+```
+
+### 6. Build
+
+```bash
+pnpm run build
+```
+
+## Credentials
+
+### 1. Set up a webhook
+
+1. Go to **Linear Settings** > **API** > **Webhooks** > **New webhook**
+2. Label: `NanoClaw`
+3. URL: `https://your-domain/webhook/linear` (the shared webhook server, default port 3000)
+4. Team: select the team you want to monitor
+5. Events: check **Comment**
+6. Save — copy the **signing secret**
+
+Note: Linear webhook delivery may be delayed 1-5 minutes for new webhooks. This is normal.
+
+### 2. Configure environment
+
+Add to `.env`:
+
+```bash
+# OAuth app (recommended)
+LINEAR_CLIENT_ID=your-client-id
+LINEAR_CLIENT_SECRET=your-client-secret
+
+# OR Personal API key (simpler, but agent posts as you)
+# LINEAR_API_KEY=lin_api_...
+
+LINEAR_WEBHOOK_SECRET=your-webhook-signing-secret
+LINEAR_BOT_USERNAME=NanoClaw Bot
+LINEAR_TEAM_KEY=ENG
+```
+
+- `LINEAR_BOT_USERNAME`: display name for the bot (used for self-message detection when using a Personal API Key)
+- `LINEAR_TEAM_KEY`: the Linear team key (e.g. `ENG`, `NAN`). Find it in Linear under Settings > Teams. All issues in this team route to one messaging group.
+
+Sync to container: `mkdir -p data/env && cp .env data/env/env`
+
+## Wiring
+
+Ask the user: **Is this a private or public Linear workspace?**
+
+- **Private workspace** — use `unknown_sender_policy: 'public'`. Only workspace members can comment.
+- **Public workspace** — use `unknown_sender_policy: 'strict'` and add trusted members (see GitHub skill for member registration example).
+
+Run `/manage-channels` to wire the Linear channel to an agent group, or insert manually:
+
+```sql
+-- Create messaging group (one per team)
+INSERT INTO messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy, created_at)
+VALUES ('mg-linear-eng', 'linear', 'linear:ENG', 'Engineering', 1, 'public', datetime('now'));
+
+-- Wire to agent group
+INSERT INTO messaging_group_agents (id, messaging_group_id, agent_group_id, trigger_rules, response_scope, session_mode, priority, created_at)
+VALUES ('mga-linear-eng', 'mg-linear-eng', '<your-agent-group-id>', '', 'all', 'per-thread', 10, datetime('now'));
+```
+
+The `platform_id` must be `linear:<TEAM_KEY>` matching the `LINEAR_TEAM_KEY` env var. Use `per-thread` session mode so each issue comment thread gets its own agent session.
+
+## Next Steps
+
+If you're in the middle of `/setup`, return to the setup flow now.
+
+Otherwise, restart the service (`systemctl --user restart nanoclaw` or `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`) to pick up the new channel.
+
+## Channel Info
+
+- **type**: `linear`
+- **terminology**: Linear has "teams" containing "issues." Each issue's comment thread is a separate conversation.
+- **how-to-find-id**: The platform ID is `linear:<TEAM_KEY>` (e.g. `linear:ENG`). Find your team key in Linear under Settings > Teams. Each issue becomes its own thread automatically.
+- **supports-threads**: yes (issue comment threads are native conversations)
+- **typical-use**: Webhook-driven — the agent receives all issue comment events and responds automatically. No @-mention needed (Linear OAuth apps can't be @-mentioned).
+- **default-isolation**: Use `per-thread` session mode. Each issue comment thread gets its own isolated agent session.

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

@@ -0,0 +1,3 @@
+# Verify Linear Channel
+
+@mention the bot in a Linear issue comment. The bot should respond within a few seconds.

package/.claude/skills/add-macos-statusbar/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: add-macos-statusbar
+description: Add a macOS menu bar status indicator for NanoClaw. Shows a bolt icon with a green/red dot indicating whether NanoClaw is running, with Start, Stop, and Restart controls. macOS only.
+---
+
+# Add macOS Menu Bar Status Indicator
+
+Adds a persistent menu bar icon that shows NanoClaw's running status and lets the user
+start, stop, or restart the service — similar to how Docker Desktop appears in the menu bar.
+
+**macOS only.** Requires Xcode Command Line Tools (`swiftc`).
+
+## Phase 1: Pre-flight
+
+### Check platform
+
+If not on macOS, stop and tell the user:
+
+> This skill is macOS only. The menu bar status indicator uses AppKit and requires `swiftc` (Xcode Command Line Tools).
+
+### Check for swiftc
+
+```bash
+which swiftc
+```
+
+If not found, tell the user:
+
+> Xcode Command Line Tools are required. Install them by running:
+>
+> ```bash
+> xcode-select --install
+> ```
+>
+> Then re-run `/add-macos-statusbar`.
+
+### Check if already installed
+
+```bash
+launchctl list | grep com.nanoclaw.statusbar
+```
+
+If it returns a PID (not `-`), tell the user it's already installed and skip to Phase 3 (Verify).
+
+## Phase 2: Compile and Install
+
+### Compile the Swift binary
+
+The source lives in the skill directory. Compile it into `dist/`:
+
+```bash
+mkdir -p dist
+swiftc -O -o dist/statusbar "${CLAUDE_SKILL_DIR}/add/src/statusbar.swift"
+```
+
+This produces a small native binary at `dist/statusbar`.
+
+On macOS Sequoia or later, clear the quarantine attribute so the binary can run:
+
+```bash
+xattr -cr dist/statusbar
+```
+
+### Create the launchd plist
+
+Determine the absolute project root and home directory:
+
+```bash
+pwd
+echo $HOME
+```
+
+Create `~/Library/LaunchAgents/com.nanoclaw.statusbar.plist`, substituting the actual values
+for `{PROJECT_ROOT}` and `{HOME}`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.nanoclaw.statusbar</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{PROJECT_ROOT}/dist/statusbar</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>{HOME}</string>
+    </dict>
+    <key>StandardOutPath</key>
+    <string>{PROJECT_ROOT}/logs/statusbar.log</string>
+    <key>StandardErrorPath</key>
+    <string>{PROJECT_ROOT}/logs/statusbar.error.log</string>
+</dict>
+</plist>
+```
+
+### Load the service
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.nanoclaw.statusbar.plist
+```
+
+## Phase 3: Verify
+
+```bash
+launchctl list | grep com.nanoclaw.statusbar
+```
+
+The first column should show a PID (not `-`).
+
+Tell the user:
+
+> The bolt icon should now appear in your macOS menu bar. Click it to see NanoClaw's status and control the service.
+>
+> - **Green dot** — NanoClaw is running
+> - **Red dot** — NanoClaw is stopped
+>
+> Use **Restart** after making code changes, and **View Logs** to open the log file directly.
+
+## Removal
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.nanoclaw.statusbar.plist
+rm ~/Library/LaunchAgents/com.nanoclaw.statusbar.plist
+rm dist/statusbar
+```

package/.claude/skills/add-macos-statusbar/add/src/statusbar.swift

@@ -0,0 +1,147 @@
+import AppKit
+
+class StatusBarController: NSObject {
+    private var statusItem: NSStatusItem!
+    private var isRunning = false
+    private var timer: Timer?
+
+    private let plistPath = "\(NSHomeDirectory())/Library/LaunchAgents/com.nanoclaw.plist"
+
+    /// Derive the NanoClaw project root from the binary location.
+    /// The binary is compiled to {project}/dist/statusbar, so the parent of
+    /// the parent directory is the project root.
+    private static let projectRoot: String = {
+        let binary = URL(fileURLWithPath: CommandLine.arguments[0]).resolvingSymlinksInPath()
+        return binary.deletingLastPathComponent().deletingLastPathComponent().path
+    }()
+
+    override init() {
+        super.init()
+        setupStatusItem()
+        isRunning = checkRunning()
+        updateMenu()
+        // Poll every 5 seconds to reflect external state changes
+        timer = Timer.scheduledTimer(withTimeInterval: 5.0, repeats: true) { [weak self] _ in
+            guard let self else { return }
+            let current = self.checkRunning()
+            if current != self.isRunning {
+                self.isRunning = current
+                self.updateMenu()
+            }
+        }
+    }
+
+    private func setupStatusItem() {
+        statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
+        if let button = statusItem.button {
+            if let image = NSImage(systemSymbolName: "bolt.fill", accessibilityDescription: "NanoClaw") {
+                image.isTemplate = true
+                button.image = image
+            } else {
+                button.title = "⚡"
+            }
+            button.toolTip = "NanoClaw"
+        }
+    }
+
+    private func checkRunning() -> Bool {
+        let task = Process()
+        task.launchPath = "/bin/launchctl"
+        task.arguments = ["list", "com.nanoclaw"]
+        let pipe = Pipe()
+        task.standardOutput = pipe
+        task.standardError = Pipe()
+        guard (try? task.run()) != nil else { return false }
+        task.waitUntilExit()
+        if task.terminationStatus != 0 { return false }
+        let output = String(data: pipe.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+        // launchctl list output: "PID\tExitCode\tLabel" — "-" means not running
+        let pid = output.trimmingCharacters(in: .whitespacesAndNewlines).components(separatedBy: "\t").first ?? "-"
+        return pid != "-"
+    }
+
+    private func updateMenu() {
+        let menu = NSMenu()
+
+        // Status row with colored dot
+        let statusItem = NSMenuItem()
+        let dot = "● "
+        let dotColor: NSColor = isRunning ? .systemGreen : .systemRed
+        let attr = NSMutableAttributedString(string: dot, attributes: [.foregroundColor: dotColor])
+        let label = isRunning ? "NanoClaw is running" : "NanoClaw is stopped"
+        attr.append(NSAttributedString(string: label, attributes: [.foregroundColor: NSColor.labelColor]))
+        statusItem.attributedTitle = attr
+        statusItem.isEnabled = false
+        menu.addItem(statusItem)
+
+        menu.addItem(NSMenuItem.separator())
+
+        if isRunning {
+            let stop = NSMenuItem(title: "Stop", action: #selector(stopService), keyEquivalent: "")
+            stop.target = self
+            menu.addItem(stop)
+
+            let restart = NSMenuItem(title: "Restart", action: #selector(restartService), keyEquivalent: "r")
+            restart.target = self
+            menu.addItem(restart)
+        } else {
+            let start = NSMenuItem(title: "Start", action: #selector(startService), keyEquivalent: "")
+            start.target = self
+            menu.addItem(start)
+        }
+
+        menu.addItem(NSMenuItem.separator())
+
+        let logs = NSMenuItem(title: "View Logs", action: #selector(viewLogs), keyEquivalent: "")
+        logs.target = self
+        menu.addItem(logs)
+
+        self.statusItem.menu = menu
+    }
+
+    @objc private func startService() {
+        run("/bin/launchctl", ["load", plistPath])
+        refresh(after: 2)
+    }
+
+    @objc private func stopService() {
+        run("/bin/launchctl", ["unload", plistPath])
+        refresh(after: 2)
+    }
+
+    @objc private func restartService() {
+        let uid = getuid()
+        run("/bin/launchctl", ["kickstart", "-k", "gui/\(uid)/com.nanoclaw"])
+        refresh(after: 3)
+    }
+
+    @objc private func viewLogs() {
+        let logPath = "\(StatusBarController.projectRoot)/logs/nanoclaw.log"
+        NSWorkspace.shared.open(URL(fileURLWithPath: logPath))
+    }
+
+    private func refresh(after seconds: Double) {
+        DispatchQueue.main.asyncAfter(deadline: .now() + seconds) { [weak self] in
+            guard let self else { return }
+            self.isRunning = self.checkRunning()
+            self.updateMenu()
+        }
+    }
+
+    @discardableResult
+    private func run(_ path: String, _ args: [String]) -> Int32 {
+        let task = Process()
+        task.launchPath = path
+        task.arguments = args
+        task.standardOutput = Pipe()
+        task.standardError = Pipe()
+        try? task.run()
+        task.waitUntilExit()
+        return task.terminationStatus
+    }
+}
+
+let app = NSApplication.shared
+app.setActivationPolicy(.accessory)
+let controller = StatusBarController()
+app.run()

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

@@ -0,0 +1,6 @@
+# Remove Matrix Channel
+
+1. Comment out `import './matrix.js'` in `src/channels/index.ts`
+2. Remove `MATRIX_BASE_URL`, `MATRIX_ACCESS_TOKEN`, `MATRIX_USER_ID`, `MATRIX_BOT_USERNAME` from `.env`
+3. `pnpm uninstall @beeper/chat-adapter-matrix`
+4. Rebuild and restart