194 lines
8.5 KiB
Markdown
194 lines
8.5 KiB
Markdown
# 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.
|