claude-sock 0.1.0__tar.gz

claude_sock-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: claude-sock
+Version: 0.1.0
+Summary: Sockpuppet for Claude Code — drive the TUI programmatically, stream JSONL like claude -p
+Author: Daniel Huynh
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dhuynh95/claude-sock
+Project-URL: Repository, https://github.com/dhuynh95/claude-sock
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# claude-sock
+
+A sockpuppet for Claude Code. Drive the TUI programmatically via a pty, stream JSONL output like `claude -p`.
+
+## Why
+
+`claude -p` (pipe mode) is great but limited — no MCP servers, no skills, no interactive tool use. `claude-sock` spawns the full Claude Code TUI, injects keystrokes through a pty, and reads structured output from the session JSONL file. Your code gets the full power of interactive Claude Code through a simple async Python API.
+
+## Install
+
+```bash
+pip install claude-sock
+```
+
+Requires Claude Code CLI (`claude`) to be installed and authenticated.
+
+## Quick start
+
+### Python API
+
+```python
+import asyncio
+from claude_sock.orchestrator import ClaudeREPL
+
+async def main():
+    async with ClaudeREPL(timeout=60) as repl:
+        messages = await repl.query("What files are in this directory?")
+        for msg in messages:
+            print(msg)
+
+asyncio.run(main())
+```
+
+### Streaming
+
+```python
+async with ClaudeREPL() as repl:
+    async for msg in repl.query_stream("Refactor main.py"):
+        print(msg)
+```
+
+### Resume a session
+
+```python
+async with ClaudeREPL(resume="ef4f97fd-d265-474e-9544-3f228e9654c0") as repl:
+    messages = await repl.query("Continue where we left off")
+```
+
+### Load skills
+
+```python
+async with ClaudeREPL() as repl:
+    await repl.send_skill("commit")
+    messages = await repl.query("Fix the login bug and commit")
+```
+
+### MCP servers
+
+```python
+# Pick servers by name from your .mcp.json
+async with ClaudeREPL(server_names=["my-server"]) as repl:
+    messages = await repl.query("Use the my-server tool")
+```
+
+### CLI (drop-in `claude -p` replacement)
+
+```bash
+echo "Explain this repo" | claude-sock -p
+claude-sock "What does main.py do?" --timeout 60
+claude-sock "Continue" --resume ef4f97fd-d265-474e-9544-3f228e9654c0
+```
+
+Output is JSONL, compatible with anything that reads `claude -p` format.
+
+## How it works
+
+```
+Your code
+   │
+   ▼ keystrokes
+┌─────────┐        ┌──────────────┐
+│   pty   │───────▶│  Claude Code  │
+│ (write) │        │    TUI        │
+└─────────┘        └──────┬───────┘
+                          │ writes
+                          ▼
+                   ┌──────────────┐
+                   │ session.jsonl │
+                   └──────┬───────┘
+                          │ reads
+                          ▼
+                   ┌──────────────┐
+                   │  Your code   │
+                   │  (parsed)    │
+                   └──────────────┘
+```
+
+- **Write channel**: pty file descriptor — fire keystrokes and forget
+- **Read channel**: `~/.claude/projects/…/{session_id}.jsonl` — poll for new lines by byte offset
+
+## API reference
+
+### `ClaudeREPL(timeout, session_id, workdir, env, server_names, resume)`
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `float` | `120` | Seconds to wait for activity before timing out |
+| `session_id` | `str \| None` | auto-generated | Force a specific session ID |
+| `workdir` | `Path \| None` | `cwd` | Working directory for Claude |
+| `env` | `dict \| None` | `None` | Extra environment variables |
+| `server_names` | `list[str] \| None` | `None` | MCP server names from `.mcp.json` |
+| `resume` | `str \| None` | `None` | Session ID to resume |
+
+### Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `query(text)` | `list[Message]` | Send a message, wait for completion |
+| `query_stream(text)` | `AsyncIterator[Message]` | Send a message, yield parsed messages |
+| `query_stream_raw(text)` | `AsyncIterator[dict]` | Send a message, yield raw JSONL dicts |
+| `send_skill(name)` | `list[Message]` | Load a slash command (e.g. `"commit"`) |
+
+### Message types
+
+- `AssistantMessage` — contains `TextBlock` and `ToolUseBlock`
+- `ToolResultMessage` — contains `ToolResultBlock`
+- `ResultMessage` — turn summary (duration, cost, session ID)
+
+## License
+
+MIT

claude_sock-0.1.0/README.md

@@ -0,0 +1,131 @@
+# claude-sock
+
+A sockpuppet for Claude Code. Drive the TUI programmatically via a pty, stream JSONL output like `claude -p`.
+
+## Why
+
+`claude -p` (pipe mode) is great but limited — no MCP servers, no skills, no interactive tool use. `claude-sock` spawns the full Claude Code TUI, injects keystrokes through a pty, and reads structured output from the session JSONL file. Your code gets the full power of interactive Claude Code through a simple async Python API.
+
+## Install
+
+```bash
+pip install claude-sock
+```
+
+Requires Claude Code CLI (`claude`) to be installed and authenticated.
+
+## Quick start
+
+### Python API
+
+```python
+import asyncio
+from claude_sock.orchestrator import ClaudeREPL
+
+async def main():
+    async with ClaudeREPL(timeout=60) as repl:
+        messages = await repl.query("What files are in this directory?")
+        for msg in messages:
+            print(msg)
+
+asyncio.run(main())
+```
+
+### Streaming
+
+```python
+async with ClaudeREPL() as repl:
+    async for msg in repl.query_stream("Refactor main.py"):
+        print(msg)
+```
+
+### Resume a session
+
+```python
+async with ClaudeREPL(resume="ef4f97fd-d265-474e-9544-3f228e9654c0") as repl:
+    messages = await repl.query("Continue where we left off")
+```
+
+### Load skills
+
+```python
+async with ClaudeREPL() as repl:
+    await repl.send_skill("commit")
+    messages = await repl.query("Fix the login bug and commit")
+```
+
+### MCP servers
+
+```python
+# Pick servers by name from your .mcp.json
+async with ClaudeREPL(server_names=["my-server"]) as repl:
+    messages = await repl.query("Use the my-server tool")
+```
+
+### CLI (drop-in `claude -p` replacement)
+
+```bash
+echo "Explain this repo" | claude-sock -p
+claude-sock "What does main.py do?" --timeout 60
+claude-sock "Continue" --resume ef4f97fd-d265-474e-9544-3f228e9654c0
+```
+
+Output is JSONL, compatible with anything that reads `claude -p` format.
+
+## How it works
+
+```
+Your code
+   │
+   ▼ keystrokes
+┌─────────┐        ┌──────────────┐
+│   pty   │───────▶│  Claude Code  │
+│ (write) │        │    TUI        │
+└─────────┘        └──────┬───────┘
+                          │ writes
+                          ▼
+                   ┌──────────────┐
+                   │ session.jsonl │
+                   └──────┬───────┘
+                          │ reads
+                          ▼
+                   ┌──────────────┐
+                   │  Your code   │
+                   │  (parsed)    │
+                   └──────────────┘
+```
+
+- **Write channel**: pty file descriptor — fire keystrokes and forget
+- **Read channel**: `~/.claude/projects/…/{session_id}.jsonl` — poll for new lines by byte offset
+
+## API reference
+
+### `ClaudeREPL(timeout, session_id, workdir, env, server_names, resume)`
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `float` | `120` | Seconds to wait for activity before timing out |
+| `session_id` | `str \| None` | auto-generated | Force a specific session ID |
+| `workdir` | `Path \| None` | `cwd` | Working directory for Claude |
+| `env` | `dict \| None` | `None` | Extra environment variables |
+| `server_names` | `list[str] \| None` | `None` | MCP server names from `.mcp.json` |
+| `resume` | `str \| None` | `None` | Session ID to resume |
+
+### Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `query(text)` | `list[Message]` | Send a message, wait for completion |
+| `query_stream(text)` | `AsyncIterator[Message]` | Send a message, yield parsed messages |
+| `query_stream_raw(text)` | `AsyncIterator[dict]` | Send a message, yield raw JSONL dicts |
+| `send_skill(name)` | `list[Message]` | Load a slash command (e.g. `"commit"`) |
+
+### Message types
+
+- `AssistantMessage` — contains `TextBlock` and `ToolUseBlock`
+- `ToolResultMessage` — contains `ToolResultBlock`
+- `ResultMessage` — turn summary (duration, cost, session ID)
+
+## License
+
+MIT

claude_sock-0.1.0/claude_sock/cli.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Drop-in replacement for `claude -p` that drives the Claude Code TUI.
+
+Accepts the same CLI interface as `claude -p` so OpenClaw (and anything
+else expecting pipe-mode Claude) can call it directly. Reads prompt from
+stdin, streams JSONL to stdout in `claude -p` format.
+"""
+
+import argparse
+import asyncio
+import json
+import sys
+import time
+from typing import Any
+
+from claude_sock.orchestrator import ClaudeREPL
+
+
+def emit(obj: dict) -> None:
+    print(json.dumps(obj), flush=True)
+
+
+def _extract_text(raw: dict[str, Any]) -> str:
+    """Pull plain text from an assistant message's content blocks."""
+    msg = raw.get("message", {})
+    parts = []
+    for block in msg.get("content", []):
+        if block.get("type") == "text":
+            parts.append(block["text"])
+    return "".join(parts)
+
+
+async def _run() -> None:
+    parser = argparse.ArgumentParser(description="claude -p compatible wrapper over Claude Code TUI.")
+    parser.add_argument("query", nargs="?", default=None, help="Message to send (or read from stdin)")
+    parser.add_argument("--timeout", type=float, default=120)
+
+    # claude -p compatible flags (accepted, mostly ignored)
+    parser.add_argument("-p", action="store_true")
+    parser.add_argument("--output-format", default=None)
+    parser.add_argument("--include-partial-messages", action="store_true")
+    parser.add_argument("--verbose", action="store_true")
+    parser.add_argument("--permission-mode", default=None)
+    parser.add_argument("--model", default=None)
+    parser.add_argument("--session-id", default=None)
+    parser.add_argument("--append-system-prompt", default=None)
+    parser.add_argument("--resume", default=None)
+    parser.add_argument("--mcp-config", default=None)
+    parser.add_argument("--strict-mcp-config", action="store_true")
+
+    args = parser.parse_args()
+
+    prompt = args.query
+    if not prompt and not sys.stdin.isatty():
+        prompt = sys.stdin.read().strip()
+    if not prompt:
+        print("Error: no prompt provided (pass as argument or via stdin)", file=sys.stderr)
+        sys.exit(1)
+
+    t0 = time.monotonic()
+
+    async with ClaudeREPL(timeout=args.timeout, server_names=[], resume=args.resume) as repl:
+        # 1. Init line
+        emit({
+            "type": "system",
+            "subtype": "init",
+            "session_id": repl.session_id,
+            "model": args.model or "",
+            "tools": [],
+            "mcp_servers": [],
+            "permissionMode": args.permission_mode or "default",
+            "claude_code_version": "claude-tui",
+            "uuid": repl.session_id,
+        })
+
+        # 2. Stream — forward assistant messages, collect final text
+        final_text = ""
+        async for raw in repl.query_stream_raw(prompt):
+            t = raw.get("type")
+            if t == "assistant":
+                emit({
+                    "type": "assistant",
+                    "message": raw.get("message", {}),
+                    "session_id": repl.session_id,
+                    "uuid": raw.get("uuid", ""),
+                })
+                final_text = _extract_text(raw) or final_text
+
+        # 3. Result line
+        elapsed_ms = int((time.monotonic() - t0) * 1000)
+        emit({
+            "type": "result",
+            "subtype": "success",
+            "is_error": False,
+            "duration_ms": elapsed_ms,
+            "num_turns": 1,
+            "result": final_text,
+            "stop_reason": "end_turn",
+            "session_id": repl.session_id,
+            "total_cost_usd": 0,
+            "usage": {},
+            "terminal_reason": "completed",
+            "uuid": repl.session_id,
+        })
+
+
+def main() -> None:
+    asyncio.run(_run())
+
+
+if __name__ == "__main__":
+    main()

claude_sock-0.1.0/claude_sock/orchestrator.py

@@ -0,0 +1,454 @@
+#!/usr/bin/env python3
+"""Programmatic interface to Claude Code CLI for batch evals.
+
+Write channel: pty fd (keystrokes into the TUI) — fire and forget.
+Read channel:  session JSONL file (~/.claude/projects/…/{session_id}.jsonl)
+
+    async with ClaudeREPL() as repl:
+        await repl.send_skill("reduck-mcp")
+        messages = await repl.query("Take a screenshot")
+
+CC JSONL format insights:
+- CC splits a single LLM response into multiple JSONL lines: thinking, text,
+  tool_use — each with stop_reason=None except (sometimes) the last.
+- stop_reason=end_turn is unreliable: CC sometimes writes None for the final
+  assistant message.
+- type=progress with hookEvent=Stop is the completion signal.  However,
+  agent_progress events appear MID-TURN while a subagent runs — these must
+  be excluded from completion detection.
+- Closing the pty master fd sends SIGHUP to the child — the process must stay
+  alive until the turn completes. close() sends /exit then kills.
+- Watermark (line offset into JSONL) scopes each wait to the current turn.
+  After completion, watermark is set via _count_lines() (not watermark +
+  len(new_lines)) to capture trailing metadata (system, file-history-snapshot).
+- The saw_user gate prevents a previous turn's progress from triggering the
+  current turn's completion: progress from the skill turn appears before the
+  query's user message in the file, so saw_user is still False.
+"""
+
+import asyncio
+import fcntl
+import json
+import os
+import pty
+import select
+import struct
+import subprocess
+import tempfile
+import termios
+import uuid
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+PROJECTS_DIR = Path.home() / ".claude" / "projects"
+FOCUS_IN = b"\x1b[I"
+POLL_INTERVAL = 0.15
+
+
+def _build_mcp_config(server_names: list[str], cwd: Path) -> dict[str, Any]:
+    """Pick servers from .mcp.json by name. Single source of truth."""
+    if not server_names:
+        return {"mcpServers": {}}
+    mcp_path = cwd / ".mcp.json"
+    if not mcp_path.exists():
+        raise FileNotFoundError(f"No .mcp.json found in {cwd}")
+    project_mcp = json.loads(mcp_path.read_text())
+    all_servers = project_mcp["mcpServers"]
+    missing = set(server_names) - set(all_servers)
+    if missing:
+        raise ValueError(f"MCP servers not found in .mcp.json: {missing}")
+    servers = {k: all_servers[k] for k in server_names}
+    return {"mcpServers": servers}
+
+
+KEYS: dict[str, bytes] = {
+    "enter": b"\r",
+    "escape": b"\x1b",
+    "tab": b"\t",
+    "shift+tab": b"\x1b[Z",
+    "ctrl+c": b"\x03",
+    "up": b"\x1b[A",
+    "down": b"\x1b[B",
+    "backspace": b"\x7f",
+}
+
+
+# -- Message types -------------------------------------------------------------
+
+
+@dataclass
+class TextBlock:
+    text: str
+    type: str = "text"
+
+
+@dataclass
+class ToolUseBlock:
+    id: str
+    name: str
+    input: dict[str, Any]
+    type: str = "tool_use"
+
+
+@dataclass
+class ToolResultBlock:
+    tool_use_id: str
+    content: str
+    type: str = "tool_result"
+
+
+@dataclass
+class AssistantMessage:
+    content: list[TextBlock | ToolUseBlock]
+    model: str = ""
+    stop_reason: str = ""
+    usage: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolResultMessage:
+    content: list[ToolResultBlock]
+
+
+@dataclass
+class ResultMessage:
+    duration_ms: int = 0
+    num_turns: int = 0
+    session_id: str = ""
+    total_cost_usd: float = 0.0
+
+
+Message = AssistantMessage | ToolResultMessage | ResultMessage
+
+
+# -- Parsing -------------------------------------------------------------------
+
+
+def _parse_assistant(raw: dict[str, Any]) -> AssistantMessage:
+    msg = raw["message"]
+    blocks: list[TextBlock | ToolUseBlock] = []
+    for b in msg.get("content", []):
+        if b.get("type") == "text":
+            blocks.append(TextBlock(text=b["text"]))
+        elif b.get("type") == "tool_use":
+            blocks.append(
+                ToolUseBlock(id=b["id"], name=b["name"], input=b.get("input", {}))
+            )
+    return AssistantMessage(
+        content=blocks,
+        model=msg.get("model", ""),
+        stop_reason=msg.get("stop_reason", ""),
+        usage=msg.get("usage", {}),
+    )
+
+
+def _parse_tool_result(raw: dict[str, Any]) -> ToolResultMessage:
+    msg = raw["message"]
+    blocks: list[ToolResultBlock] = []
+    for b in msg.get("content", []):
+        if b.get("type") == "tool_result":
+            content = b.get("content", "")
+            if isinstance(content, list):
+                content = "\n".join(
+                    p.get("text", "") for p in content if p.get("type") == "text"
+                )
+            blocks.append(
+                ToolResultBlock(tool_use_id=b.get("tool_use_id", ""), content=content)
+            )
+    return ToolResultMessage(content=blocks)
+
+
+def _parse_result(raw: dict[str, Any]) -> ResultMessage:
+    return ResultMessage(
+        duration_ms=raw.get("duration_ms", 0),
+        num_turns=raw.get("num_turns", 0),
+        session_id=raw.get("session_id", ""),
+        total_cost_usd=raw.get("total_cost_usd", 0.0),
+    )
+
+
+def _parse_line(raw: dict[str, Any]) -> Message | None:
+    t = raw.get("type")
+    if t == "assistant":
+        return _parse_assistant(raw)
+    if t == "user" and isinstance(raw.get("message", {}).get("content"), list):
+        has_tool_result = any(
+            b.get("type") == "tool_result" for b in raw["message"]["content"]
+        )
+        if has_tool_result:
+            return _parse_tool_result(raw)
+    if t == "result":
+        return _parse_result(raw)
+    return None
+
+
+def _is_done(raw: dict[str, Any]) -> bool:
+    """True if this JSONL line signals turn completion.
+
+    Primary signal: type=progress with hookEvent=Stop (written after every
+    completed turn).  agent_progress is an intermediate signal emitted while
+    a subagent is still running and must be excluded.
+    Fallback: stop_reason=end_turn on a non-tool-use assistant message,
+    because CC sometimes omits the progress line after skill turns.
+    """
+    if raw.get("type") == "result":
+        return True
+    if raw.get("type") == "progress":
+        data = raw.get("data", {})
+        # agent_progress is mid-turn — subagent still running
+        if data.get("type") == "agent_progress":
+            return False
+        return True
+    if raw.get("type") == "assistant":
+        msg = raw.get("message", {})
+        if msg.get("stop_reason") == "end_turn":
+            has_tool_use = any(
+                b.get("type") == "tool_use" for b in msg.get("content", [])
+            )
+            if not has_tool_use:
+                return True
+    return False
+
+
+def _is_user_message(raw: dict[str, Any]) -> bool:
+    return raw.get("type") == "user"
+
+
+# -- Path encoding -------------------------------------------------------------
+
+
+def encode_project_path(path: Path) -> str:
+    return str(path.resolve()).replace("/", "-").replace(".", "-")
+
+
+# -- REPL ----------------------------------------------------------------------
+
+
+class ClaudeREPL:
+    """Programmatic handle to a Claude Code TUI session.
+
+    All synchronization goes through the JSONL session file.
+    The pty is a write-only channel — fire keystrokes and forget.
+    """
+
+    def __init__(
+        self,
+        timeout: float = 120,
+        session_id: str | None = None,
+        workdir: Path | None = None,
+        env: dict[str, str] | None = None,
+        server_names: list[str] | None = None,
+        resume: str | None = None,
+    ):
+        self.timeout = timeout
+        self.session_id = resume or session_id or str(uuid.uuid4())
+        self._resume = resume
+        self._workdir = (workdir or Path.cwd()).resolve()
+        self._byte_offset = 0
+
+        # Write MCP config to temp file (auto-cleaned on process exit)
+        mcp_cfg = _build_mcp_config(server_names or [], self._workdir)
+        self._mcp_tmp = tempfile.NamedTemporaryFile(
+            mode="w", suffix=".json", prefix="mcp_", delete=False
+        )
+        json.dump(mcp_cfg, self._mcp_tmp)
+        self._mcp_tmp.close()
+
+        # Spawn pty
+        child_env = {
+            k: v
+            for k, v in os.environ.items()
+            if k not in ("CLAUDE_REPL", "CLAUDECODE")
+        }
+        child_env["TERM"] = "xterm-256color"
+        if env:
+            child_env.update(env)
+
+        self._master, slave = pty.openpty()
+        fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", 24, 80, 0, 0))
+
+        cmd = ["claude"]
+        if self._resume:
+            cmd += ["--resume", self._resume]
+        else:
+            cmd += ["--session-id", self.session_id]
+        cmd += [
+            "--dangerously-skip-permissions",
+            "--mcp-config",
+            self._mcp_tmp.name,
+            "--strict-mcp-config",
+        ]
+
+        self._proc = subprocess.Popen(
+            cmd,
+            stdin=slave,
+            stdout=slave,
+            stderr=slave,
+            close_fds=True,
+            cwd=self._workdir,
+            env=child_env,
+        )
+        os.close(slave)
+
+    @property
+    def session_path(self) -> Path:
+        project_dir = encode_project_path(self._workdir)
+        return PROJECTS_DIR / project_dir / f"{self.session_id}.jsonl"
+
+    # -- Pty helpers (write-only) ----------------------------------------------
+
+    def _type_text(self, text: str) -> None:
+        """Inject characters into the pty synchronously."""
+        for c in text:
+            os.write(self._master, c.encode())
+
+    def _drain_pty(self) -> None:
+        """Consume pty output so the buffer doesn't block."""
+        while True:
+            ready, _, _ = select.select([self._master], [], [], 0)
+            if not ready:
+                break
+            try:
+                if not os.read(self._master, 4096):
+                    break
+            except OSError:
+                break
+
+    # -- JSONL tail (read-only, source of truth) --------------------------------
+
+    async def _tail_jsonl(self, timeout: float) -> AsyncIterator[dict[str, Any]]:
+        """Yield new JSONL objects as they're appended to the session file.
+
+        Seeks to byte offset and reads forward — O(new bytes) per poll,
+        not O(total file). Deadline resets on every new line (activity-based).
+        """
+        loop = asyncio.get_event_loop()
+        deadline = loop.time() + timeout
+
+        while not self.session_path.exists():
+            if loop.time() > deadline:
+                raise TimeoutError("Session file never appeared")
+            self._drain_pty()
+            await asyncio.sleep(0.2)
+
+        with open(self.session_path) as f:
+            f.seek(self._byte_offset)
+            buf = ""
+            while loop.time() < deadline:
+                chunk = f.read()
+                if chunk:
+                    buf += chunk
+                    while "\n" in buf:
+                        line, buf = buf.split("\n", 1)
+                        if line.strip():
+                            self._byte_offset = f.tell() - len(buf.encode())
+                            deadline = loop.time() + timeout
+                            yield json.loads(line)
+                else:
+                    self._drain_pty()
+                    await asyncio.sleep(POLL_INTERVAL)
+
+        raise TimeoutError(f"No activity for {timeout:.0f}s")
+
+    # -- Public API ------------------------------------------------------------
+
+    async def _collect_turn(self, timeout: float) -> list[Message]:
+        """Collect all messages until the turn completes."""
+        saw_user = False
+        msgs: list[Message] = []
+        async for raw in self._tail_jsonl(timeout):
+            if _is_user_message(raw):
+                saw_user = True
+            if not saw_user:
+                continue
+            msg = _parse_line(raw)
+            if msg:
+                msgs.append(msg)
+            if _is_done(raw):
+                return msgs
+        return msgs
+
+    async def send_skill(
+        self, name: str, timeout: float | None = None
+    ) -> list[Message]:
+        """Load a slash command. Returns messages from the skill acknowledgment turn."""
+        timeout = timeout or self.timeout
+        text = name if name.startswith("/") else f"/{name}"
+
+        self._type_text(text)
+        await asyncio.sleep(0.05)
+        os.write(self._master, KEYS["tab"])
+        await asyncio.sleep(0.3)
+        os.write(self._master, KEYS["enter"])
+
+        return await self._collect_turn(timeout)
+
+    async def query_stream_raw(
+        self, text: str, timeout: float | None = None
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Send a message and yield raw JSONL dicts as they arrive."""
+        timeout = timeout or self.timeout
+
+        self._type_text(text)
+        await asyncio.sleep(0.05)
+        os.write(self._master, KEYS["enter"])
+
+        saw_user = False
+        async for raw in self._tail_jsonl(timeout):
+            if _is_user_message(raw):
+                saw_user = True
+            if saw_user:
+                yield raw
+            if saw_user and _is_done(raw):
+                return
+
+    async def query_stream(
+        self, text: str, timeout: float | None = None
+    ) -> AsyncIterator[Message]:
+        """Send a message and yield parsed messages as they arrive."""
+        async for raw in self.query_stream_raw(text, timeout):
+            msg = _parse_line(raw)
+            if msg:
+                yield msg
+
+    async def query(self, text: str, timeout: float | None = None) -> list[Message]:
+        """Send a message and wait for completion. Returns all messages from the turn."""
+        return [msg async for msg in self.query_stream(text, timeout)]
+
+    # -- Lifecycle -------------------------------------------------------------
+
+    async def start(self) -> None:
+        """Wait for TUI startup and activate input."""
+        await asyncio.sleep(5)
+        self._drain_pty()
+        os.write(self._master, FOCUS_IN)
+        await asyncio.sleep(0.2)
+        self._drain_pty()
+        if self.session_path.exists():
+            self._byte_offset = self.session_path.stat().st_size
+
+    async def close(self) -> None:
+        """Shut down the Claude process and close the pty."""
+        try:
+            os.write(self._master, b"/exit\r")
+            await asyncio.sleep(2)
+        except OSError:
+            pass
+        self._proc.kill()
+        try:
+            os.close(self._master)
+        except OSError:
+            pass
+        try:
+            os.unlink(self._mcp_tmp.name)
+        except OSError:
+            pass
+
+    async def __aenter__(self) -> "ClaudeREPL":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

claude_sock-0.1.0/claude_sock.egg-info/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: claude-sock
+Version: 0.1.0
+Summary: Sockpuppet for Claude Code — drive the TUI programmatically, stream JSONL like claude -p
+Author: Daniel Huynh
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dhuynh95/claude-sock
+Project-URL: Repository, https://github.com/dhuynh95/claude-sock
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# claude-sock
+
+A sockpuppet for Claude Code. Drive the TUI programmatically via a pty, stream JSONL output like `claude -p`.
+
+## Why
+
+`claude -p` (pipe mode) is great but limited — no MCP servers, no skills, no interactive tool use. `claude-sock` spawns the full Claude Code TUI, injects keystrokes through a pty, and reads structured output from the session JSONL file. Your code gets the full power of interactive Claude Code through a simple async Python API.
+
+## Install
+
+```bash
+pip install claude-sock
+```
+
+Requires Claude Code CLI (`claude`) to be installed and authenticated.
+
+## Quick start
+
+### Python API
+
+```python
+import asyncio
+from claude_sock.orchestrator import ClaudeREPL
+
+async def main():
+    async with ClaudeREPL(timeout=60) as repl:
+        messages = await repl.query("What files are in this directory?")
+        for msg in messages:
+            print(msg)
+
+asyncio.run(main())
+```
+
+### Streaming
+
+```python
+async with ClaudeREPL() as repl:
+    async for msg in repl.query_stream("Refactor main.py"):
+        print(msg)
+```
+
+### Resume a session
+
+```python
+async with ClaudeREPL(resume="ef4f97fd-d265-474e-9544-3f228e9654c0") as repl:
+    messages = await repl.query("Continue where we left off")
+```
+
+### Load skills
+
+```python
+async with ClaudeREPL() as repl:
+    await repl.send_skill("commit")
+    messages = await repl.query("Fix the login bug and commit")
+```
+
+### MCP servers
+
+```python
+# Pick servers by name from your .mcp.json
+async with ClaudeREPL(server_names=["my-server"]) as repl:
+    messages = await repl.query("Use the my-server tool")
+```
+
+### CLI (drop-in `claude -p` replacement)
+
+```bash
+echo "Explain this repo" | claude-sock -p
+claude-sock "What does main.py do?" --timeout 60
+claude-sock "Continue" --resume ef4f97fd-d265-474e-9544-3f228e9654c0
+```
+
+Output is JSONL, compatible with anything that reads `claude -p` format.
+
+## How it works
+
+```
+Your code
+   │
+   ▼ keystrokes
+┌─────────┐        ┌──────────────┐
+│   pty   │───────▶│  Claude Code  │
+│ (write) │        │    TUI        │
+└─────────┘        └──────┬───────┘
+                          │ writes
+                          ▼
+                   ┌──────────────┐
+                   │ session.jsonl │
+                   └──────┬───────┘
+                          │ reads
+                          ▼
+                   ┌──────────────┐
+                   │  Your code   │
+                   │  (parsed)    │
+                   └──────────────┘
+```
+
+- **Write channel**: pty file descriptor — fire keystrokes and forget
+- **Read channel**: `~/.claude/projects/…/{session_id}.jsonl` — poll for new lines by byte offset
+
+## API reference
+
+### `ClaudeREPL(timeout, session_id, workdir, env, server_names, resume)`
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `float` | `120` | Seconds to wait for activity before timing out |
+| `session_id` | `str \| None` | auto-generated | Force a specific session ID |
+| `workdir` | `Path \| None` | `cwd` | Working directory for Claude |
+| `env` | `dict \| None` | `None` | Extra environment variables |
+| `server_names` | `list[str] \| None` | `None` | MCP server names from `.mcp.json` |
+| `resume` | `str \| None` | `None` | Session ID to resume |
+
+### Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `query(text)` | `list[Message]` | Send a message, wait for completion |
+| `query_stream(text)` | `AsyncIterator[Message]` | Send a message, yield parsed messages |
+| `query_stream_raw(text)` | `AsyncIterator[dict]` | Send a message, yield raw JSONL dicts |
+| `send_skill(name)` | `list[Message]` | Load a slash command (e.g. `"commit"`) |
+
+### Message types
+
+- `AssistantMessage` — contains `TextBlock` and `ToolUseBlock`
+- `ToolResultMessage` — contains `ToolResultBlock`
+- `ResultMessage` — turn summary (duration, cost, session ID)
+
+## License
+
+MIT

claude_sock-0.1.0/claude_sock.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+claude_sock/__init__.py
+claude_sock/cli.py
+claude_sock/orchestrator.py
+claude_sock.egg-info/PKG-INFO
+claude_sock.egg-info/SOURCES.txt
+claude_sock.egg-info/dependency_links.txt
+claude_sock.egg-info/entry_points.txt
+claude_sock.egg-info/top_level.txt

claude_sock-0.1.0/claude_sock.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

claude_sock-0.1.0/claude_sock.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+claude-sock = claude_sock.cli:main

claude_sock-0.1.0/claude_sock.egg-info/top_level.txt

@@ -0,0 +1 @@
+claude_sock

claude_sock-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claude-sock"
+version = "0.1.0"
+description = "Sockpuppet for Claude Code — drive the TUI programmatically, stream JSONL like claude -p"
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Daniel Huynh" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/dhuynh95/claude-sock"
+Repository = "https://github.com/dhuynh95/claude-sock"
+
+[project.scripts]
+claude-sock = "claude_sock.cli:main"

claude_sock-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+