xmesh-ai 0.1.0

An interactive orchestration mesh for Claude Code sessions.

xmesh

An interactive orchestration mesh for Claude Code sessions.

xmesh drives multiple Claude Code sessions through the Claude Agent SDK and lets you run them three ways — all from one advanced, live terminal UI:

Mode	What it does
chat (interactive)	A persistent, streaming, multi-turn conversation — like a Claude Code chat. Watch the thinking stream live, send follow-up messages, background it and re-attach later.
parallel (fan-out)	Many one-shot sessions at once, bounded by a concurrency cap.
pipeline	Sequential steps; each can inject the previous step's output via {prev}.
resume	Continue any finished session by its SDK session_id.

Chat sessions use the SDK's interactive ClaudeSDKClient (retained context across turns); the one-shot modes use query().

The SDK bundles the claude CLI and runs each session as a subprocess — so you don't install Claude Code separately, but a real claude process is what does the work under the hood.

---

Install

xmesh is a pure-Python CLI published to PyPI (as xmesh-ai) — a universal py3-none-any wheel that installs the same way on Windows, macOS, and Linux (Python 3.10+). The package is xmesh-ai; the command it installs is xmesh.

Install it as an isolated global tool (recommended):

# with uv (any OS)
uv tool install xmesh-ai

# or with pipx (any OS)
pipx install xmesh-ai

That puts an xmesh command on your PATH. Then:

xmesh --mock        # explore the UI in mock mode — no API key needed

Other ways to install

pip install xmesh-ai              # into the active environment/venv
pip install "xmesh-ai[live]"     # + claude-agent-sdk for live runs

On Windows, py -m pip install xmesh-ai also works from PowerShell or cmd.

Live runs against real Claude Code sessions

uv tool install "xmesh-ai[live]" # pulls in claude-agent-sdk (+ bundled CLI)
# set ANTHROPIC_API_KEY in your shell or a local .env file, then:
xmesh                            # LIVE engine auto-detects the key

xmesh reads a .env from the current working directory, so you can drop one next to whatever project you're orchestrating.

No API key and no --mock? xmesh falls back to the simulated engine automatically so the UI is always explorable.

From source (development)

git clone https://github.com/glxymesh/xmesh && cd xmesh
uv sync                  # or: uv sync --extra live --extra dev
uv run xmesh --mock

---

The interactive CLI

A prompt_toolkit REPL with completion, history, and a live status toolbar. Long-running work renders in a Rich live dashboard you can watch and cancel.

xmesh ❯ help

Command	Description
chat [prompt]	Open a live streaming chat session (multi-turn, retains context).
fg <id>	Re-attach a backgrounded chat session.
new [prompt]	Run a one-shot session (guided wizard if no prompt given).
batch	Fan out several prompts in parallel (one per line).
pipeline	Chain steps sequentially; use {prev} to feed the prior step.
resume	Pick a finished session and continue it.
ls	List all sessions.
show s1	Show a session's transcript + metadata.
watch	Re-open the live dashboard.
kill s1 / kill all	Cancel running sessions.
set model claude-sonnet-4-6	Change a setting at runtime.
config	Show current configuration.
mock	Toggle the simulated engine.
clear / quit	Clear screen / exit.

Example: an interactive chat (streaming + multi-turn)

xmesh ❯ chat help me design a rate limiter
chat s1  ● LIVE · uses your subscription ──────────────────────
❯ help me design a rate limiter
 ▏ 💭 ⠹ Considering token-bucket vs sliding-window…     ← thinking streams live (transient)
 ▏ → Read(file=src/limit.py)  ✓ 80 lines
 ▏ Here's a token-bucket approach…                      ← answer streams in
s1 ❯ now add Redis persistence                          ← keep chatting, same context

The conversation flows as plain text — only the active turn streams in a transient region; finished turns commit as clean, borderless scrollback with thinking collapsed to a summary.

Inside a chat:

• Enter sends your message; the turn streams its thinking + tools + answer live.
• Ctrl-C backgrounds the session — it keeps running; fg s1 re-attaches.
• /stop interrupts the current turn · /exit leaves it alive in the background · /close ends it.

A chat stays in the foreground until you background it. Backgrounded sessions keep making progress, and ls shows them all.

Example: fan out three tasks

xmesh ❯ batch
? Enter one prompt per line (these run in parallel):
  Add input validation to the signup form
  Write unit tests for the auth module
  Update the README with the new API
? Name prefix: task

…then watch all three stream live, with per-session turns, tool calls, cost, and elapsed time, plus a roll-up footer.

---

Configuration

Settings resolve in this order: defaults → env / .env → CLI flags → live set commands.

Setting	Env	Flag	Default
model	XMESH_MODEL	--model	claude-opus-4-8
permission mode	XMESH_PERMISSION_MODE	--permission-mode	acceptEdits
working dir	XMESH_WORKDIR	--workdir	cwd
max concurrency	XMESH_MAX_CONCURRENCY	--max-concurrency	4
max turns	XMESH_MAX_TURNS	—	0 (∞)
mock engine	XMESH_MOCK	--mock	off

---

Architecture

xmesh/
  models.py   normalized SessionState / SessionEvent (no SDK types leak out)
  config.py   layered settings
  engine.py   Orchestrator + Runners (SDKRunner | MockRunner)
  ui.py       pure Rich renderables (banner, dashboard, transcript)
  cli.py      prompt_toolkit REPL + questionary wizards + live loop

The SDKRunner flattens the Agent SDK's typed message stream (AssistantMessage, ResultMessage, TextBlock, ToolUseBlock, …) into a small, stable event vocabulary the UI renders. Swapping in MockRunner makes the entire app runnable with zero credentials.