Collaborate with local agents from issues

Optional GitHub webhook relay

Configure a dedicated Smee channel in your repository's Webhooks settings: JSON payloads, issues and issue_comment events, and a random secret of at least 32 characters. Save the same secret locally with file permissions 600. The relay can read event contents; the host verifies GitHub signatures and repository identity independently. Use a trusted relay.

nextclaw collaboration stop
nextclaw collaboration webhook github --relay-url https://smee.io/YOUR_CHANNEL --secret-file /absolute/github-webhook.secret
nextclaw collaboration start
nextclaw collaboration status

This disables polling for that connection and receives pushed events over an outbound connection. Existing receipts and Codex task bindings continue. The webhooks status field reports connection/reconnection health. The relay is not a durable offline queue: redeliver missed events through GitHub, or stop the host and run webhook github --disable to restore 30-second polling and catch up. Other connections are unchanged.

GitHub and Linear issues can wake local Codex tasks. An invitation creates a binding; later comments continue the same task. A receipt in the issue shows when execution starts and which Codex task handles it. Existing local CLI authentication is reused.

Requires Node.js 22.13+, local Codex, and an authenticated GitHub CLI or schpet Linear CLI with project access.

Display labels belong to the caller, not the framework. Stop the host, run nextclaw collaboration presentation CONNECTION --prefix '[My Agent]', then start it again. Omitting the prefix displays only the response body. --strip-prefix LABEL... removes configured leading labels without rewriting quotes within the body. Display changes preserve signed identity and task bindings.

An eyes reaction on the original GitHub issue or comment confirms durable receipt, including while paused or when the agent later stays quiet. It does not mean execution started or completed. Status comments identify the agent and execution state; reactions from a shared account do not identify individual agents. Reaction errors are retained locally and do not prevent normal status comments or processing. Other platforms currently use status comments. Invitations, greetings and connectivity tests receive a short reply; irrelevant notifications or explicit no-reply requests may stay quiet. The host adds the public identity prefix once.

nextclaw collaboration connect github --adapter github --repository OWNER/REPO --workspace /absolute/project
nextclaw collaboration connect linear --adapter linear --team TEAM --workspace /absolute/project
nextclaw collaboration check
nextclaw collaboration start

Connect only the platforms you use. Standalone installation: npm install -g @nextclaw/collaboration; replace nextclaw collaboration with nextclaw-collaboration. Use --executable if the platform CLI is outside PATH. The default allowlist contains the current account; --allow accepts GitHub logins or Linear user UUIDs. Account changes stop consumption instead of silently changing identity.

Three priority acceptance journeys

1. Create and wake: create an issue asking the agent to remember BLUE-47, then add agent:mozhao (create this label once). With the computer awake and the host running, collection normally starts within a 30-second poll interval. Observe the received/started receipt, Codex task ID and final reply. Network delays and queueing may extend this; inspect local status.
2. Continue: ask for the code in the same issue. Expect BLUE-47 and the same task ID. Repeat on either platform. Irrelevant input may complete quietly with a status update.
3. Control: post /agent pause alone. After the pause receipt, post a question; it stays pending. Post /agent resume alone to continue it in the same task. /agent cancel requests interruption and pauses future work; /agent status reports status.

An invitation is needed only once. Use follow CONNECTION SUBJECT for older issues (GitHub issue number; Linear UUID). Closing pauses follow-up; reopening does not override a manual pause.

Operation and recovery

Use status, show CONTEXT, stop and restart without model calls. start launches a detached process, not an OS startup service; an existing service manager can run run. Offline or sleeping computers cannot process events. Restart resumes from saved state in ~/.nextclaw/collaboration. Protect this directory: it includes agent keys and input. Startup compacts completed payloads older than 30 days while retaining small binding/deduplication records.

Unknown execution acceptance is queried with reconcile CONTEXT, never blindly resubmitted. Inspect external side effects before retry-run --confirm-safe; inspect the platform before resolve-output. migrate-discussion --workspace /absolute/project imports a stopped legacy official listener's original cursor and Codex bindings.

Official-discussion connections poll no faster than every 30 seconds; shorter intervals imported from the legacy listener are normalized and persisted when the host starts. status.intervalMs reports the effective interval. Temporary source or delivery failures retain attempts, nextAttemptAt, and the error in the outbox with exponential backoff; inspect them with show CONTEXT instead of repeatedly restarting to bypass the delay.

Signed agent identities are independent of platform accounts. trust CONNECTION PUBLIC_IDENTITY_FILE ACCOUNT allows a peer to communicate even through the same account. Add --controls only for control authority. Self-output, statuses and unverified agents cannot wake the host. Defaults cap agent hops at four, runs per conversation per hour at twelve, and simultaneous executions at two.

Custom platforms implement the public SourceAdapter; ordinary commands can implement a Consumer. See the SDK protocol and non-issue example. Optional authenticated normalized-event ingress is available; ordinary polling needs no webhook server or hosted control plane.