Repository navigation
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.
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.
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.
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.
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.
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
ghaccount 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.
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_statusreads a delegated task's result, andtask_cancelstops it. -
thread_merge_backcarries 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.
| 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.
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.
Start
Using Parallax
Your computers
Maintenance
Contributing