reflexive 0.1.0

package/docs/HN-LAUNCH-PLAN.md

@@ -0,0 +1,492 @@
+# Hacker News Launch Strategy for Reflexive
+
+## Executive Summary
+
+Reflexive is positioned at the intersection of three HN-beloved categories: **developer tools**, **AI/LLM applications**, and **debugging/observability**. The core value proposition - "talk to your running app" - is novel enough to generate curiosity while solving real pain points developers face daily.
+
+Based on analysis of successful Show HN posts (particularly Claude-related tools which regularly hit 200-600+ points, and debugging tools averaging 100-150 points), Reflexive has strong potential for a successful launch.
+
+---
+
+## Title Options
+
+Ordered by predicted effectiveness based on HN patterns:
+
+### Top Recommendations
+
+1. **Show HN: Reflexive - Build apps by talking to them (Node.js + Claude Agent SDK)**
+   - Why: "Build apps by talking to them" is provocative and immediately understandable
+   - Pattern: Similar to successful "I built X that does Y" format
+
+2. **Show HN: An AI agent that lives inside your running Node.js app**
+   - Why: "Lives inside your running app" creates curiosity
+   - Pattern: Novel framing that invites clicks
+
+3. **Show HN: Chat with your Node.js app - see logs, set breakpoints, modify code**
+   - Why: Concrete features listed, clear value proposition
+   - Pattern: Feature-focused like successful dev tools
+
+### Alternative Titles
+
+4. **Show HN: I made an AI debugger that watches your app and responds to errors**
+   - Why: "Responds to errors" highlights unique watch trigger feature
+
+5. **Show HN: Reflexive - Talk to your running code, watch it respond**
+   - Why: Interactive, poetic
+
+6. **Show HN: Start with an empty file. Tell the AI what you want. Watch it build.**
+   - Why: Captures the "vibe coding" workflow perfectly
+
+7. **Show HN: What if your debugger could read your code and chat with you?**
+   - Why: Question format, invites curiosity
+
+8. **Show HN: npx reflexive app.js - now chat with your running app at localhost:3099**
+   - Why: Shows exact command, extremely concrete
+
+9. **Show HN: Claude Agent SDK + V8 debugger = AI that sets real breakpoints in your code**
+   - Why: Technical specificity appeals to HN audience
+
+10. **Show HN: Watch triggers - set a log pattern, AI automatically investigates when it appears**
+    - Why: Highlights unique feature that doesn't exist elsewhere
+
+---
+
+## The Hook
+
+### One-Liner (for post description)
+> Start with an empty file. Run it with Reflexive. Open the chat. Tell it what you want. Watch it build. This isn't monitoring - it's collaborative development with an AI that lives inside your running application.
+
+### The "Aha Moment"
+The moment of magic is when users realize they can:
+1. Run `npx reflexive --write app.js`
+2. Say "turn this into an Express server with a /users endpoint"
+3. Watch the file get rewritten AND the server restart automatically
+4. See the new endpoint working immediately
+
+**This is the moment to capture on video.** The feedback loop is instant - code changes, server restarts, you see the result. No switching between editor, terminal, and browser.
+
+### Pain Points Solved (for comment discussion)
+
+| Pain Point | How Reflexive Solves It |
+|------------|------------------------|
+| Context switching between logs, code, and debugger | One chat interface sees everything |
+| Setting up debugging for a quick script | Zero config: `npx reflexive app.js` |
+| "What's happening in my app right now?" | Real-time logs + AI that can explain them |
+| Repetitive debugging workflows | Watch triggers auto-respond to patterns |
+| Teaching a new developer the codebase | They can ask the AI which sees the running code |
+| Hot-reloading breaks inspector | Built-in watch mode preserves debug context |
+
+---
+
+## Optimal Posting Strategy
+
+### Best Times to Post
+
+Based on HN traffic patterns:
+
+| Priority | Day | Time (PT) | Time (ET) | Rationale |
+|----------|-----|-----------|-----------|-----------|
+| **Best** | Tuesday | 8-9 AM | 11 AM-12 PM | Peak HN activity, devs starting workday |
+| **Good** | Wednesday | 8-9 AM | 11 AM-12 PM | Mid-week engagement high |
+| **Good** | Monday | 9-10 AM | 12-1 PM | Monday ramp-up, avoid early conflicts |
+| Avoid | Friday afternoon | - | - | Weekend dropoff |
+| Avoid | Weekends | - | - | 30-40% less traffic |
+
+### Post Structure
+
+The Show HN post itself should include:
+
+```markdown
+Show HN: Reflexive - Build apps by talking to them (Node.js + Claude Agent SDK)
+
+https://github.com/[username]/reflexive
+
+Start with an empty file. Run it with Reflexive. Tell it what you want. Watch it build.
+
+  npx reflexive --write app.js
+  # Open http://localhost:3099
+  # Say: "Turn this into an Express server with a /users endpoint"
+
+The agent can see your code, see it running, edit files, and restart the process.
+You iterate by chatting. This isn't just monitoring - it's collaborative development
+with an AI that lives inside your running application.
+
+Key features:
+- Zero config: just npx and go
+- Real-time logs with ANSI color support
+- Watch triggers: set a log pattern, AI investigates automatically
+- V8 debugger integration with real breakpoints
+- Works with any Node.js app (CLI mode) or embed in your code (library mode)
+
+Built on the Claude Agent SDK. Two dependencies total.
+
+Demo video: [link]
+```
+
+### First Comment (Post Immediately After Submitting)
+
+```markdown
+Hey HN! I built Reflexive because I was tired of the context-switching tax during debugging.
+Open the logs, find the error, open the file, find the line, open the debugger, set the breakpoint...
+What if the debugger could just see everything and you could talk to it?
+
+The key insight is that an AI agent with access to:
+1. Your running process (stdout/stderr)
+2. Your source files
+3. Ability to edit and restart
+
+...becomes a surprisingly effective debugging partner.
+
+**Watch triggers** are my favorite feature - you set a log pattern like "Login FAILED"
+and a prompt like "investigate why authentication is failing", and when that pattern appears
+in the logs, the agent automatically investigates and responds.
+
+Some things I'd love feedback on:
+- Is the "edit files" capability too dangerous even behind a flag?
+- Would you use this in production with read-only mode?
+- What MCP tools would you add?
+
+Happy to answer any questions!
+```
+
+---
+
+## Demo Content Plan
+
+### 30-Second GIF (Primary Asset)
+
+**What to show:**
+
+Frame 1-5 (0-5s): Terminal showing:
+```bash
+echo "console.log('hello')" > app.js
+npx reflexive --write app.js
+```
+
+Frame 6-10 (5-10s): Browser opening to localhost:3099, showing the clean dashboard UI
+
+Frame 11-20 (10-20s): User typing in chat:
+> "Turn this into an Express server with a /users endpoint"
+
+Frame 21-28 (20-28s): Show the response streaming, see the file being edited (tool call badge showing), see "Process restarted" in logs
+
+Frame 29-30 (28-30s): Quick curl or browser showing `localhost:8080/users` returning JSON
+
+**Technical notes for recording:**
+- Use a dark terminal theme (matches HN aesthetic)
+- 1280x720 or 1920x1080
+- ~15 fps is fine for GIF
+- Use [asciinema](https://asciinema.org/) for terminal portion if desired
+- Tools: ScreenToGif (Windows), Kap (Mac), Peek (Linux)
+
+### 2-Minute Demo Video
+
+**Script/Outline:**
+
+```
+[0:00-0:10] Hook
+"What if you could build an app just by talking to it? Not generating code
+in a separate window - actually watching it run and evolve in real time."
+
+[0:10-0:30] The Setup
+- Show empty directory
+- "All you need is npx reflexive"
+- Run: echo "console.log('hello')" > app.js
+- Run: npx reflexive --write --open app.js
+- Browser auto-opens to dashboard
+
+[0:30-0:50] The Magic Moment
+- Type: "Turn this into an Express server with a /users endpoint that
+  returns a list of users from a mock array"
+- Show response streaming
+- Show tool calls appearing (read_file, write_file, restart_process)
+- Point out the logs updating in real-time
+
+[0:50-1:10] See It Working
+- Curl localhost:8080/users - it works!
+- Type: "Add a POST endpoint to create users"
+- Quick cut to it working
+
+[1:10-1:30] Watch Triggers Feature
+- "But here's my favorite feature - watch triggers"
+- Show an app with occasional errors in logs
+- Click the watch icon on an error log
+- Set pattern: "ERROR"
+- Set prompt: "Investigate what's causing this error and suggest a fix"
+- Show error appearing, AI automatically responding
+
+[1:30-1:50] Breakpoints Demo (Optional)
+- "You can even set breakpoints"
+- Show breakpoint being hit
+- Show AI inspecting state at breakpoint
+- Resume execution
+
+[1:50-2:00] Closing
+"Reflexive. Build apps by talking to them. Try it: npx reflexive --write app.js"
+Show GitHub link
+```
+
+**Recording tips:**
+- Use [OBS Studio](https://obsproject.com/) (free, cross-platform)
+- 1080p minimum, 4K preferred for clarity
+- Record in quiet environment or add music/voiceover later
+- Keep it FAST - no unnecessary pauses
+- Consider adding subtle zoom on important areas
+
+### Screenshots
+
+Capture these specific screens:
+
+1. **Hero Shot: Dashboard Overview**
+   - Full browser window showing logs on left, chat on right
+   - Include a few colorful log entries
+   - Show an AI response with tool call badges
+
+2. **Watch Trigger Setup**
+   - The watch trigger modal/dialog
+   - Pattern field filled with "Login FAILED"
+   - Prompt field with "Investigate authentication failure"
+
+3. **Tool Call Styling**
+   - Close-up of a chat response showing styled tool calls
+   - Blue badges with tool names, gray parameters
+
+4. **Breakpoint State**
+   - Dashboard showing "PAUSED AT BREAKPOINT" indicator
+   - Context variables visible
+   - Chat showing AI inspecting the state
+
+5. **Empty to Working App**
+   - Before/after split: empty file -> working Express server
+   - Highlight the ~20 seconds elapsed
+
+---
+
+## Landing Experience
+
+### README Priorities
+
+The README should be **scannable in 10 seconds**. Current README is good but could be tighter at the top:
+
+**Above the fold must include:**
+1. One-liner: "Build applications by talking to them."
+2. The 3-line quickstart: `echo ... && npx reflexive --write app.js && open localhost:3099`
+3. A GIF showing the core workflow
+
+**Reorganization suggestions:**
+- Move the ASCII art or add a hero image/GIF
+- "Installation" should just be `npm install reflexive` or `npx reflexive`
+- Move detailed CLI options and Library Mode API lower
+- Add a "30-second quickstart" section
+
+### Quick Start That Works in Under 1 Minute
+
+Create a dedicated `QUICKSTART.md` or README section:
+
+```markdown
+## 30-Second Quickstart
+
+1. Create a simple app:
+   ```bash
+   echo "console.log('hello world')" > app.js
+   ```
+
+2. Run with Reflexive:
+   ```bash
+   npx reflexive --write --open app.js
+   ```
+
+3. In the chat, say:
+   > Turn this into an Express server with a /users endpoint
+
+4. Watch it build. Curl `localhost:8080/users`. Done.
+
+**Requires:** Node.js 18+, Claude Code CLI (`npm install -g @anthropic-ai/claude-code && claude`)
+or ANTHROPIC_API_KEY environment variable.
+```
+
+---
+
+## Engagement Strategy
+
+### How to Respond to Comments
+
+**General principles:**
+- Respond within 10 minutes during first 2 hours (critical for ranking)
+- Be genuinely helpful, not defensive
+- Acknowledge good criticism with "that's fair" or "you're right"
+- Keep responses concise but substantive
+- Upvote good questions (don't upvote your own comments)
+
+**Response templates:**
+
+For feature requests:
+> Good idea! I've been thinking about [X] too. Right now you can work around it by [Y],
+> but native support would be cleaner. Added to the roadmap.
+
+For security concerns:
+> Totally valid concern. That's why [capability] is behind the --[flag] flag and off by default.
+> In read-only mode (no flags), the agent can only see logs and read files - can't modify anything.
+
+For "why not just use X?" comparisons:
+> [X] is great for [use case]! Reflexive is more about [differentiator].
+> The key difference is [specific capability]. That said, they could complement each other.
+
+For implementation questions:
+> Under the hood, [brief technical explanation]. The source is ~1500 lines in a single file
+> if you want to dig in: [link to reflexive.js]
+
+### Common Questions to Prepare For
+
+| Question | Prepared Answer |
+|----------|----------------|
+| "Does this work with Python/Go/Rust?" | "CLI mode monitors any Node.js app. Python is on the roadmap - the Claude Agent SDK supports it natively. Other languages would need a shim/sidecar approach." |
+| "How is this different from Cursor/Windsurf?" | "Those are editor-based. Reflexive lives inside your running process - it sees actual logs, sets real breakpoints, and can react to runtime events. The watch trigger feature is unique: AI auto-responds to log patterns." |
+| "Isn't letting AI edit files dangerous?" | "Absolutely, which is why --write is opt-in and off by default. For exploring or debugging someone else's code, read-only mode is great. For greenfield development, --write lets you iterate by chatting." |
+| "Will this work in production?" | "I'd recommend read-only mode for production debugging. The --write and --shell flags are explicitly for development. Production safety flags are on the roadmap." |
+| "What about cost/API limits?" | "Uses Claude through Claude Code CLI (if installed) or direct API key. The agent is pretty efficient - typical session is a few hundred thousand tokens. Watch triggers only fire on pattern match, not continuously." |
+| "Why not use MCP directly?" | "Reflexive is built on MCP! It exposes your running app as MCP tools. You could theoretically connect any MCP client to it." |
+| "Single file? Why?" | "Intentional constraint. No build step, direct execution, easy to fork and modify. The whole thing is ~1500 lines - you can read it in an afternoon." |
+
+### Potential Criticisms and Responses
+
+| Criticism | Response |
+|-----------|----------|
+| "This is just a wrapper around Claude" | "Fair - the AI capabilities come from Claude. The value is the integration: process management, log capture, file watching, watch triggers, and the dashboard UI. It's infrastructure for conversational development." |
+| "Security nightmare" | "I hear you. Dangerous capabilities are behind explicit flags (--write, --shell, --eval). Default mode is read-only. For production, there's a roadmap item for capability restrictions by NODE_ENV." |
+| "Why would I use this over print debugging?" | "You wouldn't replace print debugging - you'd augment it. The AI can see those prints, correlate them with source code, and help you interpret what's happening. Watch triggers take it further: auto-respond when patterns appear." |
+| "Just use a real debugger" | "Real debuggers are great but have friction: attach, set breakpoint, hit it, inspect. Reflexive gives you a conversational interface that happens to have debugger access. Ask 'what's the value of user at line 42?' and it figures out how." |
+| "Vendor lock-in to Anthropic" | "Currently yes - built on Claude Agent SDK. The MCP tools pattern would work with other providers. There's a community fork adding multi-provider support." |
+
+---
+
+## Pre-Launch Checklist
+
+### Technical Preparation
+
+**1. Demo Must Work Flawlessly**
+- [ ] Test `npx reflexive --write app.js` from clean directory
+- [ ] Test the exact commands shown in README
+- [ ] Test on Node.js 18, 20, and 22
+- [ ] Test with both Claude CLI auth and API key auth
+- [ ] Verify dashboard works in Chrome, Firefox, Safari
+- [ ] Test watch triggers end-to-end
+- [ ] Run `npm run demo` and verify all demos work
+
+**2. Repository Ready**
+- [ ] Clean up any WIP files
+- [ ] Ensure package.json has correct metadata
+- [ ] Add relevant keywords for npm search
+- [ ] Verify license file exists
+- [ ] Remove any sensitive data from git history
+- [ ] Tag release (e.g., v0.1.0)
+- [ ] Publish to npm if not already
+
+**3. GitHub Presentation**
+- [ ] Add topics: `ai`, `claude`, `debugging`, `nodejs`, `developer-tools`, `mcp`, `claude-agent-sdk`
+- [ ] Write compelling "About" description
+- [ ] Add social preview image (1280x640)
+- [ ] Enable Discussions tab for post-launch community
+
+### Content Preparation
+
+**1. Assets Ready**
+- [ ] 30-second GIF created and uploaded (to GitHub or Imgur)
+- [ ] 2-minute demo video created and uploaded (YouTube unlisted or public)
+- [ ] Key screenshots captured
+- [ ] All assets linked in README
+
+**2. Written Content**
+- [ ] Final title chosen from options above
+- [ ] Show HN post text finalized
+- [ ] First comment drafted
+- [ ] FAQ responses practiced
+- [ ] Quickstart section verified
+
+**3. Launch Logistics**
+- [ ] Calendar invite for posting time (8-9 AM PT, Tuesday or Wednesday)
+- [ ] Block 2-3 hours after posting for active engagement
+- [ ] Have HN account ready (karma helps with initial visibility)
+- [ ] Prepare backup device in case of issues
+
+### Timing Recommendations
+
+**The Day Before:**
+- Do a final test of all demos
+- Re-read this document
+- Get good sleep
+
+**Launch Day:**
+- Post at target time
+- Immediately add first comment
+- Stay active for first 2 hours minimum
+- Respond to every comment within 10 minutes
+- Do NOT ask friends to upvote (HN detects and penalizes this)
+
+**Week After:**
+- Monitor for follow-up questions
+- Collect feedback for v0.2.0
+- Write a "What I learned from the launch" post if it goes well
+
+---
+
+## Success Metrics
+
+| Metric | Good | Great | Exceptional |
+|--------|------|-------|-------------|
+| Points | 50+ | 150+ | 300+ |
+| Comments | 30+ | 75+ | 150+ |
+| GitHub stars (first week) | 100+ | 500+ | 1000+ |
+| npm downloads (first week) | 200+ | 1000+ | 5000+ |
+
+Based on comparable launches:
+- MCP servers average 100-250 points
+- Claude-related tools average 175-400 points
+- Novel dev tools average 75-200 points
+
+Reflexive combines all three categories, so 200+ points is a reasonable target.
+
+---
+
+## Post-Launch Actions
+
+**If it hits front page:**
+- Consider writing a technical blog post diving into architecture
+- Prepare for GitHub issues (bug reports, feature requests)
+- Have a CONTRIBUTING.md ready for contributors
+- Consider setting up a Discord or GitHub Discussions
+
+**Regardless of outcome:**
+- Collect all feedback into issues
+- Note which features resonated most
+- Plan v0.2.0 based on real user input
+- Thank everyone who commented
+
+---
+
+## Appendix: Reference Materials
+
+### Successful Similar Launches (for inspiration)
+
+| Title | Points | Key Takeaway |
+|-------|--------|--------------|
+| Browser MCP - Automate browser using Cursor, Claude, VS Code | 616 | MCP + popular tools = high engagement |
+| I used Claude Code to discover connections between 100 books | 524 | Novel application + impressive output |
+| Plandex - AI coding engine for complex tasks | 304 | Clear problem, clear solution |
+| Time travel debugging AI for more reliable vibe coding | 129 | "Vibe coding" framing resonates |
+| MCP server so Cursor can debug Node.js on its own | 139 | Debugging + AI + specific tool combo |
+
+### What NOT to Do
+
+- Don't use clickbait ("You won't believe...")
+- Don't exaggerate capabilities
+- Don't be defensive in comments
+- Don't ask for upvotes anywhere
+- Don't post and disappear - engagement matters
+- Don't launch on Friday or weekend
+- Don't launch same day as major tech news
+
+---
+
+*Last updated: January 2026*
+*Target launch window: Q1 2026*

package/docs/TODO.md

@@ -0,0 +1,69 @@
+# Reflexive TODO
+
+## Claude Agent SDK Features to Add
+
+### High Priority
+
+- [ ] **V8 Inspector Integration** - Replace pattern-based breakpoints with real debugger
+  - Start target with `--inspect-brk=0` to pause on first line
+  - Connect via WebSocket to CDP endpoint
+  - Use `Debugger.setBreakpointByUrl` for line-level breakpoints
+  - Handle `Debugger.paused` events for call stack / scope inspection
+  - Add MCP tools: `set_breakpoint`, `remove_breakpoint`, `debug_resume`, `step_over/into/out`, `evaluate`
+  - See `docs/V8-INSPECTOR-RESEARCH.md` for implementation details
+
+- [ ] **Plugins with Lifecycle Hooks** - Intercept tool calls, add automatic logging, modify behavior
+  ```javascript
+  plugins: [{
+    onToolCall: async (tool, input) => { /* log all tool usage */ }
+  }]
+  ```
+
+- [ ] **Session Management (v2 API)** - Persist chat history across restarts
+  ```javascript
+  unstable_v2_createSession()
+  unstable_v2_resumeSession(sessionId)
+  ```
+
+- [ ] **Granular Permission Control** - Dynamic permissions based on app state
+  ```javascript
+  canUseTool: async (tool, input) => { /* custom logic */ }
+  ```
+
+### Medium Priority
+
+- [ ] **Subagents / Orchestration** - Specialized sub-agents for different tasks
+  ```javascript
+  agents: {
+    'debugger': { description: '...', tools: [...] },
+    'code-reviewer': { description: '...', tools: [...] }
+  }
+  ```
+
+- [ ] **Tool Restrictions** - Allowlist/blocklist for tools per session
+  ```javascript
+  tools: ['read_file', 'search_logs'],
+  disallowedTools: ['shell_command']
+  ```
+
+- [ ] **Budget Limits** - Cap spending per query
+  ```javascript
+  maxBudgetUsd: 0.50
+  ```
+
+### Low Priority
+
+- [ ] **Session Forking** - Branch conversations for exploration
+  ```javascript
+  forkSession: true
+  ```
+
+- [ ] **Permission Modes** - Pre-configured permission levels
+  - `acceptEdits` - auto-accept file edits
+  - `bypassPermissions` - skip all prompts
+
+## Other Features
+
+- [ ] Multi-session support with tabs (detect existing server, add session)
+- [ ] Chat history persistence to disk
+- [ ] Export conversation as markdown