Metadata-Version: 2.4
Name: pkood
Version: 0.7.0
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

![Pkood Architecture](pkood_diag.png)

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/Windows: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/tal-franji/pkood.git
   cd pkood
   pip install -e .
   ```

4. **Verify and Configure**:
   Run the system check to ensure Tmux is installed and to automatically configure your AI agents (Gemini CLI / Claude Code) to talk to the Pkood control plane:
   ```bash
   pkood test
   ```

## 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 or a specified CLI agent in the given directory and attaches to it immediately.
  ```bash
  pkood start --dir ./my-project --cmd claude
  ```
  *Options:*
  * `--cmd <agent>`: Specify the CLI command to launch (e.g., 'gemini', 'claude'). If omitted, Pkood will auto-detect or fall back to your shell.
  * `--name <name>`: Custom session name (defaults to directory name).
  * `--fg`: Foreground - Runs the agent natively in your current terminal (without Tmux). Pkood will still track its logs and status, but you cannot remotely attach/inject into it.

- **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, IDLE, BLOCKED, or EXITED), and log sizes.
  ```bash
  pkood ls
  ```

- **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
  ```

- **Inject input**:
  Send text directly to a background agent's terminal (e.g. to unblock a prompt).
  ```bash
  pkood inject research-task "y"
  ```

### Key Shortcuts (within a session)
After attaching to the session you can use the following Tmux keys:

- **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)

## Skills and Slash Commands

Pkood can install skills and slash commands for AI agents (Gemini CLI / Claude Code) to allow them to interact with the Pkood control plane.

### Install Skills and Slash Commands

```bash
pkood test
```

### Use the Skills and Slash Commands
Pkood installs custom slash commands into your AI CLI to make fleet management seamless.

*   **View Fleet Status:** Show all active agents, their status, and an intelligent summary of what they are doing.
    ```bash
    /pkood:status
    ```
*   **Review and Unblock:** Triage all currently blocked agents in a single step, presenting a numbered list of pending actions for batch approval.
    ```bash
    /pkood:review
    ```
*   **Auto Review and Unblock:** Automatically act as a Fleet Manager to triage blocked agents. Approves actions that are not obviously dangerous or large refactoring, and rejects others with feedback.
    ```bash
    /pkood:auto
    ```
*   **Spawn a Sub-Agent:** Instruct your current agent to act as a Fleet Manager, parse your request, and spawn a new background agent to handle the task autonomously.
    ```bash
    /pkood:start
    Write a Python script that finds the first 4 perfect numbers.
    ```
*   **Kill an Agent:** Ask your current agent to terminate a specific background task.
    ```bash
    /pkood:kill <agent_name>
    ```

## The AgOps Control Plane (MCP)
This is the internal service used by the skills and slash commands. You do not need to use it directly.


Pkood includes a built-in **Model Context Protocol (MCP)** server. This transforms Pkood from a simple CLI tool into an orchestration layer that your AI agents can use to manage each other.

### Starting the Control Plane
To allow agents to see and interact with the fleet, start the MCP service:
```bash
pkood mcp
```
*(Runs on `http://localhost:8000/sse` by default)*

### What Agents Can Do
Once your agents (like Gemini CLI or Claude Code) are connected to the Pkood MCP, they gain "fleet awareness." You can give them high-level commands like:

*   **Fleet Summarization**: *"Check the logs of all active agents and give me a 1-sentence status report for each."*
*   **Remote Unblocking**: *"I see the 'worker-1' agent is stuck on a confirmation. Send it a 'y' to continue."*
*   **Autonomous Spawning**: *"Once 'data-cleanup' finishes, spawn a new agent to run the 'training-job'."*
*   **Deep Log Analysis**: *"Search through all agent logs for any 'OutOfMemory' errors."*

By exposing the low-level Tmux primitives as structured MCP tools, Pkood enables a recursive, multi-agent development workflow where one "Manager" agent can coordinate a fleet of specialized workers.

## Comparison: Pkood vs. Claude `/batch`

While Claude Code's `/batch` skill is excellent for quick, sequential automation, Pkood is designed for long-running, autonomous operations.

| Feature | Claude `/batch` | Pkood |
| :--- | :--- | :--- |
| **Persistence** | Ephemeral (stops if terminal closes) | **Persistent** (runs in background via Tmux) |
| **Visibility** | Simple progress status | **Full Terminal Attachment** (`pkood attach`) |
| **Context** | Single-session focus | **Fleet-wide awareness** via MCP |
| **Control** | Stop/Start only | **Inject input**, search logs, and manage state |
| **Workflow** | Sequential local tasks | **AgOps Orchestration** (Agents manage agents) |

**Use `/batch`** when you want to automate 10 small local edits in your current session.

**Use Pkood** when you want to run a fleet of independent agents that work autonomously across different projects and require high-level coordination.
