Cli.nt

How It Works

Cli.nt has two parts:

• • A server application that runs on your Mac or PC
• • An iOS app on your iPhone or iPad

The server launches Claude Code and keeps it running. The iOS app connects to the server over your local network or, with Tailscale, from anywhere with an internet connection. When Claude Code wants to run a command, edit a file, or use a tool, it pauses and sends an approval request to your phone.

Step 1: Server Setup

Download and install the Cli.nt server application.

Claude Configuration

• • Set the Claude Code executable path. On Windows the default is “claude”. On Mac it is “/usr/local/bin/claude”.
• • Set your projects folder. This is a sandboxed root folder that Claude Code can work within. You can narrow this further per session in the iOS app.
• • You can adjust the max token size for the context file. This file is created on the server and sent with each prompt, giving every session its own persistent context.

Network & Security

• • Go to Settings > Security & Server and set a password (minimum 4 characters).
• • The server runs on port 3001 by default. You can change this in Settings > Security & Server.
• • Enter your Tailscale Magic DNS hostname to allow remote connections. Direct Tailscale IP addresses (100.x.x.x) are disabled for security — Magic DNS hostnames are required.
• • If you prefer local network only, enable “Allow HTTP on LAN”.

Sandbox Mode

Enabled by default and recommended. Claude Code is restricted to working within the project paths set in the server and iOS settings.

Note: Claude Code is an AI agent and could potentially find ways around sandboxing. Sandboxing is a safety measure but not foolproof.

Logging

• • Console Log: The debugging log shown on the server’s main page. An option in settings enables more detailed output.
• • Execution Log: A record of events saved on your device for debugging. Adjust the retention period (7 days, 30 days, or disabled). Logs are stored locally at ~/.satellite/execution_log.json and are never uploaded.

Step 2: Connect Your Devices

You have two options for how the iOS app reaches your desktop.

Your Tailscale hostname is stable and never changes, so you only need to set this up once.

Step 3: First Launch

When you open the app for the first time and connect, a welcome screen explains how the approval system works. Tap Continue when you’re ready.

You’ll be prompted to enable Face ID or Touch ID if you want biometric lock. This protects access to your server connection and chat history — recommended if others use your device.

Step 4: Review Security Settings

Before your first session, review these settings in the desktop server under Settings > Security & Server.

Starting a Session

A session is a conversation with Claude Code that has its own context, history, and project folder. You can have many sessions — one per project, feature branch, or task.

1. 1. Tap the hamburger menu (top-left) and select New Session.
2. 2. Give the session a name — something like “Auth refactor” or “Fix login bug” makes it easy to find later.
3. 3. Set a working folder. This is the root directory Claude Code will work in, and the sandbox boundary if Sandbox Mode is on.
4. 4. Tap Connect (the green dot, top-right) if you’re not already connected.

Sending Messages

• • Type in the input field at the bottom and tap the send button. Responses stream in as Claude works.
• • To attach images, tap the photo icon. You can attach up to 4 images per message.
• • To stop a response mid-stream, tap the Stop button that appears during generation.
• • To switch models (Haiku, Sonnet, Opus), tap the model selector above the input field.

Approving Actions

When Claude Code wants to do something — run a command, edit a file, create a file, or use a tool — it pauses and sends you an approval card. The session waits until you respond.

Each approval card shows

• • A plain-English description of what Claude intends to do
• • The raw command or file path it will act on
• • The tool type (Bash, Edit, Write, etc.)

Your three options

Autonomous Mode

You can turn off approval prompts entirely in Settings > Advanced by toggling off “Require Approval for Changes”. When active:

• • The input bar turns orange as a visual warning.
• • All tool calls are auto-approved without prompting.
• • A confirmation dialog warns you before enabling.

Only use Autonomous Mode with Sandbox Mode enabled. Without both sandboxing and approval, Claude Code has unrestricted access to your entire system.

Managing Sessions

Your sessions are listed in the hamburger menu under Previous Sessions. Tap any session to resume it — the full conversation context and project folder are restored.

• • The session header shows the exchange count, context token count, and total tokens used.
• • Very long sessions accumulate context and use more tokens. Start a new session when switching topics or projects.
• • A “Loading context...” indicator appears briefly when restoring a session with a lot of history.

Keeping the Connection Alive

For long-running tasks, enable “Prevent Sleep” in Settings > Connection. The screen dims to 10% brightness after a minute of inactivity to save battery, but the app stays in the foreground and the connection stays active. Tapping the screen or picking up the device restores brightness automatically.

Can’t Connect

• • Check the server is running on your desktop — look for the green indicator.
• • Re-enter your password in iOS Settings to rule out a typo.
• • For local network: confirm both devices are on the same Wi-Fi.
• • For Tailscale: confirm both devices are signed in and Tailscale shows as connected.
• • Check the port in the iOS app matches the server port (default 3001).
• • Check your firewall isn’t blocking port 3001.

Connection Drops Frequently

• • Tailscale: check the VPN is still connected on both devices.
• • Local network: try moving closer to the router.
• • Check the Cli.nt server app is still running on your desktop.

Slow Responses

• • Long sessions accumulate large context. Start a new session to speed things up.
• • Try a faster model — Haiku responds much quicker than Opus for simpler tasks.
• • Tailscale adds a small amount of latency versus a pure local connection; this is normal.

Approval Not Appearing

• • Confirm you’re connected to the server (green indicator).
• • Check “Require Approval” is toggled on in Settings > Advanced.
• • Check the server is running — approvals won’t arrive on a dropped connection.

Session Stuck / Agent Not Responding

Long-press the connection button to restart both the approval and agent servers. This recovers most stuck states without losing your session context.

Always Allow Not Working

The “Always Allow” cache resets when you disconnect — this is intentional. Reconnect and re-approve the tool type. If it’s still not working, check the server logs for approval flow errors.

Tips for the Best Experience

• • Use Tailscale so you can connect from anywhere, not just home Wi-Fi.
• • Name your sessions descriptively — “Homepage redesign” is easier to find than “Session 4”.
• • Start a fresh session when switching projects. Context from an unrelated task just adds noise.
• • Use “Always Allow” for low-risk tools like file reads and searches to reduce approval fatigue — it resets on disconnect anyway.
• • Keep Sandbox Mode on whenever possible, especially with Autonomous Mode.
• • Enable “Prevent Sleep” for long tasks so your phone doesn’t disconnect mid-job.
• • Review the literal bash command in each approval, not just the description — Claude’s intent and the actual command can occasionally diverge.