maelyclaw-console 0.1.0

MaelyClaw Operator Console — TUI dashboard + embedded terminal + web UI

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.

Installation

Requires Python 3.10+ and uv (recommended) or pipx.

Install from PyPI:

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

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

maelyclaw console-install

For local development from a git checkout:

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

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

Usage

Terminal TUI

maelyclaw-console --provider claude

Web UI (browser)

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:

{
  "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 — TUI framework with CSS layout, 38+ widgets, and web serving
• pyte — Python terminal emulator (ANSI/VT100)
• textual-serve — serves Textual apps in the browser via WebSocket
• Rich — terminal rendering (colors, styles, markup)

Development

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