claw-army/claude-node

**A thin subprocess-based Python bridge for persistent Claude Code sessions.**
claude-node drives the local claude CLI as a long-lived subprocess and communicates with it over stream-json. Because it runs the installed CLI directly as its runtime, Python code gets access to Claude Code's native behavior through the CLI itself — achieving maximum compatibility with the CLI.
This is not a higher-level reimplementation or a message API wrapper. It is a direct bridge to the installed claude executable.
---
The CLI bridge
claude-node sits at the subprocess boundary:
- **Maximum compatibility**: because claude-node delegates entirely to the local claude CLI, any capability the CLI exposes is available — skills, slash commands, tools, agent modes, and session management.
- **Process isolation**: the Claude runtime lives in its own OS process, independent of the Python interpreter.
- **Protocol transparency**: raw stream-json behavior is visible and debuggable.
- **Easy embedding**: drop it into any Python environment — workers, web backends, job runners, or supervisor processes.
---
Positioning
claude-node gives Python direct control over the real local Claude Code runtime. It preserves native CLI capabilities with stream-json, explicit session lifecycle, and process-level supervision — built for embedding and integration, not for hiding Claude behind another framework.
**What this is not**
* Not another high-level agent framework
* Not a reimplementation of Claude
* Not a wrapper that hides the CLI behind a new abstraction
* Not a workflow or memory platform
**What this is**
* A thin Python runtime layer for controlling the real local Claude Code process
* A subprocess-first integration surface with explicit session and process control
* A practical foundation for embedding Claude Code into backends, workers, and internal tooling
---
Runtime model
This project is a **pure Python package**, but it has an **external runtime dependency**:
- The package itself is standard Python.
- At runtime, it requires a local claude executable in PATH.
In other words:
- pip install claude-node installs the Python package.
- claude-node only works if claude --version works on that machine.
This split is intentional. The project does not attempt to ship or emulate Claude Code. It controls an existing local Claude Code runtime.
---
Installation
Python package
Runtime requirement
Make sure Claude Code / Claude CLI is installed and available:
If that command fails, claude-node cannot start a session.
---
Requirements
- Python 3.11+
- a local claude executable in PATH
- a working Claude Code login / configuration on the host machine
- macOS or Linux recommended
Windows support has not been validated in this repository.
---
Quick start
Single controller
Real-time callback
Resume a session
Lightweight multi-session routing
---
Public API
The current public surface is intentionally small:
ClaudeController
Controls one long-lived Claude CLI subprocess.
Current responsibilities:
- start / stop one claude process,
- write user messages to stdin,
- read JSON lines from stdout / stderr,
- wait for type=result as the turn-completion signal,
- track session_id,
- provide parsed messages via ClaudeMessage,
- expose simple callbacks through on_message.
ClaudeMessage
Represents one parsed JSON event from the CLI stream.
Useful helpers include:
- is_init
- is_result
- is_result_ok
- is_result_error
- is_api_error
- truly_succeeded
- is_assistant
- is_tool_result
- assistant_texts
- tool_calls
- tool_results
- result_text
- session_id
- cost_usd
- num_turns
MultiAgentRouter
A minimal multi-session routing layer.