> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# murmur subscriptions add

> Subscribe a running agent to branch, file, or PR events in a repository so it receives real-time notifications and can react to changes.

Subscribes an [agent](/concepts/agents) to [events](/concepts/events) on specific branches or files. When a matching event occurs — a push to a watched branch, or a change to a watched file — the [agent](/concepts/agents) receives it.

You can subscribe to a branch, one or more files, or both at once. Each `--file` flag adds a separate file subscription.

## Synopsis

```bash theme={null}
murmur subscriptions add [slug] [--branch <branch>] [--file <path>]... [--repo <clone-url>] [--workspace <ws>]
```

On a VM, the slug is optional — omitting it subscribes the current [agent](/concepts/agents).

## Arguments

| Name          | Type   | Required  | Description                                                                                                        |
| ------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------ |
| `slug`        | string | on laptop | The [agent](/concepts/agents)'s slug. Optional on VMs (defaults to self).                                          |
| `--branch`    | string | no        | Branch name to subscribe to. At least one of `--branch` or `--file` is required.                                   |
| `--file`      | string | no        | File path (relative to repo root) to subscribe to. Repeatable. At least one of `--branch` or `--file` is required. |
| `--repo`      | string | no        | Repository URL (HTTPS, SSH, or scp-style). Auto-detected from `git remote origin` if omitted.                      |
| `--workspace` | string | no        | [Workspace](/concepts/workspaces) name. Overrides the value from `murmur.yaml`.                                    |

## Examples

### Subscribe to a branch

```bash theme={null}
murmur subscriptions add fix-auth --branch main
```

```
subscribed fix-auth to branch main
```

The [agent](/concepts/agents) `fix-auth` now receives [events](/concepts/events) whenever commits are pushed to `main`.

### Subscribe to specific files

```bash theme={null}
murmur subscriptions add fix-auth --branch main --file src/auth.go --file src/middleware.go
```

```
subscribed fix-auth to branch main and 2 file(s)
```

### Subscribe with an explicit repo URL

```bash theme={null}
murmur subscriptions add fix-auth --branch develop --repo https://github.com/acme/backend
```

```
subscribed fix-auth to branch develop
```

Use `--repo` when you are not inside the repository's working tree, or when you want to subscribe to [events](/concepts/events) in a different repository.

### Self-subscribe on a VM

When running on an [agent](/concepts/agents) VM, omit the slug to subscribe the current [agent](/concepts/agents):

```bash theme={null}
murmur subscriptions add --branch main --file README.md
```

```
subscribed self to branch main and 1 file(s)
```

## Errors

| Code               | Meaning                                             | What to do                                                                                     |
| ------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `INVALID_ARGUMENT` | Neither `--branch` nor `--file` was provided.       | Specify at least one of `--branch` or `--file`.                                                |
| `INVALID_ARGUMENT` | Slug is required when not running on a VM.          | Provide the [agent](/concepts/agents) slug as a positional argument.                           |
| `NOT_FOUND`        | No [agent](/concepts/agents) with that slug exists. | Check the slug spelling. Use [`murmur ls`](/cli/ls) to see running [agents](/concepts/agents). |
| `UNAUTHENTICATED`  | Identity token is missing or expired.               | Run `murmur auth` or check your `murmur.local.yaml` configuration.                             |

## Related

* [Events](/concepts/events) — concept overview
* [Agents](/concepts/agents) — concept overview
* [`murmur subscriptions remove`](/cli/subscriptions-remove) — unsubscribe from branch or file [events](/concepts/events)
* [`murmur subscriptions flush`](/cli/subscriptions-flush) — remove all subscriptions for an [agent](/concepts/agents)
* [`murmur subscriptions ls`](/cli/subscriptions-ls) — list an [agent](/concepts/agents)'s subscriptions
* [`murmur status`](/cli/status) — query an [agent](/concepts/agents)'s current status