Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ name: Release
# leaves `release` where it is.

on:
# Manual runs rehearse the build and packaging without publishing.
workflow_dispatch:
push:
tags:
- 'v*'
Expand Down Expand Up @@ -40,7 +42,11 @@ jobs:
id: version
env:
TAG: ${{ github.ref_name }}
EVENT: ${{ github.event_name }}
run: |
if [ "$EVENT" = workflow_dispatch ]; then
TAG="v$(sed -n 's/^version = "\(.*\)"$/\1/p' herdr-plugin.toml | head -n 1)"
fi
case "$TAG" in
*-bin) echo "::error::$TAG is an install tag, not a release tag"; exit 1 ;;
v[0-9]*) ;;
Expand Down Expand Up @@ -111,6 +117,7 @@ jobs:

publish:
name: Publish
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
needs: build
runs-on: ubuntu-latest
# The only job that can write: it runs no project code.
Expand Down
2 changes: 1 addition & 1 deletion .golangci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ formatters:
# with the given prefixes are grouped after 3rd-party packages.
# Default: []
local-prefixes:
- github.com/kriuchkov/herdr-scope
- github.com/killallgit/herdr-scope

golines:
max-len: 140
Expand Down
148 changes: 148 additions & 0 deletions CONFIGURATION-SUMMARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
# Configuration and keyboard shortcuts

Scope’s settings and Herdr’s keyboard bindings go in **different configuration files**.

## Keyboard shortcuts

`--keys` belongs to the `configure` subcommand:

```sh
bin/herdr-scope configure --keys
```

This **prints a template only**; it does not install the shortcuts. Scope binds no keys itself.

Paste the following into **Herdr’s `config.toml`**, not Scope’s plugin configuration:

```toml
[[keys.command]]
key = "prefix+a"
type = "plugin_action"
command = "killallgit.herdr-scope.view-flip"
description = "Agents: active <-> recent"

[[keys.command]]
key = "prefix+u"
type = "plugin_action"
command = "killallgit.herdr-scope.jump"
description = "Agents: next one waiting on you"

[[keys.command]]
key = "prefix+f"
type = "plugin_action"
command = "killallgit.herdr-scope.view-here"
description = "Agents: only this workspace <-> all"

[[keys.command]]
key = "prefix+m"
type = "plugin_action"
command = "killallgit.herdr-scope.fold"
description = "Agents: fold <-> unfold this folder"

[[keys.command]]
key = "prefix+comma"
type = "plugin_action"
command = "killallgit.herdr-scope.settings"
description = "herdr-scope settings"
```

With Herdr’s default prefix, press **Ctrl+B, then the second key**:

| Second key | What happens |
| --- | --- |
| `a` | Switch between grouped activity order and a flat recent-activity list |
| `u` | Jump to an agent needing attention: questions first, then unseen results |
| `f` | Toggle this workspace versus all workspaces |
| `m` | Fold/unfold the current folder; agents needing attention remain visible |
| `,` | Open Scope settings |

The README describes the comma shortcut as `prefix+,`, but the generated configuration uses **`prefix+comma`**. Use the latter in the file.

This fork uses the plugin ID `killallgit.herdr-scope`. Existing upstream installations
use a different ID and keep separate configuration and state directories; these are
not migrated automatically.

## Where to change Scope’s settings

Scope’s configuration file is:

```sh
$(herdr plugin config-dir killallgit.herdr-scope)/config.toml
```

The easiest interface is the settings popup:

- **↑/↓:** select an option
- **←/→:** change it
- **Enter:** edit
- **r:** restore its default
- **s:** save and apply
- **q:** close

Manual file edits are picked up within about two seconds.

## Panel and organization

| Option | Default | Meaning |
| --- | --- | --- |
| `agents_panel` | `plugin` | Use Scope’s Agents panel or Herdr’s native one |
| `order` | `active` | `active`: grouped, busiest first; `recent`: flat activity list; `here`: current workspace and family; `off`: Herdr’s order |
| `nest_folders` | `true` | Nest workspaces whose folders are inside another workspace; also moves them together in Herdr’s list |
| `reorder_workspaces` | `false` | Make Herdr’s workspace numbering follow Scope’s activity order |
| `group_indent` | `2` | Indentation per tree level; `0` removes tree lines |
| `group_gap` | `true` | Blank line between groups; defaults to `false` with compact layout |
| `split_corner` | `false` | Visually branch additional split panes beneath the first |

**Code detail:** `agents_panel` and `order` are special live controls in the popup, not ordinary saved settings. The file’s `order`/`sort` supplies an initial ordering choice; `agents_panel` is not parsed as a normal file setting.

## Appearance

| Option | Default | Meaning |
| --- | --- | --- |
| `layout` | `classic` | Separate logo/status cells; `compact` makes denser rows |
| `variant` | `auto` | Icons: automatically choose, force `font`, use Unicode `text`, or `none` |
| `space_mark` | `logo` | Mark workspaces with an agent logo or a `state` symbol |
| `logo_color` | `active` | Vendor colors only while working/waiting, or `always` |
| `row_label` | `title` | Show the session `title`, `tab` name, or `both` |
| `trim_group_prefix` | `true` | Remove redundant workspace names from titles |
| `worktree_mark` | `U+F418` | Worktree-header symbol; empty disables it; requires a compatible font |
| `follow_appearance` | `false` | Follow desktop light/dark appearance; requires Herdr’s `[theme]` table |
| `colors.active_row_bg_light` | `#b9cdf2` | Selected-row background for light themes |
| `colors.active_row_bg_dark` | `#232636` | Selected-row background for dark themes |

Set either color override to `""` to retain the theme’s own background.

## Status and attention

| Option | Default | Meaning |
| --- | --- | --- |
| `done_hold` | `until_seen` | Keep ✓ until you focus the pane; alternatively specify seconds or `"30s"` |
| `blocked_hold` | `true` | Keep ? until the agent resumes working |
| `idle_grace_seconds` | `2.5` | Wait this long before treating idle as a completed turn |
| `activity_fresh_minutes` | `15` | How long an inactive agent looks “fresh” |
| `activity_stale_minutes` | `120` | When an inactive agent starts looking dim/stale |
| `show_age` | `waiting` | Show elapsed time only for attention-needed rows, for `all`, or `off` |
| `mark_tabs` | `true` | Append ? or ✓ to tabs needing attention |

## Advanced, file-only settings

```toml
log_level = "info" # debug, info, warn, error
led_glyph = "●" # Shared blocked/idle symbol

[observer]
heartbeat_interval = "1s" # Agent-list refresh; 250ms–1m
reconcile_interval = "30s" # Full-session refresh; 1s–1h

[glyphs]
done = "✔" # Override individual status symbols
```

Other glyph names: `working`, `blocked`, `idle_fresh`, `idle`, `idle_stale`, `unknown`.

## Sources

- [Shortcut generation and configure command](internal/bootstrap/cli.go)
- [Settings popup fields](internal/adapters/config/fields.go)
- [Configuration parsing and saving](internal/adapters/config/plugin.go)
- [Full configuration documentation](docs/configuration.md)
50 changes: 38 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Herdr Scope

<p align="center">
<a href="https://github.com/kriuchkov/herdr-scope/actions/workflows/ci.yml"><img alt="tests" src="https://github.com/kriuchkov/herdr-scope/actions/workflows/ci.yml/badge.svg?branch=master"></a>
<a href="https://github.com/killallgit/herdr-scope/actions/workflows/ci.yml"><img alt="tests" src="https://github.com/killallgit/herdr-scope/actions/workflows/ci.yml/badge.svg?branch=master"></a>
<img alt="Go 1.26" src="https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white">
<img alt="Herdr 0.9+" src="https://img.shields.io/badge/Herdr-0.9%2B-89b4fa">
<a href="LICENSE"><img alt="license MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
Expand All @@ -21,6 +21,14 @@ A sidebar for [Herdr](https://herdr.dev) that shows which agent is working, whic
you, and which finished while you were away. It only watches and paints: it never starts,
prompts or stops an agent.

## Upstream credit

This repository, [killallgit/herdr-scope](https://github.com/killallgit/herdr-scope),
is a fork of [kriuchkov/herdr-scope](https://github.com/kriuchkov/herdr-scope)
by **Nikita Kriuchkov**. His original Herdr Scope implementation is the foundation
for this fork's development. The original MIT copyright and license remain in
[LICENSE](LICENSE); additional attributions are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## Features

![Herdr with Scope: a folder of five agents folds to one line, a finished turn and a question stay in sight, ctrl+b u jumps to each](docs/demo/scope.gif)
Expand All @@ -47,30 +55,29 @@ prompts or stops an agent.
## Install

```sh
herdr plugin install kriuchkov/herdr-scope --ref release
herdr plugin install killallgit/herdr-scope --ref release
```

The `release` branch carries prebuilt binaries for macOS, Linux and Windows. Without `--ref`,
as the [plugin catalog](https://herdr.dev/plugins/) installs it, Herdr builds from source
with Go 1.26+. Without Go, it downloads the release binary and checks its checksum. Setup
The `release` branch carries prebuilt binaries for macOS, Linux and Windows once
published for this fork. Without `--ref`, Herdr builds from source with Go 1.26+. Without Go, it downloads the release binary and checks its checksum. Setup
adds Scope's blocks to Herdr's `config.toml` between `HERDR-SCOPE` markers and installs the
icon font for your user. It requires Herdr 0.9+ (protocol 22).

> [!IMPORTANT]
> If the sidebar has not changed, start the daemon:
> `herdr plugin action invoke kriuchkov.herdr-scope.state-start`.
> `herdr plugin action invoke killallgit.herdr-scope.state-start`.
> Never run `herdr server stop` to restart anything: it ends every pane.

To update, restart the daemon after updating the plugin. To uninstall, run these in order;
your `config.toml` comes back byte for byte:

```sh
herdr plugin update kriuchkov.herdr-scope # update
herdr plugin action invoke kriuchkov.herdr-scope.state-start
herdr plugin update killallgit.herdr-scope # update
herdr plugin action invoke killallgit.herdr-scope.state-start

herdr plugin action invoke kriuchkov.herdr-scope.unconfigure # uninstall
herdr plugin action invoke kriuchkov.herdr-scope.uninstall-font
herdr plugin uninstall kriuchkov.herdr-scope
herdr plugin action invoke killallgit.herdr-scope.unconfigure # uninstall
herdr plugin action invoke killallgit.herdr-scope.uninstall-font
herdr plugin uninstall killallgit.herdr-scope
```

## Keys
Expand All @@ -90,11 +97,16 @@ Scope binds no keys itself. `bin/herdr-scope configure --keys` prints the snippe
[[keys.command]]
key = "prefix+u"
type = "plugin_action"
command = "kriuchkov.herdr-scope.jump"
command = "killallgit.herdr-scope.jump"
```

## Configuration

This fork uses plugin ID `killallgit.herdr-scope`, with separate configuration and
state directories from upstream installations. Existing settings and key bindings
are not migrated automatically. Before switching, unconfigure and uninstall the
upstream plugin using its own instructions; keep a backup of your settings.

`prefix+,` opens the popup: `↑↓` select, `←→` change, `s` save. A save is validated and
applied at once. The most used options:

Expand Down Expand Up @@ -142,6 +154,20 @@ From a checkout: `make build && herdr plugin link .` (`plugin link` runs no buil
[Architecture](docs/architecture.md), [Herdr protocol notes](docs/protocol.md),
[design decisions](docs/design.md). `docs/demo/record.sh` re-records the GIF.

### Release verification

Run a non-publishing release rehearsal on the branch to test and package all six
platform binaries:

```sh
gh workflow run release.yml --ref <branch>
```

Manual runs upload the release artifacts but skip publishing. To publish after
merging, keep `herdr-plugin.toml` and `internal/bootstrap/version.go` at the same
new version, then push its `vX.Y.Z` tag. The release workflow publishes the
archives, checksums, `vX.Y.Z-bin` tag, and (for stable versions) `release` branch.

## License

MIT, see [LICENSE](LICENSE). The icon font is forked from qintmb/herdr-icon-agent-ui (MIT),
Expand Down
2 changes: 1 addition & 1 deletion cmd/herdr-scope/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import (
"context"
"os"

"github.com/kriuchkov/herdr-scope/internal/bootstrap"
"github.com/killallgit/herdr-scope/internal/bootstrap"
)

// version overrides bootstrap.Version at build time
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Configuration

The file is `$(herdr plugin config-dir kriuchkov.herdr-scope)/config.toml`. The settings popup
The file is `$(herdr plugin config-dir killallgit.herdr-scope)/config.toml`. The settings popup
(`prefix+,`) edits it: `↑↓` select, `←→` change, `↵` edit, `r` default, `s` save, `q` close. A
save validates every value, rewrites only the lines that changed (your comments stay), and the
daemon applies it at once. Hand edits are picked up within two seconds.
Expand Down
2 changes: 1 addition & 1 deletion docs/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ model dirty, and the next frame reads the authoritative snapshot.

`null` clears a token. Indentation rides on a leading U+200B, which `trim()` keeps. A report
to a target that is gone (`pane_not_found`, `workspace_not_found`) counts as landed. Every
write carries `source = "plugin:kriuchkov.herdr-scope"`, so Scope's clears cannot touch
write carries `source = "plugin:killallgit.herdr-scope"`, so Scope's clears cannot touch
another plugin's token.

## Sidebar rows
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
module github.com/kriuchkov/herdr-scope
module github.com/killallgit/herdr-scope

go 1.26.5

Expand Down
4 changes: 2 additions & 2 deletions herdr-plugin.toml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
id = "kriuchkov.herdr-scope"
id = "killallgit.herdr-scope"
name = "Herdr Scope"
version = "1.1.2"
min_herdr_version = "0.9.0"
Expand All @@ -10,7 +10,7 @@ platforms = ["linux", "macos", "windows"]
# three ways:
#
# - Release install, no Go needed: `herdr plugin install
# kriuchkov/herdr-scope --ref release` (or `--ref vX.Y.Z-bin` to pin a
# killallgit/herdr-scope --ref release` (or `--ref vX.Y.Z-bin` to pin a
# version) checks out the tree the release workflow publishes: the tagged
# source plus prebuilt bin/herdr-scope-<os>-<arch>[.exe] for macOS, Linux
# and Windows on amd64 and arm64. The step copies this machine's binary.
Expand Down
2 changes: 1 addition & 1 deletion internal/adapters/appearance/probe.go
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import (
"sync"
"time"

"github.com/kriuchkov/herdr-scope/internal/ports"
"github.com/killallgit/herdr-scope/internal/ports"
)

const (
Expand Down
2 changes: 1 addition & 1 deletion internal/adapters/appearance/probe_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import (
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"

"github.com/kriuchkov/herdr-scope/internal/ports"
"github.com/killallgit/herdr-scope/internal/ports"
)

type answer struct {
Expand Down
4 changes: 2 additions & 2 deletions internal/adapters/config/fields.go
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ import (
"strconv"
"time"

"github.com/kriuchkov/herdr-scope/internal/domain"
"github.com/kriuchkov/herdr-scope/internal/ports"
"github.com/killallgit/herdr-scope/internal/domain"
"github.com/killallgit/herdr-scope/internal/ports"
)

// FieldKind is how a setting is edited.
Expand Down
4 changes: 2 additions & 2 deletions internal/adapters/config/managed.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ import (
"sync"
"time"

"github.com/kriuchkov/herdr-scope/internal/domain"
"github.com/kriuchkov/herdr-scope/internal/ports"
"github.com/killallgit/herdr-scope/internal/domain"
"github.com/killallgit/herdr-scope/internal/ports"
)

// Managed block names.
Expand Down
2 changes: 1 addition & 1 deletion internal/adapters/config/managed_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ import (
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"

"github.com/kriuchkov/herdr-scope/internal/ports"
"github.com/killallgit/herdr-scope/internal/ports"
)

type managedFixture struct {
Expand Down
4 changes: 2 additions & 2 deletions internal/adapters/config/plugin.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ import (

"github.com/BurntSushi/toml"

"github.com/kriuchkov/herdr-scope/internal/domain"
"github.com/kriuchkov/herdr-scope/internal/ports"
"github.com/killallgit/herdr-scope/internal/domain"
"github.com/killallgit/herdr-scope/internal/ports"
)

// PluginFile is the plugin's own config.toml. Every key has a default, so a
Expand Down
Loading
Loading