reflexive 0.1.0

package/CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Reflexive is an AI-powered introspection framework for Node.js applications using the Claude Agent SDK. It enables building applications by talking to them — an AI agent that lives inside your running application and can see logs, read source files, and modify code through chat conversation.
+
+## Commands
+
+```bash
+npm run demo          # Run self-instrumenting demo (library mode)
+npm run demo:app      # Run CLI mode monitoring demo-app.js
+```
+
+There is no build step, test suite, or linter configured. The project runs directly as ES modules with Node.js >= 18.
+
+## Architecture
+
+### Two Operating Modes
+
+**Library Mode** — Embed the agent inside your app:
+```javascript
+import { makeReflexive } from 'reflexive';
+const r = makeReflexive({ port: 3099, title: 'My App' });
+r.setState('key', value);  // Expose state to agent
+```
+
+**CLI Mode** — Monitor any Node.js app from outside:
+```bash
+reflexive [options] <script.js> [-- app-args]
+```
+
+### Single-File Implementation
+
+All functionality lives in `src/reflexive.js` (~1,500 lines). This monolithic design is intentional — no build step, direct execution. Key components within:
+
+- **AppState class** — Circular log buffer (500 entries), custom key-value state, event emitter
+- **ProcessManager class** — Child process spawning, stdout/stderr capture, restart logic, file watching
+- **MCP Server** — Tool definitions using Zod schemas for agent capabilities
+- **Dashboard HTML generator** — Self-contained SPA with chat interface and log viewer
+- **Chat streaming** — SSE-based real-time responses via Claude Agent SDK
+
+### Dashboard Server
+
+Runs on port 3099 by default. Routes:
+- `/reflexive` — Web dashboard UI
+- `/reflexive/chat` — POST, SSE stream for chat
+- `/reflexive/status` — GET, JSON status
+- `/reflexive/logs` — GET, JSON logs with filtering
+
+### MCP Tools Pattern
+
+Agent capabilities are exposed as MCP tools with Zod-validated parameters:
+- Library mode: `get_app_status`, `get_logs`, `search_logs`, `get_custom_state`
+- CLI mode: `get_process_state`, `get_output_logs`, `restart_process`, `stop_process`, `start_process`, `send_input`, `search_logs`
+
+Additional tools can be registered via the `tools` option when calling `makeReflexive()`.
+
+### CLI Capability Flags
+
+Dangerous operations are gated behind flags:
+- `--write` — Allow file modifications
+- `--shell` — Allow shell command execution
+- `--watch` — Hot-reload on file changes
+
+## Dependencies
+
+Only two runtime dependencies:
+- `@anthropic-ai/claude-agent-sdk` — Claude AI integration
+- `zod` — Parameter validation for MCP tools
+
+## Authentication
+
+Requires Claude API access via either:
+1. Claude Code CLI authentication (recommended)
+2. `ANTHROPIC_API_KEY` environment variable

package/FAILURES.md

@@ -0,0 +1,245 @@
+# Troubleshooting Reflexive
+
+## Quick Diagnosis
+
+If something breaks, run this and paste the output when reporting:
+
+```bash
+node --version
+npm --version
+npx reflexive --help
+echo $ANTHROPIC_API_KEY | head -c 10
+```
+
+## Common Failures
+
+### "Authentication failed" or "Invalid API key"
+
+**Symptom:** Agent won't respond, error about API key
+
+**Fix:**
+```bash
+# Option 1: Use Claude Code CLI auth (recommended)
+npm install -g @anthropic-ai/claude-code
+claude  # Follow login prompts
+
+# Option 2: Set API key directly
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**Check:** The Claude Code CLI stores credentials that Reflexive can use automatically. If you've logged in with `claude` before, it should just work.
+
+---
+
+### "Cannot find module 'reflexive'"
+
+**Symptom:** Import fails or npx doesn't work
+
+**Fix:**
+```bash
+# If using npx, try clearing cache
+npx clear-npx-cache
+npx reflexive ./app.js
+
+# If using as dependency
+npm install reflexive
+```
+
+---
+
+### Dashboard loads but chat doesn't work
+
+**Symptom:** You see the UI at localhost:3099 but messages don't get responses
+
+**Causes:**
+1. No authentication (see above)
+2. Claude API is down
+3. Network/proxy blocking requests
+
+**Debug:**
+```bash
+# Check if you can reach Claude API
+curl https://api.anthropic.com/v1/messages \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "content-type: application/json" \
+  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
+```
+
+---
+
+### Process starts but agent can't see output
+
+**Symptom:** Your app runs, but agent says "no logs" or can't see stdout
+
+**Causes:**
+1. App uses a logging library that doesn't write to stdout
+2. Output is buffered
+
+**Fix:**
+```bash
+# Force unbuffered output
+NODE_OPTIONS="--no-warnings" npx reflexive ./app.js
+
+# Or in your app
+process.stdout.write('message\n');  # Instead of console.log
+```
+
+---
+
+### "--debug doesn't work" / Breakpoints don't hit
+
+**Symptom:** You set breakpoints but they never trigger
+
+**Causes:**
+1. Code path not executed
+2. Source maps issue
+3. Node version < 18
+
+**Check:**
+```bash
+# Verify Node version
+node --version  # Should be >= 18
+
+# Try with explicit debug port
+npx reflexive --debug --node-args="--inspect=9229" ./app.js
+```
+
+---
+
+### "--inject causes app to crash"
+
+**Symptom:** App crashes or behaves differently with --inject
+
+**Causes:**
+1. Conflict with existing instrumentation (APM tools, etc)
+2. App uses non-standard module loading
+
+**Fix:**
+```bash
+# Try without injection first
+npx reflexive ./app.js
+
+# If that works, injection has a conflict
+# Report the error message
+```
+
+---
+
+### "--eval returns undefined for everything"
+
+**Symptom:** `evaluate_in_app` always returns undefined
+
+**Causes:**
+1. Variable is out of scope
+2. Async timing issue
+3. Code threw but error was swallowed
+
+**Debug:**
+```javascript
+// Try wrapping in try/catch
+evaluate_in_app({ code: "try { yourVar } catch(e) { e.message }" })
+```
+
+---
+
+### "Port 3099 already in use"
+
+**Symptom:** Dashboard won't start
+
+**Fix:**
+```bash
+# Use different port
+npx reflexive --port 4000 ./app.js
+
+# Or kill the existing process
+lsof -i :3099
+kill -9 <PID>
+```
+
+---
+
+### File writes fail even with --write
+
+**Symptom:** Agent says it can't write files
+
+**Causes:**
+1. File permissions
+2. Path is outside working directory
+3. File is locked
+
+**Check:**
+```bash
+# Verify working directory
+pwd
+ls -la ./your-file.js
+```
+
+---
+
+### Shell commands fail even with --shell
+
+**Symptom:** Agent can't run shell commands
+
+**Causes:**
+1. Command not in PATH
+2. Permissions issue
+3. Shell not available
+
+**Debug:**
+```bash
+# Check what shell is available
+echo $SHELL
+which bash
+```
+
+---
+
+## Known Issues
+
+### Interactive mode (-i) with certain CLI tools
+
+Some CLI tools that do complex terminal manipulation (curses, raw mode) may not work well with interactive mode. Stick to simple stdin/stdout tools.
+
+### Watch mode (-w) high CPU on large directories
+
+If watching a directory with many files (node_modules), CPU may spike. Use .gitignore patterns or run from a subdirectory.
+
+### V8 debugger with worker threads
+
+Breakpoints in worker threads may not work correctly. Main thread debugging works fine.
+
+---
+
+## Reporting Bugs
+
+Include this information:
+
+1. **Command you ran:**
+   ```bash
+   npx reflexive --write --debug ./my-app.js
+   ```
+
+2. **Node and npm versions:**
+   ```bash
+   node --version && npm --version
+   ```
+
+3. **OS:**
+   ```bash
+   uname -a  # or Windows version
+   ```
+
+4. **Error message:** Full stack trace if available
+
+5. **Minimal reproduction:** Smallest app.js that shows the problem
+
+Open an issue at: https://github.com/anthropics/reflexive/issues
+
+---
+
+## Getting Help
+
+- Check the [README](./README.md) for usage examples
+- Search existing issues before opening a new one
+- For Claude API issues, check https://status.anthropic.com

package/README.md

@@ -0,0 +1,264 @@
+# Reflexive
+
+[VIDEO: demo.gif]
+
+Embed Claude inside your running Node.js app. It sees logs, reads source, edits files, sets breakpoints, and responds to runtime events.
+
+## Quickstart
+
+```bash
+echo "console.log('hello')" > app.js
+npx reflexive --write app.js
+# Open http://localhost:3099
+# Say: "Turn this into an Express server with a /users endpoint"
+```
+
+## What This Is
+
+Claude Agent SDK (Claude Code as a library) + your running Node.js process = an agent that:
+
+- **Agent loop** - keeps working until done, tool calls, retries, reasoning
+- **Process lifecycle** - start, stop, restart, watch for file changes
+- **V8 debugger** - real breakpoints, stepping, scope inspection via Inspector protocol
+- **Watch triggers** - pattern-match logs and auto-prompt the agent
+- **File read/write + shell** - behind explicit flags
+
+```
++---------------------------------------------------------+
+|  reflexive CLI                                          |
+|  - Dashboard server (chat UI + logs)                    |
+|  - Claude Agent SDK with MCP tools                      |
+|  - Process control, file ops, shell                     |
+|                                                         |
+|  +---------------------------------------------------+  |
+|  |  your-app.js (child process)                      |  |
+|  |  - stdout/stderr captured                         |  |
+|  |  - Optional: deep instrumentation via --inject    |  |
+|  +---------------------------------------------------+  |
++---------------------------------------------------------+
+```
+
+## Safety Model
+
+**Default is read-only.** No flags = agent can see logs, read files, ask questions. Cannot modify anything.
+
+Capabilities require explicit opt-in:
+
+| Flag | Enables |
+|------|---------|
+| `--write` | File modification |
+| `--shell` | Shell command execution |
+| `--inject` | Deep instrumentation (console intercept, diagnostics, perf metrics) |
+| `--eval` | Runtime code evaluation (implies --inject) |
+| `--debug` | V8 Inspector debugging (breakpoints, stepping, scope inspection) |
+
+This is a development tool. For production, use read-only mode.
+
+## Authentication
+
+Choose one:
+
+```bash
+# Option 1: Claude Code CLI (recommended)
+npm install -g @anthropic-ai/claude-code
+claude  # Login once
+
+# Option 2: API key
+export ANTHROPIC_API_KEY=your-key
+```
+
+---
+
+## CLI Reference
+
+```bash
+reflexive [options] [entry-file] [-- app-args...]
+```
+
+### Options
+
+```
+-p, --port <port>       Dashboard port (default: 3099)
+-h, --host <host>       Dashboard host (default: localhost)
+-o, --open              Open dashboard in browser
+-w, --watch             Restart on file changes
+-i, --interactive       Proxy stdin/stdout for CLI apps
+    --inject            Deep instrumentation
+    --eval              Runtime eval (DANGEROUS)
+-d, --debug             V8 Inspector debugging
+    --write             Enable file writing
+    --shell             Enable shell access
+    --dangerously-skip-permissions  Enable everything
+    --node-args <args>  Pass args to Node.js
+```
+
+### Examples
+
+```bash
+# Basic - read-only monitoring
+npx reflexive ./server.js
+
+# Development - full control
+npx reflexive --write --shell --watch ./server.js
+
+# Debugging - set breakpoints, step through code
+npx reflexive --debug ./server.js
+
+# Deep instrumentation - GC stats, event loop, HTTP tracking
+npx reflexive --inject ./server.js
+
+# Pass args to your app
+npx reflexive ./server.js -- --port 8080
+```
+
+## Library Mode
+
+Embed the agent inside your app for deeper introspection:
+
+```javascript
+import { makeReflexive } from 'reflexive';
+
+const r = makeReflexive({
+  port: 3099,
+  title: 'My App',
+  tools: []  // Add custom MCP tools
+});
+
+// Console output captured automatically
+console.log('Server started');
+
+// Expose custom state the agent can query
+r.setState('activeUsers', 42);
+r.setState('cache.hitRate', 0.95);
+
+// Programmatic chat
+const answer = await r.chat("What's the memory usage?");
+```
+
+### Custom Tools
+
+```javascript
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+const r = makeReflexive({
+  tools: [
+    tool(
+      'get_order',
+      'Look up order by ID',
+      { orderId: z.string() },
+      async ({ orderId }) => ({
+        content: [{ type: 'text', text: JSON.stringify(orders.get(orderId)) }]
+      })
+    )
+  ]
+});
+```
+
+## V8 Debugger
+
+With `--debug`, the agent can set real breakpoints:
+
+```
+You: "Set a breakpoint on line 42 of server.js"
+Agent: [set_v8_breakpoint: file="server.js", line=42]
+       Breakpoint set.
+
+... request comes in ...
+
+Agent: Breakpoint hit at server.js:42
+
+       Call Stack:
+       - handleRequest (server.js:42)
+       - processMiddleware (middleware.js:18)
+
+       Local Variables:
+       - req: { method: "POST", url: "/api/users" }
+       - user: { id: 123, name: "Alice" }
+
+You: "What's in user.permissions?"
+Agent: [evaluate_at_breakpoint: "user.permissions"]
+       ["read", "write", "admin"]
+
+You: "Step into the next function"
+Agent: [debugger_step_into]
+       Stepped to validateUser (auth.js:55)
+```
+
+## Watch Triggers
+
+Click the eye icon on any log entry to create a watch. When that pattern appears again, the agent is automatically prompted.
+
+Use cases:
+- "When you see 'Error:', investigate and suggest a fix"
+- "When 'user signed up' appears, summarize the signup"
+- "When memory exceeds 500MB, analyze what's using it"
+
+## Injection Mode
+
+With `--inject`, your app gets automatic instrumentation without code changes:
+
+| What's Captured | Source |
+|-----------------|--------|
+| Console methods | log, info, warn, error, debug |
+| HTTP requests | Incoming and outgoing via diagnostics_channel |
+| GC events | Duration and type |
+| Event loop | Latency histogram (p50, p99) |
+| Uncaught errors | With stack traces |
+
+Your app can optionally use the injected API:
+
+```javascript
+if (process.reflexive) {
+  process.reflexive.setState('db.connections', pool.size);
+  process.reflexive.emit('userSignup', { userId: 123 });
+}
+```
+
+## Runtime Eval
+
+With `--eval`, the agent can execute code in your running app:
+
+```
+You: "What's in the config object?"
+Agent: [evaluate_in_app: code="config"]
+       { port: 3000, debug: true }
+
+You: "Clear the cache"
+Agent: [evaluate_in_app: code="cache.clear()"]
+       undefined
+```
+
+**Warning:** `--eval` allows arbitrary code execution. Development only.
+
+## Dashboard
+
+The web UI at `http://localhost:3099` provides:
+
+- Real-time chat with the agent
+- Live logs with ANSI color support
+- Process controls (stop/restart)
+- Watch pattern management
+- Breakpoint controls (with --debug)
+
+## Demos
+
+```bash
+npm run demo          # Library mode - task queue
+npm run demo:app      # CLI mode - HTTP server
+npm run demo:inject   # Deep instrumentation
+npm run demo:eval     # Runtime eval
+npm run demo:ai       # AI-powered endpoints
+```
+
+---
+
+## Links
+
+- Built on [Claude Agent SDK](https://docs.anthropic.com/en/docs/claude-code/agent-sdk) (Claude Code as a library)
+- ~1500 lines, single file, no build step
+- [Troubleshooting](./FAILURES.md)
+
+## License
+
+MIT