Metadata-Version: 2.4
Name: pyherdr
Version: 0.0.4
Summary: Python desktop and CLI fork of Herdr
Project-URL: Homepage, https://github.com/joselrnz/pyherdr
Project-URL: Repository, https://github.com/joselrnz/pyherdr
Project-URL: Issues, https://github.com/joselrnz/pyherdr/issues
Author: joselrnz
License: AGPL-3.0-or-later
License-File: LICENSE
License-File: NOTICE
Keywords: ai-agents,herdr,multiplexer,terminal,tui
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
Requires-Python: >=3.11
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyte>=0.8
Requires-Dist: pywinpty>=2.0; sys_platform == 'win32'
Requires-Dist: textual>=1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<!-- Banner: PNG via absolute raw URL so it renders on GitHub AND PyPI (relative paths / raw SVG don't render on PyPI). -->
<img src="https://raw.githubusercontent.com/joselrnz/pyherdr/main/assets/banner.png" alt="PyHerdr — herd your terminals · multi-agent multiplexer" width="820">

A terminal multiplexer for AI coding agents — a pure-Python port of herdr.

[![PyPI](https://img.shields.io/badge/pypi-v0.0.4-3775A9.svg)](https://pypi.org/project/pyherdr/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
[![Lint: ruff](https://img.shields.io/badge/lint-ruff-261230.svg)](https://github.com/astral-sh/ruff)
[![Types: mypy](https://img.shields.io/badge/types-mypy-blue.svg)](https://mypy-lang.org/)

</div>

---

PyHerdr runs many shells and AI coding agents side by side in one terminal —
workspaces, tabs, and split panes, each a real pseudo-terminal — with live
agent-status tracking and a mouse-and-keyboard [Textual](https://textual.textualize.io/)
UI. A token-authenticated background server owns the processes, so you can
detach and reattach without losing a session.

## ✨ Features

- **Workspaces · tabs · panes** — split panes in a binary tree (side-by-side or
  stacked), zoom, resize by dragging the divider, drag-free keyboard navigation.
- **Real terminals** — every pane is a live PTY (ConPTY on Windows via
  `pywinpty`, the stdlib `pty` on macOS/Linux) with scrollback.
- **Mouse *and* keyboard** — click tabs/panes, right-click for context menus, a
  clickable bottom action bar, plus a tmux-style `ctrl+b` prefix for everything.
- **Command palette** (`ctrl+b :`) — fuzzy-run any action or your own commands.
- **Live agent status** — per-pane working / blocked / done / idle rollups with
  animated spinners, surfaced in the sidebar and tab bar.
- **📊 Resource monitor** — right-click a pane or workspace → *resource usage*,
  or open *Resource monitor* — a live task-manager of CPU% + RAM per process,
  biggest-first, for one pane, a whole workspace, or every session.
- **Themes** — many built-ins (Catppuccin, Tokyo Night, Gruvbox, One Dark,
  Solarized, Rosé Pine, Kanagawa, …) with live theme + accent switching.
- **Detach / reattach** — the background server keeps panes running; reopen the
  TUI to re-attach. Named sessions via `PYHERDR_SESSION`.
- **Client / server** — newline-delimited JSON over a token-authed local socket;
  a full CLI/API mirrors the UI. Plus cron-scheduled pane commands and git
  worktree helpers.

## 📦 Install

```bash
pip install pyherdr
```

Requires **Python 3.11+**. Runtime deps install automatically: `pydantic`,
`pyte`, `textual`, `psutil`, and `pywinpty` (Windows only).

## 🚀 Quick start

```bash
pyherdr            # launch the terminal UI (same as: pyherdr tui)
```

It starts the background server if needed, opens a workspace with a shell, and
drops you into the UI. From a source checkout, use `python -m pyherdr` instead.

## 🖥️ User Interface Layout

PyHerdr organizes your workspace into a clean, mouse-supported dashboard in your terminal:

```text
┌────────────────────────────────────────────────────────────┐
│ workspace: backend    ~/code/api    [main]                 │
├────────────────────────────────┬───────────────────────────┤
│ SPACES                         │ 1:server  2:tests   [+]   │
│   backend       running        │ +-------+-------+         │
│   frontend      idle           │ |1-1    |1-2    |         │
│                                │ |$ _    |logs   |         │
│ AGENTS                         │ |shell  |run 3% |         │
│   python   server    0.8%      │ +-------+-------+         │
│   node     frontend  2.1%      │                           │
├────────────────────────────────┴───────────────────────────┤
│ ? help    : palette    + tab    theme    detach    quit    │
└────────────────────────────────────────────────────────────┘
```

- **Sidebar (Left):** Manages active workspaces, shows agent status spinners, and displays real-time CPU/RAM resource rollups.
- **Terminal Workspace (Right):** Houses your tabs and split terminal panes (stacked or side-by-side) running live processes.
- **Action Bar (Bottom):** Clickable button hotkeys to trigger standard actions without memorizing keyboard prefix chords.

## ⌨️ Keybindings

Keys go to the focused pane. Press the **prefix `ctrl+b`**, then an action key:

| | Key | Action |
|---|---|---|
| **Panes** | `v` / `-` | split right / down |
| | `h` `j` `k` `l` | focus left / down / up / right |
| | `z` · `r` | zoom · resize mode (then `h/l/j/k`, `esc`) |
| | `m` · `x` | pane menu · close pane |
| | `pgup` / `pgdn` | scroll the pane's scrollback |
| **Tabs** | `c` · `n`/`p` · `1`–`9` | new · next/prev · jump to N |
| | `<` / `>` · `T` · `X` | move left/right · rename · close |
| **Workspaces** | `N` · `w` · `{` / `}` | new (folder picker) · next · move up/down |
| **Global** | `:` · `g` · `s` | command palette · jump to pane · theme |
| | `d` · `?` · `q` | detach · help · quit |

**Mouse:** click tabs/panes, drag a divider to resize, right-click anything for
a menu (including *resource usage*). The bottom **action bar** has clickable
buttons for help, palette, new tab, split, terminal, stats, theme, detach, quit.

## 🧰 CLI

The UI is a client; everything it does is scriptable:

```bash
pyherdr status                         # server + session status
pyherdr workspace create --label api --cwd ~/code
pyherdr tab create --label tests
pyherdr pane create --title logs
pyherdr pane start 1-1 python -i
pyherdr pane send-text 1-1 "print('hi')\n"
pyherdr pane get 1-1                    # pane details incl. live running flag
pyherdr schedule add --cron "*/5 * * * *" --pane 1-1 git fetch
pyherdr server stop
```

## 🗂️ Configuration & state

- Session state: `.pyherdr/session.json` (override with `PYHERDR_STATE_PATH`).
- Server runtime metadata: `.pyherdr/server.json` (override with `PYHERDR_RUNTIME_DIR`).
- Default shell: `PYHERDR_SHELL`, or `terminal.default_shell` in config; extra
  env injected into every pane via `terminal.env`.
- Named sessions: `PYHERDR_SESSION=<name>` isolates state + server per name.

The `.pyherdr/` folder holds the auth token and is git-ignored — never commit it.

## 🛠️ Development

```bash
python -m venv .venv
# Windows:  .\.venv\Scripts\Activate.ps1   |   macOS/Linux:  source .venv/bin/activate
python -m pip install -e ".[dev]"
```

Quality gate (all must pass — CI enforces the same):

```bash
python -m ruff check pyherdr tests
python -m mypy
python -m unittest discover -s tests
```

A pure-Python port of the Rust project herdr —
see [`ARCHITECTURE.md`](ARCHITECTURE.md) for the package structure.

## 🙏 Attribution & license

PyHerdr is a Python port/fork of **herdr**, released under the
**GNU AGPL-3.0-or-later** — the same copyleft terms. See [`LICENSE`](LICENSE) and
[`NOTICE`](NOTICE) for the original project's attribution.
