Metadata-Version: 2.4
Name: python-climax
Version: 0.1.0rc1
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…).

```
┌───────────────────────────────────────────────┐
│  https://local.climax.com.mx:8011             │
│  ┌─────────────────────────────────────────┐  │
│  │                                         │  │
│  │      CANVAS  (sandboxed iframe —        │  │
│  │      agent-authored HTML, live)         │  │
│  │                                         │  │
│  └─────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────┐  │
│  │  Chat  ●  Canvas · Chat                 │  │
│  │  ...conversation with your agent...     │  │
│  │  [ type here                          ] │  │
│  └─────────────────────────────────────────┘  │
└───────────────────────────────────────────────┘
        ↑                        ↑
    WebSocket                  stdio
        ↓                        ↓
    backend  ←──── HTTP ──── mcp_server
```

## Install

One line:

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

Or with pip:

```bash
pip install climax
```

Then start it:

```bash
climax
# → https://local.climax.com.mx: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.

## Why local.climax.com.mx?

Modern browsers won't let a page at `https://climax.com.mx` talk to
`http://localhost`. So climax runs on the loopback address using a real
Let's Encrypt certificate for `local.climax.com.mx` — a public DNS name
that always resolves to `127.0.0.1`. Traffic never leaves your machine,
but the browser sees a valid HTTPS origin.

## 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).
