claude-node

March 23, 2026 · View on GitHub

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:

Your Python code          claude-node           Your local claude CLI
─────────────────        ────────────          ──────────────────────
ClaudeController  ───►   stdin/stdout   ───►   Claude Code runtime
                    ◄──   JSON events  ◄───

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

pip install claude-node

Runtime requirement

Make sure Claude Code / Claude CLI is installed and available:

claude --version

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

from claude_node import ClaudeController

with ClaudeController(skip_permissions=True) as ctrl:
    result = ctrl.send("List the files in the current directory")
    if result:
        print(result.result_text)
        print("session:", ctrl.session_id)

Real-time callback

def on_message(msg):
    if msg.is_assistant:
        for text in msg.assistant_texts:
            print("[assistant]", text)
    if msg.is_tool_result:
        for block in msg.tool_results:
            print("[tool_result]", block.get("tool_use_id"), block.get("is_error"))

ctrl = ClaudeController(on_message=on_message, skip_permissions=True)
ctrl.start()
result = ctrl.send("Run the tests and summarize failures", timeout=120)
ctrl.stop()

Resume a session

from claude_node import ClaudeController

with ClaudeController(skip_permissions=True) as ctrl:
    result = ctrl.send("Remember that the project codename is ALPHA. Reply only OK.")
    saved_session_id = ctrl.session_id

ctrl = ClaudeController(resume=saved_session_id, skip_permissions=True)
ctrl.start()
result = ctrl.send("What is the project codename?")
print(result.result_text if result else None)
ctrl.stop()

Lightweight multi-session routing

from claude_node import MultiAgentRouter, AgentNode

with MultiAgentRouter() as router:
    router.add(AgentNode("PM", system_prompt="You are a product manager."))
    router.add(AgentNode("DEV", system_prompt="You are a backend engineer."))
    router.start_all()

    pm_reply = router.send("PM", "Design a JWT login feature.")
    dev_reply = router.route(
        pm_reply or "",
        to="DEV",
        wrap="PM proposal:\n{message}\n\nPlease review technical feasibility.",
    )

    print("PM:", pm_reply)
    print("DEV:", dev_reply)

Public API

The current public surface is intentionally small:

from claude_node import (
    ClaudeController,
    ClaudeMessage,
    MultiAgentRouter,
    AgentNode,
)

`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.

It currently provides:

named node registration,
bulk start / stop,
send to one named agent,
message wrapping and routing,
simple parallel fan-out,
access to an underlying controller via get_ctrl().

This is a lightweight primitive layer, not a full orchestration framework.

Current architecture

claude_node/
├── __init__.py       # Public exports
├── controller.py     # ClaudeController, ClaudeMessage
├── router.py        # AgentNode, MultiAgentRouter
├── runtime.py       # Binary discovery and version checking
└── exceptions.py    # Typed exception hierarchy

`controller.py`

Contains:

ClaudeMessage
ClaudeController
_send_lock for serializing concurrent send calls

`router.py`

Contains:

AgentNode
MultiAgentRouter

`runtime.py`

Binary discovery and version introspection:

find_claude_binary(cli_path) — resolve CLI path via shutil.which
get_claude_version(binary_path) — read version from --version
check_claude_available(cli_path) — raises ClaudeBinaryNotFound if missing

`exceptions.py`

Typed exception hierarchy (all inherit from ClaudeError → RuntimeError):

ClaudeBinaryNotFound — claude binary not in PATH
ClaudeStartupError — subprocess failed to start
ClaudeTimeoutError — operation exceeded timeout
ClaudeSendConflictError — concurrent send to same controller

The codebase is intentionally compact. The long-term direction is to keep the library narrow and dependable, not large and feature-heavy.

The protocol this library is built on

claude-node communicates with Claude Code through newline-delimited JSON over stdin/stdout.

Typical launch shape:

claude --input-format stream-json --output-format stream-json --verbose

Typical input shape:

{"type":"user","message":{"role":"user","content":[{"type":"text","text":"your message"}]}}

Typical output flow per turn:

system/init — appears on initial startup and includes session metadata
assistant — may include thinking, text, and tool_use blocks
user/tool_result — emitted by the CLI after internal tool execution
result — the turn is complete; this is the main synchronization point

The most important rule is simple:

Wait for type=result before sending the next message.

That rule is the backbone of the current implementation.

Session model

The repository currently supports:

new sessions,
explicit resume via resume=<session_id>,
implicit “continue most recent” via continue_session=True,
session forking via controller.fork() — creates a new controller resuming the current session.

Recommended practice

In multi-session or multi-node environments, prefer:

explicit resume=<session_id>

and avoid depending on:

--continue

because --continue resumes the most recent session in the working directory rather than the exact session you intend.

Important note

The README you are reading is intentionally honest about the current code:

resume exists now,
continue_session exists now,
fork() exists now — creates a new controller resuming the current session.

Current status and known limitations

This repository is functional and in alpha state.

What works now

persistent Claude subprocess control,
multi-turn sessions,
result waiting,
assistant / tool result parsing,
basic session resume,
session forking via controller.fork(),
lightweight router patterns,
controller-level send serialization (_send_lock),
structured exception hierarchy (ClaudeError, ClaudeBinaryNotFound, etc.),
runtime discovery (claude_node.runtime),
transcript / JSONL export (transcript_path parameter).

Current limitations

send() timeout returns None rather than raising ClaudeTimeoutError (partial exception integration),
integration tests require a working local claude binary and are opt-in (see CONTRIBUTING.md).

This is why the project should currently be described as alpha.

For the full list of known limitations, see docs/06-roadmap-and-limitations.md.

docs/00-index.md — documentation index
docs/01-positioning.md — project identity and scope
docs/02-architecture.md — architecture and internal boundaries
docs/03-api-reference.md — API reference based on the current code
docs/04-protocol.md — stream-json protocol notes
docs/05-development.md — repository workflow and testing reality
docs/06-roadmap-and-limitations.md — current gaps and next steps

Runnable examples

All examples are in examples/:

examples/demo_end_to_end.py — library usage reference (all core APIs)
examples/demo_cli_native_features.py — CLI-native capabilities (skills, callbacks, transcript)
examples/demo_protocol_trace.py — raw stream-json protocol reference

See examples/README.md for the full demo map.

Contributing

See CONTRIBUTING.md for contribution guidelines, testing instructions, and scope boundaries.

License

Apache-2.0