openlens-qr

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 37 Open GitHub ↗

iOS companion app for OpenCode - chat with your AI coding assistant from your phone.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OpenLens

**iOS companion app for [OpenCode](https://opencode.ai) — chat with your AI coding assistant from your phone.**

OpenLens connects to an OpenCode server running on your Mac and gives you a native iOS interface to chat, review changes, run tests, manage sessions, and switch models — all from the couch.

## Features

- **Native chat interface** — rich Markdown rendering, code blocks, thinking indicators, agent activity cards
- **Multiple connection methods** — QR code scan, Bonjour auto-discovery on local network, manual URL entry, deep links
- **Session management** — browse, switch, and continue existing OpenCode sessions
- **Model picker** — switch between AI models (Claude Sonnet, Opus, etc.) directly from the app
- **Live Activities** — track agent progress on your Lock Screen and Dynamic Island
- **Demo mode** — try the app without a server to see how it works
- **Setup wizard & onboarding** — guided first-launch experience
- **`openlens-qr` CLI tool** — generate a QR code from your terminal for instant phone connection

## Beta / TestFlight

Want to try the latest builds before they hit the App Store? Join the TestFlight beta here:

For testers:

- Beta builds may include unfinished features, UI changes, and occasional regressions.
- If something breaks or behaves unexpectedly, please report it with the device model, iOS version, and steps to reproduce.

## Quick Start

### 1. Install OpenCode on your Mac

```bash
curl -fsSL https://opencode.ai/install | bash
```

### 2. Start the server + show QR code (recommended)

Build and run the `openlens-qr` CLI tool included in this repo:

```bash
cd Tools/openlens-qr
xcrun swift build -c release
.build/release/openlens-qr --serve
```

If you want to protect the server with a password, pass it via environment variable:

```bash
cd Tools/openlens-qr
xcrun swift build -c release
OPENLENS_QR_PASSWORD=secret .build/release/openlens-qr --serve
```

Replace `secret` with your own password. If you want to avoid leaving it in shell history, export `OPENLENS_QR_PASSWORD` only for the current session or set it right before running the command.

This will:
1. Start an OpenCode server on port `4096`
2. Display a QR code in your terminal
3. Wait for you to scan it with OpenLens on your phone
4. Press Enter to open the TUI — now you have both desktop and mobile access

### 3. Open OpenLens on your iPhone and connect

- **Scan QR** — tap "Scan QR Code" and point at the terminal
- **Auto-discover** — tap "Tap to scan for nearby servers" (Bonjour)
- **Manual** — enter your Mac's IP and port (e.g. `192.168.1.50:4096`)

That's it. You're chatting with your AI coding assistant from your phone.

---

## `openlens-qr` CLI Reference

```
Usage: openlens-qr [server-url] [options]

Arguments:
  [server-url]          Server address (e.g. 192.168.1.50:4096)
                        Optional — auto-detected if omitted

Options:
  --serve, -s           Start OpenCode server, show QR when ready, then open TUI
  --port <number>       Port when using auto-detected IP (default: 4096)
  --user, -u <name>     Username (default: opencode)
  --print-secret-link   Print the full deep link, including password if set
  --help, -h            Show this help

Environment:
  OPENLENS_QR_PASSWORD  Optional password included in the QR deep link
                        and used for serve mode
```

**Examples:**

```bash
openlens-qr                              # auto-detect IP, show QR
openlens-qr --serve                      # QR + start server & TUI
OPENLENS_QR_PASSWORD=secret openlens-qr --serve
OPENLENS_QR_PASSWORD=secret openlens-qr --print-secret-link
openlens-qr 192.168.1.50:4096            # explicit address, QR only
```

---

## Alternative: Manual Server Setup

If you prefer not to use the CLI tool, start the server yourself:

```bash
opencode serve --port 4096 --hostname 0.0.0.0
```

Then connect from the app using your Mac's local IP address.

---

## Requirements

- **iOS app**: iPhone with iOS 26+
- **Server**: macOS with [OpenCode](https://opencode.ai) installed
- **Network**: both devices on the same local network

---

## Deep Links

OpenLens supports the `openlens://` URL scheme for automated connection:

```
openlens://connect?url=192.168.1.50:4096&user=opencode&pass=optional
```

The `openlens-qr` tool encodes this into the QR code automatically.

If you use a password, prefer `OPENLENS_QR_PASSWORD` over passing secrets as command-line arguments so they do not end up in your shell history. By default the terminal output masks the password in the printed deep link; use `--print-secret-link` only when you explicitly need the full URL.

---

## License

This project is licensed under the [MIT License](LICENSE).

openlens-qr

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README