activity # activity Keep a local build, interactive terminal, file watch, or reminder alive while Pi continues working. One `activity` tool manages their lifetime, input, bounded observations, and cleanup. ![activity demo: start and inspect a process and interactive terminal, then stop the terminal](assets/demo.gif) ## Use in Pi Ask Pi to “run this build in the background”, “open an interactive terminal”, “watch this directory”, or “remind me in five minutes”. A process runs without a TTY; choose a terminal when the command needs keyboard input or a live screen. The tool is available through codemode; `/activities` opens Pi's native activity picker and inspector. Select an activity in `/activities`, then press `x` to request termination without copying its ID. In the picker, `d` hides the selected failure from the widget and `D` hides every finished activity; hidden activities stay in `/activities` and remain readable by the agent. Process, watch, and timer inspectors also accept `x`; an attached terminal keeps `x` as application input. Use `/activities ` to inspect directly, or `/activities stop ` to request termination. In an attached terminal, keys go to the application: Escape and Ctrl+C are application input; Ctrl+G detaches without stopping. The agent never opens the inspector automatically. A compact widget above the editor shows up to three active activities plus the newest unhidden failure. Finished successes and stopped activities leave the widget immediately; closing a finished activity's inspector also hides it. Process and terminal inspectors show elapsed time; completed durations stop at the recorded terminal event. State totals include hidden activities; `hidden` counts rows omitted from the widget. When nothing is active and every failure is hidden, the widget disappears. ```javascript const { activities: [job] } = await tools.activity({ action: "start", kind: "process", command: "nu", args: ["--no-config-file", "-c", "mise run //:check"], notify: true }); text(job); ``` `command` is an executable with separate `args`, not implicit shell source. Use `terminal` instead of `process` for programs requiring a TTY, keyboard input, or a current screen. `read` inspects results, `write` sends exact terminal input, `resize` sets dimensions, `wait` observes a sequence change, and `stop` requests cleanup. `wait` is bounded and cancellable; a wait timeout does not stop its activity. `write` and `resize` acknowledge input, not an application redraw; wait after the returned sequence before checking updated content. Use `write` with `paste: true` for pasted text: it honors the application's bracketed-paste mode and removes embedded Escape characters. Notifications default to off. Opting into `notify: true` allows coalesced completion, watch, and timer events to queue follow-up model turns, including when Pi is already idle. Start returns an ID immediately: Pi can continue other work or finish its turn without keeping a wait open. Unread events arrive after ongoing work reaches a turn boundary, or wake an idle agent; reading results or explicitly stopping acknowledges observed events instead of creating redundant turns. This can consume provider tokens; events are observations, never new user instructions or authorization. ## Lifetime and limits Activities survive model turns, not session replacement, reload, or orderly Pi shutdown. There is no cloud service, daemon, persistence, or execution while Pi is closed. Machine sleep can delay timers; missed repeating ticks are not a durable schedule. At most eight activities run concurrently; 32 completed records are retained. Process, terminal, watch, and repeating timer lifetimes default to one hour, configurable per start up to 24 hours. One-shot timers use their requested delay unless an explicit shorter lifetime is supplied. Repeating delays must be at least one second. Output history is bounded to 64 KiB, reads and terminal screens to 16 KiB each, event history to 32 entries; truncation is reported. Terminal dimensions are 20–200 columns and 5–60 rows. File and directory watches are nonrecursive change hints, not a complete filesystem audit trail. Terminal stdout and stderr are merged; the screen shows current rendered state rather than chronological logs. Agent observations are plain text; the human inspector preserves application colors, selections, and cursor visibility. Terminals are keyboard-driven: no mouse forwarding, image rendering, or clickable application hyperlinks. Complex emoji sequences and application-defined color palettes may differ from the host terminal. Quiet output does not mean completion. Inspect status after stopping: `stopping` is not confirmed termination. Descendant cleanup is best effort; abrupt crashes or deliberately detached children can outlive Pi. On Windows, an already-exited leader cannot safely identify its surviving descendants; stop remains unconfirmed rather than targeting a potentially reused PID. ## Availability and privacy Process, watch, and timer capabilities use Node's platform APIs. Interactive terminals require the native `@lydell/node-pty` package for the consumer's OS and architecture, including its optional platform package; missing support fails explicitly rather than substituting pipes. Windows terminals require ConPTY support. Native installation and terminal behavior must be verified on each target platform. Commands run with Pi's permissions, not in a sandbox. Existing permission hooks see the `activity` tool; policies restricted to shell tool names must explicitly cover activity launches too. Terminal and process content can contain secrets or untrusted instructions; requested observations and input can persist in session history and reach the model provider. Collapsed custom rows are compact, not a privacy boundary: codemode can show nested arguments and anything its script prints. [Installation](../../README.md#install) ### Commands | Command | Purpose | | --- | --- | | `/activities` | Inspect activities or stop one: /activities [id \| stop id] |