Skip to content
kintnerPublic

About

A macOS menu bar app for managing GitHub Codespaces

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Puffy app icon

Puffy

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
Puffy in the macOS menu bar with one stopped codespace Codespace submenu with Start, editor and browser actions, and codespace details New Codespace submenu with a Puffy repository preset

Important

This is an agent-driven project. The code has not been reviewed by a human. Use at your own risk.

Install

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.app

The app isn't Developer ID-signed or notarized; xattr clears the download quarantine that prevents launch.

Sign in

Puffy automatically uses your gh CLI login. Grant Codespaces access if needed:

gh auth refresh -s codespace

Alternatively, 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.

Usage & presets

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.

Troubleshooting

Not signed in / 403: Check your login and the permissions in Sign in. For gh, run gh auth refresh -s codespace.

Development

Requires Xcode. Build and install:

./build.sh --install

To 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 RefreshStrategySpec

Release:

./release.sh 0.0.1 --dry-run   # build and package without tagging
./release.sh 0.0.1             # bump version, tag, and publish

Releasing requires a clean, pushed working tree.

Contributing

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.

About

A macOS menu bar app for managing GitHub Codespaces

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages