Guides
Work with AI agents
Run Claude Code or opencode on one of your machines as a chat, and follow it from your computer and your phone.
Run a coding agent on one of your machines as a chat: talk to it, approve what it asks and check its changes, from your computer or your phone.
chaar works with Claude Code and opencode today. More agents are coming soon.
Install an agent on your machine
Install the agent on the machine where it will work. chaar offers it once that machine's login shell can find its command. An alias doesn't count.
| Agent | Command chaar looks for | How to install |
|---|---|---|
| Claude Code | claude-agent-acp or claude-code-acp | Claude Code's adapter for chat apps, claude-agent-acp: follow its install steps. Having claude installed isn't enough. |
| opencode | opencode | opencode.ai |
To check, run command -v claude-agent-acp or command -v opencode in a terminal on that machine. It should print a path.
After you install one, reopen the session on the phone, or quit and reopen the desktop app. When the machine has neither, Agents says None installed. If yours doesn't show up, see Your agent isn't listed.
On a machine shared with you, you need Can run to start an agent: see Share with others.
Start a chat
A chat is a tab in a session, and the agent works inside one folder you pick, usually a project. A new session is empty until you pick its first tab:
Choose the agent
In an empty session, click the Agents card and pick the agent. In a session that already has tabs, press ⌥⌘T for New agent chat. A folder dialog opens on your home folder, with your Recent folders first.
Pick a folder
Type in Filter folders, search chats to narrow the list, then choose New chat in followed by the folder's name. The chat opens as a new tab.
Open a new chat
In an empty session, tap your agent under Agents. In a session that already has tabs, tap + at the end of the tab bar, then Agent chat. You pick the agent on the next screen.
Pick the agent and folder
The rounded button at the top shows the agent. Tap it to switch. Then tap a folder under Recent, or browse to one.
Tap Start
Tap Start Claude Code in or Start opencode in at the bottom. The chat opens as a new tab.
Talk to it
Type in the box that says Ask anything, / for commands, @ for files.
/lists the agent's own commands.@finds a file in the chat's folder to point the agent at.- Files and photos. On the desktop, the + button sends files. On the phone, the photo button sends a photo. They're uploaded to the machine.
- Settings. The row below the box holds the agent's settings, such as its mode and model. The rest are under More settings (⋯). A new chat starts with the settings you last picked for that agent on that machine.
- While it works, a message you send waits its turn, and the send button becomes a stop button.
Approve what it asks
When the agent needs your OK, for example to run a command, the chat shows a card headed Needs your OK. It says what the agent wants to do, shows any file changes, and offers the agent's choices as buttons. The agent waits until you pick one.
While it waits, the tab shows , and the request appears in Needs you, the inbox of things waiting on you. Your computer and phone notify you too. See Get notified. To answer from the keyboard on your computer, see Keyboard shortcuts.
See what it changed
Click the activity button on the tab's header, or pick Show activity in the command palette. A panel opens beside the chat with Plan, Changes, Commands and Context: the agent's plan, changed files, commands run and how full its context is.
When the chat's folder is in a git repository, the Changes button on the tab's header opens the uncommitted files and their diffs.
Each edit shows in the chat as a card. Once a file has changed, a changes button at the top opens the changed files one at a time.
Pick up an earlier chat
- A chat chaar still has. The folder dialog lists this agent's chats in that folder whose tabs you haven't closed, such as one that ended when the machine restarted. Typing searches them by title. Choose one and click Continue chat.
- A conversation from the agent's own history. When the agent can list its past conversations in the chat's folder, a new chat offers Continue an earlier chat. Later, use the Earlier chats button.
When the agent can list its past conversations in the chat's folder, a new chat offers Earlier chats here. Later, use the history button.
Closing a chat tab stops its agent and deletes the chat from chaar, so it leaves the folder dialog. For when a chat stops answering or is gone, see Troubleshooting.
Run an agent's own program in a terminal tab
You can also start an agent's own command-line program in a terminal tab, for example claude, and answer it by typing, on any device.
The tab gets a status mark only if the program reports its status. Otherwise nothing tells you when it waits for you. See Show status from your scripts.
The chaar command can't show agent chats, only their marks, Needs you entries and notifications. See Use chaar in a terminal.
Stuck? Ask in the Discord community.