herdr-plugin-mado

herdr plugins that put mado, a TUI markdown viewer, in front of you while you work with agents.

An agent writing a plan, a report or a running log leaves you reading markdown in a pager, or scrolling back through the pane it was printed in. These plugins open that markdown in mado instead — in its own pane, beside the agent that is writing it.

Plugins

Plugin	Install	What it does
docs-peek	herdr plugin install hidekingerz/herdr-plugin-mado/docs-peek	Opens the focused pane's docs/ in mado, in a split to the right.
agent-report-viewer	herdr plugin install hidekingerz/herdr-plugin-mado/agent-report-viewer	Opens the markdown an agent run produced, in mado, when the run is done.
loop-dash	herdr plugin install hidekingerz/herdr-plugin-mado/loop-dash	Keeps a loop/ agent loop's state docs on screen in a mado pane that follows the files.

Updating

herdr has no plugin update command. To pick up a new release, run the same herdr plugin install … command again: it replaces the managed checkout in place and keeps your plugin config. Pin a specific release with --ref:

herdr plugin install hidekingerz/herdr-plugin-mado/agent-report-viewer            # latest
herdr plugin install hidekingerz/herdr-plugin-mado/agent-report-viewer --ref v0.3.1  # pinned

There is no auto-update; releases are listed on the releases page. A plugin you herdr plugin linked from a local clone follows that clone instead — git pull is the update. Installing it from GitHub on top fails with already linked from a local path; herdr plugin unlink <id> first if you really want the managed copy.

docs-peek

Press the key you bind to it and mado opens beside the agent, rooted at the directory that agent is working in.

The directory is taken from the focused pane's cwd — the agent you were just looking at — falling back to the workspace cwd when herdr cannot resolve one. If that directory has a docs/, mado is rooted there; otherwise it opens the whole tree and the sidebar does the work. When the installed mado supports --watch, the pane reloads by itself as the agent rewrites the files.

Install

herdr plugin install hidekingerz/herdr-plugin-mado/docs-peek
herdr plugin action list --plugin mado.docs-peek

Then bind a key in your herdr config:

[[keys.command]]
key = "prefix+d"
type = "plugin_action"
command = "mado.docs-peek.peek"
description = "peek at docs with mado"

It also runs without a keybinding:

herdr plugin action invoke mado.docs-peek.peek

Requirements

• herdr 0.8.0 or newer
• mado on your PATH — go install github.com/hidekingerz/mado@latest, or a binary from the releases page
• Linux or macOS. The entrypoints are POSIX shell scripts, so Windows is not supported yet even though mado itself runs there.
• jq is used when present and not needed otherwise; the plugin reads the one field it wants out of the invocation context either way.

Developing

git clone https://github.com/hidekingerz/herdr-plugin-mado
herdr plugin link herdr-plugin-mado/docs-peek
herdr plugin action invoke mado.docs-peek.peek
herdr plugin log list --plugin mado.docs-peek

herdr plugin unlink mado.docs-peek when you are done.

agent-report-viewer

When an agent run finishes, this plugin looks at the uncommitted *.md files in that agent pane's git work tree and opens them in mado — newest first, up to four files. Each workspace gets one mado pane; a later run adds tabs to that same pane instead of opening a new one, so the reports from a working session collect in one place beside the agent.

Install

herdr plugin install hidekingerz/herdr-plugin-mado/agent-report-viewer

It subscribes to the pane.agent_status_changed event rather than a keybinding, so there is nothing further to set up — it runs on its own whenever an agent run in a git repository finishes.

Showing a file on demand

The hook only notices markdown that is still uncommitted, so a report the agent commits in the same turn never shows. For that — or whenever you just want a file in the report pane — there is an explicit entry point. Install it once:

herdr plugin action invoke mado.agent-report-viewer.install-cli

That writes a show command into the plugin's config directory, so it works the same whether the plugin is installed from GitHub or linked from a clone. From any pane in that herdr:

sh "$(herdr plugin config-dir mado.agent-report-viewer)/show" docs/plan.md notes.md

Paths are relative to the current directory; the files open as tabs in the workspace's report pane, reusing it exactly like the hook does. An agent can run this itself after writing a plan or report, committed or not. Outside herdr, or for files that don't exist, it does nothing.

Requirements

• herdr 0.8.0 or newer
• mado v1.2.0 or newer on your PATH — this plugin needs -remote open and -watch, which older mado builds don't have
• A git repository. Runs outside one are skipped.
• Linux or macOS. The entrypoints are POSIX shell scripts, so Windows is not supported yet even though mado itself runs there.

Developing

git clone https://github.com/hidekingerz/herdr-plugin-mado
herdr plugin link herdr-plugin-mado/agent-report-viewer
herdr plugin log list --plugin mado.agent-report-viewer

herdr plugin unlink mado.agent-report-viewer when you are done.

loop-dash

A single-agent loop keeps its state under loop/ — MEMORY.md, the memory it rewrites every iteration; VISION.md, the goal and definition of done; ARCHITECTURE.md, the stack and verify command; and RULES.md, what it must not do. Press the key you bind to this plugin and those files open in a mado pane that follows them as the loop rewrites them.

The plugin looks in the focused pane's cwd for the known names loop/MEMORY.md, loop/VISION.md, loop/ARCHITECTURE.md and loop/RULES.md, and opens every one it finds as a tab, watching for changes. Each workspace gets one dashboard pane: invoking the action again refreshes the same pane instead of opening another. When none of the known files exist, nothing happens.

Install

herdr plugin install hidekingerz/herdr-plugin-mado/loop-dash
herdr plugin action list --plugin mado.loop-dash

Then bind a key in your herdr config:

[[keys.command]]
key = "prefix+t"
type = "plugin_action"
command = "mado.loop-dash.show"
description = "show loop state in mado"

It also runs without a keybinding:

herdr plugin action invoke mado.loop-dash.show

Requirements

• herdr 0.8.0 or newer
• mado v1.2.0 or newer on your PATH — this plugin needs -remote open and -watch, which older mado builds don't have
• Linux or macOS. The entrypoints are POSIX shell scripts, so Windows is not supported yet even though mado itself runs there.
• jq is used when present and not needed otherwise.

Developing

git clone https://github.com/hidekingerz/herdr-plugin-mado
herdr plugin link herdr-plugin-mado/loop-dash
herdr plugin action invoke mado.loop-dash.show
herdr plugin log list --plugin mado.loop-dash

herdr plugin unlink mado.loop-dash when you are done.

Shelved

• markdown link handler — Control+click a .md path in any pane and send it to mado. Shelved: herdr routes link-handler clicks only for http(s) URLs — bare file paths, file:// URLs, and OSC 8 hyperlinks never reach a handler (verified against herdr 0.8.0). A plugin cannot make an agent-written .md path clickable on its own. Revisit if herdr starts routing file:// or OSC 8 links; tracked in hidekingerz/mado#13.

License

Apache-2.0