Skip to content

Triggers

Ryan Stoffel edited this page Oct 29, 2026 · 1 revision

Triggers

Triggers wake an agent while you're away: schedules, webhooks, and pull request watches. Delegation lets an agent hand work to other agents and wake when it's done. They run in plxd, so they keep going with the app closed.

You create triggers by asking an agent in plain words, such as "every weekday at 9:00, summarize yesterday's merged pull requests" or "watch this PR and fix any failing check". The agent calls Parallax's tools. The app shows and manages what exists.

Schedules

A scheduled task sends a prompt on a timer (0063).

Kind Runs Rules
Interval Every N minutes At least 1 minute
Fixed time At HH:MM, every day or on chosen weekdays The host's time zone. A run missed by more than 10 minutes is skipped
Webhook Once per request to its URL See Webhooks

Where each run goes:

Task Each run
Bound to a thread (the default) Queues the prompt in that thread
Not bound Starts a new thread with the creating thread's repository, model, effort, and access
In a Project Messages the Project's coordinator

A task never overlaps itself. A prompt is at most 64 KiB.

Manage schedules

Settings > Schedules lists each computer's scheduled tasks. Pick the computer beside Scheduled tasks. Each row shows the title, the prompt, the schedule, the next run (or Paused, or Listening for a webhook), the last run's result, and a webhook's URL.

Control Does
Switch Pauses or resumes the task
Run now Runs it once. Not offered for webhooks
Delete Deletes it

Agents manage tasks with schedule_task, list_scheduled_tasks, update_scheduled_task, delete_scheduled_task, and run_scheduled_task_now.

Webhooks

A webhook task runs once per request to its URL. Where the URL can be reached depends on Settings > Connections:

Setting Address
Reach from anywhere on A public address through Parallax Relay
Pair computers on this network on An https:// address on your network or tailnet
Neither No URL. Turn one of them on

The prompt reads the request through placeholders:

Placeholder Fills in
{{body.a.b}} A field of a JSON body, such as {{body.action}}
{{headers.name}} A header
{{query.name}} A query parameter
{{body}} The whole body
{{request}} The method, headers, and body, with credentials redacted

A webhook takes at most 60 requests a minute and holds at most 20 waiting.

Signed webhooks

For a sender that signs requests, such as GitHub, the agent calls request_secret. A private card over the composer asks you for the signing secret. Parallax keeps it in the computer's keystore (the Keychain on macOS, the Secret Service on Linux) and never shows it to the agent. Each request must then carry an HMAC-SHA256 signature of its body.

Windows has no keystore yet, so request_secret and signed webhooks are refused there.

Pull request watches

An agent calls watch_pull_request on a pull request, and Parallax checks it every 2 minutes through gh. It wakes the thread when:

  • a check fails,
  • the required checks pass,
  • someone other than the signed-in gh account and the pull request's author comments or reviews,
  • or the branch starts to conflict with its base.

A watch ends when the pull request merges or closes, when its thread settles or is archived, after 8 failed reads in a row, after 10 comment-only wakes in a row, or when the agent calls unwatch_pull_request. GitHub is the only host Parallax reads.

While a thread watches a pull request, a line over its composer reads Monitoring pull request with the number. Stop there ends the watch.

Agents also read pull requests through Parallax rather than gh: pull_request_status, pull_request_diff, ci_failure_log, pull_request_comment, pull_request_review, pull_request_edit, reply_to_review_thread, and merge_when_ready.

Delegation

An agent can start other agents. These tools have no buttons in the app.

Tool The new thread Wakes the caller
thread_launch Its own worktree, a child of the caller When it ends
delegate_task Works in the caller's worktree and branch, on any provider When it ends. wait mode blocks the caller's turn instead, up to an hour
create_threads 1 to 20 top-level threads in the caller's worktree No
  • A child's mode can't need less approval than its parent's.
  • task_status reads a delegated task's result, and task_cancel stops it.
  • thread_merge_back carries a fork's or child's new conversation back to the thread it came from, with that thread's next message.
  • At most 8 threads that share another's worktree run at once on a computer.
  • A Project's threads can't use delegate_task. They start work through the coordinator. See Projects.

What wakes what

Event Wakes
A scheduled run or webhook request The bound thread, a new thread, or a Project's coordinator
A watched pull request's news The thread that watches it
A launched or delegated child ends Its parent
A Project's subagent starts, ends, or asks a question The Project's coordinator

Wake-ups that arrive within 2 seconds of each other go out as one message. After 100 wake-ups in a row with no message from you, a thread's wake-ups pause until you write (0025).

Stop on a thread stops its turn and every child it delegated or launched, and holds its queued messages until you resume it. A Project's coordinator is the exception: Stop ends only its turn, and its subagents keep working.

Notifications

Settings > General > Notifications has two switches:

  • System notifications: an alert from your computer when a thread finishes, fails, or needs you while Parallax isn't in front.
  • In-app notifications: a toast for the same events.

A Project's new Needs you item sends "Needs you: …" with Open Project.

Clone this wiki locally