Metadata-Version: 2.4
Name: side-dog
Version: 2.2.0
Summary: A narrow live activity pane for coding agents
Author: Quentin Fennessy
License-Expression: MIT
Project-URL: Homepage, https://github.com/qfennessy/side-dog
Project-URL: Changelog, https://github.com/qfennessy/side-dog/blob/main/CHANGELOG.md
Project-URL: Documentation, https://qfennessy.github.io/side-dog/
Project-URL: Issues, https://github.com/qfennessy/side-dog/issues
Project-URL: Repository, https://github.com/qfennessy/side-dog
Keywords: activity,claude-code,coding-agents,codex,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wcwidth>=0.2.13
Requires-Dist: zstandard>=0.25.0
Dynamic: license-file

# Side Dog

<p align="center">
  <img src="https://raw.githubusercontent.com/qfennessy/side-dog/main/docs/side-dog-logo.png" alt="A golden retriever watching an event timeline" width="360">
</p>

Side Dog helps you follow coding agents across projects: **Watch** shows their
activity over time, while **Board** shows the live session roster. See edits,
tests, commits, pull requests, issues, and agent turns
in your terminal or a local browser panel.

[Read the Side Dog documentation](https://qfennessy.github.io/side-dog/).

Side Dog was inspired by [Sundai Hack 138](https://sundai.club). Sundai Club is
a community for building and launching AI prototypes every Sunday.

## Install

Requires Python 3.11+, Git, and macOS or Linux. Install
[uv](https://docs.astral.sh/uv/getting-started/installation/), then:

```sh
uv tool install side-dog
side-dog --version
```

Upgrade an existing installation with `uv tool upgrade side-dog`. If the command
is not found, run `uv tool update-shell` and open a new terminal.
Follow the [platform installation guide](https://github.com/qfennessy/side-dog/blob/main/docs/install.md) for prerequisites,
PATH, upgrades, Git snapshots, uninstall, and offline man pages.

## Two terminal views

### Watch — follow the work

Watch shows a chronological feed with agent/model attribution, edits, test
results, commits, pushes, and PR observations. Press `e` to expand activity
and `b` to switch to Board.

![Side Dog Watch showing synthetic agent edits, tests, commits, and PR activity](https://raw.githubusercontent.com/qfennessy/side-dog/main/docs/side-dog-watch.gif)

### Board — see the live roster

Run `side-dog board` for the live session roster: agent, terminal or app,
repository and branch, linked issues, PR checks and review state, and status.
Use `j`/`k` to select a session, Enter for detail, and `g` to group rows.
Conflicts appear briefly when they are first detected; press `c` to show the
complete list again. Press `a` to toggle the compact recorded-contributions
table; press it again to return to the roster shown here. Press `w` to switch
to Watch.

![Side Dog Board live session roster with four synthetic agents, repositories, issues, PRs, and changing status](https://raw.githubusercontent.com/qfennessy/side-dog/main/docs/side-dog-board.gif)

Both recordings use synthetic data rendered by the current terminal UI;
they do not expose real agent sessions. See the
[recording instructions](https://github.com/qfennessy/side-dog/blob/main/docs/terminal-recordings.md).

## Try it

```sh
side-dog --version
side-dog demo --watch
side-dog doctor ~/src/my-project
side-dog watch ~/src/my-project
side-dog board
```

Replace the path with a real project. Use `side-dog demo --panel` for the browser tour.
For a real project, `side-dog panel ~/src/my-project` opens the local browser
timeline; its `/board` page shows the live roster. The server binds to loopback.
Claude Code requires optional project hooks for attributed tool activity; the
other registered agents read local metadata without Side Dog hooks.

## Coding agent support

Supports Codex, Claude Code, Pi, OpenCode, Crush, Cursor Agent, Grok Build,
DeepSeek Harness, Cline, and Antigravity CLI. Herdr is optional, not an agent.
See the [current integration table and setup instructions](https://github.com/qfennessy/side-dog/blob/main/docs/integrations.md).
It distinguishes session discovery from live activity, including Cursor/Grok
through T3 Code, and lists custom data-location variables.

## With or without Herdr

Herdr is optional. `side-dog watch .` pins an explicit folder in a standalone
terminal. Bare `watch` discovers agent folders; inside Herdr it follows Herdr
context. See [discovery and everyday use](https://github.com/qfennessy/side-dog/blob/main/docs/everyday-use.md).

## What Side Dog shows

Watch is chronological activity; Board presents current sessions. GitHub
polling adds state to matching work but never becomes credited agent effort.

Only validated metadata enters Side Dog history or its local browser panel.
See [privacy, configuration and disposable state](https://github.com/qfennessy/side-dog/blob/main/docs/configuration.md).
[Tokens and estimated cost](https://github.com/qfennessy/side-dog/blob/main/docs/usage.md) are separate from PR contribution counts.

## Terminal and panel controls

Press `?` for help, `v` for Watch settings, `b` for Board, and `w` to return.
In Board, `a` toggles contributions and the live roster, and `c` reopens the
temporary conflict notice. The browser panel's
`/board` page shows the live roster.
See [view-specific controls and workflows](https://github.com/qfennessy/side-dog/blob/main/docs/everyday-use.md).

## Configuration

Optional settings live in `~/.config/side-dog/config.toml`. Saved spaces, worktree
discovery, display preferences and notifications are explained in the
[configuration guide](https://github.com/qfennessy/side-dog/blob/main/docs/configuration.md).

## Other commands

`side-dog help` lists commands. `side-dog man` opens the bundled offline manual;
`side-dog man board` opens a command-specific page.

- [Troubleshooting](https://github.com/qfennessy/side-dog/blob/main/docs/troubleshooting.md)
- [Documentation validation and platform coverage](https://github.com/qfennessy/side-dog/blob/main/docs/validation.md)
- [Maintainer release guide](https://github.com/qfennessy/side-dog/blob/main/docs/releasing.md)
- [Dependency maintenance](https://github.com/qfennessy/side-dog/blob/main/docs/dependency-maintenance.md)
- [Security policy](https://github.com/qfennessy/side-dog/security/policy)

## Develop from a checkout

```sh
uv sync --locked
uv run python -m unittest discover -s tests -q
uv run python scripts/build_man_pages.py --check
python scripts/build_docs_site.py
python scripts/check_docs_links.py
```

Release preparation follows the maintainer guide; merging does not publish a package.

For private vulnerability reporting, use the
[security policy](https://github.com/qfennessy/side-dog/security/policy).
Do not put security details in public issues. Side Dog uses the [MIT License](https://github.com/qfennessy/side-dog/blob/main/LICENSE).
