phalanx-cli 0.1.0__tar.gz

phalanx_cli-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: phalanx-cli
+Version: 0.1.0
+Summary: Open-source, vendor-agnostic multi-agent orchestration CLI
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: libtmux>=0.37
+Requires-Dist: tomli>=2.0; python_version < "3.12"
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"

phalanx_cli-0.1.0/README.md

@@ -0,0 +1,142 @@
+# Phalanx
+
+Open-source, vendor-agnostic multi-agent orchestration CLI.
+
+Phalanx lets you spin up teams of AI coding agents from any supported backend (Cursor, Claude Code, Gemini CLI, Codex CLI) and orchestrate them through a single unified interface.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires: Python 3.11+, tmux.
+
+## Quick Start
+
+```bash
+# Single agent (proxies to your default backend)
+phalanx run "fix the failing tests"
+
+# Create a team of agents
+phalanx create-team --task "refactor auth module" --agents researcher,coder:2,reviewer --json
+
+# Check team status
+phalanx team-status <team-id> --json
+
+# Read results
+phalanx team-result <team-id> --json
+
+# Stop when done
+phalanx stop <team-id>
+```
+
+## IDE Integration
+
+```bash
+phalanx init
+```
+
+Auto-detects installed IDEs and deploys skill files:
+- **Cursor**: `.cursor/rules/phalanx.mdc`
+- **Claude Code**: `.claude/commands/phalanx.md`
+- **Gemini CLI**: `.gemini/phalanx-policy.md`
+- **Codex CLI**: `AGENTS.md`
+
+## Supported Backends
+
+| Backend | Binary | Worktree | Model Routing |
+|---------|--------|----------|---------------|
+| Cursor | `agent` | Native | All vendors |
+| Claude Code | `claude` | Native | Anthropic |
+| Gemini CLI | `gemini` | Phalanx-managed | Google |
+| Codex CLI | `codex` | Phalanx-managed | OpenAI |
+
+## Model Routing
+
+Phalanx automatically selects the best model per agent role and backend. Configurable in `~/.phalanx/config.toml`.
+
+```bash
+phalanx models show           # view routing table
+phalanx models set cursor.coder opus-4.6  # override
+phalanx models reset           # restore defaults
+```
+
+## Agent Roles
+
+| Role | Purpose |
+|------|---------|
+| `researcher` | Investigation, large-context analysis |
+| `coder` | Implementation, bug fixes, tests |
+| `reviewer` | Code review, large diffs |
+| `architect` | Design decisions, high-stakes reasoning |
+| `orchestrator` | Team lead (auto-assigned) |
+
+## Architecture
+
+- **State**: SQLite (WAL mode) at `~/.phalanx/state.db`
+- **Process isolation**: tmux sessions per agent
+- **Artifacts**: Ephemeral JSON (deleted after 24h inactivity)
+- **File locking**: Advisory locks via SQLite
+- **Stall detection**: stream.log monitoring with exponential backoff retry
+- **GC**: Opportunistic, runs on every command
+
+## Commands
+
+### User-Facing
+| Command | Description |
+|---------|-------------|
+| `phalanx run "prompt"` | Single agent session |
+| `phalanx init` | Deploy IDE skill files |
+| `phalanx create-team` | Create agent team |
+| `phalanx team-status <id>` | Team status |
+| `phalanx team-result <id>` | Read team results |
+| `phalanx message <id> "msg"` | Message team lead |
+| `phalanx stop <id>` | Stop team |
+| `phalanx resume <id>` | Resume team |
+| `phalanx status` | List all teams |
+| `phalanx config show/set` | Configuration |
+| `phalanx models show/set/reset/update` | Model routing |
+
+### Agent Tools (used by spawned agents)
+| Command | Description |
+|---------|-------------|
+| `phalanx write-artifact` | Write structured result |
+| `phalanx agent-status` | Check peer status |
+| `phalanx agent-result <id>` | Read peer artifact |
+| `phalanx message-agent <id> "msg"` | Message a worker |
+| `phalanx lock/unlock <path>` | File locking |
+
+## Testing
+
+```bash
+pytest tests/unit/          # 125 unit tests
+pytest tests/integration/   # 26 integration tests (requires tmux)
+pytest tests/e2e/           # 11 end-to-end tests
+pytest tests/               # all 162 tests
+```
+
+## Configuration
+
+Global: `~/.phalanx/config.toml`
+Workspace override: `.phalanx/config.toml`
+
+```toml
+[defaults]
+backend = "cursor"
+
+[timeouts]
+agent_inactivity_minutes = 30
+team_gc_hours = 24
+stall_seconds = 180
+
+[models.cursor]
+orchestrator = "sonnet-4.6"
+coder = "sonnet-4.6"
+researcher = "gemini-3.1-pro"
+default = "gemini-3.1-pro"
+```
+
+## License
+
+MIT

phalanx_cli-0.1.0/phalanx/__init__.py

@@ -0,0 +1,3 @@
+"""Phalanx — open-source, vendor-agnostic multi-agent orchestration CLI."""
+
+__version__ = "0.1.0"

phalanx_cli-0.1.0/phalanx/artifacts/__init__.py

@@ -0,0 +1,16 @@
+"""Artifact system: schema, writer, reader."""
+
+from .schema import Artifact, ArtifactStatus
+from .writer import write_artifact, get_artifact_path, get_stream_log_path
+from .reader import read_artifact, read_team_result, list_artifacts
+
+__all__ = [
+    "Artifact",
+    "ArtifactStatus",
+    "write_artifact",
+    "get_artifact_path",
+    "get_stream_log_path",
+    "read_artifact",
+    "read_team_result",
+    "list_artifacts",
+]

phalanx_cli-0.1.0/phalanx/artifacts/reader.py

@@ -0,0 +1,49 @@
+"""Read artifacts written by agents."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .schema import Artifact
+from .writer import get_artifact_path, TEAMS_DIR
+
+
+def read_artifact(team_id: str, agent_id: str) -> Artifact | None:
+    """Read and validate an agent's artifact. Returns None if not found."""
+    path = get_artifact_path(team_id, agent_id)
+    if not path.exists():
+        return None
+    data = json.loads(path.read_text())
+    return Artifact(**data)
+
+
+def read_team_result(team_id: str) -> Artifact | None:
+    """Read the team lead's artifact (the consolidated team result)."""
+    team_dir = TEAMS_DIR / team_id / "agents"
+    if not team_dir.exists():
+        return None
+
+    for agent_dir in team_dir.iterdir():
+        artifact_path = agent_dir / "artifact.json"
+        if artifact_path.exists():
+            data = json.loads(artifact_path.read_text())
+            if data.get("agent_id", "").startswith("lead"):
+                return Artifact(**data)
+    return None
+
+
+def list_artifacts(team_id: str) -> list[Artifact]:
+    """List all artifacts for a team."""
+    team_dir = TEAMS_DIR / team_id / "agents"
+    if not team_dir.exists():
+        return []
+
+    artifacts = []
+    for agent_dir in sorted(team_dir.iterdir()):
+        artifact_path = agent_dir / "artifact.json"
+        if artifact_path.exists():
+            data = json.loads(artifact_path.read_text())
+            artifacts.append(Artifact(**data))
+    return artifacts

phalanx_cli-0.1.0/phalanx/artifacts/schema.py

@@ -0,0 +1,31 @@
+"""Artifact Pydantic models and validation."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ArtifactStatus(str, Enum):
+    SUCCESS = "success"
+    FAILURE = "failure"
+    ESCALATION = "escalation_required"
+
+
+class TokenUsage(BaseModel):
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_cost_usd: float = 0.0
+
+
+class Artifact(BaseModel):
+    status: ArtifactStatus
+    agent_id: str
+    team_id: str
+    output: dict[str, Any] = Field(default_factory=dict)
+    warnings: list[str] = Field(default_factory=list)
+    token_usage: TokenUsage = Field(default_factory=TokenUsage)
+    created_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())

phalanx_cli-0.1.0/phalanx/artifacts/writer.py

@@ -0,0 +1,64 @@
+"""Atomic artifact writer — used by agents via `phalanx write-artifact`."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .schema import Artifact, ArtifactStatus
+
+
+TEAMS_DIR = Path.home() / ".phalanx" / "teams"
+
+
+def get_artifact_path(team_id: str, agent_id: str) -> Path:
+    return TEAMS_DIR / team_id / "agents" / agent_id / "artifact.json"
+
+
+def get_stream_log_path(team_id: str, agent_id: str) -> Path:
+    return TEAMS_DIR / team_id / "agents" / agent_id / "stream.log"
+
+
+def write_artifact(
+    status: str,
+    output: dict[str, Any],
+    team_id: str | None = None,
+    agent_id: str | None = None,
+    warnings: list[str] | None = None,
+) -> Artifact:
+    """Validate and atomically write an artifact to disk.
+
+    Reads PHALANX_TEAM_ID and PHALANX_AGENT_ID from env if not provided.
+    """
+    team_id = team_id or os.environ.get("PHALANX_TEAM_ID", "")
+    agent_id = agent_id or os.environ.get("PHALANX_AGENT_ID", "")
+
+    if not team_id or not agent_id:
+        raise ValueError("team_id and agent_id are required (set env or pass explicitly)")
+
+    artifact = Artifact(
+        status=ArtifactStatus(status),
+        agent_id=agent_id,
+        team_id=team_id,
+        output=output,
+        warnings=warnings or [],
+    )
+
+    path = get_artifact_path(team_id, agent_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Atomic write: write to temp file then rename
+    fd, tmp_path = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write(artifact.model_dump_json(indent=2))
+        os.replace(tmp_path, str(path))
+    except Exception:
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise
+
+    return artifact

phalanx_cli-0.1.0/phalanx/backends/__init__.py

@@ -0,0 +1,14 @@
+"""Backend adapters for agent CLIs."""
+
+from .base import AgentBackend
+from .registry import detect_available, detect_default, get_backend, list_backends
+from .model_router import resolve_model
+
+__all__ = [
+    "AgentBackend",
+    "detect_available",
+    "detect_default",
+    "get_backend",
+    "list_backends",
+    "resolve_model",
+]

phalanx_cli-0.1.0/phalanx/backends/base.py

@@ -0,0 +1,56 @@
+"""Abstract base class for agent CLI backends."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class AgentBackend(ABC):
+    """Interface every CLI adapter must implement."""
+
+    name: str
+
+    @abstractmethod
+    def build_interactive_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+    ) -> list[str]:
+        """Command for TUI mode (user-facing agent)."""
+
+    @abstractmethod
+    def build_headless_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+        json_output: bool = True,
+        auto_approve: bool = True,
+    ) -> list[str]:
+        """Command for --print / headless mode (team agents in tmux)."""
+
+    @abstractmethod
+    def build_resume_command(
+        self,
+        chat_id: str,
+        message: str | None = None,
+    ) -> list[str]:
+        """Resume an existing session."""
+
+    @abstractmethod
+    def detect(self) -> bool:
+        """Return True if this CLI is installed and available."""
+
+    @abstractmethod
+    def supports_worktree(self) -> bool:
+        """Whether the CLI has native --worktree support."""
+
+    @abstractmethod
+    def binary_name(self) -> str:
+        """The CLI binary name (e.g. 'agent', 'claude')."""

phalanx_cli-0.1.0/phalanx/backends/claude.py

@@ -0,0 +1,74 @@
+"""Claude Code CLI adapter (binary: claude)."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from .base import AgentBackend
+
+
+class ClaudeBackend(AgentBackend):
+    name = "claude"
+
+    def binary_name(self) -> str:
+        return "claude"
+
+    def detect(self) -> bool:
+        return shutil.which("claude") is not None
+
+    def supports_worktree(self) -> bool:
+        return True
+
+    def build_interactive_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+    ) -> list[str]:
+        cmd = ["claude"]
+        if model:
+            cmd += ["--model", model]
+        if worktree:
+            cmd += ["--worktree", worktree]
+        if soul_file:
+            cmd += ["--append-system-prompt", soul_file.read_text()]
+        if prompt:
+            cmd.append(prompt)
+        return cmd
+
+    def build_headless_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+        json_output: bool = True,
+        auto_approve: bool = True,
+    ) -> list[str]:
+        cmd = ["claude", "--print"]
+        if auto_approve:
+            cmd += ["--dangerously-skip-permissions"]
+        if model:
+            cmd += ["--model", model]
+        if worktree:
+            cmd += ["--worktree", worktree]
+        if json_output:
+            cmd += ["--output-format", "stream-json"]
+        if soul_file:
+            cmd += ["--append-system-prompt", soul_file.read_text()]
+        cmd.append(prompt)
+        return cmd
+
+    def build_resume_command(
+        self,
+        chat_id: str,
+        message: str | None = None,
+    ) -> list[str]:
+        cmd = ["claude", "--resume", chat_id, "--print", "--dangerously-skip-permissions"]
+        if message:
+            cmd.append(message)
+        return cmd

phalanx_cli-0.1.0/phalanx/backends/codex.py

@@ -0,0 +1,64 @@
+"""Codex CLI adapter (binary: codex)."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from .base import AgentBackend
+
+
+class CodexBackend(AgentBackend):
+    name = "codex"
+
+    def binary_name(self) -> str:
+        return "codex"
+
+    def detect(self) -> bool:
+        return shutil.which("codex") is not None
+
+    def supports_worktree(self) -> bool:
+        return False
+
+    def build_interactive_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+    ) -> list[str]:
+        cmd = ["codex"]
+        if model:
+            cmd += ["--model", model]
+        cmd += ["--cd", str(workspace)]
+        if prompt:
+            cmd.append(prompt)
+        return cmd
+
+    def build_headless_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+        json_output: bool = True,
+        auto_approve: bool = True,
+    ) -> list[str]:
+        cmd = ["codex", "exec"]
+        if model:
+            cmd += ["--model", model]
+        cmd += ["--cd", str(workspace)]
+        if auto_approve:
+            cmd += ["--sandbox", "workspace-write", "-a", "never"]
+        cmd.append(prompt)
+        return cmd
+
+    def build_resume_command(
+        self,
+        chat_id: str,
+        message: str | None = None,
+    ) -> list[str]:
+        cmd = ["codex", "resume", "--last"]
+        return cmd

phalanx_cli-0.1.0/phalanx/backends/cursor.py

@@ -0,0 +1,72 @@
+"""Cursor CLI adapter (binary: agent)."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from .base import AgentBackend
+
+
+class CursorBackend(AgentBackend):
+    name = "cursor"
+
+    def binary_name(self) -> str:
+        return "agent"
+
+    def detect(self) -> bool:
+        return shutil.which("agent") is not None
+
+    def supports_worktree(self) -> bool:
+        return True
+
+    def build_interactive_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+    ) -> list[str]:
+        cmd = ["agent"]
+        if model:
+            cmd += ["--model", model]
+        if worktree:
+            cmd += ["--worktree", worktree]
+        cmd += ["--workspace", str(workspace)]
+        if prompt:
+            cmd.append(prompt)
+        return cmd
+
+    def build_headless_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+        json_output: bool = True,
+        auto_approve: bool = True,
+    ) -> list[str]:
+        cmd = ["agent", "--print"]
+        if model:
+            cmd += ["--model", model]
+        if worktree:
+            cmd += ["--worktree", worktree]
+        if json_output:
+            cmd += ["--output-format", "stream-json"]
+        cmd += ["--workspace", str(workspace)]
+        if auto_approve:
+            cmd += ["--trust", "--force", "--approve-mcps"]
+        cmd.append(prompt)
+        return cmd
+
+    def build_resume_command(
+        self,
+        chat_id: str,
+        message: str | None = None,
+    ) -> list[str]:
+        cmd = ["agent", "--resume", chat_id, "--print", "--force", "--trust"]
+        if message:
+            cmd.append(message)
+        return cmd

phalanx_cli-0.1.0/phalanx/backends/gemini.py

@@ -0,0 +1,70 @@
+"""Gemini CLI adapter (binary: gemini)."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from .base import AgentBackend
+
+
+class GeminiBackend(AgentBackend):
+    name = "gemini"
+
+    def binary_name(self) -> str:
+        return "gemini"
+
+    def detect(self) -> bool:
+        return shutil.which("gemini") is not None
+
+    def supports_worktree(self) -> bool:
+        return False
+
+    def build_interactive_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+    ) -> list[str]:
+        cmd = ["gemini"]
+        if model:
+            cmd += ["--model", model]
+        if soul_file:
+            cmd += ["--policy", str(soul_file)]
+        if prompt:
+            cmd.append(prompt)
+        return cmd
+
+    def build_headless_command(
+        self,
+        prompt: str,
+        workspace: Path,
+        model: str | None = None,
+        worktree: str | None = None,
+        soul_file: Path | None = None,
+        json_output: bool = True,
+        auto_approve: bool = True,
+    ) -> list[str]:
+        cmd = ["gemini"]
+        if model:
+            cmd += ["--model", model]
+        if json_output:
+            cmd += ["-o", "stream-json"]
+        if soul_file:
+            cmd += ["--policy", str(soul_file)]
+        if auto_approve:
+            cmd += ["--yolo"]
+        cmd += ["-p", prompt]
+        return cmd
+
+    def build_resume_command(
+        self,
+        chat_id: str,
+        message: str | None = None,
+    ) -> list[str]:
+        cmd = ["gemini", "--resume", chat_id, "--yolo"]
+        if message:
+            cmd += ["-p", message]
+        return cmd

phalanx_cli-0.1.0/phalanx/backends/model_router.py

@@ -0,0 +1,15 @@
+"""Config-driven model routing: role + backend → model name."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def resolve_model(backend: str, role: str, config: dict[str, Any]) -> str:
+    """Look up the model for a given backend and role from config.
+
+    Fallback: config[backend][role] → config[backend]["default"].
+    Raises KeyError if the backend section is missing from config.
+    """
+    models = config["models"][backend]
+    return models.get(role, models["default"])