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
