clover's git

the-knife

1	# Devices
2
3	The Device panel shows a live iOS Simulator or Android Emulator next to a
4	thread, so you can watch an agent verify mobile work and tap the device
5	yourself. Agents get the same device through `device_*` tools and the
6	`agent-device` command line, which T3 Code sets up for them.
7
8	## Open a device
9
10	Open the right panel in a project thread and choose **Device**. On first use,
11	the panel walks through three steps: starting the device hub, checking iOS and
12	Android support, and choosing whether agents may control devices. Opening the
13	panel alone does not download or start anything. If the hub is already
14	installed, the setup screen says so and reuses it.
15
16	Choose a running device to watch it, or choose **Start** next to a stopped
17	device to boot it. The panel shows when you or an agent starts a device.
18	Each device opens in its own tab. Use **+ → Device** to open another, and
19	double-click a tab name or choose **Rename** from its context menu to rename it.
20	Only the visible tab streams video; switching tabs keeps both devices running.
21	Choose **Float device over chat** in the toolbar to keep watching and tapping the
22	device in a small window while the right panel shows something else; drag the
23	window by its handle, resize it from any edge, and use **Open in right panel**
24	to bring it back.
25	Turn off the device hub in **Settings → Integrations → Devices** to stop the
26	helper processes; simulators and emulators keep running until you power them
27	off.
28
29	Simulators run on the machine that hosts the environment server. iOS needs
30	macOS with Xcode. Android needs the SDK Platform-Tools, Android Emulator,
31	and Command-line Tools (latest), plus a virtual device created in Android
32	Studio's Device Manager. T3 Code detects standard SDK locations; set
33	`ANDROID_HOME` for a custom location. The panel explains missing dependencies.
34	After installing them, restart the environment server and refresh devices.
35
36	The screen is interactive: click and drag to touch, type while the screen is
37	focused, and use the toolbar for Home, Back, and Recents on Android, rotate on
38	iOS, and power off. Close the tab to stop watching; the device keeps running
39	unless you power it off. Closed tabs stay closed after a reload. To watch the
40	device again, choose it from **+ → Device**.
41
42	Choose **3D view** to inspect supported devices while the live screen stays
43	interactive. On iPhone Duo, use the fold and stance controls to change its
44	physical pose, or pinch over the device to adjust the hinge. Turning the model
45	to the other screen switches the live display and touch input to that screen.
46	**Restore 3D view** returns the device to a screen-facing position.
47	On supported Android foldables, use **Fold device** and **Unfold device** beside
48	the screen to change its posture in either view.
49
50	## Tools
51
52	The toolbar's **Tools** button opens a drawer for the open device. It shows the
53	foreground app, and lets you switch light and dark mode, change text size,
54	flip accessibility settings, overlay the accessibility element frames on the
55	screen, set a fake location, and grant or revoke app permissions. iOS also
56	exposes Liquid Glass, color filters, VoiceOver, and sending a test push
57	notification; Android adds orientation and toggling the network. The drawer
58	only shows what the platform can do, and every control reflects the value read
59	back from the device after a change.
60
61	## Agents and devices
62
63	When an agent opens a device, it floats over the chat in web and desktop clients
64	connected to the thread, the same way an agent-driven browser does. Turn off
65	**Auto-show floating preview** in **Settings → Integrations → Browser** to open a
66	right-panel tab instead. In the mobile app, open the agent's thread and tap the
67	device button above the composer to watch the live screen and control it.
68	If the thread has several devices open, choose one in the viewer. Closing the
69	viewer stops streaming and leaves the device available to the agent. Device
70	activity also appears in the thread timeline.
71
72	Agents drive the device through the `agent-device` command line. T3
73	Code installs and starts it only after **Agent device access** is enabled. iOS
74	taps build a small test runner on first use, which takes a couple of minutes
75	once per server. Restart an existing agent session after granting access so it
76	receives the device CLI environment.
77
78	To keep agents away from simulators, turn off **Agent device access** in
79	**Settings → Integrations → Devices**. This hides the device tools from agents
80	started from then on; your own Device panel is unaffected.
81
82	## Remote connections
83
84	The device stream goes through the environment server, so it works over the
85	local network, Tailscale, and T3 Connect. Live video needs a secure page
86	(HTTPS or localhost); on a plain-HTTP remote origin iOS falls back to a slower
87	still-image stream and Android cannot show video.
88
89	## SSH device hosts
90
91	In Settings → Integrations → Devices, choose the environments that should use
92	the host and add it under **Device hosts**. Enter an SSH alias or `user@host`, with
93	an optional identity file and port. These resolve on the environment server,
94	so use the SSH configuration and keys available there. Password prompts are
95	not supported.
96
97	**Test connection** checks SSH, Node, npm, and platform tools without installing
98	anything, with a result for each selected environment. Targets that resolve to
99	the environment’s own machine are skipped, since its devices are already local.
100	The first device listing installs pinned device tools on the host.
101	Node 22 or newer and npm must be available to non-interactive SSH commands.
102	T3 checks common Homebrew and Android SDK locations; custom installations need
103	the appropriate PATH and ANDROID_HOME on the host.
104
105	The picker identifies devices by host when several hosts are configured.
106	Connections recover after interruptions. Removing a host closes its device
107	sessions and stops its T3 helpers when reachable; simulators keep running.
108
109	T3 provides discovery, streaming, and control. Arrange app builds,
110	installation, and connectivity to development servers such as Metro separately.
111	A simulator on another machine cannot reach Metro through your environment's
112	localhost without forwarding or another reachable address.
113
114	## Device tool updates
115
116	The connected T3 server manages the device hub and agent tools on its own machine and configured SSH hosts. Required versions install automatically the next time those tools are used. Settings → Integrations → Check device tool versions reads installed versions without installing tools or starting devices.
117
118	To receive newer tool versions on a remote environment, update that environment's T3 server. Updating only the browser or mobile app does not update the remote server. An offline host keeps its installed files, but an update needs network access before device support can start; T3 does not fall back to an older version. Reconnect the host and use Retry if installation fails. Existing device and agent-access settings are preserved.