pkood 0.7.0

An Agentic Operations (AgOps) orchestrator for recursive, parallel development.

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/Windows:WSL2).

2. Install via PyPI:

   pip install pkood
   

3. Install from Source: Clone the repository and install in editable mode:

   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:

   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.

  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.

  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.

  pkood ls
  

• Attach to a session: Join a running agent's terminal.

  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.

  pkood kill research-task
  

• Inject input: Send text directly to a background agent's terminal (e.g. to unblock a prompt).

  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

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.

  /pkood:status
  

• Review and Unblock: Triage all currently blocked agents in a single step, presenting a numbered list of pending actions for batch approval.

  /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.

  /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.

  /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.

  /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:

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.