feat: add clear-herd CLI and cross-platform builds

.github/workflows/build.yml

@@ -0,0 +1,47 @@
+name: Build clear-herd
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: false
+      - run: go test ./...
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        goos: [darwin, linux, windows]
+        goarch: [amd64, arm64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: false
+      - name: Build
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: 0
+        run: |
+          mkdir -p dist
+          suffix=""
+          if [ "$GOOS" = windows ]; then suffix=".exe"; fi
+          go build -trimpath -o "dist/clear-herd-${GOOS}-${GOARCH}${suffix}" ./cmd/clear-herd
+      - uses: actions/upload-artifact@v4
+        with:
+          name: clear-herd-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: dist/*
+          if-no-files-found: error

.gitignore

@@ -1 +1,4 @@
-.DS_Store
+.DS_Store
+dist/
+clear-herd
+clear-herd.exe

README.md

@@ -1,6 +1,88 @@
-Remove the content below and rewrite a README.md when done completing the following tasks. Once these tasks are completed and this content in the README.md is deleted, then rewrite the README.md with instructions on how to use this repo, how to build it, and how to use the command and what it does.
+# clear-herd
 
-1. Create a repo with a Go project that will build into a CLI tool for Windows, Linux, or MacOS (ARM or Intel). Create the project infrastructure to get all of those executables from a Github build.
-2. The CLI app that should be built is as follows. A CLI tool that will enable going through all of the herdr terminals that are open and closing all of the agents with their respective /clear and /exit commands, whatever those might be. Once cleared the terminal is then also "clear"ed with the respective clear command used for the terminal or terminal types that are open (i.e. Powershell, MacOS Terminal, Ubuntu Terminal, or whatever). Generally that is always just a plain old "clear" command issued.
-3. When that command is run, we'll call it "clear-herd" once it is done closing all of the agents in the respective terminals it should return a bulleted list of all the sessions resume commands. i.e. for example codex when it is given an /exit returns a resume or reconnect command like "codex resume 01a13c1d-73ec-72b3-8159-5eb85647d384". Return all of those, regardless of agent, as a bulleted list and also return what kind of agent the resume command is from, i.e. is it codex or claude or cursor's agent or whatever else it might be.
-4. Otherwise log an error if the command to resume isn't given.
+`clear-herd` closes supported coding agents in a [Herdr](https://herdr.dev/) session, clears their terminal panes, and prints commands to resume the saved conversations. It uses Herdr's agent and pane CLI, so the same executable works whether Herdr is displayed in Terminal, iTerm2, Windows Terminal, or a Linux terminal emulator.
+
+## Requirements
+
+- [Herdr](https://herdr.dev/docs/quick-start/) installed and running, with its `herdr` CLI on `PATH`.
+- Agents running **inside Herdr panes**. Ordinary terminal windows outside Herdr are not visible to this tool.
+- A native session ID reported by a Herdr agent integration, or a resume command printed in the agent's terminal output. Install available integrations with `herdr integration install <name>` and check `herdr agent list` for `agent_session`.
+
+The built-in command profiles are Codex (`/clear`, `/exit`, `codex resume ID`), Claude Code (`/clear`, `/exit`, `claude --resume ID`), and Cursor Agent (`/clear`, `/exit`, `agent --resume=ID`). Other agent kinds can be added through a profiles file.
+
+## Install and build
+
+With Go 1.23 or newer:
+
+```sh
+go build -o clear-herd ./cmd/clear-herd
+```
+
+On Windows, use `go build -o clear-herd.exe ./cmd/clear-herd`. Move the resulting executable to a directory on `PATH`.
+
+The [Build clear-herd workflow](.github/workflows/build.yml) runs tests and uploads six executables as GitHub Actions artifacts for macOS, Linux, and Windows, each on Intel/AMD (`amd64`) and ARM (`arm64`). Open a successful workflow run's **Artifacts** section and download the archive for your operating system and CPU. On macOS and Linux, make the downloaded executable executable with `chmod +x`.
+
+## Use
+
+From a shell where the Herdr CLI can reach the desired server:
+
+```sh
+clear-herd --dry-run
+clear-herd
+```
+
+`--dry-run` lists agents and any resume commands already available from Herdr session metadata. The normal command:
+
+1. Lists agents from `herdr agent list`.
+2. Saves each agent's native session ID before `/clear` can start a fresh chat.
+3. Sends the agent's clear and exit commands, then waits for the agent to disappear from its pane.
+4. Reads exit output for a resume command if Herdr did not report an ID.
+5. Runs `clear` in the freed shell pane (`cls` on Windows).
+6. Prints a bulleted list with agent kind, pane ID, and resume command.
+
+For example:
+
+```text
+Resume commands:
+- codex [w1:p1]: codex resume 01a13c1d-73ec-72b3-8159-5eb85647d384
+- claude [w1:p2]: claude --resume 229a1d26-70d2-4758-9b10-58eeb31d1648
+```
+
+Run it from a regular shell pane. If the command runs inside a pane currently hosting an agent, that pane is skipped so the command can finish. Agents with an active approval prompt are also skipped. Working agents are given up to `--timeout` to become idle. Errors, including missing resume commands, are printed to stderr and cause exit status 1; other panes continue processing.
+
+Options:
+
+```text
+--dry-run          Show available commands without changing panes
+--profiles FILE    Load additional or replacement agent command profiles
+--herdr PATH       Use a Herdr CLI at PATH (default: herdr)
+--timeout 15s      Maximum time to wait for an agent to become idle or exit
+--version          Show the tool version
+```
+
+Herdr's `HERDR_SESSION` and `HERDR_SOCKET_PATH` environment variables are inherited by the CLI, so they can target a named/local session. This command handles one Herdr server per run.
+
+## Add an agent profile
+
+Create a JSON file mapping Herdr's `agent` kind to its interactive clear and exit commands and its resume command. The resume arguments must contain `{id}`, `{path}`, or `{session}`; those placeholders are filled from Herdr's `agent_session` field. `{id}` only accepts ID references, `{path}` only path references, and `{session}` accepts either.
+
+```json
+{
+  "myagent": {
+    "clear": "/reset",
+    "exit": "/quit",
+    "resume": ["myagent", "resume", "{id}"]
+  }
+}
+```
+
+Then run `clear-herd --profiles profiles.json --dry-run` to check session metadata before using `clear-herd --profiles profiles.json`. A profile replaces a built-in one with the same kind. An agent without a profile is left untouched and reported as an error.
+
+## Development
+
+```sh
+go test ./...
+go build ./cmd/clear-herd
+```
+
+The CLI uses only the Go standard library. Its tests use a scripted Herdr CLI, so they do not close live agents.