openmax 0.1.0__tar.gz

openmax-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.so
+*.pyd
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment / secrets
+.env
+.env.*
+
+# Editors / IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.settings/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# openMax runtime state
+.openmax_state.json
+
+# Coverage / testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

openmax-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cklxx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openmax-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: openmax
+Version: 0.1.0
+Summary: Multi AI Agent orchestration hub — dispatch interactive AI agents across terminal panes
+Project-URL: Homepage, https://github.com/anthropics/openMax
+Project-URL: Repository, https://github.com/anthropics/openMax
+Author: Chen Kailun
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,codex,multi-agent,orchestration,terminal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: claude-agent-sdk>=0.1.0
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# openMax
+The more, the better.

openmax-0.1.0/README.md

@@ -0,0 +1,2 @@
+# openMax
+The more, the better.

openmax-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openmax"
+version = "0.1.0"
+description = "Multi AI Agent orchestration hub — dispatch interactive AI agents across terminal panes"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Chen Kailun" },
+]
+keywords = ["ai", "agent", "orchestration", "multi-agent", "claude", "codex", "terminal"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "claude-agent-sdk>=0.1.0",
+    "click>=8.0",
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/anthropics/openMax"
+Repository = "https://github.com/anthropics/openMax"
+
+[project.scripts]
+openmax = "openmax.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openmax"]

openmax-0.1.0/src/openmax/__init__.py

@@ -0,0 +1,3 @@
+"""openMax - Multi AI Agent orchestration hub."""
+
+__version__ = "0.1.0"

openmax-0.1.0/src/openmax/adapters/__init__.py

@@ -0,0 +1,18 @@
+"""Agent adapters for openMax."""
+
+from openmax.adapters.base import AgentAdapter, AgentCommand
+from openmax.adapters.claude_code import ClaudeCodeAdapter, ClaudeCodePrintAdapter
+from openmax.adapters.codex_adapter import CodexAdapter, CodexExecAdapter
+from openmax.adapters.opencode_adapter import OpenCodeAdapter
+from openmax.adapters.subprocess_adapter import SubprocessAdapter
+
+__all__ = [
+    "AgentAdapter",
+    "AgentCommand",
+    "ClaudeCodeAdapter",
+    "ClaudeCodePrintAdapter",
+    "CodexAdapter",
+    "CodexExecAdapter",
+    "OpenCodeAdapter",
+    "SubprocessAdapter",
+]

openmax-0.1.0/src/openmax/adapters/base.py

@@ -0,0 +1,40 @@
+"""Base adapter for AI agents."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class AgentCommand:
+    """Describes how to launch an agent.
+
+    For interactive agents: `launch_cmd` starts the CLI,
+    then `initial_input` is sent via kaku send-text.
+
+    For non-interactive agents: `launch_cmd` includes the prompt,
+    `initial_input` is None.
+    """
+
+    launch_cmd: list[str]
+    initial_input: str | None = None
+    interactive: bool = True
+
+
+class AgentAdapter(ABC):
+    """Abstract base class for agent adapters."""
+
+    @property
+    @abstractmethod
+    def agent_type(self) -> str:
+        """Identifier for this agent type."""
+        ...
+
+    @property
+    def interactive(self) -> bool:
+        """Whether this agent runs interactively (default True)."""
+        return True
+
+    @abstractmethod
+    def get_command(self, prompt: str, cwd: str | None = None) -> AgentCommand:
+        """Return the command spec to start this agent with the given prompt."""
+        ...

openmax-0.1.0/src/openmax/adapters/claude_code.py

@@ -0,0 +1,47 @@
+"""Claude Code agent adapter."""
+
+from openmax.adapters.base import AgentAdapter, AgentCommand
+
+
+class ClaudeCodeAdapter(AgentAdapter):
+    """Adapter for Claude Code CLI (interactive mode).
+
+    Launches `claude` interactively so the user can see plan mode,
+    tool usage, and token consumption. The initial prompt is sent
+    via kaku send-text.
+    """
+
+    @property
+    def agent_type(self) -> str:
+        return "claude-code"
+
+    def get_command(self, prompt: str, cwd: str | None = None) -> AgentCommand:
+        launch = ["claude"]
+        if cwd:
+            launch.extend(["--add-dir", cwd])
+        return AgentCommand(
+            launch_cmd=launch,
+            initial_input=prompt,
+            interactive=True,
+        )
+
+
+class ClaudeCodePrintAdapter(AgentAdapter):
+    """Adapter for Claude Code in non-interactive (print) mode.
+
+    Used for one-shot tasks where interactive control isn't needed.
+    """
+
+    @property
+    def agent_type(self) -> str:
+        return "claude-code-print"
+
+    @property
+    def interactive(self) -> bool:
+        return False
+
+    def get_command(self, prompt: str, cwd: str | None = None) -> AgentCommand:
+        cmd = ["claude", "-p", prompt]
+        if cwd:
+            cmd.extend(["--add-dir", cwd])
+        return AgentCommand(launch_cmd=cmd, interactive=False)

openmax-0.1.0/src/openmax/adapters/codex_adapter.py

@@ -0,0 +1,36 @@
+"""Codex CLI agent adapter."""
+
+from openmax.adapters.base import AgentAdapter, AgentCommand
+
+
+class CodexAdapter(AgentAdapter):
+    """Adapter for OpenAI Codex CLI (interactive mode)."""
+
+    @property
+    def agent_type(self) -> str:
+        return "codex"
+
+    def get_command(self, prompt: str, cwd: str | None = None) -> AgentCommand:
+        return AgentCommand(
+            launch_cmd=["codex"],
+            initial_input=prompt,
+            interactive=True,
+        )
+
+
+class CodexExecAdapter(AgentAdapter):
+    """Adapter for Codex CLI in non-interactive (exec) mode."""
+
+    @property
+    def agent_type(self) -> str:
+        return "codex-exec"
+
+    @property
+    def interactive(self) -> bool:
+        return False
+
+    def get_command(self, prompt: str, cwd: str | None = None) -> AgentCommand:
+        return AgentCommand(
+            launch_cmd=["codex", "exec", prompt],
+            interactive=False,
+        )

openmax-0.1.0/src/openmax/adapters/opencode_adapter.py

@@ -0,0 +1,18 @@
+"""OpenCode CLI agent adapter."""
+
+from openmax.adapters.base import AgentAdapter, AgentCommand
+
+
+class OpenCodeAdapter(AgentAdapter):
+    """Adapter for OpenCode CLI (interactive mode)."""
+
+    @property
+    def agent_type(self) -> str:
+        return "opencode"
+
+    def get_command(self, prompt: str, cwd: str | None = None) -> AgentCommand:
+        return AgentCommand(
+            launch_cmd=["opencode"],
+            initial_input=prompt,
+            interactive=True,
+        )

openmax-0.1.0/src/openmax/adapters/subprocess_adapter.py

@@ -0,0 +1,52 @@
+"""Generic subprocess agent adapter for arbitrary CLI agents."""
+
+from openmax.adapters.base import AgentAdapter, AgentCommand
+
+
+class SubprocessAdapter(AgentAdapter):
+    """Adapter for any CLI-based agent.
+
+    Supports both interactive and non-interactive modes.
+
+    For interactive: `command_template` is the launch command (no prompt),
+    prompt is sent via send-text.
+
+    For non-interactive: `command_template` may contain `{prompt}` which
+    gets replaced with the actual prompt.
+
+    Examples:
+        # Interactive agent
+        SubprocessAdapter("my-agent", ["my-agent"], interactive=True)
+
+        # Non-interactive agent
+        SubprocessAdapter("my-agent", ["my-agent", "--prompt", "{prompt}"], interactive=False)
+    """
+
+    def __init__(
+        self,
+        name: str,
+        command_template: list[str],
+        is_interactive: bool = True,
+    ) -> None:
+        self._name = name
+        self._command_template = command_template
+        self._interactive = is_interactive
+
+    @property
+    def agent_type(self) -> str:
+        return self._name
+
+    @property
+    def interactive(self) -> bool:
+        return self._interactive
+
+    def get_command(self, prompt: str, cwd: str | None = None) -> AgentCommand:
+        if self._interactive:
+            return AgentCommand(
+                launch_cmd=list(self._command_template),
+                initial_input=prompt,
+                interactive=True,
+            )
+        else:
+            cmd = [part.replace("{prompt}", prompt) for part in self._command_template]
+            return AgentCommand(launch_cmd=cmd, interactive=False)

openmax-0.1.0/src/openmax/cli.py

@@ -0,0 +1,97 @@
+"""CLI entry point for openMax."""
+
+from __future__ import annotations
+
+import os
+import signal
+import sys
+
+import click
+from rich.console import Console
+
+from openmax.kaku import is_kaku_available
+from openmax.lead_agent import run_lead_agent
+from openmax.pane_manager import PaneManager
+
+console = Console()
+
+
+@click.group()
+def main() -> None:
+    """openMax — Multi AI Agent orchestration hub."""
+
+
+@main.command()
+@click.argument("task")
+@click.option("--cwd", default=None, help="Working directory for agents")
+@click.option("--model", default=None, help="Model for the lead agent")
+@click.option("--max-turns", default=50, type=int, help="Max agent loop turns")
+def run(task: str, cwd: str | None, model: str | None, max_turns: int) -> None:
+    """Decompose TASK and dispatch sub-agents in Kaku panes."""
+    if cwd is None:
+        cwd = os.getcwd()
+
+    if not is_kaku_available():
+        console.print("[red]Error: kaku CLI not available. Run inside Kaku terminal.[/red]")
+        raise SystemExit(1)
+
+    with PaneManager() as pane_mgr:
+        # Register signal handlers so Ctrl-C / kill also cleans up
+        def _cleanup_and_exit(signum, frame):
+            console.print("\n[yellow]Interrupted — cleaning up panes...[/yellow]")
+            pane_mgr.cleanup_all()
+            console.print("[green]All managed panes closed.[/green]")
+            sys.exit(130 if signum == signal.SIGINT else 143)
+
+        signal.signal(signal.SIGINT, _cleanup_and_exit)
+        signal.signal(signal.SIGTERM, _cleanup_and_exit)
+
+        plan = run_lead_agent(
+            task=task,
+            pane_mgr=pane_mgr,
+            cwd=cwd,
+            model=model,
+            max_turns=max_turns,
+        )
+
+        # Session complete — show final summary before cleanup
+        summary = pane_mgr.summary()
+        console.print(
+            f"\n[bold green]Done.[/bold green] "
+            f"{len(plan.subtasks)} sub-tasks | "
+            f"{summary['windows']} windows | "
+            f"{summary['done']} done"
+        )
+        console.print("[dim]Closing managed panes...[/dim]")
+
+    # __exit__ runs cleanup_all here
+    console.print("[green]All managed panes closed.[/green]")
+
+
+@main.command()
+def panes() -> None:
+    """List all kaku panes."""
+    if not is_kaku_available():
+        console.print("[red]kaku CLI not available.[/red]")
+        raise SystemExit(1)
+
+    all_panes = PaneManager.list_all_panes()
+    console.print(f"[bold]Found {len(all_panes)} panes:[/bold]")
+    for p in all_panes:
+        active = " [green]★[/green]" if p.is_active else ""
+        console.print(
+            f"  Pane {p.pane_id}: {p.title or '(untitled)'} "
+            f"[dim]({p.cols}x{p.rows})[/dim]{active}"
+        )
+
+
+@main.command("read-pane")
+@click.argument("pane_id", type=int)
+def read_pane(pane_id: int) -> None:
+    """Read the text content of a specific pane."""
+    mgr = PaneManager()
+    try:
+        text = mgr.get_text(pane_id)
+        console.print(text)
+    except RuntimeError as e:
+        console.print(f"[red]{e}[/red]")

openmax-0.1.0/src/openmax/kaku.py

@@ -0,0 +1,28 @@
+"""Kaku terminal integration — thin convenience wrappers.
+
+Most pane management goes through PaneManager.
+This module provides standalone utility functions for quick operations.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+
+def get_current_pane_id() -> int | None:
+    """Get the pane ID of the current terminal (from WEZTERM_PANE env)."""
+    import os
+    pane = os.environ.get("WEZTERM_PANE")
+    return int(pane) if pane else None
+
+
+def is_kaku_available() -> bool:
+    """Check if the kaku CLI is available."""
+    try:
+        result = subprocess.run(
+            ["kaku", "cli", "list"],
+            capture_output=True, text=True, timeout=5,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False

openmax-0.1.0/src/openmax/lead_agent.py

@@ -0,0 +1,359 @@
+"""Lead Agent — orchestration via claude-agent-sdk with custom tools.
+
+Custom tools (dispatch_agent, read_pane_output, etc.) run in-process
+via SDK MCP server. The lead agent uses ClaudeSDKClient for interactive
+multi-turn orchestration.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+import anyio
+from rich.console import Console
+from rich.panel import Panel
+
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ClaudeSDKClient,
+    ResultMessage,
+    TextBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    create_sdk_mcp_server,
+    tool,
+)
+
+from openmax.pane_manager import PaneManager
+
+console = Console()
+
+
+# ── Data types ────────────────────────────────────────────────────
+
+
+class TaskStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    DONE = "done"
+    ERROR = "error"
+
+
+@dataclass
+class SubTask:
+    name: str
+    agent_type: str
+    prompt: str
+    status: TaskStatus = TaskStatus.PENDING
+    pane_id: int | None = None
+
+
+@dataclass
+class PlanResult:
+    goal: str
+    subtasks: list[SubTask] = field(default_factory=list)
+
+
+# ── System prompt ─────────────────────────────────────────────────
+
+SYSTEM_PROMPT = """\
+You are the Lead Agent of openMax, a multi-AI-agent orchestration system.
+You operate as a project manager following a strict management lifecycle:
+
+## Phase 1: Align Goal
+- Clarify the user's intent. Restate the goal precisely.
+- Identify constraints, scope boundaries, and success criteria.
+
+## Phase 2: Plan & Decompose
+- Break the goal into concrete, parallelizable sub-tasks.
+- For each sub-task, decide which agent type is best suited.
+
+## Phase 3: Dispatch
+- Use the `dispatch_agent` tool to assign each sub-task to an agent.
+- Each agent runs interactively in its own terminal pane.
+
+## Phase 4: Monitor & Correct
+- Use `read_pane_output` to check each agent's progress.
+- If an agent is stuck or off-track, use `send_text_to_pane` to intervene.
+- Use `mark_task_done` when a task is finished.
+
+## Phase 5: Summarize & Report
+- When all tasks are done, use `report_completion` to finalize.
+- Provide a summary of what was accomplished.
+
+## Available agent types:
+- "claude-code": Claude Code CLI — best for most coding tasks. Supports plan mode, interactive editing, full tool access.
+- "codex": OpenAI Codex CLI — good for code generation and review.
+- "opencode": OpenCode CLI — alternative coding assistant.
+- "generic": Falls back to interactive claude session.
+
+## Important:
+- Each agent runs interactively in a kaku terminal pane — users can click in and intervene.
+- Be decisive. Dispatch agents quickly after planning.
+- Monitor actively — read pane output to check progress.
+- Correct course when agents drift from the goal.
+"""
+
+
+# ── Tool definitions ──────────────────────────────────────────────
+
+# These are module-level so they can capture the shared state via closure
+_pane_mgr: PaneManager | None = None
+_plan: PlanResult | None = None
+_cwd: str = ""
+
+
+@tool(
+    "dispatch_agent",
+    "Dispatch a sub-task to an AI agent by opening a new interactive terminal pane. Returns the pane_id.",
+    {
+        "task_name": str,
+        "agent_type": str,
+        "prompt": str,
+    },
+)
+async def dispatch_agent(args: dict[str, Any]) -> dict[str, Any]:
+    from openmax.adapters import (
+        ClaudeCodeAdapter,
+        CodexAdapter,
+        OpenCodeAdapter,
+        SubprocessAdapter,
+    )
+
+    adapters = {
+        "claude-code": ClaudeCodeAdapter(),
+        "codex": CodexAdapter(),
+        "opencode": OpenCodeAdapter(),
+        "generic": SubprocessAdapter("generic", ["claude"]),
+    }
+
+    task_name = args["task_name"]
+    agent_type = args.get("agent_type", "claude-code")
+    prompt = args["prompt"]
+
+    adapter = adapters.get(agent_type, adapters["generic"])
+    cmd_spec = adapter.get_command(prompt, cwd=_cwd)
+
+    pane = _pane_mgr.spawn_window(
+        command=cmd_spec.launch_cmd,
+        purpose=f"subtask: {task_name}",
+        agent_type=agent_type,
+        cwd=_cwd,
+    )
+
+    # For interactive agents, send the initial prompt after CLI starts
+    if cmd_spec.interactive and cmd_spec.initial_input:
+        await anyio.sleep(3)
+        _pane_mgr.send_text(pane.pane_id, cmd_spec.initial_input)
+
+    subtask = SubTask(
+        name=task_name,
+        agent_type=agent_type,
+        prompt=prompt,
+        status=TaskStatus.RUNNING,
+        pane_id=pane.pane_id,
+    )
+    _plan.subtasks.append(subtask)
+
+    console.print(
+        f"  [green]✓[/green] Dispatched [bold]{task_name}[/bold] "
+        f"→ pane {pane.pane_id} ({agent_type})"
+    )
+
+    return {
+        "content": [
+            {
+                "type": "text",
+                "text": json.dumps({
+                    "status": "dispatched",
+                    "pane_id": pane.pane_id,
+                    "agent_type": agent_type,
+                    "task_name": task_name,
+                }),
+            }
+        ]
+    }
+
+
+@tool(
+    "read_pane_output",
+    "Read the current terminal output of an agent pane to check progress.",
+    {"pane_id": int},
+)
+async def read_pane_output(args: dict[str, Any]) -> dict[str, Any]:
+    pane_id = args["pane_id"]
+    try:
+        text = _pane_mgr.get_text(pane_id)
+        lines = text.splitlines()
+        if len(lines) > 150:
+            text = "\n".join(lines[-150:])
+        return {"content": [{"type": "text", "text": text}]}
+    except RuntimeError as e:
+        return {"content": [{"type": "text", "text": f"Error: {e}"}]}
+
+
+@tool(
+    "send_text_to_pane",
+    "Send text/instructions to an agent pane, as if typed by the user. Use to give follow-up instructions or intervene.",
+    {"pane_id": int, "text": str},
+)
+async def send_text_to_pane(args: dict[str, Any]) -> dict[str, Any]:
+    pane_id = args["pane_id"]
+    text = args["text"]
+    _pane_mgr.send_text(pane_id, text + "\n")
+    console.print(f"  [yellow]→[/yellow] Sent to pane {pane_id}: {text[:80]}")
+    return {"content": [{"type": "text", "text": f"Sent to pane {pane_id}"}]}
+
+
+@tool(
+    "list_managed_panes",
+    "List all managed panes and their current states.",
+    {},
+)
+async def list_managed_panes(args: dict[str, Any]) -> dict[str, Any]:
+    _pane_mgr.refresh_states()
+    summary = _pane_mgr.summary()
+    return {"content": [{"type": "text", "text": json.dumps(summary, ensure_ascii=False)}]}
+
+
+@tool(
+    "mark_task_done",
+    "Mark a sub-task as completed.",
+    {"task_name": str},
+)
+async def mark_task_done(args: dict[str, Any]) -> dict[str, Any]:
+    task_name = args["task_name"]
+    for st in _plan.subtasks:
+        if st.name == task_name:
+            st.status = TaskStatus.DONE
+            console.print(f"  [green]✓✓[/green] [bold]{task_name}[/bold] done")
+            return {"content": [{"type": "text", "text": f"Marked '{task_name}' as done"}]}
+    return {"content": [{"type": "text", "text": f"Task '{task_name}' not found"}]}
+
+
+@tool(
+    "report_completion",
+    "Report overall goal completion percentage and summary. Call when all tasks are done.",
+    {"completion_pct": int, "notes": str},
+)
+async def report_completion(args: dict[str, Any]) -> dict[str, Any]:
+    pct = args["completion_pct"]
+    notes = args["notes"]
+    console.print(Panel(
+        f"[bold]Completion: {pct}%[/bold]\n{notes}",
+        title="Progress Report",
+        border_style="cyan",
+    ))
+    return {"content": [{"type": "text", "text": f"Reported {pct}% — {notes}"}]}
+
+
+# ── Run the lead agent ────────────────────────────────────────────
+
+
+def run_lead_agent(
+    task: str,
+    pane_mgr: PaneManager,
+    cwd: str,
+    model: str | None = None,
+    max_turns: int = 50,
+) -> PlanResult:
+    """Run the lead agent synchronously (wraps async)."""
+    return anyio.run(_run_lead_agent_async, task, pane_mgr, cwd, model, max_turns)
+
+
+async def _run_lead_agent_async(
+    task: str,
+    pane_mgr: PaneManager,
+    cwd: str,
+    model: str | None,
+    max_turns: int,
+) -> PlanResult:
+    global _pane_mgr, _plan, _cwd
+
+    _pane_mgr = pane_mgr
+    _plan = PlanResult(goal=task)
+    _cwd = cwd
+
+    # Create SDK MCP server with our tools
+    server = create_sdk_mcp_server(
+        name="openmax",
+        version="0.1.0",
+        tools=[
+            dispatch_agent,
+            read_pane_output,
+            send_text_to_pane,
+            list_managed_panes,
+            mark_task_done,
+            report_completion,
+        ],
+    )
+
+    tool_names = [
+        "mcp__openmax__dispatch_agent",
+        "mcp__openmax__read_pane_output",
+        "mcp__openmax__send_text_to_pane",
+        "mcp__openmax__list_managed_panes",
+        "mcp__openmax__mark_task_done",
+        "mcp__openmax__report_completion",
+    ]
+
+    options = ClaudeAgentOptions(
+        system_prompt=SYSTEM_PROMPT,
+        mcp_servers={"openmax": server},
+        allowed_tools=tool_names,
+        disallowed_tools=[
+            "Read", "Write", "Edit", "Bash", "Glob", "Grep",
+            "Agent", "NotebookEdit", "WebFetch", "WebSearch",
+        ],
+        max_turns=max_turns,
+        cwd=cwd,
+        permission_mode="bypassPermissions",
+        env={"CLAUDECODE": ""},
+    )
+    if model:
+        options.model = model
+
+    prompt = (
+        f"Goal: {task}\n\n"
+        f"Working directory: {cwd}\n\n"
+        "Proceed through the management lifecycle:\n"
+        "1. Align goal\n"
+        "2. Plan & decompose\n"
+        "3. Dispatch agents\n"
+        "4. Monitor & correct\n"
+        "5. Summarize & report"
+    )
+
+    console.print(Panel(
+        f"[bold]Goal:[/bold] {task}",
+        title="openMax Lead Agent",
+        border_style="blue",
+    ))
+
+    async with ClaudeSDKClient(options=options) as client:
+        await client.query(prompt)
+
+        async for msg in client.receive_response():
+            if isinstance(msg, AssistantMessage):
+                for block in msg.content:
+                    if isinstance(block, TextBlock) and block.text.strip():
+                        console.print(block.text)
+                    elif isinstance(block, ToolUseBlock):
+                        console.print(f"  [dim]⚙ {block.name}[/dim]")
+            elif isinstance(msg, ResultMessage):
+                cost = msg.total_cost_usd or 0
+                console.print(Panel(
+                    f"Cost: ${cost:.4f}\n"
+                    f"Duration: {msg.duration_ms / 1000:.1f}s\n"
+                    f"Turns: {msg.num_turns}",
+                    title="Lead Agent Summary",
+                    border_style="green",
+                ))
+
+    return _plan

openmax-0.1.0/src/openmax/pane_manager.py

@@ -0,0 +1,369 @@
+"""Kaku pane manager — tracks all panes created by openMax."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from urllib.parse import unquote, urlparse
+
+
+def _wrap_command_clean_env(command: list[str]) -> list[str]:
+    """Wrap a command to run without CLAUDECODE env var.
+
+    This prevents 'nested session' errors when spawning
+    Claude Code in new kaku panes.
+    """
+    return ["env", "-u", "CLAUDECODE", "-u", "CLAUDE_CODE_ENTRYPOINT"] + command
+
+
+class PaneState(str, Enum):
+    IDLE = "idle"
+    RUNNING = "running"
+    DONE = "done"
+    ERROR = "error"
+
+
+@dataclass
+class ManagedPane:
+    """A pane managed by openMax."""
+
+    pane_id: int
+    window_id: int | None
+    purpose: str  # e.g. "lead-agent", "subtask: Write components"
+    agent_type: str  # e.g. "claude-code", "codex"
+    state: PaneState = PaneState.IDLE
+    created_at: float = field(default_factory=time.time)
+
+
+@dataclass
+class KakuPaneInfo:
+    """Raw pane info from kaku cli list."""
+
+    window_id: int
+    tab_id: int
+    pane_id: int
+    workspace: str
+    rows: int
+    cols: int
+    title: str
+    cwd: str
+    is_active: bool
+    is_zoomed: bool
+    cursor_visibility: str
+
+
+class PaneManager:
+    """Manages kaku windows and panes for openMax."""
+
+    def __init__(self) -> None:
+        self._managed: dict[int, ManagedPane] = {}
+        self._windows: set[int] = set()  # window IDs we created
+
+    @property
+    def panes(self) -> dict[int, ManagedPane]:
+        return dict(self._managed)
+
+    @property
+    def active_count(self) -> int:
+        return sum(1 for p in self._managed.values() if p.state == PaneState.RUNNING)
+
+    @property
+    def idle_panes(self) -> list[ManagedPane]:
+        return [p for p in self._managed.values() if p.state == PaneState.IDLE]
+
+    @property
+    def managed_windows(self) -> set[int]:
+        return set(self._windows)
+
+    # ── Kaku CLI wrappers ──────────────────────────────────────────
+
+    @staticmethod
+    def list_all_panes() -> list[KakuPaneInfo]:
+        """List all kaku panes (not just managed ones)."""
+        result = subprocess.run(
+            ["kaku", "cli", "list", "--format", "json"],
+            capture_output=True, text=True,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"kaku cli list failed: {result.stderr}")
+        raw = json.loads(result.stdout)
+        panes = []
+        for p in raw:
+            cwd = p.get("cwd", "")
+            if cwd.startswith("file://"):
+                cwd = unquote(urlparse(cwd).path)
+            panes.append(KakuPaneInfo(
+                window_id=p["window_id"],
+                tab_id=p["tab_id"],
+                pane_id=p["pane_id"],
+                workspace=p.get("workspace", ""),
+                rows=p["size"]["rows"],
+                cols=p["size"]["cols"],
+                title=p.get("title", ""),
+                cwd=cwd,
+                is_active=p.get("is_active", False),
+                is_zoomed=p.get("is_zoomed", False),
+                cursor_visibility=p.get("cursor_visibility", ""),
+            ))
+        return panes
+
+    # ── Window management ──────────────────────────────────────────
+
+    def spawn_window(
+        self,
+        command: list[str],
+        purpose: str,
+        agent_type: str,
+        cwd: str | None = None,
+    ) -> ManagedPane:
+        """Open a NEW window with a command and track it.
+
+        Returns the ManagedPane for the pane in the new window.
+        """
+        args = ["kaku", "cli", "spawn", "--new-window"]
+        if cwd:
+            args.extend(["--cwd", cwd])
+        args.append("--")
+        args.extend(_wrap_command_clean_env(command))
+
+        result = subprocess.run(args, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"kaku spawn --new-window failed: {result.stderr}")
+
+        pane_id = int(result.stdout.strip())
+
+        # Find which window this pane belongs to
+        window_id = self._find_pane_window(pane_id)
+        if window_id is not None:
+            self._windows.add(window_id)
+
+        pane = ManagedPane(
+            pane_id=pane_id,
+            window_id=window_id,
+            purpose=purpose,
+            agent_type=agent_type,
+            state=PaneState.RUNNING,
+        )
+        self._managed[pane_id] = pane
+        return pane
+
+    def spawn_tab(
+        self,
+        command: list[str],
+        purpose: str,
+        agent_type: str,
+        cwd: str | None = None,
+        window_id: int | None = None,
+    ) -> ManagedPane:
+        """Open a new tab (in an existing window or default) and track it."""
+        args = ["kaku", "cli", "spawn"]
+        if window_id is not None:
+            args.extend(["--window-id", str(window_id)])
+        if cwd:
+            args.extend(["--cwd", cwd])
+        args.append("--")
+        args.extend(_wrap_command_clean_env(command))
+
+        result = subprocess.run(args, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"kaku spawn failed: {result.stderr}")
+
+        pane_id = int(result.stdout.strip())
+        win_id = window_id or self._find_pane_window(pane_id)
+
+        pane = ManagedPane(
+            pane_id=pane_id,
+            window_id=win_id,
+            purpose=purpose,
+            agent_type=agent_type,
+            state=PaneState.RUNNING,
+        )
+        self._managed[pane_id] = pane
+        return pane
+
+    def split_pane(
+        self,
+        command: list[str],
+        purpose: str,
+        agent_type: str,
+        direction: str = "right",
+        cwd: str | None = None,
+        target_pane_id: int | None = None,
+    ) -> ManagedPane:
+        """Split an existing pane and track the new one."""
+        args = ["kaku", "cli", "split-pane"]
+        if target_pane_id is not None:
+            args.extend(["--pane-id", str(target_pane_id)])
+        if direction == "right":
+            args.append("--right")
+        elif direction == "left":
+            args.append("--left")
+        elif direction == "bottom":
+            args.append("--bottom")
+        elif direction == "top":
+            args.append("--top")
+        if cwd:
+            args.extend(["--cwd", cwd])
+        args.append("--")
+        args.extend(_wrap_command_clean_env(command))
+
+        result = subprocess.run(args, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"kaku split-pane failed: {result.stderr}")
+
+        pane_id = int(result.stdout.strip())
+        win_id = self._find_pane_window(pane_id)
+
+        pane = ManagedPane(
+            pane_id=pane_id,
+            window_id=win_id,
+            purpose=purpose,
+            agent_type=agent_type,
+            state=PaneState.RUNNING,
+        )
+        self._managed[pane_id] = pane
+        return pane
+
+    # ── Pane I/O ───────────────────────────────────────────────────
+
+    def send_text(self, pane_id: int, text: str, submit: bool = True) -> None:
+        """Send text to a pane as paste, then optionally press Enter to submit.
+
+        Args:
+            pane_id: Target pane.
+            text: Text to send.
+            submit: If True, send a carriage return after the text to trigger
+                    submission (e.g. in interactive CLIs like Claude Code).
+        """
+        content = text.rstrip("\n").rstrip("\r")
+        result = subprocess.run(
+            ["kaku", "cli", "send-text", "--pane-id", str(pane_id), "--", content],
+            capture_output=True, text=True,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"kaku send-text failed: {result.stderr}")
+
+        if submit:
+            # Wait for the CLI to finish processing the pasted text
+            time.sleep(0.5)
+            # Send raw carriage return byte via stdin to trigger Enter
+            result = subprocess.run(
+                ["kaku", "cli", "send-text", "--pane-id", str(pane_id), "--no-paste"],
+                input="\r",
+                capture_output=True, text=True,
+            )
+            if result.returncode != 0:
+                raise RuntimeError(f"kaku send-text (enter) failed: {result.stderr}")
+
+    def get_text(self, pane_id: int, start_line: int | None = None) -> str:
+        """Read text content from a pane."""
+        args = ["kaku", "cli", "get-text", "--pane-id", str(pane_id)]
+        if start_line is not None:
+            args.extend(["--start-line", str(start_line)])
+        result = subprocess.run(args, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise RuntimeError(f"kaku get-text failed: {result.stderr}")
+        return result.stdout
+
+    def activate_pane(self, pane_id: int) -> None:
+        """Focus a pane."""
+        subprocess.run(
+            ["kaku", "cli", "activate-pane", "--pane-id", str(pane_id)],
+            capture_output=True, text=True,
+        )
+
+    def kill_pane(self, pane_id: int) -> None:
+        """Kill a managed pane and remove it from tracking."""
+        subprocess.run(
+            ["kaku", "cli", "kill-pane", "--pane-id", str(pane_id)],
+            capture_output=True, text=True,
+        )
+        self._managed.pop(pane_id, None)
+
+    def set_title(self, pane_id: int, title: str) -> None:
+        """Set the tab title for a pane."""
+        subprocess.run(
+            ["kaku", "cli", "set-tab-title", "--pane-id", str(pane_id), title],
+            capture_output=True, text=True,
+        )
+
+    def set_window_title(self, pane_id: int, title: str) -> None:
+        """Set the window title via a pane in that window."""
+        subprocess.run(
+            ["kaku", "cli", "set-window-title", "--pane-id", str(pane_id), title],
+            capture_output=True, text=True,
+        )
+
+    # ── State management ───────────────────────────────────────────
+
+    def update_state(self, pane_id: int, state: PaneState) -> None:
+        if pane_id in self._managed:
+            self._managed[pane_id].state = state
+
+    def is_pane_alive(self, pane_id: int) -> bool:
+        try:
+            all_panes = self.list_all_panes()
+            return any(p.pane_id == pane_id for p in all_panes)
+        except RuntimeError:
+            return False
+
+    def refresh_states(self) -> None:
+        """Check all managed panes and update states for dead ones."""
+        try:
+            alive_ids = {p.pane_id for p in self.list_all_panes()}
+        except RuntimeError:
+            return
+        for pane_id, pane in list(self._managed.items()):
+            if pane_id not in alive_ids:
+                pane.state = PaneState.DONE
+
+    def summary(self) -> dict:
+        return {
+            "total": len(self._managed),
+            "windows": len(self._windows),
+            "running": sum(1 for p in self._managed.values() if p.state == PaneState.RUNNING),
+            "idle": sum(1 for p in self._managed.values() if p.state == PaneState.IDLE),
+            "done": sum(1 for p in self._managed.values() if p.state == PaneState.DONE),
+            "error": sum(1 for p in self._managed.values() if p.state == PaneState.ERROR),
+            "panes": [
+                {
+                    "pane_id": p.pane_id,
+                    "window_id": p.window_id,
+                    "purpose": p.purpose,
+                    "agent_type": p.agent_type,
+                    "state": p.state.value,
+                }
+                for p in self._managed.values()
+            ],
+        }
+
+    def cleanup_all(self) -> None:
+        """Kill all managed panes and close managed windows."""
+        for pane_id in list(self._managed):
+            self.kill_pane(pane_id)
+        self._windows.clear()
+
+    # ── Context manager ────────────────────────────────────────────
+
+    def __enter__(self) -> "PaneManager":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.cleanup_all()
+        return None
+
+    # ── Internal helpers ───────────────────────────────────────────
+
+    def _find_pane_window(self, pane_id: int) -> int | None:
+        """Find which window a pane belongs to."""
+        try:
+            for p in self.list_all_panes():
+                if p.pane_id == pane_id:
+                    return p.window_id
+        except RuntimeError:
+            pass
+        return None