# AI Sounds — full docs (https://aisounds.dev)

> Self-contained dump of every documentation page. For a lighter index, use /llms.txt.


---

# Source: https://aisounds.dev/docs

# AI Sounds documentation

> Open-source platform for adding sound notifications to AI coding tools like Cursor, Claude Code, and VS Code.

AI Sounds (AISE) lets developers install **sound packs** that play audio feedback when AI agents complete tasks, fail, send prompts, or trigger other lifecycle events. Packs are installed and managed through a small CLI, which configures the right hooks in each supported tool automatically.

## What you get

- A growing catalogue of community-uploaded sound packs.
- A single CLI (`aisounds`) that installs packs into Cursor, Claude Code, and more.
- A canonical event vocabulary (**AISE**) so the same pack works across tools.
- Per-pack control: activate one pack at a time, enable or disable individual events.

## Where to start

- **New here?** Read Getting started to install your first pack.
- **Confused by tools vs scopes?** Jump to Concepts: tools and scopes.
- **Looking for a command?** See the CLI reference.
- **Building a pack or integrating a tool?** Check the AISE events reference.
- **AI agent / LLM?** See For AI agents and /llms.txt.

## Supported tools

| Tool | Status | Hook config |
|------|--------|-------------|
| Cursor | Stable | `.cursor/hooks.json` |
| Claude Code | Stable | `.claude/settings.json` |
| VS Code | Planned | `settings.json` |
| Windsurf | Planned | TBD |
| Aider | Planned | TBD |

## License

The platform code is open source. Each pack carries its own license (CC0, CC-BY, CC-BY-SA, or MIT) declared in its manifest.


---

# Source: https://aisounds.dev/docs/getting-started

# Getting started

This guide walks you through installing the **`@aisounds/cli`** package (its binary is `aisounds`) and adding your first sound pack to **Cursor** or **Claude Code**.

## Prerequisites

- Node.js **>= 20**
- One of: Cursor, Claude Code (more tools coming soon)
- A terminal (PowerShell on Windows, bash/zsh on macOS / Linux)

## 1. Pick a pack

Browse aisounds.dev/packs and copy the slug of any pack you like. Every pack page has an **Install** snippet you can copy directly.

## 2. Install for a project

Run the CLI from the root of the project where you want sounds to play. The pack is downloaded and the corresponding tool's hook config is updated automatically.

```bash
npx @aisounds/cli@latest install <slug> --tool cursor
npx @aisounds/cli@latest activate <slug>
```

For Claude Code, just change the tool flag:

```bash
npx @aisounds/cli@latest install <slug> --tool claude-code
npx @aisounds/cli@latest activate <slug>
```

## 3. Install globally (optional)

If you want the same pack to apply across all your projects, use `--global`:

```bash
npx @aisounds/cli@latest install <slug> --tool claude-code --global
npx @aisounds/cli@latest activate <slug> --global
```

Global installs write to `~/.claude/settings.json` (Claude Code) or your tool's user-level config. See Concepts: tools and scopes for the full breakdown.

## 4. Restart your tool

Most tools only re-read their hook configuration on startup. **Close and reopen** Cursor or Claude Code after installing a new pack so the hooks load.

## 5. Trigger a sound

- In **Cursor**: ask the agent to do something and wait for it to finish — the `task_complete` sound plays on `Stop`.
- In **Claude Code**: send a prompt; on submit you should hear `prompt_sent`, and on response you should hear `task_complete`.

If nothing plays:

- Verify the pack was installed: `npx @aisounds/cli@latest list`
- Verify the pack is active: the active pack appears with a `*` next to it
- Inspect the tool's hook config (`.cursor/hooks.json` or `.claude/settings.json`)
- Try the audio command from the hook directly in your terminal
- Restart the tool

## Next steps

- Read Concepts: tools and scopes to understand how installs are isolated by project.
- Open the CLI reference for every command and flag.
- Want to mute some events? See `aisounds sounds <slug>` in the CLI reference.


---

# Source: https://aisounds.dev/docs/concepts

# Concepts: tools and scopes

When you install an `aisounds` pack you are choosing **two independent things at once**:

1. **Which tool** the sounds are wired into (Cursor, Claude Code, …).
2. **Which scope** they apply to (this project, or your whole user account).

These two dimensions are **orthogonal**: any combination is valid. Confusing them is the most common source of "why isn't it playing?" questions, so let's break them down.

## 1. Tool dimension

A **tool** is the AI coding app you want to react to events with sound. Each tool has its own:

- **Hook config file** the CLI writes into.
- **Set of supported events** (the names differ between tools).
- **Execution model** for hooks.

Same pack, same audio files under `.aisounds/packs/<slug>/`, but each tool gets its own "plug" in its native config format.

| Tool | Where we write | Supported events (sample) |
|------|----------------|----------------------------|
| **Cursor** | `.cursor/hooks.json` + scripts in `.cursor/hooks/aisounds/` | `stop`, `sessionStart`, `beforeSubmitPrompt`, `preToolUse` |
| **Claude Code** | `.claude/settings.json` (`hooks` block) | `Stop`, `StopFailure`, `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PermissionRequest`, `Notification` |
| **VS Code** | `.vscode/aisounds.json` + scripts in `.vscode/aisounds/` | `onChatResponseComplete`, `onChatRequestSent`, `onToolInvocation` (scripts; Copilot has no public auto-hooks yet) |
| **Windsurf / Aider** | — | Coming soon — use `--tool cursor` or `--tool claude-code` today |

You select the tool with `--tool` on `install`:

```bash
npx @aisounds/cli@latest install retro-beeps --tool cursor
npx @aisounds/cli@latest install retro-beeps --tool claude-code
npx @aisounds/cli@latest install retro-beeps --tool vscode
```

You can run both commands to install the same pack in **both** tools. They don't conflict — they write to different config files.

## 2. Scope dimension

A **scope** is where the install applies. There are two:

| Scope | Flag | Where state and hooks live |
|--------|-------|----------------------------|
| **Project** (default) | _none_ or `--project <path>` | Inside your project: `.aisounds/installed.json`, `.cursor/hooks.json`, `.claude/settings.json` |
| **Global** | `--global` | In your user folder: `~/.aisounds/installed.json`, `~/.claude/settings.json`, `~/.cursor/hooks.json` |

- **Project scope** is the default and is what you want for "sounds only when I work in this repo".
- **Global scope** applies to every workspace your tool opens, unless overridden by a project-level config.

The active pack and the list of installed packs are tracked **per scope**. Each scope has its own `installed.json`.

## 3. How they combine

The two dimensions form a 2x2 matrix. Every install command picks **one cell**:

|              | **Project**                                     | **Global**                                       |
|--------------|--------------------------------------------------|--------------------------------------------------|
| **Cursor**   | `install <slug> --tool cursor`                  | `install <slug> --tool cursor --global`         |
| **Claude**   | `install <slug> --tool claude-code`             | `install <slug> --tool claude-code --global`    |

You can fill multiple cells at once. For example:

```bash
# Pack A in this project, Cursor + Claude
npx @aisounds/cli@latest install pack-a --tool cursor
npx @aisounds/cli@latest install pack-a --tool claude-code

# Pack B globally for Claude only
npx @aisounds/cli@latest install pack-b --tool claude-code --global
```

`activate` works **per scope**: activating in project does not change global, and vice versa.

```bash
npx @aisounds/cli@latest activate pack-a              # affects project state only
npx @aisounds/cli@latest activate pack-b --global     # affects global state only
```

## 4. AISE: the canonical event vocabulary

Each pack maps audio files to events from the **AISE** (AI Sound Events) standard, e.g. `task_complete`, `task_failed`, `prompt_sent`. Tools translate AISE events into their own hook names through internal mappings.

This means a pack author writes once against AISE, and the same pack works in any supported tool.

## 5. Quick troubleshooting

- **Pack installed but no sound?** Check that you ran `activate` for the right scope, and restart the tool.
- **Two packs interfering?** Activating a pack in a scope replaces the previous active one in that same scope. They don't stack.
- **Wrong scope?** Run `aisounds list` (project) or `aisounds list --global` (global) to see what is installed where.
- **Want to silence one event?** Use `aisounds sounds <slug>` to enable / disable specific events without uninstalling.


---

# Source: https://aisounds.dev/docs/cli

# CLI reference

The CLI is published on npm as **`@aisounds/cli`** (the binary it installs is named `aisounds`). You can run it directly with `npx`:

```bash
npx @aisounds/cli@latest <command> [options]
```

Or install it globally and use the shorter `aisounds` binary:

```bash
npm install -g @aisounds/cli
aisounds <command> [options]
```

## Common flags

These are accepted by most commands:

| Flag | Description |
|------|-------------|
| `--global` | Operate on **global scope** instead of project scope. |
| `--project <path>` | Operate on a specific project path instead of the current directory. |
| `--tool <tool>` | Target a specific tool: `cursor`, `claude-code`, `vscode` (planned), `windsurf` (planned), `aider` (planned). |

See Concepts: tools and scopes for the full meaning of these dimensions.

---

## install

Download a pack from aisounds.dev and configure hooks for the chosen tool.

```bash
aisounds install <slug> [--tool <tool>] [--global] [--project <path>]
```

If no pack is currently active in the target scope, the newly installed pack is **automatically activated**. Otherwise it is downloaded but not enabled — run `activate` to switch.

**Examples**

```bash
npx @aisounds/cli@latest install retro-beeps --tool cursor
npx @aisounds/cli@latest install retro-beeps --tool claude-code --global
npx @aisounds/cli@latest install retro-beeps --tool cursor --project ./my-app
```

## activate

Set the **active pack** in a scope. The CLI removes hooks for any other pack in that same scope and writes hooks only for the chosen pack. Only one pack is active per scope.

```bash
aisounds activate <slug> [--global] [--project <path>]
```

**Examples**

```bash
npx @aisounds/cli@latest activate retro-beeps
npx @aisounds/cli@latest activate retro-beeps --global
```

## remove

Remove an installed pack and revert its hook entries from the tool config(s).

```bash
aisounds remove <slug> [--tool <tool>] [--global] [--project <path>]
```

By default, hooks are removed from **every tool** the pack was installed for. Pass `--tool` to remove from a single tool only.

**Examples**

```bash
npx @aisounds/cli@latest remove retro-beeps
npx @aisounds/cli@latest remove retro-beeps --tool cursor
```

## list

List all installed packs across project and global scopes. The active pack in each scope is marked with a `*`.

```bash
aisounds list [--global] [--project <path>]
```

## info

Show details for a pack from aisounds.dev (works without installing).

```bash
aisounds info <slug>
```

## sounds

Open an interactive checklist to enable or disable individual events for an installed pack. Useful when you want a pack but only some of its sounds.

```bash
aisounds sounds <slug> [--project <path>]
```

If the pack is the active one, hooks are regenerated immediately based on the new selection.

## preview

Play every sound in a pack from the terminal, in order. Useful for auditioning packs before installing.

```bash
aisounds preview <slug>
```

### Linux playback requirements

On Linux, playback is best-effort and requires at least one backend:

- `paplay` (`pulseaudio-utils`)
- `ffplay` (`ffmpeg`)
- `mpv` (`mpv`)

If users hear distorted/noisy output, it usually means none of those backends are installed. Install at least one backend and retry `aisounds preview <slug>`.

## update

Re-install packs whose upstream version has changed.

```bash
aisounds update [--global] [--project <path>]
```

## State files

The CLI stores its bookkeeping in JSON files. You normally don't edit these by hand, but they're useful for debugging:

- **Project**: `<project>/.aisounds/installed.json`
- **Global**: `~/.aisounds/installed.json`

Each file tracks the installed pack list, the active pack slug, and per-pack disabled events.


---

# Source: https://aisounds.dev/docs/events

# AISE events reference

**AISE** (AI Sound Events) is the canonical vocabulary every pack maps its sounds against. Pack authors target AISE; tool installers translate AISE into the native hook names of each tool.

Only `task_complete` is **required** in a pack — every other event is optional.

## All AISE events

Events are grouped by category. The **Required** column shows whether a pack must include a sound for that event (only `task_complete` is mandatory).

### Agent

| Event | Required | Description |
| :---- | :--------: | :---------- |
| `task_complete` | Yes | Agent finished the current task successfully |
| `task_failed` |  | Agent stopped with an error or was aborted |
| `subtask_complete` |  | A subtask within a larger task finished |
| `subtask_failed` |  | A subtask within a larger task failed |

### User interaction

| Event | Required | Description |
| :---- | :--------: | :---------- |
| `prompt_sent` |  | The user submitted a prompt |
| `approval_needed` |  | The agent is requesting user permission |
| `approval_granted` |  | The user approved a request |
| `approval_denied` |  | The user denied a request |

### Processing

| Event | Required | Description |
| :---- | :--------: | :---------- |
| `thinking_start` |  | The agent began reasoning |
| `thinking_end` |  | The agent finished reasoning |
| `tool_called` |  | The agent invoked a tool |
| `tool_complete` |  | A tool invocation finished |

### File system

| Event | Required | Description |
| :---- | :--------: | :---------- |
| `file_created` |  | A file was created |
| `file_modified` |  | A file was modified |
| `file_deleted` |  | A file was deleted |

### Session

| Event | Required | Description |
| :---- | :--------: | :---------- |
| `session_start` |  | A new agent session started |
| `session_end` |  | An agent session ended |
| `session_error` |  | An agent session crashed |

### Special

| Event | Required | Description |
| :---- | :--------: | :---------- |
| `notification` |  | A generic notification |
| `warning` |  | A non-fatal warning |
| `celebration` |  | A milestone or celebration |

All sounds must be **<= 10 seconds** long. The `loop` flag is forbidden except optionally on `thinking_start`.

## Tool mappings

Not every tool exposes every AISE event. The CLI only writes hooks for the events a tool actually supports.

### Cursor

Hooks live in `.cursor/hooks.json` (project) or `~/.cursor/hooks.json` (global). Cursor multiplexes both task results into the single `stop` hook with a `status` field.

| AISE event | Cursor hook |
| :--------- | :---------- |
| `task_complete` | `stop` when `status=completed` |
| `task_failed` | `stop` when `status=error` or `status=aborted` |
| `prompt_sent` | `beforeSubmitPrompt` |
| `tool_called` | `preToolUse` |
| `session_start` | `sessionStart` |

### Claude Code

Hooks live under `hooks` in `.claude/settings.json` (project) or `~/.claude/settings.json` (global). Claude Code uses separate hooks for success vs failure.

| AISE event | Claude Code hook |
| :--------- | :--------------- |
| `task_complete` | `Stop` |
| `task_failed` | `StopFailure` |
| `session_start` | `SessionStart` |
| `session_end` | `SessionEnd` |
| `prompt_sent` | `UserPromptSubmit` |
| `approval_needed` | `PermissionRequest` |
| `notification` | `Notification` |

### VS Code (planned)

| AISE event | VS Code hook |
| :--------- | :----------- |
| `task_complete` | `onChatResponseComplete` |
| `prompt_sent` | `onChatRequestSent` |
| `tool_called` | `onToolInvocation` |

### Windsurf, Aider (planned)

These installers are stubs today and will be filled in as the integrations mature.

## How a pack maps events

Pack manifests use AISE keys directly. Example fragment of a `aisounds.json`:

```json
{
  "sounds": {
    "task_complete": {
      "file": "sounds/task_complete.ogg",
      "file_fallback": "sounds/task_complete.mp3",
      "duration_ms": 1200,
      "loop": false
    },
    "task_failed": {
      "file": "sounds/task_failed.ogg",
      "file_fallback": "sounds/task_failed.mp3",
      "duration_ms": 1800,
      "loop": false
    }
  }
}
```

The CLI never asks you which tool hook to wire each sound to — the AISE -> tool mappings above are applied automatically based on the `--tool` flag.


---

# Source: https://aisounds.dev/docs/for-llms

# For AI agents

If you are an AI coding assistant (Cursor agent, Claude Code, ChatGPT in a CLI session, …) reading this page on behalf of a user, this is the canonical reference for installing **aisounds** packs autonomously.

There is also a machine-friendly index at /llms.txt and a self-contained dump at /llms-full.txt.

The CLI is published on npm as **`@aisounds/cli`** (the installed binary is named `aisounds`).

## When the user asks for a sound pack

1. **Find the pack slug.** It is in the URL of the pack page: `aisounds.dev/packs/<slug>`. The user will usually paste it directly.
2. **Pick a tool.** Use the tool the user is currently driving you in:
   - In Cursor -> `--tool cursor`
   - In Claude Code -> `--tool claude-code`
3. **Pick a scope.** Default to **project** (no flag) unless the user asks for "everywhere" / "all projects" / "globally" — then add `--global`.

## Canonical install command

Run these from the **project root** the user wants the sounds in.

For Cursor:

```bash
npx @aisounds/cli@latest install <slug> --tool cursor
npx @aisounds/cli@latest activate <slug>
```

For Claude Code:

```bash
npx @aisounds/cli@latest install <slug> --tool claude-code
npx @aisounds/cli@latest activate <slug>
```

After installing, **tell the user to restart their tool** so the hook config is reloaded.

## Multiple tools at once

If the user uses both Cursor and Claude Code, install for both:

```bash
npx @aisounds/cli@latest install <slug> --tool cursor
npx @aisounds/cli@latest install <slug> --tool claude-code
npx @aisounds/cli@latest activate <slug>
```

Each install writes only to its tool's config file; they do not conflict.

## Linux audio prerequisites

On Linux, hook playback is best-effort and expects at least one available backend:

- `paplay` (package: `pulseaudio-utils`)
- `ffplay` (package: `ffmpeg`)
- `mpv` (package: `mpv`)

If the user reports noisy/distorted output, treat it as a missing backend issue and tell them to install at least one of the three backends above, then run:

```bash
npx @aisounds/cli@latest preview <slug>
```

## Verifying

```bash
npx @aisounds/cli@latest list
```

Look for the pack slug followed by `*` — that's the active pack. If a sound does not play, check:

1. Pack is installed and active for the right scope.
2. The user restarted Cursor / Claude Code after install.
3. The relevant audio file under `.aisounds/packs/<slug>/sounds/` exists.
4. Tool hook config (`.cursor/hooks.json` or `.claude/settings.json`) contains an entry tagged with `_aisounds`.

## Disabling individual events

If the user wants only some sounds, do not edit the hook configs by hand. Use:

```bash
npx @aisounds/cli@latest sounds <slug>
```

This is interactive (checkbox UI). If you cannot run interactive commands, ask the user to run it themselves and explain that they can deselect events they don't want.

## Removing

```bash
npx @aisounds/cli@latest remove <slug>
```

Removes the pack and reverts every hook entry the CLI wrote for it.

## Don't do these

- **Don't write to `.cursor/hooks.json` or `.claude/settings.json` by hand.** Always use the CLI — it is non-destructive and keeps `_aisounds` markers so it can revert cleanly later.
- **Don't run `aisounds install` from a random directory.** Run it from the project root so project scope is correct, or pass `--project <path>` explicitly.
- **Don't use `--global` unless asked.** Project scope is the safer default.