Agent Client Protocol in LatchLoop desktop
LatchLoop Desktop can connect to local coding agents through the Agent Client Protocol (ACP). This makes it possible to run compatible external agents, such as Codex or Claude Code local coding tools, while keeping the task workflow inside LatchLoop.
External agent support is a desktop-first feature. Exact setup depends on the agent and adapter you are using.
What external agents can do
External agents can help with task work while LatchLoop provides the surrounding workflow:
- task context and instructions
- local repository access boundaries
- progress shown in the AI sidebar
- file-change summaries
- permission prompts for sensitive operations
- task timeline visibility
This is useful if your team already uses a local agent CLI and wants to run it from inside the LatchLoop desktop app.
Agent profiles
External agents are configured as profiles. A profile can include:
- agent name and type
- command or executable path
- environment variables
- working directory expectations
- whether the profile is enabled
Sensitive environment values are handled as secrets and should not be pasted into normal task descriptions or public docs.
Permissions and safety
External agents run locally and are constrained by the desktop integration.
LatchLoop applies safety controls such as:
- repository-root path validation for file access
- explicit permission handling for writes or sensitive operations
- guarded process launching
- no automatic sharing of LatchLoop credentials with the external agent
- task-scoped progress and activity tracking
Only approve requests you understand. If an agent asks for unexpected access, reject it and add clarification in the task.
Switching agents and reading external agent progress
After a run you can switch from one agent to another. Use LatchLoop’s agent harness or swap between it and Codex or Claude Code on the same task. The AI sidebar can show external agent activity such as:
- start and finish messages
- planning updates
- tool activity
- changed files
- completion summaries
LatchLoop stores these updates as task activity so the run remains understandable after refresh.
Troubleshooting
Agent is not detected
- Confirm the external CLI is installed.
- Confirm it works in your normal terminal.
- If the desktop app was launched from Finder on macOS, check that the CLI is in a common path such as
/opt/homebrew/bin, /usr/local/bin, or ~/.local/bin.
- Enter the executable path manually if auto-detection cannot find it.
Connection test fails
- Open the agent’s CLI directly and confirm you are signed in.
- Check required environment variables.
- Review the error shown in the profile setup UI.
Activity appears duplicated or missing
- Refresh the task. LatchLoop persists external agent activity and should show one copy of each event after sync.
- If progress is sparse, the external agent or adapter may not emit detailed activity events yet.
File access is denied
- Confirm the project has a mapped local repository.
- Confirm the requested file is inside the repository root.
- Approve write permissions only when the path and action are expected.