# Droidtty

> Droidtty is a phone app (Android and iPhone) for coding agents running in Herdr. It shows what each agent is doing, notifies you only when one needs you, and lets you answer its questions, approve its commands, review its diffs and open a real terminal from your phone. A small bridge, droidtty-cli, runs on the computer next to Herdr.

## How it works

- [Herdr](https://herdr.dev) runs your coding agents in terminal workspaces and knows each agent's state.
- The bridge (`droidtty-cli`, npm package `@droidtty/cli`) runs on the same machine. It reads Herdr's socket API, each agent's own session log (Claude Code, Codex) and the workspace's git, and serves that to the phone over a WebSocket with TLS pinned to the bridge's certificate. The phone connects straight to your machine, over your Wi-Fi or Tailscale, and there's no account.
- Approvals and answers go back through Herdr's API, not typed into a terminal.
- Pairing: `droidtty-cli tui` (or `droidtty-cli pair`) shows a QR code with a single-use code valid for 5 minutes; scan it in the app.

## Features

- The Herd: every agent across your workspaces, sorted by what needs you, what's working and what's done.
- Attention, not activity: reading, editing and testing don't notify you; a question or a permission request does.
- Approvals show the exact command and its risk; allowing takes a deliberate hold. Questions show the agent's options plus a free-text answer.
- A session timeline of prompts, reads, edits, commands, tests and results.
- Diffs of the workspace's changes, with a "Why" note on each block an agent edited: the reasoning it gave right before the edit.
- A real terminal: the agent's own pane, or a shell in the project. Android draws it with Ghostty's terminal engine; the iPhone app uses SwiftTerm.
- Program status (OSC 7501): ordinary command-line tools can report working, blocked, done or failed.
- Agents: Herdr detects 21 coding agents (Claude Code, Codex, Gemini CLI, Cursor, Copilot, opencode, Amp, Pi, Droid, Antigravity, Cline, Devin, Grok, Hermes, Kilo Code, Kimi, Kiro, Letta, Mastra, Qoder, Qwen Code); Claude Code and Codex also get full timelines and exact approvals.

## Set up

1. On the Mac or Linux machine where Herdr runs: `npm install -g @droidtty/cli`, then `droidtty-cli tui` (a terminal UI that runs the bridge and shows the pairing code). `droidtty-cli serve` runs it without the UI; add `--demo` for a simulated herd without Herdr.
2. Install the app and scan the code.

The bridge ships for macOS on Apple Silicon and for Linux on x64 and arm64 (static binaries). The Android app needs Android 9 or later (arm64); the iPhone app needs iOS 26 or later.

## Links

- [Website](https://droidtty.com/): overview and downloads
- [Android app (APK, version 0.4.1)](https://hzbekorpbjfrpw9z.public.blob.vercel-storage.com/android/9a1150d67ab0/droidtty-0.4.1-arm64.apk): direct download
- [iPhone app (TestFlight beta)](https://testflight.apple.com/join/ZqxmnExn)
- [Security](https://droidtty.com/security): no cloud relay, pinned TLS, pairing, device permissions and what leaves the computer
- [Changelog](https://droidtty.com/changelog): every release, also as RSS at https://droidtty.com/changelog.xml
- [Bridge on npm](https://www.npmjs.com/package/@droidtty/cli): `@droidtty/cli`
- [Herdr](https://herdr.dev): the agent workspace manager Droidtty works with

## Optional

- [Shepherd](https://tryshepherd.xyz): by the same author, a macOS notch app that shows when your Herdr agents need you
- License: MIT