ensemble-claude 0.3.0__py3-none-any.whl

ensemble/__init__.py

@@ -0,0 +1,5 @@
+"""Ensemble AI Orchestration - Multi-agent orchestration for Claude Code."""
+
+__version__ = "0.3.0"
+__author__ = "Ensemble Team"
+

ensemble/ack.py

@@ -0,0 +1,86 @@
+"""
+ACK（受領確認）機構
+
+タスク配信の確認をファイルベースで行う。
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from pathlib import Path
+
+from ensemble.lock import atomic_write
+
+
+class AckManager:
+    """
+    ACK管理クラス
+
+    タスク配信後、エージェントからの受領確認を管理する。
+    """
+
+    def __init__(self, ack_dir: Path | None = None) -> None:
+        """
+        ACKマネージャを初期化する
+
+        Args:
+            ack_dir: ACKファイル保存ディレクトリ（デフォルト: queue/ack/）
+        """
+        self.ack_dir = ack_dir if ack_dir else Path("queue/ack")
+        self.ack_dir.mkdir(parents=True, exist_ok=True)
+
+    def send(self, task_id: str, agent: str) -> None:
+        """
+        ACKを送信する
+
+        Args:
+            task_id: タスクID
+            agent: ACKを送信したエージェント名
+        """
+        ack_file = self.ack_dir / f"{task_id}.ack"
+        content = f"{agent}\n{datetime.now().isoformat()}\n"
+        atomic_write(str(ack_file), content)
+
+    def wait(self, task_id: str, timeout: float = 30.0, interval: float = 0.1) -> bool:
+        """
+        ACKを待機する
+
+        Args:
+            task_id: タスクID
+            timeout: タイムアウト秒数
+            interval: ポーリング間隔
+
+        Returns:
+            ACK受信時True、タイムアウト時False
+        """
+        ack_file = self.ack_dir / f"{task_id}.ack"
+        elapsed = 0.0
+
+        while elapsed < timeout:
+            if ack_file.exists():
+                return True
+            time.sleep(interval)
+            elapsed += interval
+
+        return False
+
+    def check(self, task_id: str) -> bool:
+        """
+        ACKが存在するか確認する
+
+        Args:
+            task_id: タスクID
+
+        Returns:
+            ACK存在時True
+        """
+        ack_file = self.ack_dir / f"{task_id}.ack"
+        return ack_file.exists()
+
+    def cleanup(self) -> None:
+        """
+        全てのACKファイルを削除する
+        """
+        for ack_file in self.ack_dir.glob("*.ack"):
+            ack_file.unlink()

ensemble/cli.py

@@ -0,0 +1,31 @@
+"""Ensemble CLI - AI Orchestration Tool for Claude Code."""
+
+import click
+
+from ensemble import __version__
+from ensemble.commands.init import init
+from ensemble.commands.launch import launch
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="ensemble")
+def cli() -> None:
+    """Ensemble - AI Orchestration Tool for Claude Code.
+
+    Ensemble provides multi-agent orchestration for complex development tasks,
+    enabling parallel execution, automatic code review, and self-improvement.
+    """
+    pass
+
+
+cli.add_command(init)
+cli.add_command(launch)
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

ensemble/commands/__init__.py

@@ -0,0 +1 @@
+"""Ensemble CLI commands."""

ensemble/commands/_init_impl.py

@@ -0,0 +1,208 @@
+"""Implementation of the ensemble init command."""
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from ensemble.templates import get_template_path
+
+
+def run_init(full: bool = False, force: bool = False) -> None:
+    """Run the init command implementation.
+
+    Args:
+        full: If True, copy all agent definitions locally.
+        force: If True, overwrite existing files.
+    """
+    project_root = Path.cwd()
+    ensemble_dir = project_root / ".ensemble"
+
+    click.echo(f"Initializing Ensemble in {project_root}")
+
+    # Create directory structure
+    _create_directories(ensemble_dir)
+
+    # Create CLAUDE.md or append Ensemble section
+    _setup_claude_md(project_root, force)
+
+    # Update .gitignore
+    _update_gitignore(project_root)
+
+    # Create initial dashboard
+    _create_dashboard(ensemble_dir)
+
+    # Create panes.env placeholder
+    _create_panes_env(ensemble_dir)
+
+    # If --full, copy agent definitions
+    if full:
+        _copy_agent_definitions(project_root, force)
+
+    click.echo(click.style("Ensemble initialized successfully!", fg="green"))
+    click.echo("\nNext steps:")
+    click.echo("  1. Run 'ensemble launch' to start the tmux session")
+    click.echo("  2. Use '/go <task>' to begin orchestration")
+
+
+def _create_directories(ensemble_dir: Path) -> None:
+    """Create the .ensemble directory structure."""
+    dirs = [
+        ensemble_dir,
+        ensemble_dir / "queue" / "conductor",
+        ensemble_dir / "queue" / "tasks",
+        ensemble_dir / "queue" / "reports",
+        ensemble_dir / "queue" / "ack",
+        ensemble_dir / "status",
+    ]
+
+    for dir_path in dirs:
+        dir_path.mkdir(parents=True, exist_ok=True)
+        click.echo(f"  Created {dir_path.relative_to(ensemble_dir.parent)}")
+
+
+def _setup_claude_md(project_root: Path, force: bool) -> None:
+    """Create or update CLAUDE.md with Ensemble section."""
+    claude_md = project_root / "CLAUDE.md"
+    ensemble_section = '''
+## Ensemble AI Orchestration
+
+This project uses Ensemble for AI-powered development orchestration.
+
+### Quick Start
+- `/go <task>` - Start a task with automatic planning and execution
+- `/go-light <task>` - Lightweight execution for simple changes
+- `/status` - View current progress
+
+### Communication Protocol
+- Agent communication via file-based queue (.ensemble/queue/)
+- Dashboard updates in .ensemble/status/dashboard.md
+
+For more information, see the [Ensemble documentation](https://github.com/ChikaKakazu/ensemble).
+'''
+
+    if claude_md.exists():
+        content = claude_md.read_text()
+        if "## Ensemble AI Orchestration" in content:
+            if force:
+                # Remove existing section and re-add
+                lines = content.split("\n")
+                new_lines = []
+                skip = False
+                for line in lines:
+                    if line.startswith("## Ensemble AI Orchestration"):
+                        skip = True
+                        continue
+                    if skip and line.startswith("## "):
+                        skip = False
+                    if not skip:
+                        new_lines.append(line)
+                content = "\n".join(new_lines)
+            else:
+                click.echo("  CLAUDE.md already contains Ensemble section (use --force to overwrite)")
+                return
+
+        # Append Ensemble section
+        with open(claude_md, "a") as f:
+            f.write(ensemble_section)
+        click.echo("  Updated CLAUDE.md with Ensemble section")
+    else:
+        # Create new CLAUDE.md
+        with open(claude_md, "w") as f:
+            f.write(f"# {project_root.name}\n")
+            f.write(ensemble_section)
+        click.echo("  Created CLAUDE.md")
+
+
+def _update_gitignore(project_root: Path) -> None:
+    """Update .gitignore with Ensemble exclusions."""
+    gitignore = project_root / ".gitignore"
+    ensemble_ignores = """
+# Ensemble
+.ensemble/queue/
+.ensemble/panes.env
+"""
+
+    if gitignore.exists():
+        content = gitignore.read_text()
+        if "# Ensemble" in content:
+            click.echo("  .gitignore already contains Ensemble section")
+            return
+        with open(gitignore, "a") as f:
+            f.write(ensemble_ignores)
+        click.echo("  Updated .gitignore")
+    else:
+        with open(gitignore, "w") as f:
+            f.write(ensemble_ignores.strip() + "\n")
+        click.echo("  Created .gitignore")
+
+
+def _create_dashboard(ensemble_dir: Path) -> None:
+    """Create initial dashboard.md."""
+    dashboard = ensemble_dir / "status" / "dashboard.md"
+    content = """# Ensemble Dashboard
+
+## Current Task
+None
+
+## Execution Status
+| Pane/Worktree | Status | Agent | Progress |
+|---|---|---|---|
+| - | idle | - | - |
+
+## Recent Completed Tasks
+| Task | Result | Completed |
+|------|--------|-----------|
+| - | - | - |
+
+---
+*Last updated: -
+"""
+    dashboard.write_text(content)
+    click.echo("  Created status/dashboard.md")
+
+
+def _create_panes_env(ensemble_dir: Path) -> None:
+    """Create panes.env placeholder."""
+    panes_env = ensemble_dir / "panes.env"
+    content = """# Ensemble pane IDs (auto-generated by launch)
+# This file will be populated when 'ensemble launch' is run
+"""
+    panes_env.write_text(content)
+    click.echo("  Created panes.env placeholder")
+
+
+def _copy_agent_definitions(project_root: Path, force: bool) -> None:
+    """Copy agent definitions to local .claude/agents/."""
+    click.echo("\nCopying agent definitions for local customization...")
+
+    claude_agents_dir = project_root / ".claude" / "agents"
+    claude_agents_dir.mkdir(parents=True, exist_ok=True)
+
+    template_agents = get_template_path("agents")
+    if not template_agents.exists():
+        click.echo(click.style("  Warning: Agent templates not found", fg="yellow"))
+        return
+
+    for agent_file in template_agents.glob("*.md"):
+        dest = claude_agents_dir / agent_file.name
+        if dest.exists() and not force:
+            click.echo(f"  Skipped {agent_file.name} (exists, use --force to overwrite)")
+            continue
+        shutil.copy(agent_file, dest)
+        click.echo(f"  Copied {agent_file.name}")
+
+    # Also copy commands
+    claude_commands_dir = project_root / ".claude" / "commands"
+    claude_commands_dir.mkdir(parents=True, exist_ok=True)
+
+    template_commands = get_template_path("commands")
+    if template_commands.exists():
+        for cmd_file in template_commands.glob("*.md"):
+            dest = claude_commands_dir / cmd_file.name
+            if dest.exists() and not force:
+                click.echo(f"  Skipped {cmd_file.name} (exists)")
+                continue
+            shutil.copy(cmd_file, dest)
+            click.echo(f"  Copied {cmd_file.name}")

ensemble/commands/_launch_impl.py

@@ -0,0 +1,217 @@
+"""Implementation of the ensemble launch command."""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from ensemble.templates import get_template_path
+
+
+def run_launch(session: str = "ensemble", attach: bool = True) -> None:
+    """Run the launch command implementation.
+
+    Args:
+        session: Name of the tmux session.
+        attach: Whether to attach to the session after creation.
+    """
+    # Check prerequisites
+    if not _check_tmux():
+        click.echo(click.style("Error: tmux is not installed or not in PATH", fg="red"))
+        sys.exit(1)
+
+    if not _check_claude():
+        click.echo(click.style("Error: claude CLI is not installed or not in PATH", fg="red"))
+        click.echo("Install Claude Code from: https://claude.ai/code")
+        sys.exit(1)
+
+    # Check if session already exists
+    if _session_exists(session):
+        click.echo(f"Session '{session}' already exists.")
+        if attach:
+            click.echo(f"Attaching to existing session...")
+            _attach_session(session)
+        return
+
+    project_root = Path.cwd()
+    ensemble_dir = project_root / ".ensemble"
+
+    # Verify project is initialized
+    if not ensemble_dir.exists():
+        click.echo(click.style("Error: Project not initialized for Ensemble", fg="red"))
+        click.echo("Run 'ensemble init' first")
+        sys.exit(1)
+
+    click.echo(f"Launching Ensemble session '{session}'...")
+
+    # Get agent paths
+    agents = _resolve_agent_paths(project_root)
+
+    # Create tmux session with layout
+    _create_session(session, project_root, agents)
+
+    # Save pane IDs
+    _save_pane_ids(session, ensemble_dir)
+
+    click.echo(click.style("Ensemble session started!", fg="green"))
+
+    if attach:
+        _attach_session(session)
+
+
+def _check_tmux() -> bool:
+    """Check if tmux is available."""
+    return shutil.which("tmux") is not None
+
+
+def _check_claude() -> bool:
+    """Check if claude CLI is available."""
+    return shutil.which("claude") is not None
+
+
+def _session_exists(session: str) -> bool:
+    """Check if a tmux session exists."""
+    result = subprocess.run(
+        ["tmux", "has-session", "-t", session],
+        capture_output=True,
+    )
+    return result.returncode == 0
+
+
+def _attach_session(session: str) -> None:
+    """Attach to an existing tmux session."""
+    os.execvp("tmux", ["tmux", "attach-session", "-t", session])
+
+
+def _resolve_agent_paths(project_root: Path) -> dict[str, Path]:
+    """Resolve agent definition paths with priority.
+
+    Priority order:
+    1. Local project: ./.claude/agents/
+    2. Global config: ~/.config/ensemble/agents/
+    3. Package templates
+    """
+    agents = {}
+    agent_names = ["conductor", "dispatch", "worker", "reviewer", "security-reviewer", "integrator", "learner"]
+
+    local_agents = project_root / ".claude" / "agents"
+    global_agents = Path.home() / ".config" / "ensemble" / "agents"
+    template_agents = get_template_path("agents")
+
+    for name in agent_names:
+        filename = f"{name}.md"
+
+        # Check local first
+        local_path = local_agents / filename
+        if local_path.exists():
+            agents[name] = local_path
+            continue
+
+        # Check global
+        global_path = global_agents / filename
+        if global_path.exists():
+            agents[name] = global_path
+            continue
+
+        # Fall back to template
+        template_path = template_agents / filename
+        if template_path.exists():
+            agents[name] = template_path
+
+    return agents
+
+
+def _create_session(session: str, project_root: Path, agents: dict[str, Path]) -> None:
+    """Create the tmux session with Ensemble layout."""
+    # Create new session (detached)
+    subprocess.run(
+        [
+            "tmux", "new-session",
+            "-d",
+            "-s", session,
+            "-c", str(project_root),
+            "-n", "main",
+        ],
+        check=True,
+    )
+
+    # Split into 3 panes: Conductor (left), Dashboard (top-right), Dispatch (bottom-right)
+    # First split vertically (creates pane 1 on right)
+    subprocess.run(
+        ["tmux", "split-window", "-t", f"{session}:main", "-h", "-c", str(project_root)],
+        check=True,
+    )
+
+    # Split the right pane horizontally (creates pane 2 at bottom-right)
+    subprocess.run(
+        ["tmux", "split-window", "-t", f"{session}:main.1", "-v", "-c", str(project_root)],
+        check=True,
+    )
+
+    # Set pane titles
+    subprocess.run(["tmux", "select-pane", "-t", f"{session}:main.0", "-T", "conductor"], check=True)
+    subprocess.run(["tmux", "select-pane", "-t", f"{session}:main.1", "-T", "dashboard"], check=True)
+    subprocess.run(["tmux", "select-pane", "-t", f"{session}:main.2", "-T", "dispatch"], check=True)
+
+    # Start Claude in Conductor pane (pane 0)
+    conductor_agent = agents.get("conductor")
+    if conductor_agent:
+        cmd = f"claude --agent {conductor_agent}"
+    else:
+        cmd = "claude"
+    subprocess.run(
+        ["tmux", "send-keys", "-t", f"{session}:main.0", cmd, "Enter"],
+        check=True,
+    )
+
+    # Start dashboard watch in Dashboard pane (pane 1)
+    dashboard_path = project_root / ".ensemble" / "status" / "dashboard.md"
+    subprocess.run(
+        ["tmux", "send-keys", "-t", f"{session}:main.1", f"watch -n 2 cat {dashboard_path}", "Enter"],
+        check=True,
+    )
+
+    # Start Claude in Dispatch pane (pane 2)
+    dispatch_agent = agents.get("dispatch")
+    if dispatch_agent:
+        cmd = f"claude --agent {dispatch_agent}"
+    else:
+        cmd = "claude"
+    subprocess.run(
+        ["tmux", "send-keys", "-t", f"{session}:main.2", cmd, "Enter"],
+        check=True,
+    )
+
+    # Select Conductor pane
+    subprocess.run(["tmux", "select-pane", "-t", f"{session}:main.0"], check=True)
+
+
+def _save_pane_ids(session: str, ensemble_dir: Path) -> None:
+    """Save pane IDs to panes.env file."""
+    # Get pane IDs
+    result = subprocess.run(
+        ["tmux", "list-panes", "-t", f"{session}:main", "-F", "#{pane_index}:#{pane_id}"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+
+    pane_map = {}
+    for line in result.stdout.strip().split("\n"):
+        if ":" in line:
+            idx, pane_id = line.split(":", 1)
+            pane_map[int(idx)] = pane_id
+
+    # Write panes.env
+    panes_env = ensemble_dir / "panes.env"
+    with open(panes_env, "w") as f:
+        f.write("# Ensemble pane IDs (auto-generated)\n")
+        f.write(f"CONDUCTOR_PANE={pane_map.get(0, '%0')}\n")
+        f.write(f"DASHBOARD_PANE={pane_map.get(1, '%1')}\n")
+        f.write(f"DISPATCH_PANE={pane_map.get(2, '%2')}\n")
+
+    click.echo(f"  Saved pane IDs to {panes_env.relative_to(ensemble_dir.parent)}")

ensemble/commands/init.py

@@ -0,0 +1,35 @@
+"""Ensemble init command - Initialize a project for Ensemble."""
+
+from pathlib import Path
+
+import click
+
+
+@click.command()
+@click.option(
+    "--full",
+    is_flag=True,
+    help="Copy all agent definitions to local project for customization.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Overwrite existing configuration files.",
+)
+@click.pass_context
+def init(ctx: click.Context, full: bool, force: bool) -> None:
+    """Initialize the current project for Ensemble.
+
+    This command sets up the necessary directory structure and configuration
+    files for using Ensemble in your project.
+
+    Creates:
+    - .ensemble/ directory with queue/ and status/ subdirectories
+    - Adds Ensemble section to CLAUDE.md (creates if not exists)
+    - Updates .gitignore to exclude queue files
+
+    Use --full to copy all agent definitions locally for customization.
+    """
+    from ensemble.commands._init_impl import run_init
+
+    run_init(full=full, force=force)

ensemble/commands/launch.py

@@ -0,0 +1,32 @@
+"""Ensemble launch command - Start the Ensemble tmux session."""
+
+import click
+
+
+@click.command()
+@click.option(
+    "--session",
+    "-s",
+    default="ensemble",
+    help="Name of the tmux session to create.",
+)
+@click.option(
+    "--attach/--no-attach",
+    default=True,
+    help="Attach to the session after creation.",
+)
+@click.pass_context
+def launch(ctx: click.Context, session: str, attach: bool) -> None:
+    """Launch the Ensemble tmux session.
+
+    This command creates a tmux session with the Conductor, Dispatch,
+    and Dashboard panes configured and ready for orchestration.
+
+    The session will use configuration from (in priority order):
+    1. ./.ensemble/agents/*.md (local project customization)
+    2. ~/.config/ensemble/agents/*.md (global customization)
+    3. Package bundled templates (defaults)
+    """
+    from ensemble.commands._launch_impl import run_launch
+
+    run_launch(session=session, attach=attach)