Desktop integration

Samaya is pre-beta. Commands and output may change before the beta.

samaya opens or reveals the app. On Linux, samaya --hidden starts it in the tray. Add that command to your desktop's login applications to keep Samaya ready for task capture and bar controls.

Windows currently has no tray icon: closing the window quits Samaya, and --hidden opens a regular window. See Getting started.

samaya compose --window opens the task composer in its own window, starting Samaya if needed. Enter adds the task to today in Inbox.org unless a composer token says otherwise. Escape cancels. Focusing another window hides the popup and keeps its draft.

samaya compose opens the composer in the main window and preserves its draft. After upgrading from a version without compose --window, restart Samaya before using the command.

In your Hyprland 0.56 Lua configuration:

hl.bind("SUPER + N", hl.dsp.exec_cmd("samaya compose --window"))

hl.window_rule({
    name  = "samaya-compose",
    match = { class = "^samaya-compose$" },
    float       = true,
    center      = true,
    border_size = 0,
    no_shadow   = true,
    no_blur     = true,
    no_anim     = true,
})

Use the absolute path to samaya if it is not on the compositor's PATH. The popup opens on the current workspace. On Wayland, the compositor controls focus; test the shortcut in your session.

In GNOME, KDE or another desktop, create a custom keyboard shortcut that runs samaya compose --window. Other compositors can match the window class samaya-compose. Your desktop controls popup placement.

On Windows, create a shortcut to samaya.exe and put it in the Start menu folder, opened with Win + R and shell:programs. In the shortcut's Properties, append = compose --window= to Target. Set Shortcut key to your preferred combination, such as Ctrl + Alt + A.

Use native Noctalia 5.3.0 and Samaya 1.12.0 or later. Install the desktop app separately and make sure samaya is on Noctalia's PATH.

1. Open Noctalia Settings → Plugins → Add source.

2. Choose Git, name it samaya and enter https://git.hegdeatri.com/hegdeatri/samaya-releases.

3. Enable Samaya. Add its Focus widget through the bar's Add widget picker.

The widget shows your Focus clock and meetings. Its panel provides Focus, meeting Join, Add a task and calendar sync controls.

Choose Auto-update plugins → All sources to include this plugin source, or use its Update action manually. Update the desktop app separately. See the public plugin guide for settings and removal.

Status and control commands require the Linux desktop app. Keep it running, including hidden in the tray, to use these commands. Status reports offline when the app is unavailable; control commands reject the request. Neither starts the app.

samaya status --json
samaya status --watch

The first command prints status as JSON. The second provides updates as one JSON object per line, including offline status. Standard output contains only JSON; diagnostics go to standard error.

Status includes Focus clock values, current and upcoming timed events, scheduled work, sync status and available actions. Display the supplied clock values. Use the task, session, phase and occurrence IDs from status for the controls below. Pass each ID as one argument; scripts should use argument arrays rather than build shell commands from text.

Each control prints a JSON reply. A successful command reports ok and exits successfully. Other results are rejected, failed or unknown. Show the reported reason to the user. If the outcome is unknown, check status or open Samaya before repeating the action.