https://github.com/fiam/octowatch
https://github.com/fiam/octowatch
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/fiam/octowatch
- Owner: fiam
- License: mit
- Created: 2026-04-03T13:41:45.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T21:19:22.000Z (2 months ago)
- Last Synced: 2026-04-12T23:12:42.166Z (2 months ago)
- Language: Swift
- Size: 3.18 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Octowatch
Octowatch is a macOS app that watches GitHub and pulls the work
that needs your attention into one place.
It lives in the menu bar, opens into a full triage window when you need
more context, and focuses on actionable pull requests, notifications,
workflow runs, and security alerts without requiring a GitHub App or
webhooks.
Website: [octowatch.app](https://octowatch.app)
## Requirements
- macOS 26 or newer
- Swift 6.2+
- XcodeGen for local Xcode project generation
## Install
Published releases are universal (`arm64` + `x86_64`), Developer ID
signed, notarized, and support Sparkle in-app updates.
- Direct download: [octowatch.app](https://octowatch.app)
- GitHub Releases:
- Homebrew:
```bash
brew install --cask fiam/tap/octowatch
```
## Screenshot
## What It Does
- Builds a single inbox from pull requests, issues, workflows, and
GitHub notifications
- Highlights a `Your Turn` section with configurable rules for what
needs action now
- Shows rich pull request detail with checks, review threads, timeline,
merge state, and direct actions
- Tracks workflow failures and approval-gated deployments connected to
your pull requests
- Surfaces GitHub security alerts without collapsing them into generic
comment notifications
- Supports local read state, snoozing, ignoring, undo, and a menu bar
quick-view for fast triage
## Authentication
Octowatch prefers GitHub CLI when it is available:
- if `gh` is installed and authenticated, Octowatch reuses
`gh auth token`
- if you do not want to use GitHub CLI, you can enter a personal access
token in Settings
- Settings includes a helper sheet that explains how to create a token
and links directly to GitHub token settings
- manually entered tokens are saved in Keychain for future launches
On first launch, Octowatch always shows a setup guide so the auth path
is explicit. The guide first explains how GitHub notifications shape
repository coverage, then how the default `Your Turn` and
`On Your Radar` inbox sections work, and finally how Octowatch will
authenticate on this Mac. If GitHub CLI is already ready, the guide
tells you that Octowatch will use it and still offers a direct path to
switch to a personal access token.
Because Octowatch reads GitHub notifications, the token must work with
the Notifications API. In practice, that usually means:
- classic personal access tokens work
- fine-grained personal access tokens are often not enough for the
notifications endpoints Octowatch depends on
Repository coverage follows GitHub notifications:
- subscribe to a repository on GitHub if you want Octowatch to surface
more of that repository's activity
- if a repository is ignored on GitHub, GitHub stops sending those
notifications and Octowatch will stay silent about that repository too
- ignoring an item in Octowatch only hides it in Octowatch; it does not
change your notification settings for that repository on GitHub
## Getting Started
To run Octowatch from source:
```bash
git clone
cd octowatch
swift build
swift run
```
If you want to work in Xcode:
```bash
xcodegen generate
open Octowatch.xcodeproj
```
The generated `.xcodeproj` is local-only and is not committed.
## Website And Releases
- The project website sources live in [`website/`](website/).
- GitHub Pages deployment is defined in
[`.github/workflows/pages.yml`](.github/workflows/pages.yml).
- CI validation is defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
- Release automation is defined in
[`.github/workflows/release.yml`](.github/workflows/release.yml).
- Releases are versioned with `release-please`; see
[docs/RELEASING.md](docs/RELEASING.md) for the public release flow.
## Product Notes
- Polling only. No GitHub App, webhooks, or background service
required.
- Default refresh interval is 60 seconds.
- GitHub notification threads are fetched from both read and unread
feeds, while the inbox read/unread state remains local to Octowatch.
- If the app starts while offline, it shows a dedicated recovery state
and retries automatically when connectivity returns.
## Roadmap
The current shipped scope and remaining gaps live in
[PRD.md](PRD.md).
The main items still open are:
- richer issue detail
- mark-section-read / mark-all-read actions
- deeper keyboard navigation
- stale PR indicators
- deep-link support
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
## Security
See [SECURITY.md](SECURITY.md).
## License
[MIT](LICENSE)