1. Requirements
2. Installation
3. First launch
4. Daily usage
5. Slash commands
6. Settings & configuration
7. Troubleshooting
8. Development
9. Project layout

Pick one method below.

Best if you want the fastest install path with the fewest manual steps.

brew install --cask random-guy-05/tap/hackclub-ai

What this cask does:

• downloads the release DMG from GitHub Releases
• installs HackClub AI.app into your Applications folder
• removes the quarantine attribute automatically
• launches the app automatically after install

If you prefer to add the tap first, this works too:

brew tap random-guy-05/tap && brew install --cask hackclub-ai

Best if you just want the app and do not need to touch the source code.

1. Get a DMG

   • Download a release from GitHub Releases, or
   • Build one locally (see Method 3).

2. Open the DMG
   Double-click HackClub-AI.dmg.

3. Drag to Applications
   Drag HackClub AI onto the Applications folder shortcut in the window.

4. Launch the app

   • Open Applications and double-click HackClub AI, or
   • Press ⌘Space, type HackClub AI, and press Return.

5. First launch security (if macOS blocks the app)
   If you see “cannot be opened because the developer cannot be verified”:

   • Open System Settings → Privacy & Security
   • Click Open Anyway next to the HackClub AI message, then confirm.

   Alternatively, right-click the app in Finder → Open → Open again.

Best if you are developing, want the latest code, or need to create a DMG to share.

# 1. Clone the repo
git clone https://github.com/random-guy-05/hackclub-ai.git ~/Documents/hackclub-ai
cd ~/Documents/hackclub-ai

# 2. Build the app bundle, install it, and create a DMG
chmod +x scripts/build_macos_app.sh
./scripts/build_macos_app.sh

What this produces:

The built app bundles its own Python runtime — you do not need a separate venv to run it.

Launch after build:

open ~/Applications/HackClub\ AI.app

Use this when you are actively editing code and want instant changes without rebuilding the .app.

# 1. Clone the repo
git clone https://github.com/random-guy-05/hackclub-ai.git ~/Documents/hackclub-ai
cd ~/Documents/hackclub-ai

# 2. Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Launch the UI
python hackclub_app.py

Optional launch flags:

python hackclub_app.py "explain quicksort"     # start with an initial prompt
python hackclub_app.py --resume                  # pick a saved session on launch
python hackclub_app.py --resume SESSION_ID       # resume a specific session

1. HackClub AI opens with an empty chat or welcome screen.

2. Enter your API key when prompted.
   Get a free key at ai.hackclub.com.

3. The key is saved locally at:

   ~/.hackclub-ai/config.json
   

   You can change it anytime in Settings (⌘,).

4. Start chatting — type a message and press Return.

Upgrading from an older install?
If you previously used .hackclub-ai-shell/, the app automatically migrates your config and sessions to ~/.hackclub-ai/ on first launch.

The composer footer shows context usage and token counts (ctx, in, out).

Sessions auto-save to ~/.hackclub-ai/sessions/.

Attach files or folders when you want the model to read project context:

There is no fixed workspace — attach context only when you need it.

• Switch in Settings, View menu, or with /theme.
• Compact message view — denser transcript; toggle in Settings or View → Toggle Compact.

Type / in the composer to open the command menu, or enter a command directly.

Exported chats are saved to ~/Downloads/hackclub-chat-*.{md,json}.

Open Settings (⌘,):

These override defaults. The built .app reads HACKCLUB_API_KEY from config first; env vars are mainly useful when running from source.

This is most likely with locally built apps or direct DMG installs because the app is not notarized by Apple.

1. Try the Homebrew install path first. It removes quarantine automatically and opens the app after install.
2. If you installed from a DMG or built locally, right-click HackClub AI in Applications → Open → confirm Open.
3. Or use System Settings → Privacy & Security → Open Anyway.

1. Confirm your key at ai.hackclub.com.
2. Open Settings (⌘,) and re-enter the key.
3. Or edit ~/.hackclub-ai/config.json directly.

Check the log:

tail -50 ~/Library/Logs/HackClub-AI.log

Then rebuild:

cd ~/Documents/hackclub-ai
./scripts/build_macos_app.sh

cd ~/Documents/hackclub-ai
rm -rf build dist ~/Applications/HackClub\ AI.app
./scripts/build_macos_app.sh

python scripts/make_icon.py

python scripts/render_ui.py           # conversation view
WELCOME=1 python scripts/render_ui.py # welcome screen

./scripts/build_macos_app.sh

./scripts/build_macos_app.sh now regenerates Casks/hackclub-ai.rb automatically after building the DMG.

You can also regenerate it directly:

python3 scripts/generate_homebrew_cask.py

1. Set the release version in VERSION.
2. Run ./scripts/build_macos_app.sh.
3. Upload dist/HackClub-AI.dmg to GitHub Releases under tag v<version>.
4. Commit the updated Casks/hackclub-ai.rb.
5. Copy Casks/hackclub-ai.rb into the homebrew-tap repository so users can run brew install --cask random-guy-05/tap/hackclub-ai.

Released under the MIT License.