feresaria/docs/configuration/activities.md

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:

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. For the IPC schema and publisher lifetimes, see Publishing activities.

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

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.

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.

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.

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.