clover's git

the-knife

1	# ACP providers
2
3	T3 Code can run installed ACP commands or coding agents from the official
4	[ACP Registry](https://agentclientprotocol.com/get-started/registry). Registry agents bring their
5	own models, tools, and sign-in, while T3 Code provides projects, threads, checkpoints, and task
6	delegation.
7
8	Google Antigravity is available through its official `antigravity-acp` Registry entry. Add it like
9	any other Registry agent; it does not need an Antigravity-specific T3 Code provider.
10
11	T3 Code prefers the current ACP v2 preview protocol and uses its richer messages, usage, plans,
12	configuration, compaction, and agent-terminal updates when the agent supports them. It also
13	negotiates ACP v1 for Registry agents that have not migrated yet, so agents such as Pi continue to
14	work through the same generic integration.
15
16	## Add an agent
17
18	1. Open **Settings → Providers**.
19	2. Select **Add provider** and search the ACP Registry.
20	3. Search for the agent and select **Add** on its result.
21	4. Confirm the name and instance ID, then complete the agent's sign-in step.
22
23	Search only shows agents that can run on the connected server. Registry agents are third-party
24	code; review an agent's source and license before adding it.
25
26	## Add a local command
27
28	In **Settings → Providers → Add provider**, select **Local ACP command**. Enter the executable
29	name or path on the selected environment, add one literal argument per row, and choose a display
30	name. For DeepSeek Harness, use `dsh` with arguments `--profile` and `acp`.
31
32	Local commands require no registry entry or download. Environment overrides apply to the command;
33	credentials and skills remain managed by the installed agent or its wrapper. Models and reasoning
34	options come from ACP, including model IDs that contain JSON. T3 Code launches the executable directly
35	without expanding shell expressions.
36
37	## Where agents run
38
39	Registry agents always run on the machine that hosts your T3 Code server. That stays true when you
40	connect through `app.t3.codes`, T3 Connect, or a relay.
41
42	Agents install under `tools/<agent-id>/<version>/` inside T3 home. T3 Code verifies SHA-256 when the Registry entry
43	provides one; entries without a checksum retain the Registry's HTTPS distribution guarantee.
44	Registry `npx` and `uvx` packages use T3-owned npm prefixes and Python tool directories at the exact
45	version published by the Registry. Their commands are available in a new server terminal for
46	sign-in and direct use. Removing an agent's last provider instance removes T3-managed binary files
47	but keeps package installs. To use an existing local binary, set **Executable override** explicitly.
48
49	## Signing in
50
51	Open the agent's account section in **Settings → Providers** on web or desktop. Choose
52	**Sign in** and, if the agent offers several methods, select one. For an installed, configured
53	provider, mobile also offers **Settings → Provider accounts**.
54
55	Browser sign-in shows the agent's URL and waits for you to open or copy it before telling the
56	agent to proceed. The page opens on your device, while the agent runs on the environment.
57	Terminal methods run in an in-app terminal on that environment. On mobile, send responses
58	through the terminal response field. T3 Code reconnects after terminal login and waits for the
59	agent to confirm sign-in before reporting success. You can cancel or retry an expired attempt.
60
61	Browser and terminal sign-in leave credentials in the agent's own store. Agents that use API keys
62	through environment variables still take those keys in the instance's environment settings.
63	A configured environment or agent home applies to both sign-in and chat.
64
65	If the agent advertises logout, choose **Sign out**. Changing a shared agent login stops running
66	threads for instances of that same agent on the environment. Thread history and workspace files
67	are kept. ACP does not describe account isolation, so adding another instance does not guarantee
68	a separate account; use the agent's own configuration to isolate accounts when supported.
69
70	If an agent cannot complete its advertised flow remotely, its CLI remains available on the
71	server. For example, Codex supports `codex login --device-auth`, and Grok Build supports
72	`grok login --device-auth`.
73
74	## Models and options
75
76	The model picker lists the models the agent reports. If the agent reports none, or hides some, add
77	your own model IDs under **Custom models** in the instance settings.
78
79	Other settings the agent offers, such as reasoning effort or approval mode, appear in the
80	composer's model options menu like they do for built-in providers. Agents with their own plan and
81	build modes follow T3 Code's Plan and Build toggle. Models and options that change while an agent
82	is running update the picker without waiting for another provider probe.
83
84	## Commands and skills
85
86	Slash commands the agent provides appear under **Provider** in the `/` menu while a session is
87	running. Commands the agent names with a `$` prefix appear in T3 Code's `$` skill menu instead.
88
89	## Native sessions
90
91	When an agent advertises ACP session listing and import support, expand its provider card,
92	choose a project, and select **List sessions**. Importing one creates a deterministic T3 thread
93	backed by that native session. Importing the same agent session again returns the existing thread,
94	including when another client performs the import.
95
96	The thread keeps the native session's title and last-update value as provider metadata without
97	overwriting a title you set in T3 Code. Agents that report ACP context usage drive the composer's
98	context meter and cumulative cost metadata. Text resources and links render as assistant output;
99	binary resources, images, and audio that T3 Code cannot render yet appear as explicit placeholders
100	instead of disappearing.
101
102	## Permissions and terminals
103
104	Registry agents read files, edit, and run commands themselves, under their own sandbox and
105	approval rules. They start in their own default mode, and their mode picker in the model options
106	menu switches it. How far an agent is confined depends on that mode and the agent's own settings,
107	so use its sandbox and permission controls when that matters.
108
109	When a registry agent asks for approval, T3 Code answers by the thread's
110	[permission mode](./permission-modes.md): **Supervised** shows the request in the conversation,
111	**Auto-accept edits** approves edits and shows the rest, and **Auto** and **Full access** approve
112	automatically. File reads and searches never wait for approval.
113
114	Devin runs its commands through T3 Code's terminals, and those commands follow the thread's
115	permission mode. For other agents, T3 Code shows the command, output, and exit status the agent
116	reports but does not run or stop their terminals.
117
118	Registry agents can schedule work and use T3's MCP tools. Child-task presentation depends on what
119	the agent exposes: ACP has no portable native subagent-lineage contract, so richer delegation views
120	remain agent-specific.
121
122	## Checkpoints
123
124	Checkpoint rollback restores your files as usual. ACP agents cannot rewind their own conversation,
125	so the next turn after a rollback starts a fresh agent session that no longer remembers the
126	conversation from before the checkpoint.
127
128	Registry instances are not used for T3's app-owned text generation, such as thread titles, commit
129	messages, branch names, or pull request descriptions. Configure a text-generation-capable provider
130	for those actions.
131
132	## Advanced configuration
133
134	- **Executable override** runs an existing local executable instead of the managed distribution,
135	keeping the registry-declared arguments and environment.
136	- **Authentication method** picks a specific method when the agent advertises more than one.
137	- **Custom models** adds model IDs the agent does not report.