# Configure Activities

Select Morph in **Settings → Panel & Shell** to find **Visible activities** and
**Show activity count** in its appearance controls. These set the compact slots
and `+n` badge; hiding the badge still lets you open the full list.

Set sources, timing and command rules in the top-level `activities` block in
`~/.config/ferese/config.kdl`. Merge fields into an existing block rather than
adding a second one. This example enables the shell hook:

```kdl
activities {
    max-visible 2
    show-badge #true
    start-delay-ms 300
    result-flash-ms 1500
    sources {
        shell-hook #true
        process-watch #false
        notification-bridge #false
    }
}
```

For hook installation and everyday use, see [Live Activities](../activities.md).
For the IPC schema and publisher lifetimes, see [Publishing activities](../development/activities.md).

## Settings

Omitted fields use these built-in defaults. Integer ranges include both endpoints.

| Key | Type / accepted values | Default | Meaning |
| --- | --- | --- | --- |
| `max-visible` | Integer 1–2 | `2` | Compact activity slots |
| `show-badge` | Boolean | `#true` | Show `+n` for tasks beyond those slots |
| `max-total` | Integer 1–128 | `128` | Session record limit, including delayed and completed entries |
| `owner-ceiling` | Integer 0–255 | `160` | Highest base priority used to rank ordinary activities |
| `start-delay-ms` | Integer 0–60000 | `300` | Minimum delay before a task appears; a rule can require a longer delay |
| `result-flash-ms` | Integer 0–10000 | `1500` | How long an eligible completion result remains visible |
| `pomodoro` | Nested block | [Defaults below](#pomodoro) | Focus intervals, breaks and completion notifications |

## Sources

Set these booleans inside `activities.sources`:

| Key | Built-in default | Meaning |
| --- | --- | --- |
| `shell-hook` | `#false` | Accept command start/end events from an installed shell hook |
| `process-watch` | `#false` | Sample processes when hooks are unavailable; disappearance removes the task without inferring success or failure |
| `notification-bridge` | `#false` | Show notifications as activities instead of duplicate toasts, respecting Do not disturb and notification popup settings |

All three sources are off in the built-in defaults. First-time installer setup
enables `shell-hook` unless you explicitly set it to `#false`. The process watcher
and notification bridge stay off unless you enable them.

Media comes from MPRIS. Downloads and call statuses need an integration that
publishes them; microphone or camera use alone does not create a call activity.

Changes reload live. Invalid edits leave the last valid configuration in use.
Check an edit with `ferese --check-config ~/.config/ferese/config.kdl`.

## Turn off automatic command detection

Set `shell-hook #false` inside `activities.sources`. Leave `process-watch` off
as well if you don't want process detection. You can still use `feresectl run`
and direct publishers.

To skip shell and Activities setup during installation, pass
`./scripts/install.sh --no-activities`. This skips setup for that installation;
it doesn't remove an existing hook or disable an already configured source.

## Command rules

A named `rule` matches command text and supplies its title, icon, priority and
completion messages. Rules are matched in declaration order, then unreplaced
built-ins in Cargo, npm/pnpm, make, git-push, docker-build order. A user rule
replaces the entire built-in with the same name. One command selects one rule,
which stays attached to that invocation until it ends.

```kdl
activities {
    max-visible 2
    show-badge #true
    start-delay-ms 300
    result-flash-ms 1500
    sources {
        shell-hook #true
        process-watch #false
        notification-bridge #false
    }
    rule "cargo" {
        match #"^cargo (build|check|test|run|clippy)\b"#
        title "cargo {1}"
        icon "hammer"
        priority 100
        progress "indeterminate"
        min-duration-ms 1500
        ignore-parents "rust-analyzer"
        dedupe-by "cwd"
        flash-on-fail #true
        result ok="Finished" fail="Command failed"
    }
}
```

These defaults apply to a new custom rule. Built-in rules have their own values,
shown in the [source catalog](../../crates/ferese-config/activities.kdl).

| Key | Type / accepted values | Default for a custom rule |
| --- | --- | --- |
| Rule name | String, up to 256 UTF-8 bytes, no control characters; unique | Required positional argument |
| `match` | Valid regular expression, up to 2048 UTF-8 bytes | Required |
| `title` | String, up to 256 UTF-8 bytes, no control characters | Required |
| `icon` | Symbolic name, up to 64 ASCII letters, digits or hyphens | `"ferese"` |
| `priority` | Integer 0–255; ranking caps it at `owner-ceiling` | `100` |
| `progress` | `"indeterminate"` or `"cargo-json"` | `"indeterminate"` |
| `min-duration-ms` | Integer 0–60000 | `0` |
| `ignore-parents` | Up to 16 names, each up to 128 UTF-8 bytes | No ignored parents |
| `dedupe-by` | `"cwd"`, or omit for no grouping | Unset |
| `flash-on-fail` | Boolean | `#true` |
| `result.ok` | String, up to 256 UTF-8 bytes, no control characters | `"Finished"` |
| `result.fail` | String, up to 256 UTF-8 bytes, no control characters | `"Command failed"` |

Use `result ok="Finished" fail="Command failed"` inside the rule to change both
messages. If you provide `result`, both fields are required. Title placeholders
refer to regex captures: `{0}` is the whole match, `{1}` the first group, and so
on. Invalid capture references reject the configuration. An expanded title over
256 bytes or containing control characters is discarded during matching.

`ignore-parents` accepts multiple names in one node, such as
`ignore-parents "rust-analyzer" "editor"`. `dedupe-by "cwd"` groups tasks by a
hash of the working directory within the same owner and rule. Invocations retain
independent lifetimes, and progress is never averaged.

`progress "cargo-json"` enables the adapter for matching `feresectl run`
commands. Shell hooks do not wrap commands or parse their output automatically;
see [Cargo progress](../activities.md#cargo-progress).

## Visibility and matching limits

The visibility delay is the larger of `start-delay-ms` and `min-duration-ms`.
Completion before that delay, including failure, never flashes. Eligible results
last 1500 ms by default; `flash-on-fail #false` removes failures directly.

At most 64 rules may remain after unreplaced built-ins are added. Command input
is limited to 4096 UTF-8 bytes, working directories to 1024 bytes and parent lists
to 16 entries. The matcher sets a 256 KiB compiled-size limit and a 256 KiB DFA-size limit.
Command and cwd metadata are used only during matching; nonmatches are discarded
and never logged.

Configuration is validated before application; an invalid reload preserves the
last valid configuration. Diagnostics include source offsets for activity
configuration errors.

## Pomodoro

Pomodoro uses the Activities item and works without shell hooks. Add these
settings inside your existing `activities` block to change the defaults:

```kdl
activities {
    pomodoro {
        work-minutes 25
        short-break-minutes 5
        long-break-minutes 15
        intervals 4
        auto-advance #false
        notifications #true
    }
}
```

`work-minutes` accepts 1–180, `short-break-minutes` accepts 1–60 and
`long-break-minutes` accepts 1–120. `intervals` accepts 1–12 work intervals
per session. The session ends after its long break; start another when you
want to continue. These settings apply when you start or reset a session,
so reloading configuration doesn't change an interval already in progress.

With `auto-advance #false`, a completed interval leaves the next phase ready
until you start it. Enabling it starts the next phase automatically. A running
interval includes time spent asleep, but a paused interval does not. If an
interval expires during suspend, Ferese completes that interval on wake and
starts any automatic next phase then; it doesn't count more work while the
machine is asleep.

Completion notifications identify the phase that ended and the next phase.
They are silent and use the normal notification service, including Do Not
Disturb and lock-screen privacy. Set `notifications #false` to turn them off.
Stopping, resetting or skipping an interval doesn't send a completion alert.

The compositor owns the timer, so closing a terminal or restarting the shell
won't stop it. Restarting the compositor ends the session without restoring its
timer or replaying completion notifications.