Metadata-Version: 2.4
Name: maelyclaw-console
Version: 0.1.0
Summary: MaelyClaw Operator Console — TUI dashboard + embedded terminal + web UI
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/maelyai/maelyclaw
Project-URL: Repository, https://github.com/maelyai/maelyclaw
Project-URL: Issues, https://github.com/maelyai/maelyclaw/issues
Keywords: maelyclaw,console,tui,textual,operator,dashboard
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: textual>=8.0
Requires-Dist: textual-serve>=1.1
Requires-Dist: pyte>=0.8
Requires-Dist: rich>=13.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: setuptools>=68.0; extra == "dev"
Requires-Dist: textual-dev; extra == "dev"
Requires-Dist: wheel; extra == "dev"

# MaelyClaw Console

Operator dashboard for MaelyClaw — the autonomous AI coding agent runtime. Provides real-time monitoring of lanes, workers, cycles, and logs with an embedded AI terminal session (Claude Code, Codex, or shell) that has live MCP tools for engine control.

Works as both a **terminal TUI** and a **browser-accessible web UI**.

![Web Screenshot](docs/web-screenshot.png)

## Installation

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/) (recommended) or `pipx`.

Install from PyPI:

```bash
uv tool install maelyclaw-console
# or
pipx install maelyclaw-console
```

If you already installed the Node package from npm, you can also run:

```bash
maelyclaw console-install
```

For local development from a git checkout:

```bash
# From the maelyclaw repo root:
./console/install.sh
```

This creates a venv, installs dependencies, and symlinks `maelyclaw-console` and `maelyclaw-web` into `bin/` at the repo root.

Alternatively, install manually:

```bash
cd console
uv venv .venv
uv pip install -e ".[dev]" -p .venv
```

## Usage

### Terminal TUI

```bash
maelyclaw-console --provider claude
```

### Web UI (browser)

```bash
maelyclaw-web --provider claude
```

Opens at `http://localhost:9090`. Each browser tab gets its own session. The AI conversation persists across browser refreshes via `--continue` / `resume --last`.

### Options

| Flag | Default | Description |
|------|---------|-------------|
| `--provider` | From config | `claude`, `codex`, or `shell` |
| `--socket` | `/tmp/maelyclaw.sock` | Engine IPC socket path |
| `--config` | `~/.maelyclaw/maelyclaw.config.json` | Config file |
| `--log-file` | From config | Log file to tail. Defaults to `logging.dir/maelyclaw.log` or `<stateDir>/logs/maelyclaw.log` |
| `--tmux` | Off (TUI) / On (web) | Persistent terminal via tmux |
| `--port` | 9090 | Web UI port (web only) |
| `--host` | 0.0.0.0 | Web UI bind address (web only) |

## Layout

```
+------------------------------------------+
| ✦ maelyclaw  ● ▲ 2h15m           idle   |
|   Ctrl+o panels  F2-F5 jump  F1 help    |
+----------+-------------------------------+
| Lanes    | Operator Terminal             |
|  ✓ closer|  Claude Code / Codex / shell  |
|  ▶ health|  with MaelyClaw MCP tools     |
|  — plan  |                               |
+----------+                               |
| Cycle    |  "check engine status"        |
|  042 exec|  "disable lane-improve"       |
+----------+  "kill worker QA-038"         |
| Workers  |                               |
|  ▶ QA-042|                               |
|  ● fix   |                               |
+----------+-------------------------------+
| Logs                          ⤢ Enter / l|
|  [04-10 14:32] sched executing health    |
|  [04-10 14:33] QA-042 All tests passed   |
+------------------------------------------+
```

## Keybindings

### Navigation (work everywhere, including inside the terminal)

| Key | Action |
|-----|--------|
| `Ctrl+o` | Cycle to next panel |
| `F2`-`F5` | Jump to panel (Lanes, Cycle, Workers, Terminal) |
| `F1` | Help overlay |

### Outside the terminal

| Key | Action |
|-----|--------|
| `Tab` / `Shift+Tab` | Cycle panels |
| `1`-`4` | Jump to panel |
| `h` | Help |
| `q` | Quit |
| `r` | Force refresh engine data |
| `e` / `d` | Enable / disable selected lane |
| `k` | Kill selected worker |
| `Enter` | Expand focused panel to full-screen modal |
| `l` | Expand logs with search and filter |

### Inside the terminal

All keys go to the embedded CLI session. Use `Ctrl+o` or `F2`-`F5` to navigate out.

## Panels

### Lanes
Shows all scheduled lanes with status icons (▶ running, ✓ done, ✗ failed, ○ disabled, — never run), next cron minute, and duration. Use `e`/`d` to enable/disable.

### Cycle
Current cycle details: ID, label, branch, Linear issue, queue items with completion state, pending actions. Scrollable with mouse wheel.

### Workers
Active and recent workers sorted by state (running first). Shows task name and elapsed time. Use `k` to kill. Border title shows active/total count.

### Logs
Color-coded log stream with timestamps. Sources: scheduler (yellow), workers (blue), engine (dim), slack (purple), console (green). Expandable modal with search and source filtering.

### Operator Terminal
Embedded PTY running Claude Code, Codex, or a shell. Auto-discovers MaelyClaw MCP tools for status, sessions, work-state, lane control, memory ops, log ops, spawn/kill workers, messages, and gate checks. On first launch, the AI introduces itself and suggests actions based on current engine state.

## Configuration

The console reads `~/.maelyclaw/maelyclaw.config.json`:

```json
{
  "agentDir": "/path/to/agent/workspace",
  "targetRepoDir": "/path/to/target/repo",
  "stateDir": "/path/to/state",
  "logging": {
    "dir": "/path/to/state/logs"
  },
  "defaults": {
    "conversation": {
      "provider": "claude",
      "model": "opus"
    }
  }
}
```

- `agentDir` — working directory for the terminal session; where `.mcp.json` is generated
- `stateDir` — where `work-state.json` lives (for cycle panel)
- `logging.dir` — optional override for the tailed log directory
- `defaults.conversation.provider` — default `--provider` if not specified on CLI

## Architecture

```
maelyclaw (TypeScript)     — engine, scheduler, workers, IPC server
maelyclaw-mcp (TypeScript) — MCP server (engine + memory + log tools, stdio JSON-RPC)
maelyclaw-console (Python) — TUI dashboard + embedded terminal
maelyclaw-web (Python)     — web UI via textual-serve
```

The console connects to the engine via Unix socket IPC (`/tmp/maelyclaw.sock`), polls every 5s for status updates, and tails the persistent MaelyClaw text log every 200ms. The embedded terminal spawns a PTY process with MCP environment variables so the AI CLI auto-discovers engine tools.

### Key dependencies

- [Textual](https://textual.textualize.io/) — TUI framework with CSS layout, 38+ widgets, and web serving
- [pyte](https://pyte.readthedocs.io/) — Python terminal emulator (ANSI/VT100)
- [textual-serve](https://github.com/Textualize/textual-serve) — serves Textual apps in the browser via WebSocket
- [Rich](https://rich.readthedocs.io/) — terminal rendering (colors, styles, markup)

## Development

```bash
# Run console tests
cd console
.venv/bin/python3 -m pytest maelyclaw_console/tests/ -q

# Or from repo root:
npm run console:test
```

`npm run console:test` bootstraps `console/.venv` automatically if it does not exist yet.

## License

Same as MaelyClaw (see root LICENSE).
