Skip to content

docs(connect): shorten the /connect guide and keep text out of shell source - #144

Merged
khaliqgant merged 4 commits into
mainfrom
docs/connect-guide-simplify
Oct 8, 2026
Merged

khaliqgant merged 4 commits into
mainfrom
docs/connect-guide-simplify

Conversation

@khaliqgant

@khaliqgant khaliqgant commented Oct 7, 2026 •

Copy link
Copy Markdown
Member

Shortens the /connect agent guide that #141 shipped to four steps (install, join or create, talk, finish), plus a short "if something fails" list.

  • Shell safety: the agent writes the task or message to a file with its file-editing tool, then passes --task "$(cat /tmp/relay-task.txt)" or sends with < /tmp/relay-message.txt. A file's contents are never parsed as shell. The previous printf '%s' '…' example put the message into shell source (flagged by skills#138's reviewers), and a here-document closes early on its marker line (Devin, on this PR). Here-documents remain a fallback only, with a random marker absent from the text. Verified in sh and zsh with hostile input, including lines exactly matching the old markers: nothing executed.
  • Finish: end (host, also removes its own session) and leave (guest) are alternatives. Running leave first made the host's end fail and left the room open.
  • Codex on macOS: sandbox note from the end-to-end proof. Commands fail inside the sandbox until rerun with escalated permissions.

The guide test also pins the < file form and the absence of printf '%s' ' and ARELAY_TASK. Tests: connect-guide plus connect-install, 21/21.

Companion: AgentWorkforce/skills#138 (the relay-connect skill now uses the same command forms).

🤖 Generated with Claude Code


Note

Low Risk
Documentation and test-only changes to the Connect agent guide; no runtime application logic or security-sensitive code paths.

Overview
Rewrites the /connect agent markdown guide into four steps (install → join/create → talk → finish) plus a short “If something fails” section, with tighter intro copy and clearer permission boundaries for agents.

Shell safety is the main behavioral change in the instructions: agents must write task and message text with a file-editing tool, then use --task "$(cat /tmp/relay-task.txt)" and connect send … < /tmp/relay-message.txt instead of embedding user text in the command or the old printf '%s' '…' pipe. Here-documents stay as a fallback only, with guidance to use a random marker that must not appear in the message.

Finish now separates host end (closes the room for everyone; do not leave first) from guest leave, documents Codex on macOS sandbox failures and escalated permissions, and trims other installer/probe detail into the troubleshooting list.

connect-guide.test.ts expands assertions to require the new command forms, send/status/leave, no printf '%s' ', no inline quoted --task, and ordering of task-file instructions before create.

Reviewed by Cursor Bugbot for commit 72b2eb6. Bugbot is set up for automated code reviews on this repo. Configure here.

@coderabbitai

coderabbitai Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 48 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 9555a4aa-d4ca-4ad6-9a64-64a784a77859
📥 Commits

Reviewing files that changed from the base of the PR and between a0f4bfa and 72b2eb6.

📒 Files selected for processing (2)
  • web/lib/connect-guide.ts
  • web/lib/test/connect-guide.test.ts
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployed!

Environment URL
Web https://6099f92f-agentrelay-web.agent-workforce.workers.dev

This is a Cloudflare Workers preview version of this PR's build.

@willwashburn
willwashburn added this pull request to stack #147 October 7, 2026 16:12
Base automatically changed from codex/curl-connect to main October 8, 2026 00:07
Four steps (install, join or create, talk, finish) plus a short failure
list. create passes --task through a quoted here-document and send reads
the message from one, so apostrophes and shell syntax are passed
literally; finish presents end (host) and leave (guest) as alternatives.
Adds the Codex-on-macOS sandbox note found during the end-to-end proof.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@khaliqgant
khaliqgant force-pushed the docs/connect-guide-simplify branch from 0e57c22 to 58a242d Compare October 8, 2026 00:12
@khaliqgant
khaliqgant marked this pull request as ready for review October 8, 2026 00:12
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 8, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-08T00:15:43.569488Z 58a242d Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@khaliqgant khaliqgant changed the title docs(connect): shorten the native Connect guide to four steps docs(connect): shorten the /connect guide and keep text out of shell source Oct 8, 2026

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 potential issue.

Devin Review

Comment thread web/lib/connect-guide.ts Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 58a242de76

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread web/lib/connect-guide.ts Outdated
…source

A here-document closes early if the text contains its marker line, which
can run the following lines as shell. Agents now write the task or message
with their file-editing tool and pass it as --task "$(cat file)" or on stdin
with < file; a file's contents are never parsed. Here-documents remain a
fallback only with a marker absent from the text. Verified in sh and zsh
with lines matching the old markers plus $(), backtick and quote-breakout
payloads: all passed literally, nothing executed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread web/lib/connect-guide.ts Outdated

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 2 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread web/lib/test/connect-guide.test.ts
Comment thread web/lib/connect-guide.ts Outdated
Comment thread web/lib/connect-guide.ts
Comment thread web/lib/connect-guide.ts Outdated
…allback

- Tell the agent to write /tmp/relay-task.txt before showing the create
  command, so a top-down read never runs create with an empty task.
- Restore: never send share_text to another person unless asked.
- Show the quoted here-document fallback for send, with a fresh random
  marker the text must not contain.
- "No relay process starts" instead of "Nothing runs": the installer
  executes the probe to verify it.
- Pin the file-based create --task form and the step order in tests.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 8d4a3f7. Configure here.

Comment thread web/lib/test/connect-guide.test.ts Outdated
… text

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@khaliqgant
khaliqgant merged commit 36aa1bb into main Oct 8, 2026
5 checks passed
@khaliqgant
khaliqgant deleted the docs/connect-guide-simplify branch October 8, 2026 01:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant