udha

Connect your iPhone to Claude Code running on your computer. Chat with Claude AI from anywhere using the Udha iOS app.

What is Udha?

Udha is a bridge that connects your iPhone to Claude Code running on your Mac. Once set up, you can:

• Send messages to Claude from your phone while away from your computer
• See Claude's responses in real-time
• Approve or deny permission requests remotely
• Access a full terminal view when needed

Your Mac stays at home running Claude Code, and you interact with it from anywhere through your phone.

How It Works

┌─────────────┐         ┌─────────────────┐         ┌─────────────┐
│   iOS App   │◀───────▶│  Cloud Relay    │◀───────▶│    udha     │
│  (iPhone)   │   WSS   │ (amk.solutions) │   WSS   │ (Your Mac)  │
└─────────────┘         └─────────────────┘         └─────────────┘

1. udha runs on your Mac and spawns Claude Code when you send a message
2. Your messages are securely relayed through our cloud server
3. Claude's responses stream back to your phone in real-time
4. All communication is encrypted (WSS) and authenticated (Auth0 JWT)

Prerequisites

Before installing udha, make sure you have:

1. Node.js 18 or later

Check if you have Node.js installed:

node --version

If not installed, or version is below 18, install via Homebrew:

brew install node

Or download from nodejs.org.

2. Claude Code CLI

Install Claude Code if you haven't already:

npm install -g @anthropic-ai/claude-code

Verify it's installed:

claude --version

Make sure you've authenticated Claude Code at least once:

claude

This will prompt you to log in with your Anthropic account.

3. Udha iOS App

Download the Udha app from the App Store (or TestFlight during beta).

Installation

Install udha globally via npm:

npm install -g udha

Verify the installation:

udha --version

Quick Start

Step 1: Start udha

Open Terminal and navigate to the project directory you want to work in:

cd ~/my-project
udha

Important: udha uses the current directory as the working directory for Claude Code. Run it from the project folder you want Claude to work in.

Step 2: Authenticate (First Run Only)

On the first run, your browser will open to the login page:

1. Create an account or sign in
2. After successful login, you'll see "Authentication Successful!"
3. Return to your terminal

Your credentials are saved to ~/.appmaker/credentials.json and will be reused automatically.

Step 3: Scan the QR Code

After authentication, a QR code appears in your terminal:

═══════════════════════════════════════════════════════════════
  Scan this QR code with the Udha iOS app to connect:
═══════════════════════════════════════════════════════════════

    █▀▀▀▀▀█ ▄▄▄▄▄ █▀▀▀▀▀█
    █ ███ █ █▄▄▄█ █ ███ █
    ...

Instance: MacBook-Pro - my-project
═══════════════════════════════════════════════════════════════

1. Open the Udha iOS app
2. Tap "Scan QR Code" or use the camera icon
3. Point your camera at the QR code
4. You're connected!

Step 4: Start Chatting

Once connected, you can send messages from your iPhone. Claude Code will process them on your Mac and stream responses back to your phone.

Running Multiple Projects

You can run udha in multiple project directories simultaneously. Each directory gets its own instance:

Terminal 1:

cd ~/project-a
udha

Terminal 2:

cd ~/project-b
udha

Each instance appears separately in the iOS app, labeled with the folder name.

Keeping It Running

udha prevents your Mac from sleeping while running (using caffeinate). However, if you want it to run persistently:

Option 1: Terminal Multiplexer (tmux)

# Install tmux if needed
brew install tmux

# Start a new session
tmux new -s udha

# Run udha
cd ~/my-project
udha

# Detach with Ctrl+B, then D
# Reattach later with: tmux attach -t udha

Option 2: Keep Terminal Open

Simply leave the Terminal window open. Your Mac won't sleep while udha is running.

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CLAUDE_PATH | ~/.local/bin/claude | Path to Claude CLI executable | | RELAY_URL | wss://relay.amk.solutions | Relay server WebSocket URL |

Example with custom Claude path:

CLAUDE_PATH=/usr/local/bin/claude udha

Credential Storage

• Auth tokens: ~/.appmaker/credentials.json
• Instance ID: .claude-instance-id (in working directory)
• Message history: .claude-chat-history.json (in working directory)

Troubleshooting

"command not found: udha"

Make sure npm global bin is in your PATH:

# Find where npm installs global packages
npm config get prefix

# Add to your shell profile (~/.zshrc or ~/.bash_profile)
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload your shell
source ~/.zshrc

"Cannot find Claude"

If Claude Code is installed but not found:

# Find where claude is installed
which claude

# Set the path explicitly
CLAUDE_PATH=$(which claude) udha

Authentication Issues

If you need to re-authenticate:

# Remove saved credentials
rm ~/.appmaker/credentials.json

# Run udha again to trigger login
udha

QR Code Not Scanning

• Make sure your terminal font is monospace
• Try making the terminal window larger
• Ensure good lighting and hold phone steady
• The QR code refreshes every 5 minutes for security

Connection Drops

udha automatically reconnects if the connection drops. If you're having persistent issues:

1. Check your internet connection
2. Make sure port 443 outbound is not blocked
3. Try restarting udha

"Another instance is running"

Each directory can only have one udha instance. If you see this message:

# Find and kill the existing process
pkill -f "node.*udha"

# Or find the specific process
ps aux | grep udha
kill <PID>

Security

• End-to-end encryption: All WebSocket connections use TLS (WSS)
• JWT authentication: Tokens are RS256 signed and validated
• No password storage: PKCE flow means no secrets on your device
• Token refresh: Access tokens auto-refresh before expiry
• Local credentials: Auth tokens stored with restricted permissions (600)

Uninstalling

# Remove the package
npm uninstall -g udha

# Optionally remove credentials
rm -rf ~/.appmaker

License

MIT