pneuma-skills 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pandazki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# Pneuma Skills
+
+**Let Code Agents do WYSIWYG editing on HTML-based content.**
+
+> **"pneuma"** — Greek *pneuma*, meaning soul, breath, life force.
+
+Pneuma Skills is a framework that connects a Code Agent (like Claude Code) to a browser-based editor, giving users a real-time WYSIWYG experience for AI-assisted content editing. The agent edits files on disk; Pneuma watches for changes and streams a live preview to the browser alongside a chat interface.
+
+```
+Pneuma Skills = Content Mode x Code Agent Backend x Editor Shell
+```
+
+## Demo
+
+Currently ships with **Doc Mode** — a markdown editing environment where Claude Code edits `.md` files and you see the rendered result in real-time.
+
+```
+┌─────────────────────────────┬──────────────────────────┐
+│                             │  Chat with Claude Code   │
+│   Live Markdown Preview     │                          │
+│                             │  > Add a features section│
+│   # My Document             │                          │
+│   ## Features               │  [Thinking... 3s]        │
+│   - Real-time preview       │                          │
+│   - GFM support             │  ✎ Edit README.md        │
+│   - Image rendering         │  ✎ Write hero.png        │
+│                             │                          │
+├─────────────────────────────┴──────────────────────────┤
+│  ● Connected  session:abc123  $0.02  3 turns           │
+└────────────────────────────────────────────────────────┘
+```
+
+## Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`claude` command available in PATH)
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/pandazki/pneuma-skills.git
+cd pneuma-skills
+bun install
+
+# Start Doc Mode on a workspace directory
+bun bin/pneuma.ts doc --workspace ~/my-notes
+
+# Or use the current directory
+bun bin/pneuma.ts doc
+```
+
+This will:
+
+1. Install a skill prompt into `<workspace>/.claude/skills/`
+2. Start the Pneuma server (default port 17996)
+3. Spawn a Claude Code CLI session connected via WebSocket
+4. Open your browser with the editor UI
+
+## CLI Usage
+
+```
+pneuma <mode> [options]
+
+Modes:
+  doc    Markdown document editing mode
+
+Options:
+  --workspace <path>   Target workspace directory (default: current directory)
+  --port <number>      Server port (default: 17996)
+  --no-open            Don't auto-open the browser
+```
+
+## Architecture
+
+```
+Browser (React)                 Pneuma Server (Bun + Hono)              Claude Code CLI
+┌──────────────┐    JSON/WS     ┌─────────────────────┐    NDJSON/WS    ┌──────────────┐
+│ Chat Panel   │◄──────────────►│                     │◄───────────────►│              │
+│ Live Preview │                │   WebSocket Bridge  │                 │  claude      │
+│ Permissions  │                │   File Watcher      │                 │  --sdk-url   │
+│ Status Bar   │                │   Content Server    │                 │              │
+└──────────────┘                └─────────────────────┘                 └──────────────┘
+                                         │
+                                    watches disk
+                                         │
+                                   ┌─────────────┐
+                                   │  Workspace   │
+                                   │  *.md files  │
+                                   └─────────────┘
+```
+
+The server maintains dual WebSocket channels:
+- **Browser channel** (`/ws/browser/:sessionId`) — JSON messages for the React UI
+- **CLI channel** (`/ws/cli/:sessionId`) — NDJSON messages for Claude Code's `--sdk-url` protocol
+
+When Claude Code edits files, chokidar detects the changes and pushes updated content to the browser for live preview.
+
+## Project Structure
+
+```
+pneuma-skills/
+├── bin/pneuma.ts              # CLI entry point
+├── server/
+│   ├── index.ts               # Hono HTTP server + content API
+│   ├── ws-bridge.ts           # Dual WebSocket bridge (browser <-> CLI)
+│   ├── cli-launcher.ts        # Claude Code process spawner
+│   ├── file-watcher.ts        # chokidar-based file watcher
+│   └── skill-installer.ts     # Copies skill prompts to workspace
+├── src/
+│   ├── App.tsx                # Root layout (resizable panels)
+│   ├── main.tsx               # React entry
+│   ├── store.ts               # Zustand state management
+│   ├── ws.ts                  # Browser WebSocket client
+│   ├── types.ts               # Shared TypeScript types
+│   └── components/
+│       ├── ChatPanel.tsx      # Chat message feed
+│       ├── ChatInput.tsx      # Message input box
+│       ├── MarkdownPreview.tsx # Live markdown renderer
+│       ├── MessageBubble.tsx  # Rich message rendering (text, tools, thinking)
+│       ├── ToolBlock.tsx      # Expandable tool call cards
+│       ├── StreamingText.tsx  # Streaming response display
+│       ├── ActivityIndicator.tsx # Thinking/tool progress indicator
+│       ├── PermissionBanner.tsx  # Tool permission approval UI
+│       └── StatusBar.tsx      # Connection status + session info
+├── skill/
+│   └── doc/SKILL.md           # Doc Mode skill prompt for Claude Code
+├── docs/adr/                  # Architecture Decision Records
+└── draft.md                   # Full requirements document (Chinese)
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Runtime | [Bun](https://bun.sh) |
+| Server | [Hono](https://hono.dev) |
+| Frontend | React 19 + [Vite](https://vite.dev) 6 |
+| Styling | [Tailwind CSS](https://tailwindcss.com) 4 + Typography plugin |
+| State | [Zustand](https://zustand.docs.pmnd.rs) 5 |
+| Markdown | [react-markdown](https://github.com/remarkjs/react-markdown) + remark-gfm |
+| File Watching | [chokidar](https://github.com/paulmillr/chokidar) 4 |
+| Agent | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) via `--sdk-url` |
+
+## How It Works
+
+1. **Skill Installation** — Pneuma copies a mode-specific skill prompt (e.g. `skill/doc/SKILL.md`) into the workspace's `.claude/skills/` directory. Claude Code natively discovers and loads skills from this location.
+
+2. **Agent Spawning** — The CLI launcher spawns `claude --sdk-url ws://localhost:17007/ws/cli/<sessionId>` which connects Claude Code's streaming output to the Pneuma server.
+
+3. **Message Bridge** — The WebSocket bridge translates between the browser's JSON protocol and Claude Code's NDJSON protocol, handling message routing, permission flows, and event replay.
+
+4. **Live Preview** — When Claude Code writes or edits files, chokidar detects changes and pushes updated content to all connected browsers via WebSocket.
+
+5. **Rich Chat UI** — The browser renders Claude Code's full output: streaming text with markdown, expandable tool call cards, collapsible thinking blocks, and an activity indicator.
+
+## Content Mode System
+
+Pneuma is designed to be extensible with different content modes. Each mode defines:
+
+- **Renderer** — How to render the content in the browser
+- **Skill** — Domain-specific prompt for the Code Agent
+- **File Convention** — How content is organized on disk
+- **Navigator** — Structural navigation (outline, page list, etc.)
+
+Currently implemented: **Doc Mode** (markdown). Future modes could include slides, mindmaps, canvas, and more.
+
+## Roadmap
+
+- [x] Doc Mode MVP — Markdown WYSIWYG editing
+- [x] Element selection — Click to select and instruct edits on specific elements
+- [ ] Slide Mode — Presentation editing with page navigation
+- [ ] Session persistence — Resume previous editing sessions
+- [ ] Multiple agent backends — Codex CLI, custom agents
+- [ ] Production build — Single binary distribution
+
+## Acknowledgements
+
+This project's WebSocket bridge, NDJSON protocol handling, and chat UI rendering are heavily ~~inspired by~~ copied from [Companion](https://github.com/The-Vibe-Company/companion) by The Vibe Company. To be honest, the entire technical approach was basically Claude Code reading Companion's source code and reproducing it here. We stand on the shoulders of giants — or more accurately, we asked an AI to stand on their shoulders for us.
+
+Thank you Companion for figuring out the undocumented `--sdk-url` protocol so we didn't have to.
+
+## License
+
+[MIT](LICENSE)

package/bin/pneuma.ts

@@ -0,0 +1,202 @@
+#!/usr/bin/env bun
+/**
+ * Pneuma Skills CLI entry point.
+ *
+ * Usage:
+ *   pneuma doc --workspace /path/to/project [--port 17996] [--no-open]
+ */
+
+import { resolve, dirname, join } from "node:path";
+import { existsSync, copyFileSync, mkdirSync, readFileSync } from "node:fs";
+import * as readline from "node:readline";
+import { startServer } from "../server/index.js";
+import { CliLauncher } from "../server/cli-launcher.js";
+import { installSkill } from "../server/skill-installer.js";
+import { startFileWatcher } from "../server/file-watcher.js";
+
+const PROJECT_ROOT = resolve(dirname(import.meta.path), "..");
+
+function parseArgs(argv: string[]) {
+  const args = argv.slice(2); // skip bun + script path
+  let mode = "";
+  let workspace = process.cwd();
+  let port = 0; // 0 = auto-detect based on mode
+  let noOpen = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--workspace" && i + 1 < args.length) {
+      workspace = args[++i];
+    } else if (arg === "--port" && i + 1 < args.length) {
+      port = Number(args[++i]);
+    } else if (arg === "--no-open") {
+      noOpen = true;
+    } else if (!arg.startsWith("--")) {
+      mode = arg;
+    }
+  }
+
+  return { mode, workspace: resolve(workspace), port, noOpen };
+}
+
+function ask(question: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function main() {
+  const { mode, workspace, port, noOpen } = parseArgs(process.argv);
+
+  if (!mode || mode !== "doc") {
+    console.log("Usage: pneuma doc --workspace /path/to/project [--port 17996] [--no-open]");
+    process.exit(1);
+  }
+
+  if (!existsSync(workspace)) {
+    const answer = await ask(`Workspace does not exist: ${workspace}\nCreate it? [Y/n] `);
+    if (answer.toLowerCase() === "n") {
+      console.log("[pneuma] Aborted.");
+      process.exit(0);
+    }
+    mkdirSync(workspace, { recursive: true });
+    console.log(`[pneuma] Created workspace: ${workspace}`);
+  }
+
+  console.log(`[pneuma] Mode: ${mode}`);
+  console.log(`[pneuma] Workspace: ${workspace}`);
+
+  // 1. Install skill + inject CLAUDE.md
+  console.log("[pneuma] Installing skill and preparing environment...");
+  installSkill(workspace);
+
+  // 1.5 Seed default content if workspace has no meaningful markdown files
+  const contentFiles = Array.from(
+    new Bun.Glob("**/*.md").scanSync({ cwd: workspace, absolute: false })
+  ).filter((f) => f !== "CLAUDE.md" && !f.startsWith(".claude/"));
+
+  const hasContent = contentFiles.some((f) => {
+    try {
+      return readFileSync(join(workspace, f), "utf-8").trim().length > 0;
+    } catch { return false; }
+  });
+
+  if (!hasContent) {
+    const readmeSrc = join(PROJECT_ROOT, "README.md");
+    if (existsSync(readmeSrc)) {
+      copyFileSync(readmeSrc, join(workspace, "README.md"));
+      console.log("[pneuma] Seeded workspace with default README.md");
+    }
+  }
+
+  // 2. Detect dev vs production mode
+  const distDir = resolve(PROJECT_ROOT, "dist");
+  const isDev = !existsSync(join(distDir, "index.html"));
+
+  if (isDev) {
+    console.log("[pneuma] Development mode (serving via Vite)");
+  } else {
+    console.log("[pneuma] Production mode (serving built assets)");
+  }
+
+  // 3. Start server
+  //    Dev mode:  backend on 17007, Vite on 17996 (user-facing)
+  //    Prod mode: backend on 17996 (serves everything)
+  const serverPort = port || (isDev ? 17007 : 17996);
+  const { server, wsBridge, port: actualPort } = startServer({
+    port: serverPort,
+    workspace,
+    ...(isDev ? {} : { distDir }),
+  });
+
+  // 4. Launch CLI
+  const launcher = new CliLauncher(actualPort);
+
+  // When the CLI reports its internal session_id, store it
+  wsBridge.onCLISessionIdReceived((sessionId, cliSessionId) => {
+    launcher.setCLISessionId(sessionId, cliSessionId);
+  });
+
+  const session = launcher.launch({
+    cwd: workspace,
+    permissionMode: "bypassPermissions",
+  });
+
+  console.log(`[pneuma] CLI session started: ${session.sessionId}`);
+
+  // 5. Start file watcher
+  startFileWatcher(workspace, (files) => {
+    wsBridge.broadcastToSession(session.sessionId, {
+      type: "content_update",
+      files,
+    });
+  });
+
+  // 6. Frontend serving
+  let viteProc: ReturnType<typeof Bun.spawn> | null = null;
+  let browserPort = actualPort;
+
+  if (isDev) {
+    // Dev mode: start Vite dev server
+    const VITE_PORT = 17996;
+    console.log(`[pneuma] Starting Vite dev server on port ${VITE_PORT}...`);
+    viteProc = Bun.spawn(
+      ["bunx", "vite", "--port", String(VITE_PORT), "--strictPort"],
+      {
+        cwd: PROJECT_ROOT,
+        stdout: "pipe",
+        stderr: "pipe",
+      }
+    );
+
+    const pipeViteOutput = async (stream: ReadableStream<Uint8Array>) => {
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const text = decoder.decode(value, { stream: true });
+        for (const line of text.split("\n")) {
+          if (line.trim()) console.log(`[vite] ${line}`);
+        }
+      }
+    };
+    if (viteProc.stdout && typeof viteProc.stdout !== "number") pipeViteOutput(viteProc.stdout);
+    if (viteProc.stderr && typeof viteProc.stderr !== "number") pipeViteOutput(viteProc.stderr);
+    browserPort = VITE_PORT;
+    // Wait for Vite to start
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+
+  // 7. Open browser
+  if (!noOpen) {
+    const url = `http://localhost:${browserPort}?session=${session.sessionId}`;
+    console.log(`[pneuma] Opening browser: ${url}`);
+    try {
+      const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+      Bun.spawn([opener, url], { stdout: "ignore", stderr: "ignore" });
+    } catch {
+      console.log(`[pneuma] Could not open browser. Visit: ${url}`);
+    }
+  }
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    console.log("\n[pneuma] Shutting down...");
+    viteProc?.kill();
+    await launcher.killAll();
+    server.stop(true);
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+
+main().catch((err) => {
+  console.error("[pneuma] Fatal error:", err);
+  process.exit(1);
+});