Control Claude Code from your phone

Claude Code asks before it runs a command, edits a file or uses a tool you haven’t allowed. Connect it to Tealhand and each of those questions goes to your phone instead: “Claude wants to run npm test in ~/app on Lab PC”. Approve with your fingerprint, or Decline. When Claude waits for you or finishes, your phone says so too.

Nothing is ever allowed without your phone. A request is denied when you decline, when nobody answers within a minute, when no phone of yours is online, or when Tealhand isn’t running on that computer.

Connect it

Claude Code and Tealhand run on the same computer, and your phone is connected to that computer.

In the Tealhand app on that computer: Settings, Coding agents, turn on Claude Code.

In a terminal (any computer, also one without a screen):

tealhand-host agent setup claude

Then start a new Claude Code session. Already running sessions keep their old settings until they restart.

What it changes

Tealhand adds three hooks to Claude Code’s user settings, ~/.claude/settings.json (or the folder in CLAUDE_CONFIG_DIR). Everything else in the file stays as it was, and the first change keeps a copy of the original next to it, settings.json.tealhand-backup.

{
  "hooks": {
    "PermissionRequest": [
      { "matcher": "*", "hooks": [
        { "type": "command", "command": "C:\\Program Files\\Tealhand\\tealhand-host.exe",
          "args": ["agent", "hook", "PermissionRequest"], "timeout": 120 } ] }
    ],
    "Notification": [
      { "matcher": "idle_prompt|elicitation_dialog|elicitation_url_dialog|agent_needs_input", "hooks": [
        { "type": "command", "command": "C:\\Program Files\\Tealhand\\tealhand-host.exe",
          "args": ["agent", "hook", "Notification"], "timeout": 30, "async": true } ] }
    ],
    "Stop": [
      { "hooks": [
        { "type": "command", "command": "C:\\Program Files\\Tealhand\\tealhand-host.exe",
          "args": ["agent", "hook", "Stop"], "timeout": 30, "async": true } ] }
    ]
  }
}

• PermissionRequest runs only when Claude Code is about to ask you. Tool calls you already allowed in Claude Code, and everything in bypassPermissions mode, never reach the phone.
• Notification sends “Claude needs your input in ~/app on Lab PC”.
• Stop sends “Claude finished in ~/app on Lab PC”.

Always ask

Every tool call Claude Code would ask you about goes to your phone, every time. There is no “always allow” on the phone yet. To stop being asked about a command, allow it in Claude Code itself (its permission rules); to stop using the phone for Claude Code, disconnect it.

Disconnect

Settings, Coding agents, turn Claude Code off, or:

tealhand-host agent remove claude

Only Tealhand’s hooks leave the file: a hook that only looks like ours (another program, other arguments) stays. Claude Code asks you in its terminal again.

What your phone shows

The card names the agent, the tool, what it would do and the project folder: the command for Bash, the file for an edit, the address for a fetch, else the tool’s input. Line breaks show as ↵. Invisible and direction-changing characters are removed. A long command keeps its start and its end, with “[… N more characters …]” in between: if that marker is there, check the full command at the computer before you approve.

What the card says comes from the agent. A project can contain text written to make an agent ask for something harmful (“run this setup script”). Read the command, and approve only what you expect.

What is recorded

The computer’s Activity lists each request: asked (with the tool, the folder and the short summary), approved on which phone, declined, no answer, or refused because no phone was online.

How it works

The hook is a short-lived tealhand-host process. It talks to the Tealhand Host on the same computer over the local endpoint that AI apps use (127.0.0.1 only, with a token from this user’s credential store); nothing new listens on the network. The Host asks your connected phones; your phone signs the approval with its fingerprint key, bound to this one request, valid for at most 90 seconds and usable once. The Host checks that signature against the device list your phone signed, then answers the hook.