# App rules

> Make a key do something different in one app, matched by the exact bundle ID of the app in front.

---

LLMS index: [llms.txt](/llms.txt)

---

An app rule makes a key do something different while a particular app is in
front, without changing what it does everywhere else.

## How rules are matched {#matching}

Each mapping has a **Default action** and, optionally, a list of **App rules**.
When you press the chord, Capslock checks the rules from top to bottom against
the app in front. The first rule that names that app wins. If none does, the
default action runs.

Apps are identified by their exact bundle ID, such as `com.apple.Safari`. A
rule keeps working if the app is moved or renamed, and it never matches a
different app with a similar name.

## Add a rule {#add}

From a key:

1. Click the key on the Keyboard page, then **Edit…**.
2. Under **App rules**, click **Add App Rule**.
3. Under **Applies in**, click **Add App** and choose one or more apps.
4. Choose the action to run in those apps, then save.
{.steps}

From the **Apps** page, click **Add Rule…**, choose an app, and the mapping
editor opens with that app already filled in. To pick an app that is not
installed yet, type its bundle ID instead of browsing.

Use the arrows next to a rule to change its order. Every rule must name at
least one app.

## The Apps page {#apps-page}

The Apps page lists every app that has rules, marks the ones that are not
installed, and shows each rule. From an app's menu you can add another rule
for it or **Remove All Rules**. Removing all rules for an app is a single
change: it is backed up first and can be undone.

## In the configuration file {#yaml}

A rule is a `bindings` entry on the mapping. This one keeps `⇪ N` deleting
the previous word with ⌥⌫ everywhere, but sends ⌃W in Terminal and iTerm,
where shells expect it:

```yaml
- trigger:
    kind: hyper_plus_key
    key: 78            # N
    plane: 0           # Base
  action:
    kind: key_combo
    target_key: 8      # Backspace
    with_alt: true
  bindings:
  - when:
    - type: frontmost_app
      include:
      - com.apple.Terminal
      - com.googlecode.iterm2
    action:
      kind: key_combo
      target_key: 87   # W
      with_ctrl: true
```

Rules the editor cannot display are shown as "Advanced rule (edit in YAML)"
and kept unchanged. See [Configuration file](/docs/reference/configuration/).

---

Backlinks:

- [Keyboard editor](/docs/guide/editor/)
- [Configuration file](/docs/reference/configuration/)