corral-herdr 0.1.0__tar.gz

corral_herdr-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

corral_herdr-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (2026-09-25)
+
+
+### Features
+
+* initial corral release ([cbb4ff1](https://github.com/johnfoland/corral/commit/cbb4ff1dc0e5a169d9c999cd857f77f6ef71d155))
+
+
+### Bug Fixes
+
+* publish to PyPI as corral-herdr ([a6d4cab](https://github.com/johnfoland/corral/commit/a6d4cab405cfacb0444d105bd405a32ae2f9c42c))
+* **tui:** don't crash when a refresh outlives the widgets ([8311947](https://github.com/johnfoland/corral/commit/8311947be4076687ce5b554c0aacfcd81c73aa1f))

corral_herdr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Foland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

corral_herdr-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: corral-herdr
+Version: 0.1.0
+Summary: Round up your projects into herdr workspaces: a utility tab plus model/effort agent tabs, from a CLI or a TUI.
+Project-URL: Homepage, https://github.com/johnfoland/corral
+Project-URL: Changelog, https://github.com/johnfoland/corral/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/johnfoland/corral/issues
+Author-email: John Foland <john@johnfoland.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude,codex,herdr,terminal,tui,workspace
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Requires-Dist: textual<9,>=8
+Description-Content-Type: text/markdown
+
+# corral
+
+Round up your projects into [herdr](https://herdr.dev) workspaces.
+
+corral sets up a herdr workspace for any project under a root directory
+(`~/Code` by default). Each workspace gets a utility tab (file manager, shell
+and git UI by default) and one or more agent tabs, each named for the model
+and effort it runs: `Sonnet•medium`, `Opus•high`, `Codex•xhigh`. Use the TUI
+to browse projects and act with single keys, or the CLI (with `--json`) for
+scripts and coding agents.
+
+```
+┌ corral 0.1.0 ─────────────────────────── ~/Code ┐
+│ ● cEntities        wY  ● Opus xhi  ● Opus hi   develop  │ cruzainet
+│ ○ ▸ Archive/ · 5 repos                                   │ ~/Code/cruzainet
+│ ○ ▾ cruzainet                             master        │
+│ ○   ├─ api                                develop       │ kind     git repo
+│ ○   ├─ web-app                            style/visual… │ nested   8 repos below
+│ ○   └─ specs                              master        │ branch   master
+└ o Open  a Add agent  f Fill  s Stop  x Close WS  / Filter ┘
+```
+
+## Install
+
+Requires Python 3.11+ and herdr 0.8+.
+
+```sh
+uv tool install corral-herdr    # or: pipx install corral-herdr
+brew install johnfoland/tap/corral
+```
+
+The PyPI package is `corral-herdr`; the command it installs is `corral`.
+
+## Use
+
+```sh
+corral                                  # the TUI
+corral up ~/Code/api                    # build the workspace, or focus it if it exists
+corral up ~/Code/api --agent opus/high --agent codex/xhigh
+corral up --fill                        # add whatever tabs the current project's workspace lacks
+corral tab opus/high                    # an agent tab in the workspace you're in
+corral tab sonnet --new                 # another one: Sonnet•medium-2
+corral stop "Opus•high"                 # by tab label, agent name or pane id
+corral close courses --dry-run          # what closing would take with it
+corral ls                               # projects, workspaces, agents
+corral models                           # the model matrix
+```
+
+Every command takes `--json`: the result goes to stdout as JSON, progress to
+stderr. Exit codes: `0` ok, `1` a target failed, `2` usage/config error, `3`
+herdr not running. `--json`, `--root` and `--config` go before or after the
+command (`corral --root ~/Work ls`).
+
+### Projects and labels
+
+Every directory in the root is a project. So is every git repo nested up to
+`scan_depth` levels inside one (`cruzainet/api`), along with the plain folders
+that lead to one (`Archive/AyeAI/`). A project's workspace is labelled with
+its path relative to the root, so two nested repos that share a name don't
+collide. Hidden directories and dependency/build folders (`node_modules`,
+`vendor`, `dist`, …) are skipped.
+
+### TUI keys
+
+| Key | Action |
+|---|---|
+| `o` / enter | open: build the workspace, or switch to it |
+| `a` | add an agent tab: pick a model, then an effort (always a new tab) |
+| `f` / `u` | add any missing tabs / only the utility tab |
+| `s` | stop running agents (pick them) |
+| `F` | force-fill: shows the plan, runs on `y` |
+| `x` | close the workspace: shows what goes with it, runs on `y` |
+| `→` `←` space | unfold / fold / toggle the tree |
+| `/` `g` `q` | filter, refresh, quit |
+
+## Configure
+
+```sh
+corral config init      # writes a commented ~/.config/corral/config.toml
+corral config show      # the settings in effect
+```
+
+The file lives at `$CORRAL_CONFIG`, else `$XDG_CONFIG_HOME/corral/config.toml`,
+else `~/.config/corral/config.toml` (on macOS too). Every key is optional.
+
+```toml
+root = "~/Code"                     # also --root / $CORRAL_ROOT
+scan_depth = 3
+default_agents = ["sonnet/medium"]
+
+[utility]                           # "" = plain shell
+top = "yazi"
+bottom_left = ""
+bottom_right = "lazygit"
+
+[efforts]
+claude = ["low", "medium", "high", "xhigh", "max"]
+
+[[models]]                          # any herdr agent kind: claude, codex, gemini, opencode, ...
+key = "opus"
+tool = "claude"
+display = "Opus"
+args = ["--model", "opus", "--effort", "{effort}"]
+```
+
+## Agent skill
+
+`skills/corral/SKILL.md` teaches coding agents to drive corral through its
+`--json` CLI. The repo is also a Claude Code plugin marketplace:
+
+```
+/plugin marketplace add johnfoland/corral
+/plugin install corral@corral
+```
+
+Or copy `skills/corral` into your agent's skills directory.
+
+## Develop
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+Tests run against an in-memory fake herdr (`tests/fake_herdr.py`); nothing
+touches a real herdr session. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+commit conventions and the release process.
+
+## License
+
+MIT

corral_herdr-0.1.0/README.md

@@ -0,0 +1,132 @@
+# corral
+
+Round up your projects into [herdr](https://herdr.dev) workspaces.
+
+corral sets up a herdr workspace for any project under a root directory
+(`~/Code` by default). Each workspace gets a utility tab (file manager, shell
+and git UI by default) and one or more agent tabs, each named for the model
+and effort it runs: `Sonnet•medium`, `Opus•high`, `Codex•xhigh`. Use the TUI
+to browse projects and act with single keys, or the CLI (with `--json`) for
+scripts and coding agents.
+
+```
+┌ corral 0.1.0 ─────────────────────────── ~/Code ┐
+│ ● cEntities        wY  ● Opus xhi  ● Opus hi   develop  │ cruzainet
+│ ○ ▸ Archive/ · 5 repos                                   │ ~/Code/cruzainet
+│ ○ ▾ cruzainet                             master        │
+│ ○   ├─ api                                develop       │ kind     git repo
+│ ○   ├─ web-app                            style/visual… │ nested   8 repos below
+│ ○   └─ specs                              master        │ branch   master
+└ o Open  a Add agent  f Fill  s Stop  x Close WS  / Filter ┘
+```
+
+## Install
+
+Requires Python 3.11+ and herdr 0.8+.
+
+```sh
+uv tool install corral-herdr    # or: pipx install corral-herdr
+brew install johnfoland/tap/corral
+```
+
+The PyPI package is `corral-herdr`; the command it installs is `corral`.
+
+## Use
+
+```sh
+corral                                  # the TUI
+corral up ~/Code/api                    # build the workspace, or focus it if it exists
+corral up ~/Code/api --agent opus/high --agent codex/xhigh
+corral up --fill                        # add whatever tabs the current project's workspace lacks
+corral tab opus/high                    # an agent tab in the workspace you're in
+corral tab sonnet --new                 # another one: Sonnet•medium-2
+corral stop "Opus•high"                 # by tab label, agent name or pane id
+corral close courses --dry-run          # what closing would take with it
+corral ls                               # projects, workspaces, agents
+corral models                           # the model matrix
+```
+
+Every command takes `--json`: the result goes to stdout as JSON, progress to
+stderr. Exit codes: `0` ok, `1` a target failed, `2` usage/config error, `3`
+herdr not running. `--json`, `--root` and `--config` go before or after the
+command (`corral --root ~/Work ls`).
+
+### Projects and labels
+
+Every directory in the root is a project. So is every git repo nested up to
+`scan_depth` levels inside one (`cruzainet/api`), along with the plain folders
+that lead to one (`Archive/AyeAI/`). A project's workspace is labelled with
+its path relative to the root, so two nested repos that share a name don't
+collide. Hidden directories and dependency/build folders (`node_modules`,
+`vendor`, `dist`, …) are skipped.
+
+### TUI keys
+
+| Key | Action |
+|---|---|
+| `o` / enter | open: build the workspace, or switch to it |
+| `a` | add an agent tab: pick a model, then an effort (always a new tab) |
+| `f` / `u` | add any missing tabs / only the utility tab |
+| `s` | stop running agents (pick them) |
+| `F` | force-fill: shows the plan, runs on `y` |
+| `x` | close the workspace: shows what goes with it, runs on `y` |
+| `→` `←` space | unfold / fold / toggle the tree |
+| `/` `g` `q` | filter, refresh, quit |
+
+## Configure
+
+```sh
+corral config init      # writes a commented ~/.config/corral/config.toml
+corral config show      # the settings in effect
+```
+
+The file lives at `$CORRAL_CONFIG`, else `$XDG_CONFIG_HOME/corral/config.toml`,
+else `~/.config/corral/config.toml` (on macOS too). Every key is optional.
+
+```toml
+root = "~/Code"                     # also --root / $CORRAL_ROOT
+scan_depth = 3
+default_agents = ["sonnet/medium"]
+
+[utility]                           # "" = plain shell
+top = "yazi"
+bottom_left = ""
+bottom_right = "lazygit"
+
+[efforts]
+claude = ["low", "medium", "high", "xhigh", "max"]
+
+[[models]]                          # any herdr agent kind: claude, codex, gemini, opencode, ...
+key = "opus"
+tool = "claude"
+display = "Opus"
+args = ["--model", "opus", "--effort", "{effort}"]
+```
+
+## Agent skill
+
+`skills/corral/SKILL.md` teaches coding agents to drive corral through its
+`--json` CLI. The repo is also a Claude Code plugin marketplace:
+
+```
+/plugin marketplace add johnfoland/corral
+/plugin install corral@corral
+```
+
+Or copy `skills/corral` into your agent's skills directory.
+
+## Develop
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+Tests run against an in-memory fake herdr (`tests/fake_herdr.py`); nothing
+touches a real herdr session. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+commit conventions and the release process.
+
+## License
+
+MIT

corral_herdr-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "corral-herdr"
+version = "0.1.0"
+description = "Round up your projects into herdr workspaces: a utility tab plus model/effort agent tabs, from a CLI or a TUI."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "John Foland", email = "john@johnfoland.net" }]
+requires-python = ">=3.11"
+dependencies = ["textual>=8,<9"]
+keywords = ["herdr", "terminal", "workspace", "tui", "claude", "codex", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development",
+    "Topic :: Terminals",
+]
+
+[project.urls]
+Homepage = "https://github.com/johnfoland/corral"
+Changelog = "https://github.com/johnfoland/corral/blob/master/CHANGELOG.md"
+Issues = "https://github.com/johnfoland/corral/issues"
+
+[project.scripts]
+corral = "corral.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/corral"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "skills", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.6"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]

corral_herdr-0.1.0/skills/corral/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: corral
+description: Drive herdr project workspaces with the `corral` CLI — build a workspace for a project (a utility tab plus model/effort agent tabs), open more agent tabs ("give me an Opus high tab", "another Sonnet in courses"), stop agents, close whole workspaces, and list which projects have workspaces and what their agents are doing. Use this whenever the user wants to open, set up, launch or get started on a project in herdr, says "open X in herdr" or "set me up for Y", asks for a new agent tab or pane with a given model/effort, wants to stop an agent or close a workspace, asks what is running where, or wants a herdr agent prompted at a later time. Also covers corral's config (~/.config/corral/config.toml) and the herdr workspace-trust prompt.
+---
+
+# corral
+
+corral rounds up the projects under a root directory (default `~/Code`) into
+[herdr](https://herdr.dev) workspaces. herdr is a terminal agent multiplexer:
+a *workspace* holds *tabs*, a tab holds *panes*, a pane is a terminal.
+
+A corral workspace has one shape:
+
+| Tab | Label | Contents |
+|---|---|---|
+| utility | the project label (`courses`, `cruzainet/api`) | configurable panes; by default yazi on top, a shell bottom-left, lazygit bottom-right |
+| agent tabs | `<Model>•<effort>` (`Sonnet•medium`, `Opus•high`) | one interactive agent each |
+
+A second tab of the same model and effort is `Sonnet•medium-2`, then `-3`.
+The agent in it is named after the label (`claude-sonnet-medium-2`).
+
+**Use the CLI with `--json`, not the TUI.** Bare `corral` opens an
+interactive TUI meant for the human. Every command takes `--json`: the result
+is JSON on stdout, progress lines go to stderr. Exit codes: `0` ok, `1` some
+target failed, `2` usage or config error, `3` herdr not running.
+
+## Look before acting
+
+```sh
+corral ls --json            # every project: path, branch, workspace, agent tabs
+corral ls --open --json     # only projects that have a workspace
+corral models --json        # model keys, tools, effort levels
+```
+
+In `ls` output each project has `workspace: null` or
+`{id, label, status, tabs, agents: [{label, status, pane_id, name, kind}]}`.
+Agent `status` is herdr's `idle` / `working` / `blocked` / `done` / `unknown`,
+or `exited` for an agent tab whose agent has gone. `other_workspaces` lists
+workspaces that belong to no project under the root.
+
+Project labels are paths relative to the root: a nested repo is
+`cruzainet/api`. Refer to projects by path when running `up`; `ls` gives you
+the path.
+
+## Opening a project
+
+```sh
+corral up ~/Code/courses --json                     # build, or focus if it exists
+corral up ~/Code/api --agent opus/high --json       # choose the agent tab(s); repeatable
+corral up ~/Code/notes --no-agent --json            # utility tab only
+corral up ~/Code/courses --fill --agent opus/high --json   # top up an existing one
+```
+
+If the workspace exists, `up` only focuses it. `--fill` adds whichever tabs
+it lacks and is safe to repeat. `--force-fill` fills, then closes every tab
+that is neither the utility tab nor an agent tab; tabs hosting a live agent
+are kept and reported. When the user asks to force-fill, just run it. Use
+`--dry-run` only if they want to see the plan first.
+
+`--no-focus` leaves the user's focus where it is. Use it when acting in the
+background.
+
+## Adding agent tabs
+
+```sh
+corral tab opus/high --json                          # in the workspace you run in
+corral tab sonnet -w w5 --json                       # effort defaults to medium
+corral tab sonnet --new -w w5 --json                 # another one -> Sonnet•medium-2
+```
+
+Without `--new`, a model/effort that already has a tab is focused rather than
+duplicated. When the user asks for *another* or *a second* agent, pass `--new`.
+`-w` defaults to `$HERDR_WORKSPACE_ID`. Get other workspace ids from `corral
+ls --json`.
+
+## Stopping agents, closing workspaces
+
+```sh
+corral stop "Opus•high" -w w5 --json         # by tab label, agent name, or pane id
+corral stop --all -w w5 --json               # every running agent tab in w5
+corral close courses --dry-run --json        # what would go: tabs, running agents
+corral close w5 --json                       # by id or exact label
+```
+
+Stopping closes the agent's pane; herdr has no `agent stop`. When the user says
+to stop something, just do it.
+
+Closing a workspace takes every tab, pane and agent with it, and herdr doesn't
+ask for confirmation. Run `--dry-run` first and be sure of the id. corral
+refuses a label that several workspaces share, and refuses the workspace you
+are running in unless `--include-self` is passed. Don't close anything the
+user didn't ask you to close. Their own sessions, possibly including yours,
+live in these workspaces.
+
+## Configuration
+
+`corral config path` prints the file location: `$CORRAL_CONFIG`, else
+`$XDG_CONFIG_HOME/corral/config.toml`, else `~/.config/corral/config.toml`,
+on macOS too. `corral config init` writes a commented starter file, and
+`corral config show` prints the settings in effect. The root can also come
+from `--root` or `$CORRAL_ROOT`.
+
+To add a model, add a `[[models]]` entry with `key`, `tool` (the herdr agent
+kind: claude, codex, gemini, opencode, …), `display` and `args` (`{effort}` is
+substituted). Effort levels per tool are under `[efforts]`.
+
+## Prompting an agent later
+
+For "send 'continue' to the Codex tab in the chocs workspace at 9:30", use
+the system `at` command rather than a long `sleep`, cron or polling. Find
+the pane **now**, at scheduling time:
+
+```sh
+corral ls --open --json   # -> the project's workspace.agents[] -> pane_id, e.g. w6:p4
+```
+
+Write the job to a small script file rather than an inline `at <<EOF`
+heredoc, whose quoting breaks once the prompt has spaces or punctuation:
+
+```sh
+cat > /tmp/at-job-$$.sh <<'EOF'
+herdr agent prompt w6:p4 "continue" --wait --timeout 120000
+EOF
+at 9:30am -f /tmp/at-job-$$.sh && rm /tmp/at-job-$$.sh
+```
+
+The `at` job captures `PATH` from the shell that queued it. `atq` lists
+queued jobs and `atrm <n>` cancels one. `herdr agent prompt` rejects a text
+starting with `/`. Send slash commands with a leading space: `' /compact'`.
+
+## The workspace-trust prompt
+
+A claude or codex agent started in a directory it has never seen stops at
+the "do you trust this folder" dialog. herdr reports the agent as `blocked`,
+not `idle`, even though starting it succeeded, so check `status` in `corral
+ls --json` after building a workspace in a new place. Nothing pre-accepts the
+dialog: permission-mode flags don't, running `claude -p` there first doesn't,
+and editing `~/.claude.json` gets overwritten by running sessions. Tell the
+user to answer it once in that tab. It is remembered per directory.
+
+## Beyond corral
+
+For anything corral doesn't cover (sending prompts, reading pane output,
+splitting panes), herdr ships its own agent instructions:
+
+```sh
+herdr --skill     # the authority on the herdr CLI, its JSON shapes and safety rules
+```
+
+Two findings it doesn't mention:
+- `herdr agent list` is the authority on which panes host an agent. `pane list`
+  reports `agent_status: unknown` for plain shells, so it can't tell you a pane
+  has no agent.
+- A pane created moments ago isn't at its prompt yet: `agent start` fails with
+  `agent_pane_busy`. Retry for a second. `--timeout` doesn't help, because it
+  governs agent detection afterwards.

corral_herdr-0.1.0/src/corral/__init__.py

@@ -0,0 +1,3 @@
+"""corral -- round up your projects into herdr workspaces."""
+
+__version__ = "0.1.0"  # x-release-please-version

corral_herdr-0.1.0/src/corral/__main__.py

@@ -0,0 +1,3 @@
+from corral.cli import main
+
+raise SystemExit(main())