Install, pair, and use Pairling.

Install and pair

Install one Mac runtime and pair one iPhone.

Install Pairling on the Mac

1. Open Terminal on the Mac that runs your coding CLIs.
2. Install Pairling with npm install -g pairling.
3. Start setup with pairling setup.
4. Review each proposed change before setup applies it.

Install Pairling on the iPhone

1. Install Pairling from TestFlight.
2. Open Pairling and start setup.
3. Scan the QR code on the Mac.
4. Confirm the Mac name and route.

The iPhone stores pairing credentials in Keychain. The Mac stores a hash of the bearer token and the device scope.

Inspect the npm package

Use npm pack pairling --dry-run to list the package files.

Use npm audit signatures to check registry signatures.

Connect to a Mac

Use a private route on the same network or away from the Mac.

Use Pairling Connect

Pairling Connect embeds Tailscale technology in the app. It does not require a separate VPN app or system VPN profile.

The iPhone and Mac join the selected tailnet. Pairling sends control traffic through the encrypted tailnet data path.

PairDrop requires Pairling Connect. Regular session control can also use a local network route or a configured SSH route.

Use a custom control server

1. Open Pairling Connect settings.
2. Select the custom control server option.
3. Enter a compatible control server address.
4. Complete the server approval flow.

The default control server is Tailscale. The custom server controls its own metadata and retention.

Use an SSH route

1. Run pairling setup --ssh on an already paired Mac.
2. Add the SSH route in Pairling.
3. Check the Mac host key before you approve it.

The SSH route forwards only the Pairling gateway port. It does not give the iPhone a shell.

Understand Mac sleep

Pairling can prevent idle sleep while a live session needs the Mac. A closed laptop lid can still put the Mac to sleep.

Control a coding session

Open a live session and act on the Mac from the iPhone.

Open the session

1. Open the Pairling dashboard.
2. Select the active Mac.
3. Select a live or recent coding session.
4. Choose Transcript or Terminal.

Transcript shows structured provider output. Terminal shows the live terminal surface when that session has a supported terminal.

For provider-specific setup and boundaries, read how to control Claude Code from your iPhone.

Send input

Enter text in the compose field and select Send. Pairling sends the text to the exact session on the Mac.

Use the pending input card when the coding CLI asks a question. Use the approval card when the coding CLI requests approval.

Interrupt work

Use Interrupt for a normal stop request. Use the terminal controls when the session needs direct terminal input.

Pairling waits for Mac state before it clears pending cards. The iPhone does not claim success from a local tap alone.

Start or resume work

Choose a coding CLI, a project, and the correct session.

Start a session

1. Open the new session sheet.
2. Select a coding CLI that is available on the Mac.
3. Select the project directory.
4. Enter the first prompt.
5. Review the launch settings and start the session.

Resume a session

1. Open a past session.
2. Check the provider, project, and last activity.
3. Select Continue.
4. Confirm the resumed session before you send new input.

The coding CLI controls its native resume behavior. Pairling shows the session state that the Mac reports.

Search and export

Find work across sessions and move a reviewed result to another app.

Run an exact search

Enter a search term and select exact search. The Mac searches the provider transcript files that Pairling can read.

Run a semantic search

1. Build the local semantic index on the iPhone.
2. Enter a question or idea.
3. Open a result and check its source session.

The iPhone creates and stores the embedding index. The index contains short snippets and numeric vectors.

Export a session

Open the session export control. Select the format, review the output, and use the iOS share sheet.

Clear iPhone history

Clear history removes the saved iPhone snapshot and hides selected rows. It does not delete provider transcripts on the Mac.

Send text and files

Add source material to the session that needs it.

Attach a photo or video

1. Open the compose attachment menu.
2. Select Photos.
3. Select the photo or video.
4. Wait for the Mac path to appear in the draft.
5. Send the draft to the session.

Attach a file

1. Open the compose attachment menu.
2. Select Files.
3. Select one file of 100 MB or less.
4. Review the inserted Mac path.
5. Send the draft.

The Mac stores regular attachments under ~/Pairling/uploads. Pairling does not remove these uploads automatically.

Open a OneStream handoff

Open the handoff JSON with Pairling. Pairling loads its prompt and transcript text into the compose draft.

Pairling includes an iOS Share Extension for text, links, images, videos, and files. Shared items queue in a protected local inbox. Pairling transfers them to PairDrop when it can connect. You then choose whether to attach an item to an existing session.

Dictate and improve prompts

Turn speech or rough text into a reviewed compose draft.

Use short dictation

1. Select the microphone in the compose field.
2. Speak one short request.
3. Stop dictation and review the text.
4. Edit the text before you send it.

Short dictation prefers on-device recognition. Apple can process the audio when the selected locale has no on-device recognition.

Record or import audio in Compose

1. Open Compose.
2. Select Record, or select Import Audio and choose an audio file.
3. For a recording, speak while the transcript appears, then select Stop Recording.
4. Open the saved item to play the audio, edit the transcript, or regenerate word timings.
5. Extract key points or turn the transcript into an improved prompt.
6. Sync the item to your Mac through PairDrop, attach its audio, or send its prompt to a selected session.

Compose keeps the audio, transcript, word timings, key points, and prompt together on the iPhone. Deleting the item removes that local copy. A copy already synced to PairDrop remains on the Mac.

Use Prompt Helper

1. Enter or dictate a draft.
2. Select Prompt Helper.
3. Select a Prompt Preset.
4. Review the changed draft.
5. Undo the change when it does not match your intent.

Prompt Helper uses Apple Foundation Models on the iPhone. It does not send drafts or preset instructions to a network fallback.

User Prompt Presets are Markdown files under ~/.pairling/prompt-presets on the Mac.

Use PairDrop

Move files between the iPhone and the Mac through Pairling Connect.

Send a file to the Mac

1. Confirm that Pairling Connect is active.
2. Open PairDrop.
3. Select a file.
4. Wait for the upload to finish.

A small upload can be 10 MB. A resumable foreground upload can be 100 MB.

Use a PairDrop file in a session

1. Open the file in PairDrop.
2. Select Attach to session.
3. Select the session.
4. Review the exact Mac path in the draft.

The reviewed Mac source stores PairDrop under ~/PairDrop. Files use your Mac storage.

Download a file to the iPhone

Open the PairDrop item and download its content. Pairling verifies the byte count and SHA-256 value before it uses the preview.

Delete a PairDrop item

Delete hides the item and sets its deletion time. It does not erase the object bytes from the Mac.

Run an orchestration

Give one objective to a planner and a bounded set of workers.

Create the run

1. Open the orchestration sheet.
2. Select the project and coding providers.
3. Enter one objective.
4. Select a mode and autonomy level.
5. Select one to four workers.
6. Set the time limit and stop condition.
7. Review the run and start it.

Each run has one planner. The run can use one to four workers and can last from five to 180 minutes.

Choose the mode

Understand permissions

Pairling records the selected permission profile and gives it to each role. The coding CLI process still controls actual file and command access.

The reviewed launch code can use provider bypass flags. Do not treat the selected profile as an operating-system sandbox.

Stop the run

Select Stop to send a termination signal to active run processes. The run files and provider transcripts stay on the Mac.

Use alerts and Live Activities

Follow work without keeping Pairling open.

Enable notifications

1. Open Pairling notification settings.
2. Allow alerts, sounds, and badges in iOS.
3. Select the Pairling events that you need.

Pairling can notify you about required input, results, failures, route risk, worker pressure, and deployment results.

Use a Live Activity

A Live Activity can show the session, provider, project, current step, latest event, result, risk, and required action.

Pairling excludes raw prompts, transcripts, command output, credentials, and full paths from push event payloads.

Disable alerts

Disable notifications to stop future delivery. This action does not erase all stored registration and delivery records.

Configure coding CLI tools

Use native iPhone controls for common coding CLI configuration.

Use the slash command library

Type a slash in the compose field. Pairling lists commands, skills, and plugins that the selected provider reports.

The Mac reads command metadata from provider, user, plugin, and project files. Pairling inserts the selected command into the draft.

Change Claude permissions

Open the Permissions picker. Review the allow, deny, ask, directory, default mode, and effort values before you save.

Saving changes the matching values in ~/.claude/settings.json.

Manage Claude hooks

Open the Hooks picker. Add or remove a supported event, matcher, command, and timeout.

Saving replaces the hooks block in ~/.claude/settings.json.

Manage project memory

Open Memory to list, read, create, edit, or delete project memory files. Pairling also updates the project MEMORY.md index.

Check MCP servers

Open MCP to read the server list and status from the Claude CLI. Select one server when you need a restart attempt.

Set provider visibility

Hide a provider to remove it from Pairling selection controls. This setting does not uninstall the coding CLI.

Use Phone Tools, Shortcuts, and Watch

Extend a coding session through other Apple system surfaces.

Use Phone Tools

1. Enable Phone Tools in Pairling settings.
2. Keep Pairling open in the foreground.
3. Call a Pairling phone tool from the Mac session.
4. Review the result in that session.

Phone Tools can provide a second opinion, a vibe check, a preference check, or local corpus recall.

The Mac holds requests in memory. A model fallback can send a request to the selected coding provider.

Use Siri and Shortcuts

Shortcuts can summarize attention, open an active session, stop stale workers, open a draft, or send confirmed text.

Direct send requires its Pairling setting and a confirmation. Siri and Shortcuts can process input through Apple system services.

Use Apple Watch

The Watch can show bounded Mac and session state. It can refresh, open the exact iPhone route, or snooze a Sentinel alert.

Manage stored data

Know which action erases data and which action only hides or revokes it.

Uploaded attachments, handoffs, and orchestration runs have no automatic cleanup in the reviewed source. Remove these files on the Mac.

Read the Privacy Policy for the complete feature data map.

Pairling protocol

Review the enforced connection boundary between the iPhone and a paired Mac.

The Pairling Connect bridge permits a defined path list. The Mac then checks the paired device, its scope, and request proof.

Open the Pairling Protocol Reference for the complete path list.

FAQ

Read the boundaries that affect normal use.

Support

Check the paired Mac, prepare a safe report, or remove access.