Metadata-Version: 2.4
Name: xmesh-ai
Version: 0.1.1
Summary: An interactive orchestration mesh for Claude Code sessions.
Project-URL: Homepage, https://github.com/glxymesh/xmesh
Project-URL: Repository, https://github.com/glxymesh/xmesh
Project-URL: Issues, https://github.com/glxymesh/xmesh/issues
Author: Abhishek
License-Expression: MIT
License-File: LICENSE
Keywords: agent-sdk,claude,claude-code,cli,orchestration,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: prompt-toolkit>=3.0.43
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: questionary>=2.0.1
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: live
Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'live'
Description-Content-Type: text/markdown

# xmesh

**An interactive orchestration mesh for Claude Code sessions.**

`xmesh` drives multiple Claude Code sessions through the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) 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):

```bash
# 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:

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

<details>
<summary>Other ways to install</summary>

```bash
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.
</details>

### Live runs against real Claude Code sessions

```bash
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)

```bash
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. |
| `update` | Upgrade xmesh to the latest PyPI release (auto-detects uv/pipx/pip). |
| `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.
