A local agent lets Dart send work to an AI coding tool running on your computer. This is useful when you want to assign work from Dart while keeping the actual coding session close to your local repository, credentials, and development environment.
The usual setup starts in Dart, then continues in your terminal.
Before you start
Install and log in to the Dart CLI:
Bash
pip install dart-tools dart login
You should also have the local coding tool you want to use installed and ready in the terminal where you plan to run the agent. Dart currently supports Claude Code, Codex, Gemini, and OpenCode as local agent options.
Create a local agent in Dart
Open Agents in the left navigation bar.
Create a custom agent, or open an existing custom agent.
In the agent setup, choose Local.
Choose which local tool should run the work, such as Claude Code, Codex, Gemini, or OpenCode.
Copy the command shown in the Command section. It will look like this:
dart agent-connect <agent_id>
Run that command in a terminal on the machine where you want the agent to work. When the connection is active, Dart will show the agent as Connected.
Keep the terminal process running while you want the local agent to accept work. If the process stops, Dart will show the agent as waiting for connection, and new local agent work will not start until you reconnect it.
Send the work to the local agent
Once the agent is connected, you can use it from Dart like other agents:
Assign a task to the local agent
Mention the local agent in a task comment
Chat with the local agent
Dart sends the work to the connected terminal session, and the local agent's response appears back in the task or chat where the work started.
Run the connection in the background
For regular use, you may want the connection to keep running without holding open an interactive terminal session:
Start in background:
dart agent-connect <agent_id> --backgroundList background connections:
dart agent-connectionsStop connection(s):
dart agent-disconnect <agent_id>(use--allto stop all)Hide messages (foreground):
dart agent-connect <agent_id> --quiet
Start from the CLI instead
The Dart UI flow is the easiest way to choose and copy the exact command for an existing local agent. However, you can also start from the terminal by running: dart agent-connect
When you omit the agent ID, the CLI opens a setup wizard that creates a local agent and connects it for you.
Troubleshooting
If the agent stays in "Waiting for connection", make sure the copied
dart agent-connect <agent_id>command is still running and that you are logged in withdart loginIf a background connection already exists for the agent, use
dart agent-connectionsto find it anddart agent-disconnect <agent_id>to stop it before starting a new oneIf the agent is connected to the wrong local tool, change the Local agent dropdown in Dart, then reconnect the agent from your terminal