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.
