Metadata-Version: 2.5
Name: python-climax
Version: 0.1.0rc6
Summary: Local browser + MCP surface for coding agents — chat, canvas, multi-agent tabs.
Project-URL: Homepage, https://github.com/sheunaluko/climax
Project-URL: Repository, https://github.com/sheunaluko/climax
Project-URL: Issues, https://github.com/sheunaluko/climax/issues
Author: Sheun Aluko
License: MIT
License-File: LICENSE
Keywords: agent,browser,canvas,chat,claude,cli,codex,local,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=2.0
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# climax

> A local browser + MCP surface for coding agents. Chat, live canvas, and
> multi-agent tabs — all running on your machine, orchestrated by any MCP-
> speaking CLI (Claude Code, codex, gemini, aider, cursor-agent…).

**🌐 [climax.com.mx](https://climax.com.mx)** — hosted UI · **[climax.com.mx/app](https://climax.com.mx/app)** — launch straight into the app (talks to your local backend over CORS)

## Demo

![climax demo: launching a Claude Code agent and watching it author a welcome UI](site/img/hero.gif)

_Real recording: empty state → `+ agent` → Claude Code → agent authors a welcome UI on the canvas.
[Watch the full-quality MP4](site/img/hero.mp4)._

|   |   |
|---|---|
| ![agent-authored HTML rendering on the canvas — a palette generator mini-app](site/img/feat-render.png) | ![live pty terminal in climax showing a running Claude Code session](site/img/feat-pty.png) |
| **Agents render real apps.** One `page_set(html)` call → your idea rendered live in a sandboxed iframe. `postMessage` events pipe back so the agent can react to clicks. | **See the CLI session, live.** The pty terminal streams into an xterm.js panel — thinking, tool calls, output. Type into it, resize it, `Ctrl-C` it. |

## Install

One line:

```bash
curl -fsSL https://climax.com.mx/install.sh | sh
```

Or with pip (pre-release for now — remove `--pre` once `0.1.0` ships):

```bash
pip install --pre python-climax
```

> The PyPI name is `python-climax` because plain `climax` was already
> taken. The command and import name are still `climax`.

Then start it:

```bash
climax
# → http://127.0.0.1:8011
```

Open the URL. Click **+ agent** in the browser to launch a coding agent —
the backend spawns it with an ephemeral MCP config, so nothing to wire up
by hand.

## MCP tools exposed to the agent

| Tool | What it does |
|------|--------------|
| `page_set(html)`     | Replace the canvas with new HTML. |
| `page_append(html)`  | Append an HTML fragment to the canvas. |
| `notify(msg, level)` | Corner toast (info · success · warn). |
| `chat_say(msg)`      | Send an assistant bubble to the chat. |
| `wait(timeout?)`     | Block until the user chats **or** the canvas emits an event. |
| `snapshot_*`         | Save/list/restore/patch canvas snapshots. |
| `telemetry_recent`   | Recent backend events for debugging. |

The canvas iframe can talk back to the agent:

```js
window.parent.postMessage({
  type: 'climax.event',
  name: 'submit',
  data: { /* whatever */ },
}, '*');
```

`wait` returns `{stream:'canvas', name, data, ts}` for canvas events and
`{stream:'chat', msg}` for typed chat. One tool, both surfaces.

## Multi-agent

Every MCP client identifies itself with an `X-Climax-Agent` header. The
browser shows one tab per agent — canvas, chat, and pty terminal each.
Click **+ agent** to launch a new one from a preset (see
`climax/agents.toml`). Bring-your-own preset via `~/.climax/agents.toml`.

## Development

```bash
git clone https://github.com/sheunaluko/climax
cd climax
pip install -e ".[dev]"
climax --host 127.0.0.1 --port 8011
```

Set `PYTHON=/path/to/python ./start.sh` for the convenience launcher
(kills a stale instance on the port first).

## Design notes

- Iframe is `sandbox="allow-scripts allow-forms allow-popups"` — no
  parent-frame access, no cookies. Safe for LLM-authored HTML.
- Backend state is per-agent in-memory; snapshots persist to a local
  SQLite file for offline reference.
- `wait` races both queues so agents never miss input on the wrong
  stream.

## License

MIT — see [LICENSE](LICENSE).
