parallel-codex 0.1.2__tar.gz

parallel_codex-0.1.2/.gitignore

@@ -0,0 +1,108 @@
+# Node.js and npm
+node_modules/
+npm-debug.log
+npm-error.log
+yarn-error.log
+yarn.lock
+pnpm-lock.yaml
+.pnpm-store/
+
+# TypeScript
+*.tsbuildinfo
+dist/
+build/
+*.d.ts.map
+.tsc-output/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.hypothesis/
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+*.pyc
+.uv/
+
+# IDE and Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+.project
+.classpath
+.c9/
+*.sublime-workspace
+*.sublime-project
+.tern-port
+.env.local
+.env.*.local
+
+# OS
+Thumbs.db
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Project specific
+.env
+.env.local
+.env.*.local
+.env.production.local
+.env.development.local
+.env.test.local
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
+*.backup
+.cache/
+tmp/
+temp/
+
+# Logs
+logs/
+*.log
+
+# Build artifacts
+.next/
+out/
+
+# Coverage
+coverage/
+.nyc_output/
+
+.agents/

parallel_codex-0.1.2/.python-version

@@ -0,0 +1 @@
+3.11

parallel_codex-0.1.2/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: parallel-codex
+Version: 0.1.2
+Summary: Python toolkit for orchestrating Parallel Codex agents across isolated worktrees.
+Project-URL: Homepage, https://github.com/parallel-codex/parallel-codex
+Project-URL: Issues, https://github.com/parallel-codex/parallel-codex/issues
+Project-URL: Repository, https://github.com/parallel-codex/parallel-codex.git
+Project-URL: Documentation, https://github.com/parallel-codex/parallel-codex/tree/main/packages/python-package
+Author-email: Parallel Codex Team <alejandro.quiros3101@gmail.com>
+License: MIT
+Keywords: agents,automation,codex,git,worktree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# parallel-codex
+
+Python helpers for orchestrating Parallel Codex agents working in isolated Git worktrees. The toolkit offers a typed core module and a small CLI for planning agent worktrees that the TypeScript layer can execute.
+
+## Install
+
+```bash
+uv tool install parallel-codex
+# or: pip install parallel-codex
+```
+
+You’ll get two CLIs:
+- `pcodex` – minimal, cross‑platform helper that manages git worktrees + tmux and can run `codex .`
+- `parallel-codex` – lower-level planner/list/prune for worktree metadata
+
+Prerequisites:
+- `git` and `tmux` on PATH. On Windows without tmux, `pcodex` auto-falls back to `wsl.exe -- tmux ...`.
+- The `codex` command should be available if you use `--run-codex`.
+
+## Commands
+
+- `uv sync` – install dependencies defined in `pyproject.toml`
+- `uv build` – build a wheel and sdist using Hatchling
+- `uv run pytest` – execute the test suite
+- `uv run ruff check .` – lint the codebase
+- `uv run mypy src/` – run type checking with MyPy
+
+## Release Checklist
+
+1. Update the `version` field in `pyproject.toml`.
+2. Commit and push the changes.
+3. Tag the commit with `py-vX.Y.Z` (or `vX.Y.Z`) and push the tag to trigger the GitHub Actions publish workflow.
+4. Confirm the new release appears on [PyPI](https://pypi.org/project/parallel-codex/).
+
+## CLI Usage (quickstart)
+
+```bash
+pcodex up reviewer main --run-codex --attach
+pcodex switch reviewer
+pcodex list
+pcodex prune reviewer --kill-session --remove-dir
+```
+
+## CLI Usage (development, no install)
+
+Run the CLIs without installing the package:
+
+```bash
+uv run src/main.py plan reviewer main --base-dir ./.agents
+# or the single-file helper:
+uv run src/parallel_codex/pcodex.py up reviewer main --run-codex --attach
+```
+
+The published CLIs expose sub-commands:
+
+- `parallel-codex plan <agent> <branch>` – calculate (and optionally materialise) a worktree plan.
+- `parallel-codex list` – list discovered plans inside a base directory.
+- `parallel-codex prune <agent>` – remove stored metadata, with `--prune-dir` to delete the folder entirely.
+- `pcodex up <agent> <branch>` – ensure git worktree, ensure tmux session, optionally run `codex .`, and attach.
+- `pcodex switch <agent>` – switch/attach to the tmux session.
+- `pcodex list` – list worktrees and tmux session state.
+- `pcodex prune <agent> [--kill-session] [--remove-dir]` – kill session and/or remove directory.
+
+Each sub-command accepts `--base-dir` to target a custom location (defaults to `./.agents`).
+
+## Library Usage
+
+Import the helpers in automation scripts:
+
+```python
+from pathlib import Path
+from parallel_codex import plan_worktree
+
+plan = plan_worktree(Path("./agents"), "summariser", "feature/summary")
+print(plan.path)
+```
+
+Or rely on the CLI for quick experiments:
+
+```bash
+uv run parallel-codex summariser feature/summary --base-dir ./agents
+```
+
+The CLI prints a single line summary describing the worktree location, agent name, and branch target.

parallel_codex-0.1.2/README.md

@@ -0,0 +1,84 @@
+# parallel-codex
+
+Python helpers for orchestrating Parallel Codex agents working in isolated Git worktrees. The toolkit offers a typed core module and a small CLI for planning agent worktrees that the TypeScript layer can execute.
+
+## Install
+
+```bash
+uv tool install parallel-codex
+# or: pip install parallel-codex
+```
+
+You’ll get two CLIs:
+- `pcodex` – minimal, cross‑platform helper that manages git worktrees + tmux and can run `codex .`
+- `parallel-codex` – lower-level planner/list/prune for worktree metadata
+
+Prerequisites:
+- `git` and `tmux` on PATH. On Windows without tmux, `pcodex` auto-falls back to `wsl.exe -- tmux ...`.
+- The `codex` command should be available if you use `--run-codex`.
+
+## Commands
+
+- `uv sync` – install dependencies defined in `pyproject.toml`
+- `uv build` – build a wheel and sdist using Hatchling
+- `uv run pytest` – execute the test suite
+- `uv run ruff check .` – lint the codebase
+- `uv run mypy src/` – run type checking with MyPy
+
+## Release Checklist
+
+1. Update the `version` field in `pyproject.toml`.
+2. Commit and push the changes.
+3. Tag the commit with `py-vX.Y.Z` (or `vX.Y.Z`) and push the tag to trigger the GitHub Actions publish workflow.
+4. Confirm the new release appears on [PyPI](https://pypi.org/project/parallel-codex/).
+
+## CLI Usage (quickstart)
+
+```bash
+pcodex up reviewer main --run-codex --attach
+pcodex switch reviewer
+pcodex list
+pcodex prune reviewer --kill-session --remove-dir
+```
+
+## CLI Usage (development, no install)
+
+Run the CLIs without installing the package:
+
+```bash
+uv run src/main.py plan reviewer main --base-dir ./.agents
+# or the single-file helper:
+uv run src/parallel_codex/pcodex.py up reviewer main --run-codex --attach
+```
+
+The published CLIs expose sub-commands:
+
+- `parallel-codex plan <agent> <branch>` – calculate (and optionally materialise) a worktree plan.
+- `parallel-codex list` – list discovered plans inside a base directory.
+- `parallel-codex prune <agent>` – remove stored metadata, with `--prune-dir` to delete the folder entirely.
+- `pcodex up <agent> <branch>` – ensure git worktree, ensure tmux session, optionally run `codex .`, and attach.
+- `pcodex switch <agent>` – switch/attach to the tmux session.
+- `pcodex list` – list worktrees and tmux session state.
+- `pcodex prune <agent> [--kill-session] [--remove-dir]` – kill session and/or remove directory.
+
+Each sub-command accepts `--base-dir` to target a custom location (defaults to `./.agents`).
+
+## Library Usage
+
+Import the helpers in automation scripts:
+
+```python
+from pathlib import Path
+from parallel_codex import plan_worktree
+
+plan = plan_worktree(Path("./agents"), "summariser", "feature/summary")
+print(plan.path)
+```
+
+Or rely on the CLI for quick experiments:
+
+```bash
+uv run parallel-codex summariser feature/summary --base-dir ./agents
+```
+
+The CLI prints a single line summary describing the worktree location, agent name, and branch target.

parallel_codex-0.1.2/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "parallel-codex"
+version = "0.1.2"
+description = "Python toolkit for orchestrating Parallel Codex agents across isolated worktrees."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Parallel Codex Team", email = "alejandro.quiros3101@gmail.com" },
+]
+keywords = ["codex", "automation", "git", "agents", "worktree"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.1.0",
+    "mypy>=1.7.0",
+]
+
+[project.scripts]
+parallel-codex = "parallel_codex.cli:main"
+pcodex = "parallel_codex.pcodex:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/parallel_codex"]
+
+[project.urls]
+Homepage = "https://github.com/parallel-codex/parallel-codex"
+Issues = "https://github.com/parallel-codex/parallel-codex/issues"
+Repository = "https://github.com/parallel-codex/parallel-codex.git"
+Documentation = "https://github.com/parallel-codex/parallel-codex/tree/main/packages/python-package"
+
+[tool.uv]
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.1.0",
+    "mypy>=1.7.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true

parallel_codex-0.1.2/src/main.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from parallel_codex.cli import run
+
+# Convenience entry point for local development. Allows running the CLI via
+# `uv run src/main.py` without installing the package.
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run()

parallel_codex-0.1.2/src/parallel_codex/__init__.py

@@ -0,0 +1,24 @@
+"""Parallel Codex Python toolkit."""
+
+from __future__ import annotations
+
+from .core import (
+    WorktreePlan,
+    ensure_worktree,
+    find_worktree,
+    format_plan,
+    list_worktrees,
+    plan_worktree,
+    prune_worktree,
+)
+
+__all__ = [
+    "WorktreePlan",
+    "plan_worktree",
+    "ensure_worktree",
+    "list_worktrees",
+    "find_worktree",
+    "prune_worktree",
+    "format_plan",
+]
+__version__ = "0.1.1"

parallel_codex-0.1.2/src/parallel_codex/cli.py

@@ -0,0 +1,49 @@
+"""Command-line interface entry point for the Parallel Codex toolkit."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+
+from . import __version__
+from .commands import register as register_commands
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the top-level CLI parser."""
+
+    parser = argparse.ArgumentParser(
+        prog="parallel-codex",
+        description="Utilities for orchestrating Parallel Codex agents",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"parallel-codex {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    register_commands(subparsers)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Return an exit code after executing the requested subcommand."""
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler: Callable[..., int] | None = getattr(args, "handler", None)
+    if handler is None:
+        parser.error("No handler registered for command.")
+    return handler(args)
+
+
+def run(argv: list[str] | None = None) -> None:
+    """Execute the CLI and exit the current process."""
+
+    sys.exit(main(argv))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run()

parallel_codex-0.1.2/src/parallel_codex/commands/__init__.py

@@ -0,0 +1,27 @@
+"""Command modules for the Parallel Codex CLI."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, _SubParsersAction
+from pathlib import Path
+
+
+def add_common_arguments(parser: ArgumentParser) -> None:
+    """Attach arguments shared by multiple subcommands."""
+
+    parser.add_argument(
+        "--base-dir",
+        type=Path,
+        default=Path("./.agents"),
+        help="Directory where agent worktrees are stored (default: ./.agents)",
+    )
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    """Import command modules and register their subparsers."""
+
+    from . import list_worktrees, plan, prune
+
+    plan.register(subparsers)
+    list_worktrees.register(subparsers)
+    prune.register(subparsers)

parallel_codex-0.1.2/src/parallel_codex/commands/list_worktrees.py

@@ -0,0 +1,35 @@
+"""`parallel-codex list` implementation."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+from ..core import format_plan, list_worktrees
+from . import add_common_arguments
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "list",
+        help="List discovered agent worktrees",
+    )
+    add_common_arguments(parser)
+    parser.add_argument(
+        "--agent",
+        help="Filter results to a specific agent name",
+    )
+    parser.set_defaults(handler=execute)
+
+
+def execute(args: Namespace) -> int:
+    plans = list_worktrees(args.base_dir)
+    if args.agent:
+        plans = [plan for plan in plans if plan.name == args.agent]
+
+    if not plans:
+        print("No worktrees found.")
+        return 0
+
+    for plan in plans:
+        print(format_plan(plan))
+    return 0

parallel_codex-0.1.2/src/parallel_codex/commands/plan.py

@@ -0,0 +1,32 @@
+"""`parallel-codex plan` implementation."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+from ..core import ensure_worktree, format_plan, plan_worktree
+from . import add_common_arguments
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "plan",
+        help="Create or update the plan for a Codex agent worktree",
+    )
+    add_common_arguments(parser)
+    parser.add_argument("agent", help="Agent identifier to plan")
+    parser.add_argument("branch", help="Git branch the agent should track")
+    parser.add_argument(
+        "--ensure",
+        action="store_true",
+        help="Materialise the plan by creating the worktree folder and metadata",
+    )
+    parser.set_defaults(handler=execute)
+
+
+def execute(args: Namespace) -> int:
+    plan = plan_worktree(args.base_dir, args.agent, args.branch)
+    if args.ensure:
+        ensure_worktree(plan)
+    print(format_plan(plan))
+    return 0

parallel_codex-0.1.2/src/parallel_codex/commands/prune.py

@@ -0,0 +1,34 @@
+"""`parallel-codex prune` implementation."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace, _SubParsersAction
+
+from ..core import find_worktree, prune_worktree
+from . import add_common_arguments
+
+
+def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
+    parser = subparsers.add_parser(
+        "prune",
+        help="Remove plan metadata (and optionally the worktree directory)",
+    )
+    add_common_arguments(parser)
+    parser.add_argument("agent", help="Agent identifier to prune")
+    parser.add_argument(
+        "--prune-dir",
+        action="store_true",
+        help="Delete the worktree directory in addition to metadata",
+    )
+    parser.set_defaults(handler=execute)
+
+
+def execute(args: Namespace) -> int:
+    plan = find_worktree(args.base_dir, args.agent)
+    if plan is None:
+        print(f"No plan found for agent '{args.agent}'.")
+        return 1
+
+    prune_worktree(plan, remove_path=args.prune_dir)
+    print(f"Pruned plan for agent '{args.agent}'.")
+    return 0

parallel_codex-0.1.2/src/parallel_codex/core.py

@@ -0,0 +1,95 @@
+"""Core functionality for orchestrating Parallel Codex agents."""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+BRANCH_METADATA = ".parallel-codex-branch"
+
+
+@dataclass(slots=True)
+class WorktreePlan:
+    """Describes the desired state for an agent worktree."""
+
+    name: str
+    branch: str
+    path: Path
+
+
+def plan_worktree(base_dir: Path, agent_name: str, branch: str) -> WorktreePlan:
+    """Create a worktree plan rooted within ``base_dir``.
+
+    Args:
+        base_dir: Root directory containing agent worktrees.
+        agent_name: Identifier for the Codex agent.
+        branch: Target git branch for the worktree.
+
+    Returns:
+        A :class:`WorktreePlan` describing the desired worktree placement.
+    """
+
+    worktree_path = base_dir / agent_name
+    return WorktreePlan(name=agent_name, branch=branch, path=worktree_path)
+
+
+def format_plan(plan: WorktreePlan) -> str:
+    """Render a human-friendly summary of a worktree plan."""
+
+    return f"agent={plan.name} branch={plan.branch} path={plan.path}"
+
+
+def ensure_worktree(plan: WorktreePlan) -> None:
+    """Materialise metadata for a planned worktree."""
+
+    plan.path.mkdir(parents=True, exist_ok=True)
+    (plan.path / BRANCH_METADATA).write_text(f"{plan.branch}\n", encoding="utf-8")
+
+
+def list_worktrees(base_dir: Path) -> list[WorktreePlan]:
+    """Enumerate worktree plans stored under ``base_dir``."""
+
+    if not base_dir.exists():
+        return []
+
+    plans: list[WorktreePlan] = []
+    for candidate in base_dir.iterdir():
+        if not candidate.is_dir():
+            continue
+
+        branch = _load_branch(candidate)
+        if branch is None:
+            continue
+        plans.append(WorktreePlan(name=candidate.name, branch=branch, path=candidate))
+
+    return sorted(plans, key=lambda plan: plan.name)
+
+
+def find_worktree(base_dir: Path, agent_name: str) -> WorktreePlan | None:
+    """Return the stored worktree plan for ``agent_name`` if present."""
+
+    candidate = base_dir / agent_name
+    branch = _load_branch(candidate)
+    if branch is None:
+        return None
+    return WorktreePlan(name=agent_name, branch=branch, path=candidate)
+
+
+def prune_worktree(plan: WorktreePlan, *, remove_path: bool = False) -> None:
+    """Remove stored metadata (and optionally the directory) for a plan."""
+
+    branch_file = plan.path / BRANCH_METADATA
+    if branch_file.exists():
+        branch_file.unlink()
+
+    if remove_path and plan.path.exists():
+        shutil.rmtree(plan.path)
+
+
+def _load_branch(path: Path) -> str | None:
+    branch_file = path / BRANCH_METADATA
+    if not branch_file.exists():
+        return None
+    raw = branch_file.read_text(encoding="utf-8").strip()
+    return raw or None

parallel_codex-0.1.2/src/parallel_codex/pcodex.py

@@ -0,0 +1,419 @@
+#!/usr/bin/env python3
+"""
+pcodex - ultra-minimal cross-platform CLI to manage agent worktrees + tmux sessions.
+
+Commands:
+  up <agent> <branch>      Ensure git worktree and tmux session;
+                           optionally run `codex .` and attach/switch.
+  switch <agent>           Switch/attach to tmux session.
+  list                     List worktrees and tmux session status.
+  prune <agent>            Optionally kill tmux session and/or remove the worktree directory.
+
+Requires: git, tmux (or WSL with tmux installed).
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from collections.abc import Iterable
+from pathlib import Path
+
+BRANCH_METADATA = ".parallel-codex-branch"
+DEFAULT_BASE_DIR = Path("./.agents")
+SESSION_PREFIX = "pcx-"
+
+
+def _supports_ansi() -> bool:
+    if os.environ.get("NO_COLOR") or os.environ.get("PCX_NO_COLOR"):
+        return False
+    try:
+        return sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+ANSI = {
+    "reset": "\x1b[0m",
+    "green": "\x1b[32m",
+    "red": "\x1b[31m",
+    "cyan": "\x1b[36m",
+    "dim": "\x1b[2m",
+}
+USE_ANSI = _supports_ansi()
+
+
+def _c(code: str, text: str) -> str:
+    if not USE_ANSI:
+        return text
+    return f"{ANSI.get(code, '')}{text}{ANSI['reset']}"
+
+
+class Spinner:
+    def __init__(self, message: str, done_text: str | None = None):
+        self.message = message
+        self.done_text = done_text or message
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+    def __enter__(self):
+        if not sys.stdout.isatty():
+            print(f"{self.message} …", flush=True)
+            return self
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+        return self
+
+    def _spin(self):
+        i = 0
+        while not self._stop.is_set():
+            frame = self._frames[i % len(self._frames)]
+            line = f"{_c('cyan', frame)} {_c('dim', self.message)}"
+            print(f"\r{line}", end="", flush=True)
+            time.sleep(0.08)
+            i += 1
+
+    def __exit__(self, exc_type, exc, tb):
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=0.2)
+        if sys.stdout.isatty():
+            print("\r", end="")
+        if exc is None:
+            print(f"{_c('green', '✔')} {self.done_text}")
+        else:
+            print(f"{_c('red', '✖')} {self.done_text}")
+        return False
+
+
+def run(
+    cmd: Iterable[str],
+    *,
+    check: bool = True,
+    capture: bool = False,
+    env: dict[str, str] | None = None,
+    cwd: Path | None = None,
+) -> subprocess.CompletedProcess:
+    kwargs = {
+        "check": check,
+        "cwd": str(cwd) if cwd else None,
+        "env": env or os.environ.copy(),
+        "text": True,
+    }
+    if capture:
+        kwargs.update({"stdout": subprocess.PIPE, "stderr": subprocess.PIPE})
+    return subprocess.run(list(cmd), **kwargs)  # type: ignore[arg-type]
+
+
+def which(name: str) -> str | None:
+    return shutil.which(name)
+
+
+class Tmux:
+    def __init__(self, prefix: list[str], path_mapper):
+        self.prefix = prefix
+        self.path_mapper = path_mapper
+
+    def _cmd(self, *args: str) -> list[str]:
+        return [*self.prefix, *args]
+
+    def has_session(self, name: str) -> bool:
+        proc = run(self._cmd("has-session", "-t", name), check=False, capture=True)
+        return proc.returncode == 0
+
+    def new_session(self, name: str, cwd: Path) -> None:
+        run(self._cmd("new-session", "-ds", name, "-c", self.path_mapper(cwd)))
+
+    def send_keys(self, name: str, command: str) -> None:
+        run(self._cmd("send-keys", "-t", name, command, "C-m"))
+
+    def switch_or_attach(self, name: str) -> None:
+        inside_tmux = bool(os.environ.get("TMUX"))
+        if inside_tmux:
+            run(self._cmd("switch-client", "-t", name), check=False)
+        else:
+            run(self._cmd("attach", "-t", name), check=False)
+
+    def kill_session(self, name: str) -> None:
+        run(self._cmd("kill-session", "-t", name), check=False)
+
+
+def _windows_wsl_path(path: Path) -> str:
+    wsl = which("wsl.exe")
+    if wsl:
+        try:
+            proc = run([wsl, "wslpath", "-a", str(path)], capture=True)
+            return proc.stdout.strip()
+        except Exception:
+            pass
+    p = str(path)
+    if len(p) >= 2 and p[1] == ":":
+        drive = p[0].lower()
+        rest = p[2:].replace("\\", "/")
+        return f"/mnt/{drive}{rest if rest.startswith('/') else '/' + rest}"
+    return p.replace("\\", "/")
+
+
+def tmux_strategy(*, prefer_wsl: bool = False) -> Tmux:
+    is_windows = os.name == "nt"
+    native_tmux = which("tmux")
+    wsl = which("wsl.exe")
+    if prefer_wsl and is_windows and wsl:
+        return Tmux(prefix=[wsl, "--", "tmux"], path_mapper=_windows_wsl_path)
+    if native_tmux:
+        return Tmux(prefix=[native_tmux], path_mapper=lambda p: str(p))
+    if is_windows:
+        if wsl:
+            return Tmux(prefix=[wsl, "--", "tmux"], path_mapper=_windows_wsl_path)
+    return Tmux(prefix=["tmux"], path_mapper=lambda p: str(p))
+
+
+def ensure_worktree(repo: Path, base_dir: Path, agent: str, branch: str) -> Path:
+    base_dir.mkdir(parents=True, exist_ok=True)
+    worktree = base_dir / agent
+    if not worktree.exists():
+        worktree.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        run(["git", "-C", str(repo), "worktree", "add", "-B", branch, str(worktree)], check=True)
+    except subprocess.CalledProcessError:
+        pass
+    try:
+        (worktree / BRANCH_METADATA).write_text(f"{branch}\n", encoding="utf-8")
+    except Exception:
+        pass
+    return worktree
+
+
+def read_branch_file(worktree: Path) -> str | None:
+    meta = worktree / BRANCH_METADATA
+    if meta.exists():
+        raw = meta.read_text(encoding="utf-8").strip()
+        return raw or None
+    return None
+
+
+def cmd_up(args: argparse.Namespace) -> int:
+    tmux = tmux_strategy(prefer_wsl=bool(getattr(args, "wsl", False)))
+    session = SESSION_PREFIX + args.agent
+    repo = Path(args.repo).resolve()
+    base_dir = Path(args.base_dir).resolve()
+
+    with Spinner(
+        f"Ensuring worktree for agent '{args.agent}' on '{args.branch}'",
+        "Worktree ensured",
+    ):
+        worktree = ensure_worktree(repo, base_dir, args.agent, args.branch)
+
+    # If we're about to create the session for the first time, try to prepare
+    # the Python environment so jumping into the session is ready to go.
+    needs_session = not tmux.has_session(session)
+    if needs_session and bool(getattr(args, "prep_env", False)):
+        # Detect if tmux will run under WSL so we prep the env in the same OS.
+        is_wsl_tmux = bool(
+            tmux.prefix
+            and os.path.basename(tmux.prefix[0]).lower().startswith("wsl")
+        )
+        if is_wsl_tmux:
+            wsl = tmux.prefix[0]
+            wsl_worktree = _windows_wsl_path(worktree)
+            # Check if uv exists inside WSL
+            uv_present = (
+                run(
+                    [wsl, "--", "bash", "-lc", "command -v uv >/dev/null 2>&1"],
+                    check=False,
+                ).returncode
+                == 0
+            )
+            if uv_present:
+                with Spinner(
+                    "Preparing Python env in WSL (uv sync + install -e)",
+                    "Python env ready",
+                ):
+                    commands = [
+                        f"cd {shlex.quote(wsl_worktree)}",
+                        "uv sync --project packages/python-package",
+                        (
+                            "uv run --project packages/python-package python -m pip install -e "
+                            "packages/python-package"
+                        ),
+                    ]
+                    cmd = " && ".join(commands)
+                    run([wsl, "--", "bash", "-lc", cmd], check=False)
+            else:
+                print(_c("dim", "Tip: 'uv' not found in WSL; skipping dependency sync/install."))
+        else:
+            uv = which("uv")
+            if uv:
+                with Spinner(
+                    "Preparing Python env (uv sync + install -e)",
+                    "Python env ready",
+                ):
+                    # Best-effort; do not fail the whole command if these error
+                    run(
+                        [uv, "sync", "--project", "packages/python-package"],
+                        check=False,
+                        cwd=worktree,
+                    )
+                    run(
+                        [
+                            uv,
+                            "run",
+                            "--project",
+                            "packages/python-package",
+                            "python",
+                            "-m",
+                            "pip",
+                            "install",
+                            "-e",
+                            "packages/python-package",
+                        ],
+                        check=False,
+                        cwd=worktree,
+                    )
+            else:
+                print(_c("dim", "Tip: 'uv' not found on PATH; skipping dependency sync/install."))
+
+    with Spinner(f"Ensuring tmux session '{session}'", "Tmux session ready"):
+        if needs_session:
+            tmux.new_session(session, worktree)
+        if args.run_codex:
+            tmux.send_keys(session, "codex .")
+
+    if args.attach:
+        tmux.switch_or_attach(session)
+    else:
+        print(f"{_c('dim', 'Tip:')} run with --attach to switch/attach to the session.")
+    return 0
+
+
+def cmd_switch(args: argparse.Namespace) -> int:
+    tmux = tmux_strategy(prefer_wsl=bool(getattr(args, "wsl", False)))
+    session = SESSION_PREFIX + args.agent
+    if not tmux.has_session(session):
+        print(_c("red", f"Session '{session}' not found."), file=sys.stderr)
+        return 1
+    tmux.switch_or_attach(session)
+    return 0
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    tmux = tmux_strategy(prefer_wsl=bool(getattr(args, "wsl", False)))
+    base_dir = Path(args.base_dir).resolve()
+    if not base_dir.exists():
+        print("No worktrees found.")
+        return 0
+    any_printed = False
+    for child in sorted(base_dir.iterdir(), key=lambda p: p.name):
+        if not child.is_dir():
+            continue
+        agent = child.name
+        session = SESSION_PREFIX + agent
+        branch = read_branch_file(child) or "?"
+        tmux_up = "up" if tmux.has_session(session) else "down"
+        print(f"agent={agent} branch={branch} path={child} tmux={tmux_up}")
+        any_printed = True
+    if not any_printed:
+        print("No worktrees found.")
+    return 0
+
+
+def cmd_prune(args: argparse.Namespace) -> int:
+    tmux = tmux_strategy(prefer_wsl=bool(getattr(args, "wsl", False)))
+    base_dir = Path(args.base_dir).resolve()
+    worktree = base_dir / args.agent
+    session = SESSION_PREFIX + args.agent
+    if args.kill_session:
+        with Spinner(f"Killing tmux session '{session}'", "Tmux session handled"):
+            tmux.kill_session(session)
+    if args.remove_dir and worktree.exists():
+        with Spinner(f"Removing worktree directory '{worktree}'", "Worktree directory handled"):
+            shutil.rmtree(worktree, ignore_errors=True)
+    print(f"Pruned '{args.agent}'.")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="pcodex", description="Parallel Codex single-file CLI")
+    p.add_argument(
+        "--base-dir",
+        default=str(DEFAULT_BASE_DIR),
+        help="Directory for agent worktrees (default: ./.agents)",
+    )
+    sub = p.add_subparsers(dest="command", required=True)
+
+    up = sub.add_parser("up", help="Ensure worktree + tmux; optionally run codex and attach")
+    up.add_argument("agent")
+    up.add_argument("branch")
+    up.add_argument("--repo", default=".", help="Path to git repo (default: .)")
+    up.add_argument(
+        "--attach",
+        action="store_true",
+        help="Switch/attach to the tmux session after setup",
+    )
+    up.add_argument("--run-codex", action="store_true", help="Send 'codex .' into the tmux session")
+    up.add_argument(
+        "--prep-env",
+        action="store_true",
+        help="Before creating the session, run 'uv sync' and install the package in editable mode",
+    )
+    up.add_argument(
+        "--wsl",
+        action="store_true",
+        help="Force tmux to run via WSL on Windows and run commands inside WSL",
+    )
+    up.set_defaults(handler=cmd_up)
+
+    sw = sub.add_parser("switch", help="Switch/attach to an existing tmux session")
+    sw.add_argument("agent")
+    sw.add_argument(
+        "--wsl",
+        action="store_true",
+        help="Use WSL tmux session (Windows)",
+    )
+    sw.set_defaults(handler=cmd_switch)
+
+    ls = sub.add_parser("list", help="List known agent worktrees and tmux state")
+    ls.add_argument(
+        "--wsl",
+        action="store_true",
+        help="Use WSL tmux instance to query session state (Windows)",
+    )
+    ls.set_defaults(handler=cmd_list)
+
+    pr = sub.add_parser("prune", help="Kill tmux and/or remove a worktree directory")
+    pr.add_argument("agent")
+    pr.add_argument(
+        "--kill-session",
+        action="store_true",
+        help="Kill the tmux session for the agent",
+    )
+    pr.add_argument("--remove-dir", action="store_true", help="Delete the agent worktree directory")
+    pr.add_argument(
+        "--wsl",
+        action="store_true",
+        help="Target a WSL tmux session (Windows)",
+    )
+    pr.set_defaults(handler=cmd_prune)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.error("No handler.")
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+
+

parallel_codex-0.1.2/tests/__init__.py

@@ -0,0 +1 @@
+"""Test package for parallel_codex."""

parallel_codex-0.1.2/tests/test_core.py

@@ -0,0 +1,86 @@
+"""Tests for the Parallel Codex core helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from parallel_codex.core import (
+    BRANCH_METADATA,
+    WorktreePlan,
+    ensure_worktree,
+    find_worktree,
+    format_plan,
+    list_worktrees,
+    plan_worktree,
+    prune_worktree,
+)
+
+
+@pytest.fixture()
+def base_dir(tmp_path: Path) -> Path:
+    target = tmp_path / "agents"
+    target.mkdir()
+    return target
+
+
+def test_plan_worktree_creates_expected_plan(base_dir: Path) -> None:
+    plan = plan_worktree(base_dir, "agent-a", "feature/awesome")
+    assert plan == WorktreePlan(
+        name="agent-a",
+        branch="feature/awesome",
+        path=base_dir / "agent-a",
+    )
+
+
+def test_format_plan(base_dir: Path) -> None:
+    plan = plan_worktree(base_dir, "reviewer", "main")
+    summary = format_plan(plan)
+    assert str(plan.path) in summary
+    assert "agent=reviewer" in summary
+    assert "branch=main" in summary
+
+
+def test_ensure_worktree_creates_metadata(base_dir: Path) -> None:
+    plan = plan_worktree(base_dir, "lint", "lint-branch")
+    ensure_worktree(plan)
+    branch_file = plan.path / BRANCH_METADATA
+    assert branch_file.exists()
+    assert branch_file.read_text(encoding="utf-8").strip() == "lint-branch"
+
+
+def test_list_worktrees_discovers_plans(base_dir: Path) -> None:
+    plan_a = plan_worktree(base_dir, "alpha", "main")
+    plan_b = plan_worktree(base_dir, "beta", "feature/beta")
+    ensure_worktree(plan_a)
+    ensure_worktree(plan_b)
+
+    plans = list_worktrees(base_dir)
+    assert [plan.name for plan in plans] == ["alpha", "beta"]
+
+
+def test_find_worktree_returns_none_when_missing(base_dir: Path) -> None:
+    assert find_worktree(base_dir, "ghost") is None
+
+
+def test_find_worktree_returns_plan_when_present(base_dir: Path) -> None:
+    plan = plan_worktree(base_dir, "alpha", "main")
+    ensure_worktree(plan)
+    found = find_worktree(base_dir, "alpha")
+    assert found == plan
+
+
+def test_prune_worktree_removes_metadata_only(base_dir: Path) -> None:
+    plan = plan_worktree(base_dir, "agent", "branch")
+    ensure_worktree(plan)
+    prune_worktree(plan, remove_path=False)
+    assert not (plan.path / BRANCH_METADATA).exists()
+    assert plan.path.exists()
+
+
+def test_prune_worktree_can_remove_directory(base_dir: Path) -> None:
+    plan = plan_worktree(base_dir, "agent", "branch")
+    ensure_worktree(plan)
+    prune_worktree(plan, remove_path=True)
+    assert not plan.path.exists()