A macOS menu bar app for GitHub Codespaces. See status, start and stop codespaces, create from presets, and open in VS Code or your browser.
| Menu bar | Codespace actions | New Codespace |
|---|---|---|
Important
This is an agent-driven project. The code has not been reviewed by a human. Use at your own risk.
Download and unzip the latest app from Releases, then run:
mv Puffy.app /Applications/
xattr -dr com.apple.quarantine /Applications/Puffy.app
open /Applications/Puffy.appThe app isn't Developer ID-signed or notarized; xattr clears the download
quarantine that prevents launch.
Puffy automatically uses your gh CLI login.
Grant Codespaces access if needed:
gh auth refresh -s codespaceAlternatively, paste a fine-grained token in Settings → Account with these repository permissions:
| Permission | Access |
|---|---|
| Codespaces | Read and write |
| Codespaces lifecycle admin | Read and write |
| Codespaces metadata | Read-only |
| Metadata | Read-only |
A classic token with
the codespace scope works as well.
Tokens are stored in the macOS login Keychain.
Open the menu to view and manage codespaces. Puffy refreshes on menu open, hover, wake, and during operations—not on a fixed schedule.
Add a repository in Settings → Presets, choose a branch, devcontainer, and
machine, then create from New Codespace. Blank optional fields use GitHub's
defaults. Presets live at ~/.config/puffy/presets.json; after manual edits,
choose New Codespace → Reload Presets.
Settings → General controls your preferred editor, automatic opening,
notifications, and launch at login. Move Puffy to /Applications before
enabling launch at login.
Not signed in / 403: Check your login and the permissions in
Sign in. For gh, run gh auth refresh -s codespace.
Requires Xcode. Build and install:
./build.sh --installTo run without installing, use ./build.sh && open build/Puffy.app.
See DESIGN.md for architecture and implementation details.
See screenshot instructions to reproduce the README images with isolated demo data.
Smoke tests drive the real app against a stub API and require Accessibility permission for your terminal:
./build.sh && swift test --filter RefreshStrategySpecRelease:
./release.sh 0.0.1 --dry-run # build and package without tagging
./release.sh 0.0.1 # bump version, tag, and publishReleasing requires a clean, pushed working tree.
Puffy is a personal passion project exploring agentic workflows. Pull requests are disabled, but you're welcome to fork the project and have your own agent remix it as needed.