Metadata-Version: 2.4
Name: pkood
Version: 0.6.1
Summary: An Agentic Operations (AgOps) orchestrator for recursive, parallel development.
Author-email: Tal Franji <tal.franji@gmail.com>
License: CC0-1.0
Project-URL: Homepage, https://github.com/tal-franji/pkood
Project-URL: Bug Tracker, https://github.com/tal-franji/pkood/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]

# Pkood

Run tens of agent sessions (Claude-code / Gemini-CLI) in parallel. Monitor them and attach to them when needed. Get notified when they are blocked and await your input.

## Installation

1. **Requirements**: 
   - Python 3.10+
   - `tmux` (Available via `brew install tmux` on macOS or `sudo apt install tmux` on Linux/WSL2).

2. **Install via PyPI**:
   ```bash
   pip install pkood
   ```

3. **Install from Source**:
   Clone the repository and install in editable mode:
   ```bash
   git clone https://github.com/your-username/pkood.git
   cd pkood
   pip install -e .
   ```

## Operation

Pkood treats AI agents and long-running tasks as managed services. All state is stored in `~/.pkood/`.

### Commands

- **Start an interactive session**:
  Creates a new session running your default shell in the specified directory and attaches to it immediately.
  ```bash
  pkood start --dir ./my-project
  ```
  *Note: The session name defaults to the directory name if `--name` is omitted.*

- **Spawn a background agent**:
  Runs a specific command in a managed background session.
  ```bash
  pkood spawn --name research-task "gemini 'research the latest AgOps trends'"
  ```

- **List active agents**:
  Shows all agents, their current status (RUNNING, BLOCKED, or EXITED), and log sizes.
  ```bash
  pkood ls
  # or
  pkood ps
  ```

- **Attach to a session**:
  Join a running agent's terminal.
  ```bash
  pkood attach research-task
  ```
  *To detach without killing the agent, press `Ctrl+B` then `D`.*

- **Kill an agent**:
  Terminates the session and cleans up associated sockets and state files.
  ```bash
  pkood kill research-task
  ```

### Key Shortcuts (within a session)
- **Detach**: `Ctrl+B` followed by `D`
- **Scroll Mode**: `Ctrl+B` followed by `[` (Press `q` to exit)
- **Force Exit**: `Ctrl+D` (This kills the agent and closes the session)
