AgentCraft Sound Packs

Sound packs are git repos containing audio files. Any GitHub repo can be a pack — no approval, no registry required. Install by publisher/name slug, same as GitHub.

Installing Packs

From the CLI

agentcraft init                                    # first-time setup
agentcraft add rohenaz/agentcraft-sounds           # official pack
agentcraft add publisher/repo-name                 # any GitHub repo
agentcraft list                                    # show installed packs
agentcraft update rohenaz/agentcraft-sounds        # git pull one pack
agentcraft update                                  # update all packs
agentcraft remove publisher/repo-name              # uninstall
agentcraft init my-sounds                          # scaffold a new pack repo

agentcraft pack install publisher/repo-name resolves to https://github.com/publisher/repo-name and clones into ~/.agentcraft/packs/publisher/repo-name/.

Install the CLI globally:

bun install -g agentcraft   # or: npm install -g agentcraft

From the Dashboard

Open the PACKS tab in the AgentCraft dashboard. When opening the dashboard, always pass the client identifier: http://localhost:4040?client=claude-code or http://localhost:4040?client=opencode. Installed packs show UPDATE/REMOVE buttons. The BROWSE PACKS section fetches the community registry and shows packs not yet installed with an INSTALL button.

Manual Install (identical result)

git clone https://github.com/publisher/repo-name ~/.agentcraft/packs/publisher/repo-name

Manual clone and CLI install are exactly equivalent — no manifest or registration step.

Pack Storage

Packs live at ~/.agentcraft/packs/<publisher>/<name>/. The dashboard auto-discovers everything at that path depth — any directory placed there works.

~/.agentcraft/packs/
  rohenaz/
    agentcraft-sounds/     ← official pack
  publisher/
    custom-pack/           ← any git repo cloned here

Sound Assignment Paths

Assigned sounds are stored in ~/.agentcraft/assignments.json with a pack-prefixed path:

rohenaz/agentcraft-sounds:sc2/terran/session-start/scv-ready.mp3

Format: publisher/name:internal/path/to/sound.mp3

The hook script resolves this to the absolute path at runtime:

~/.agentcraft/packs/rohenaz/agentcraft-sounds/sc2/terran/session-start/scv-ready.mp3

Publishing a Pack

Any GitHub repo with audio files (.mp3, .wav, .ogg, .m4a) is a valid pack. No manifest required — directory structure is the organization.

Step 0: Scaffold with the CLI (fastest path)

agentcraft init my-sounds

This generates a ready-to-use pack directory with pack.json, README.md, example directories, and publishing instructions. Then drop your audio files in and push.

Step 1: Organize the repo

Recommended structure — group sounds into directories by game, theme, or purpose:

my-sounds/
  sc2/
    terran/
      session-start/
        ready.mp3
      task-complete/
        salute.mp3
  halo/
    unsc/
      session-start/
        wake-up.mp3
  ui/               ← optional: UI theme sounds
    sc2/
      click.mp3
      hover.mp3

Any directory layout works. The dashboard groups sounds by their directory path.

Step 2: Add pack.json (optional but recommended)

{
  "name": "my-sounds",
  "publisher": "your-github-username",
  "version": "1.0.0",
  "description": "Short description of the pack",
  "types": ["sounds", "ui"]
}

types is informational. Use "ui" if the pack includes a ui/ directory with dashboard theme sounds.

Step 3: Tag the repo on GitHub

Add the agentcraft-pack topic to the GitHub repo. This makes it discoverable in:

• The community registry at https://rohenaz.github.io/agentcraft-registry/
• GitHub search: https://github.com/topics/agentcraft-pack

To tag: GitHub repo → Settings → Topics → type agentcraft-pack → Save.

The registry GitHub Action runs every 6 hours and automatically picks up newly tagged repos.

Step 4: Share the install command

agentcraft add your-username/your-repo-name

That's the entire publish workflow — push to GitHub, tag it, done.

Pack Discovery

Find community packs three ways:

1. Dashboard — PACKS tab → BROWSE PACKS section shows the registry
2. Registry — https://github.com/topics/agentcraft-pack
3. Registry JSON — https://rohenaz.github.io/agentcraft-registry/index.json

UI Theme Sounds

Packs can include a ui/ directory with sounds that play during dashboard interactions (hover, click, page change, etc.). The dashboard's UI SFX dropdown selects which pack's UI theme to use.

Structure the ui/ directory by theme name:

ui/
  sc2/
    click.mp3
    hover.mp3
    confirm.mp3
    error.mp3
    pageChange.mp3
  wc3/
    click.mp3
    ...

Additional Resources

• references/pack-format.md — Full audio file requirements, directory naming conventions, and pack.json schema
• Registry source — https://github.com/rohenaz/agentcraft-registry