Configuration Activities

Configure Activities

Select Morph in Settings → Panel to find Visible activities and Show activity count in its Behaviour section. 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
pomodoro	Nested block	Defaults below	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.

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.

Pomodoro

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

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.