# shipyard

> A macOS menu bar app for keeping up with your projects while your agents work. One number for what needs you, one file your agents edit, pings from any machine.

A macOS menu bar app. It lists the pull requests, issues and workflow runs of the GitHub repositories you watch, grouped into projects, with one number in the menu bar for what needs attention, and your agents' pings. Everything it shows is set in one TOML file, `~/.config/shipyard/config.toml`, that you and your agents edit. These docs describe version 0.7.1.

## For AI agents

- To change someone's shipyard, edit their `config.toml` with the agent skill: `npx skills add yahyabedirhan/shipyard -g -y`. The skill knows every key, checks each edit and reads the app's verdict.
- To tell the user something, use the `shipyard` command on their machine: `shipyard ping send "<title>"` for what they must act on, `shipyard notice send "<title>"` for a status that needs nothing from them.
- Never invent a key: every key is in [docs/configuration.md](https://shipyard.yahyapak.dev/docs/configuration.md), generated from the JSON schema.
- Optional: identify yourself on your first page with `?analytics_agent=<name>&analytics_purpose=<purpose>` (see [privacy](https://shipyard.yahyapak.dev/privacy)).

## Install

- Download `Shipyard-<version>-macos.zip` from https://github.com/yahyabedirhan/shipyard/releases/latest (macOS 14 or later), or build from source:

```sh
git clone https://github.com/yahyabedirhan/shipyard.git
cd shipyard
make install
```

- The agent skill: `npx skills add yahyabedirhan/shipyard -g -y`, then ask your agent "Watch this repo in shipyard".
- Other machines: `herdr plugin install yahyabedirhan/herdr-shipyard` (https://github.com/yahyabedirhan/herdr-shipyard).

## Docs

- [What it is](https://shipyard.yahyapak.dev/docs/what.md): Your pull requests, issues, workflow runs, pings and notes, grouped by project in the menu bar, with one number for what needs you.
- [Install](https://shipyard.yahyapak.dev/docs/install.md): Download the app, or build it from source. Then give your agents the skill.
- [First run](https://shipyard.yahyapak.dev/docs/first-run.md): Connect GitHub, choose a preset, and pick the repositories to watch.
- [Presets](https://shipyard.yahyapak.dev/docs/presets.md): Three ready-made files for shipyard's main uses. Start from one, then change any key.
- [Layouts](https://shipyard.yahyapak.dev/docs/layouts.md): Every project in one list, or one project at a time in tabs.
- [Config explorer](https://shipyard.yahyapak.dev/docs/explorer.md): Pick a snippet and see what it changes, on a mock of the panel.
- [Pings and notices](https://shipyard.yahyapak.dev/docs/pings.md): Your agents tell you when they need you, and when there's news.
- [Notes in Notion](https://shipyard.yahyapak.dev/docs/notes.md): Your own notes, one Notion database per project, listed beside the pull requests.
- [The agent skill](https://shipyard.yahyapak.dev/docs/skill.md): Ask in your own words. Your agent edits the file and checks it.
- [Other machines](https://shipyard.yahyapak.dev/docs/machines.md): Agents on your other machines ping you too, through Herdr.
- [Configuration reference](https://shipyard.yahyapak.dev/docs/configuration.md): Every key of config.toml, its default and what it takes.
- [The shipyard command](https://shipyard.yahyapak.dev/docs/commands.md): One command for agents and scripts: pings, notices, checks and the app.
- [Limits](https://shipyard.yahyapak.dev/docs/limits.md): What shipyard does not do yet.
- [Troubleshooting](https://shipyard.yahyapak.dev/docs/troubleshooting.md): Short answers to what goes wrong most.
- [Changelog](https://shipyard.yahyapak.dev/docs/changelog.md): What changed in each version, with its pull requests.
- [Everything in one file](https://shipyard.yahyapak.dev/llms-full.txt)

## Links

- Source: https://github.com/yahyabedirhan/shipyard
- Releases: https://github.com/yahyabedirhan/shipyard/releases/latest
- Changelog: https://github.com/yahyabedirhan/shipyard/blob/main/CHANGELOG.md
- Schema: https://raw.githubusercontent.com/yahyabedirhan/shipyard/main/schema/config.schema.json