Everyday use

With or without Herdr

Herdr is optional. Side Dog works without it by reading each coding agent’s local session data.

Herdr adds information that agent files do not have: the terminal pane, tab, workspace, and terminal title. When Herdr and an agent file describe the same session, Side Dog keeps Herdr’s terminal details and adds the model and reasoning information from the agent.

Inside Herdr, a bare command follows every live Herdr agent folder across all workspaces:

side-dog watch

Outside Herdr, the same command discovers active agent folders on the machine. To require Herdr discovery, use --herdr. If Herdr is unavailable, Side Dog stops and explains the problem instead of silently watching the wrong folders. To restrict the watch to the Herdr workspace containing the current pane, use side-dog watch --workspace.

Startup progress

Interactive side-dog watch shows one transient status row before the normal feed when startup takes more than a short moment. It names only the current stage, includes elapsed time for a slow stage, and ends with the total startup duration:

Starting Side Dog...
Finding projects... 0.2s
Finding coding agents... 0.4s
Finding projects and worktrees... 1.1s
Loading recent activity... 1.8s
Refreshing optional context... 2.3s
Ready in 2.6s

Fast starts do not flash every stage. Optional context is labeled as optional so a slow or unavailable usage/GitHub enrichment does not look like a failure. The --once form remains synchronous and prints exactly one complete frame; it does not emit the interactive progress row.

What Side Dog shows

The timeline reports:

• file and configuration writes, with lines added and removed since the last commit;
• tests starting, passing, and failing;
• branch, worktree, commit, and push operations;
• pull requests opening, checks running, checks passing or failing, and merges;
• issues being created, closed, or reopened;
• failed commands, identified only by program name; and
• agent sessions, turns, and subagent activity.

An authenticated gh CLI lets Side Dog confirm pull-request state, CI, reviews, mergeability, and merges. Without it, local agent, file, test, and Git activity still works.

GitHub readback is per watched folder, not per agent. Active pull requests use a 60-second default interval. Branches without a pull request and partial/error states back off to at least five minutes; closed and merged pull requests back off to at least 15 minutes. A pull-request command or branch switch still triggers an immediate readback. The browser panel always uses this schedule. For terminal side-dog watch, use --github-poll 0 to disable readback.

Side Dog is an activity display, not an audit log or a security boundary. It stores short event metadata, but never stores prompts, responses, file contents, diffs, full shell commands, stdout, or stderr.

Report suspected vulnerabilities privately by following the security policy. Do not put security details or sensitive local activity in a public issue.

When an observation fails the privacy policy, Side Dog keeps only a fixed diagnostic. Repeated hook reports for one tool call are counted once beside the matching session rather than becoming timeline rows. Compound commands that finish with a recognized gh action use the command’s reported exit status; commits with the same message and author in separate worktrees of one repository are folded into one display row.

Status and color

Side Dog uses the same small visual vocabulary in the terminal and browser panel. Blue marks navigation and selection, purple identifies an agent or source, green means completed, amber means running or warning, red means failed, and neutral text means idle or unknown. Each watched folder keeps one muted color of its own, used as a thin bar at the left edge of its roster and timeline lines, on its [folder] badge, and on its column title. The color is a tint on plain text, never a filled block, so you can follow the folder without mistaking it for status. A badge appears on the first line of a run from one folder and again after a day divider; the rows inside a task card never repeat it, and a title that already starts with the badge text drops it.

Color is never the only signal. Agent rows and pull-request lines start with ● (working, completed, failed, or an open PR) or ○ (idle, unknown, or closed), and the state is also spelled out in a word. Timeline status uses ✓ for completed, … for running, ! for warning, × for failed, ○ for idle, and a quiet · when Side Dog could not determine the state. These labels remain in plain and redirected output. Terminal colors use the terminal theme; the browser panel provides matching light and dark themes.

Choose what to watch

Watch one project and its active worktrees:

side-dog watch ~/src/my-project

Watch several folders together:

side-dog watch ~/src/project ~/src/project-issue-42 ~/src/another-project

Run side-dog watch with no folders to discover where agents are working. Run side-dog watch . when you want to pin Side Dog to the current project.

By default, active worktrees join the display and finished ones leave it. Use --no-follow-worktrees to watch only the folders you named.

Save a group of folders and open it later:

side-dog watch ~/src/project ~/src/project-issue-42 --save review
side-dog watch @review

Side Dog watches at most eight folders by default and gives space to the busiest ones. Folders named on the command line or pinned in the configuration are not removed.

The terminal roster uses one line for a folder with one active agent. When a repository has multiple watched worktrees, it groups them under the repository name and labels each row by branch or task purpose; directory hashes are never used as names. Folder names are bold in color, while model/effort and age are dimmed; status still has both a word and a glyph. Idle sessions fold into one summary line by default. Lifecycle bookkeeping is collected but hidden with the background activity toggle, and recent resumed/ended times remain on the roster.

Watch and panel controls

The most useful controls are:

The day divider repeats the active timeline controls as key hints: r for order and e for detail. It adds f only when the event filter is narrower than all events, and shows the off-screen activity count with its direction.

The first Ctrl-C opens the same confirmation. Press Ctrl-C again while it is open to quit immediately.

Run side-dog watch --help or side-dog panel --help for every option.

Board

Run side-dog board for the current session roster. Press j/k to select, o to open the selected work, and w to switch to Watch. Enter or d toggles detail, i opens linked issues, and g cycles grouping. Conflicts appear in a complete, temporary block when they are new; c shows that block again after it clears. ? explains each view. Board quits directly with q; Watch uses a quit confirmation.

Board shares Watch’s SIDE DOG masthead: the version, the mode (Board or Attention), the session and repository counts, the working count, and the clock, with the same stripe motif where the width allows. It stays on the top line whichever mode is showing and however short or narrow the pane is.

Uppercase A toggles Attention mode. It keeps only the sessions that need a person and adds an ATTENTION column saying why: a folder, branch, or issue conflict with another session; a blocked session; a newest test run that failed; an open pull request with failing checks or requested changes; or work that has gone quiet for the same window after which a finished session leaves the board. The masthead then reads Attention · 2 of 5 sessions, rows keep their sort and grouping, and an empty Attention roster says that no session currently needs attention. Reasons are built only from what the row already shows; they never quote a prompt, command, file, or path.

The detail pane opens with a session brief above the recent timeline:

• status – the row’s status and how long since it last did anything;
• work – the confirmed issue and the pull request with its checks and review;
• latest – the newest milestone (tests, commit, push, pull request, merge, branch, or worktree) with its outcome and age;
• events – counts of edits, tests (and failures), commits, and PR updates from the session’s own recorded events;
• cue – a rule-based operator cue with its evidence: resolve conflict, unblock the session, investigate failed tests, fix failing checks, address review changes, review PR, merge PR, check the stalled session, or no action indicated.

A session with no recorded events still shows its identity, status, and an explicit no observed activity state. In a short pane the cue and status survive first. The browser /board page shows the same brief fields under each row.

Each row names the agent, the model it runs, its surface, branch, linked issue, pull request and status. The model matters when two sessions of one agent are otherwise identical rows. A narrow pane gives up the pull request column first, then the issue, then the surface, and the model last of the optional columns.

The panel at /board remains the live session roster, matching the terminal Board view, including the session brief under each row.

Live Board issue evidence

Live Board issue links require PR closing data, a recent successful session-scoped issue command with a known repository, or a verified explicit branch/title candidate. GitHub verification runs in the background and is cached for five minutes; unavailable lookups leave the Issue column blank. Dates and build numbers in branches are never issue candidates. These live work links do not establish historical model contribution attribution.