Docs/claude code integration

doc/dev/2026-02-24-echokit-remote-control-claude-code.md

@@ -0,0 +1,198 @@
+---
+slug: echokit-remote-control-claude-code
+title: "My Coding Assistant Lives in a Box Now | EchoKit"
+tags: [echokit, claude-code, remote-control, voice-ai]
+---
+
+It was 2 AM. I was deep in a coding session, fingers flying across the keyboard, completely in the zone. Then I hit a bug. I needed to run the tests.
+
+Which meant breaking my flow. Switching windows. Typing the command. Waiting. Switching back.
+
+I thought: *What if I could just say it?*
+
+**Not into my phone.** Not unlocking an app. Just speak—to a device sitting on my desk.
+
+## A Small Device, Big Idea
+
+That moment sparked an experiment. What if my AI coding assistant wasn't trapped in a terminal window, but lived in a small device on my desk? What if I could speak to it like a pair programmer sitting next to me?
+
+Not voice typing—I hate that. But voice *commands*. Like having a junior developer who actually does things, not just suggests them.
+
+So I built it.
+
+Today, I'm excited to share how EchoKit became a voice remote control for Claude Code. And why this changes everything about how I work.
+
+## It Started with a Problem
+
+Claude Code is amazing. It writes code, fixes bugs, runs tests, explains errors.
+
+**Yes, Claude Code now has an official Remote Control feature for mobile and web access.** But it's designed for phones and browsers—not for hands-free voice control or physical devices. You still need to look at a screen and tap buttons.
+
+I wanted something different. Something that felt like... magic.
+
+## The Missing Piece
+
+I had EchoKit—my open-source voice AI device sitting on my desk. It can hear me, think, and respond. But it couldn't control my code editor.
+
+I needed a bridge.
+
+That bridge is called [echokit_pty](https://github.com/second-state/echokit_pty).
+
+**What is echokit_pty?** It's the web version of Claude Code, but with a superpower: a WebSocket interface.
+
+See, Claude Code was designed as a CLI tool. You run it in your terminal, type commands, get responses. That's great for terminal workflows. But for voice control? For remote access? For building *anything* on top of Claude Code?
+
+You need something more.
+
+echokit_pty is that "more."
+
+## How echokit_pty Changed Everything
+
+Here's what echokit_pty does: it takes Claude Code and exposes it through a WebSocket server. Suddenly, Claude Code isn't just a terminal app—it's a service that *anything* can talk to.
+
+My EchoKit device can send commands. A web app could send commands. A mobile app. A game controller. Anything that speaks WebSocket.
+
+But here's the beautiful part: it's still Claude Code. All the capabilities, all the intelligence, everything that makes Claude Code amazing—just accessible through a clean, simple interface.
+
+## The Setup: Three Pieces, One Experience
+
+Now my coding setup looks like this:
+
+**1. echokit_pty runs on my machine** — Starts a WebSocket server (ws://localhost:3000/ws)
+
+**2. EchoKit Server connects to it** — Handles speech recognition and text-to-speech
+
+**3. EchoKit Device sits on my desk** — Listens for my voice, speaks back responses
+
+```
+My Voice: "Run the tests"
+    ↓
+EchoKit Device (hears me)
+    ↓
+EchoKit Server (transcribes speech)
+    ↓
+echokit_pty (WebSocket connection)
+    ↓
+Claude Code (executes the command)
+    ↓
+Tests run, results stream back
+    ↓
+EchoKit speaks: "142 tests passed, 3 failed"
+```
+
+All while I keep typing. No window switching. No flow breaking.
+
+## A Day in the Life
+
+Let me show you what this actually feels like.
+
+**Morning:**
+I sit down with coffee. "EchoKit, run the full test suite." I start reading emails while tests run in the background. Five minutes later: "Tests complete. Two failures in the auth module."
+
+**Afternoon:**
+I'm stuck on a bug. "EchoKit, why is the login failing?" It explains the issue while I'm looking at the code. "Can you fix it?" "Done. Want me to run the tests?" "Yes."
+
+**Evening:**
+I'm tired, don't want to type. "EchoKit, create a new feature branch called dark-mode." "Deploy staging." "Check if the build passed." Each command happens while I'm leaning back in my chair.
+
+It feels like having a coding companion. Not a tool—a teammate.
+
+## Why This Matters
+
+I know what you're thinking: *Voice control for coding? Sounds weird.* And doesn't Claude Code have Remote Control now?
+
+You're right—it *is* weird at first. But here's the thing: **Claude Code's Remote Control is great for mobile access, but EchoKit isn't your phone.** It's a dedicated device that sits on your desk. Always on. Always listening. No unlocking, no apps, no picking it up.
+
+Here's what I discovered:
+
+**It's not about voice typing.** I'm not dictating code. That would be terrible.
+
+**It's about having a physical device.** Think of it like a smart speaker for coding. It just sits there, ready to help. No screens to tap, no apps to open, no phone to find.
+
+**The magic is the always-there presence.** The device lives on my desk. It's part of my workspace. I don't need to grab anything or unlock anything. I just speak.
+
+**It keeps me in the flow.** That's the biggest one. I can stay focused on coding while EchoKit handles tasks in the background. It's like having a second pair of hands.
+
+## The Tech Behind the Magic
+
+If you're curious how echokit_pty works technically, here's the short version:
+
+**PTY** stands for "pseudo-terminal"—a Unix concept that lets a program control a terminal as if a user were typing. echokit_pty uses this to create a bridge between:
+- **WebSocket clients** → send JSON commands
+- **Claude Code CLI** → executes the commands
+- **Response streaming** → sends results back
+
+It's built with Rust, runs locally, and is completely open source. No cloud required. Your code never leaves your machine.
+
+But here's what I care about: it just works.
+
+## What You Can Do
+
+So what does this actually look like in practice?
+
+**"Create a web page for me"**
+→ Claude Code generates the HTML, EchoKit confirms when done
+
+**"Run the tests"**
+→ Tests execute, EchoKit tells me the results
+
+**"Explain this error"**
+→ Claude Code analyzes, EchoKit reads the explanation
+
+**"Deploy to staging"**
+→ Deployment triggers, EchoKit confirms when complete
+
+**"Create a new branch"**
+→ Git command executes, no typing required
+
+I can speak from across the room. Keep my hands on the keyboard while EchoKit works in the background. Get voice feedback without breaking my flow.
+
+## Building Your Own
+
+This is the part I'm most excited about: everything here is open source.
+
+- **EchoKit** — Open hardware, Rust firmware, fully customizable
+- **echokit_pty** — Open source WebSocket interface for Claude Code
+- **EchoKit Server** — Rust-based voice AI server
+
+You can build this yourself. Or modify it. Or extend it.
+
+Want to add custom voice commands? Go ahead.
+Want to integrate with other tools? echokit_pty makes it possible.
+Want to build a completely different interface? The WebSocket is waiting.
+
+## The Future
+
+This experiment showed me something: AI coding assistants can take many forms beyond screens and apps.
+
+**Claude Code's Remote Control solved mobile access.** But what about specialized hardware? What about completely hands-free experiences? What about devices that do one thing perfectly?
+
+echokit_pty is the bridge that makes these experiments possible. And EchoKit is just one example.
+
+Imagine what else we could build:
+- Voice-controlled development environments
+- Specialized devices for specific workflows
+- Educational tools that feel like magic
+- Assistive technology for developers with disabilities
+
+All built on top of echokit_pty's open WebSocket interface.
+
+## Try It Yourself
+
+Ready to turn your AI assistant into a physical device?
+
+**Full Documentation:** [Remote Control Claude Code with Your Voice](https://echokit.dev/docs/use-cases/claude-code)
+
+**EchoKit Hardware:**
+- [EchoKit Box](https://echokit.dev/echokit_box.html) — Pre-assembled device
+- [EchoKit DIY Kit](https://echokit.dev/echokit_diy.html) — Build it yourself
+
+**echokit_pty Repository:** [github.com/second-state/echokit_pty](https://github.com/second-state/echokit_pty)
+
+**Join the Community:** [EchoKit Discord](https://discord.gg/Fwe3zsT5g3)
+
+Build something cool. Then tell me about it.
+
+---
+
+*PS: The first time I heard EchoKit say "Tests passed" while I was making coffee? That's when I knew this wasn't just a cool experiment. This was how I wanted to work from now on.*

doc/dev/2026-02-25-echokit-pty-intro.md

@@ -0,0 +1,185 @@
+---
+slug: echokit-pty-websocket-claude-code
+title: "echokit_pty: Giving Claude Code a Remote Control"
+tags: [echokit-pty, claude-code, websocket, developer-tools]
+---
+
+Claude Code is amazing. It writes code, fixes bugs, runs tests, explains errors. But it lives in your terminal. To use it, you type commands, get responses. It's a CLI tool, designed for terminal workflows.
+
+But what if you want to build something on top of Claude Code? What if you want a web app? A mobile interface? A physical device? Voice control?
+
+That's why we built **echokit_pty**.
+
+## What Is echokit_pty?
+
+**echokit_pty** is the web version of Claude Code with a superpower: a WebSocket interface.
+
+It handles Claude Code's input and output, turning its CLI into a WebSocket service. Suddenly, Claude Code isn't just a terminal app—it's a service that *any application* can talk to.
+
+**What makes it special?**
+- Full Claude Code capabilities (file editing, command execution, tool use)
+- **Clean JSON API for integrations**. Check out the full API documentation [here](https://github.com/second-state/echokit_pty?tab=readme-ov-file#api).
+- **Open and extensible** - unlike Claude Code's official Remote Control, you have full control over the protocol and can customize every aspect
+- **No subscription required** - free and open source vs. Max-only Remote Control
+- Bidirectional streaming (real-time responses)
+- Runs locally
+- Built for developers building custom solutions
+
+## The Problem: Claude Code Is Trapped in the Terminal
+
+Claude Code was designed as a CLI tool. You run it in your terminal, type commands, get responses. This works great for terminal workflows.
+
+But what if you want to:
+- Build a web app that uses Claude Code?
+- Create a physical device that talks to Claude Code?
+- Integrate Claude Code into another tool?
+- Build a custom application that needs programmatic access?
+
+**Yes, Claude Code now has an official Remote Control feature** for mobile and web access. But it's designed as a user-facing feature, not a developer platform. It requires a Max subscription, uses a closed protocol, and can't be integrated into custom applications.
+
+That's where echokit_pty comes in.
+
+## The Solution: PTY + WebSocket
+
+The bridge is **echokit_pty**.
+
+**What does "pty" mean?**
+
+PTY stands for "pseudo-terminal"—a Unix concept that allows a program to control a terminal as if a user were typing.
+
+echokit_pty uses this technology to create a bridge between:
+- **WebSocket clients** → send JSON commands
+- **Claude Code CLI** → executes the commands
+- **Response streaming** → sends results back
+
+## How It Works
+
+echokit_pty is built with Rust. Here's the architecture:
+
+```
+┌─────────────────┐     WebSocket      ┌──────────────┐
+│   Any Client    │ ◄─────────────────► │ echokit_pty  │
+│  (Web, Mobile,  │     (ws://localhost)│   (Rust)     │
+│   Device, etc.) │                     └──────┬───────┘
+└─────────────────┘                            │
+                                               │ PTY
+                                               ↓
+                                        ┌──────────────┐
+                                        │ Claude Code  │
+                                        │    CLI       │
+                                        └──────────────┘
+```
+
+**The flow:**
+1. echokit_pty starts a WebSocket server (default: `ws://localhost:3000/ws`)
+2. Clients connect via WebSocket and send JSON commands
+3. echokit_pty forwards commands to Claude Code CLI through a pseudo-terminal
+4. Claude Code executes the command
+5. Results stream back through the WebSocket in real-time
+
+**Example:**
+```json
+// Client sends
+{"type": "command", "content": "run the tests"}
+
+// echokit_pty forwards to Claude Code
+
+// Results stream back
+{"type": "response", "content": "Running tests...\n142 passed, 3 failed"}
+```
+
+## Use Cases: What Can You Build?
+
+The beauty of echokit_pty is that it turns Claude Code into a *platform*. Here's what you can build:
+
+### Voice-Controlled Coding
+Speak commands, Claude Code executes, hear results. Perfect for hands-free workflows. This is what EchoKit + echokit_pty enables.
+
+**Why echokit_pty for voice control?** While Claude Code's Remote Control works great for mobile/web access, it doesn't support voice interfaces or custom hardware. echokit_pty's open API lets you build exactly the voice experience you need—whether that's a custom device, specialized voice commands, or integration with other speech services.
+
+But it's just one implementation. For more details, check out EchoKit's full integration [documentation](https://echokit.dev/docs/use-cases/claude-code).
+
+### Web Apps
+Build a web interface for Claude Code. No terminal required. Just open a browser, connect to the WebSocket, and start coding. Great for presentations, teaching, or developers who prefer GUIs.
+
+### Mobile Apps
+Control Claude Code from your phone. Run tests while walking. Check build status from the couch. Deploy from anywhere. Your coding environment fits in your pocket.
+
+### Pair Programming Platforms
+Create a web app where multiple people can interact with Claude Code simultaneously. Real-time collaboration, shared context, better than screen sharing.
+
+### Teaching & Demos
+Show Claude Code in presentations without terminal windows cluttering the screen. A clean web interface for live coding demos, tutorials, and workshops.
+
+### Custom Developer Tools
+Build your own tools on top of Claude Code. Automations, dashboards, integrations—anything you can imagine. The WebSocket interface makes Claude Code a building block.
+
+### IDE Integrations
+Embed Claude Code directly into your IDE. VS Code extension, JetBrains plugin, custom editor—give Claude Code a proper home in your development environment.
+
+## Getting Started
+
+**Installation:**
+
+First, clone and build echokit_pty:
+
+```bash
+git clone https://github.com/second-state/echokit_pty.git
+cd echokit_pty
+cargo build --release --bin echokit_cc
+```
+
+**Running echokit_pty:**
+
+Set your workspace directory and start the server:
+
+```bash
+ECHOKIT_WORKING_PATH="/path/to/your/workspace" \
+./target/release/echokit_cc -c ./run_cc.sh -b "localhost:3000"
+```
+
+The WebSocket server will start on `ws://localhost:3000/ws`.
+
+![](./2026-02-25-echokit-pty.jpg)
+
+## echokit_pty vs. Claude Code Remote Control
+
+You might be wondering: *Should I use echokit_pty or Claude Code's official Remote Control?*
+
+**Use Claude Code Remote Control if:**
+- You want to control Claude Code from your phone or browser
+- You have a Max subscription and don't need customization
+- You just need remote access, not programmatic control
+
+**Use echokit_pty if:**
+- You're building a custom application or service
+- You need full control over the protocol and behavior
+- You want to integrate Claude Code into hardware (voice devices, custom interfaces)
+- You need a free, open-source solution
+- You're building something beyond simple remote control
+
+**They're complementary, not competing.** Remote Control is perfect for individual developers who want mobile access. echokit_pty is for builders who want to create entirely new experiences on top of Claude Code.
+
+## The Vision
+
+Claude Code is the most capable AI coding assistant today. With Remote Control, it can now follow you beyond the terminal. But that's just the beginning.
+
+echokit_pty is about turning Claude Code into a true **platform for innovation**.
+
+Imagine what we can build:
+
+- Voice-controlled coding assistants with custom hardware
+- Specialized interfaces for specific workflows
+- Custom developer tools and dashboards
+- AI-powered IDE integrations
+- Educational platforms with tailored experiences
+
+All built on top of echokit_pty's open API.
+
+**Claude Code as a platform for builders, not just a tool for users.**
+
+---
+
+**Ready to build something?**
+
+Start with the [echokit_pty repository](https://github.com/second-state/echokit_pty). See EchoKit's full integration [documentation](https://echokit.dev/docs/use-cases/claude-code) for a complete example. Join our [Discord community](https://discord.gg/Fwe3zsT5g3) to share your ideas.