Using Ace.

01Open a project

A project is a folder with a Git repository. On first launch the window offers Open folder… ⌘O; press ⌘O or choose File → Open Folder… and pick your repo. Opening a folder adds a project. It doesn’t start a channel, and it doesn’t need a model key yet.

In a browser there’s no folder picker, so a dialog asks for a path such as ~/code/project.

02Initialize Git, if the folder needs it

Agents work in lanes, which are Git worktrees, so a folder without a commit shows Initialize Git. It runs git init, writes a .gitignore that leaves out secrets, dependencies and build output, and commits the rest. If the folder already has a .gitignore, Ace leaves the first commit to you.

A project you have on GitHub but haven’t checked out on this machine shows Set up on this Mac, which clones it and opens it.

03Start a channel

The Dashboard (⌘1) asks what you’d like to work on, with a project chip above and a composer below. Type a request and send it: Ace creates a channel in that project and hands your words to its agent. New channel makes an empty one. Pick back up lists the project’s channels with their summaries and your open pull requests and assigned issues, and Team pulse shows what teammates are working on. With cloud compute on, choose This Mac or Run in cloud before you send.

A new channel gets a random name. The agent renames it once it knows what the work is, and keeps a short summary up to date. Fork channel, from a channel’s menu, starts a sibling channel from its summary and lane.

04Ask the agent, and watch it work

A channel opens on its Chat tab. The composer has two modes. Ace asks the agent. Chat posts to the room without starting a run, unless you mention @ace. Press Esc to switch to Chat, and Esc twice to come back.

While the agent works, its tool calls collect into groups. A fast model captions each group as it runs, and the finished turn folds into a short recap. Stop response ends the run; the chat stays usable. A message sent while the agent is busy waits above the composer and steers the run. Stopping hands any queued messages back to their authors as drafts, and the timeline says who stopped the run. A failed run offers Try again, switching to Automatic when the model was the problem.

An agent can stop and ask the chat a question, with options to pick or a written answer; you can also skip it. Attach files by dropping or pasting them: images, text files and PDFs, which are sent as their text. Dictate into the composer with the microphone. You can edit or delete your own messages, and anyone can react to a message.

When a run finishes while Ace isn’t focused, macOS shows Agent finished or Agent run failed, and an @mention of you notifies you, including ones that arrived while you were away. In the channel, a line marks where unread messages start and mentions of you are highlighted.

05Choose a model, and add your keys

In Ace mode the composer has a model picker: Automatic, plus every model from the providers you’ve set up. Models that support it get an effort picker, from Minimal to Max. The choice applies to that run.

Keys live in your system keychain and never reach the app’s UI. Add them under Settings → Providers with Add key, then Check and save. Settings → General → Default model sets the model for a chat’s first run; new channels from the Dashboard start on your last pick. If a provider rejects a saved key, Settings says so. The usage indicator by the composer shows how full the context is, tokens and estimated cost.

06Work in tabs: Chat, Diff, Terminal

Each channel has a tab strip. + adds a Diff or a Terminal, and Split right and Split down put panes side by side. Drag tabs between panes; right-click one to rename or close it. When the agent first changes files, a Diff tab opens behind Chat.

The terminal is a real shell in the chat’s current lane, on the channel’s host, so a teammate’s channel doesn’t offer one. A multi-line paste asks first, since the shell would run each line.

07Review the diff

The Diff tab compares the chat’s current lane against its base, the branch the lane started from, and refreshes while it’s open. It’s exactly what a pull request into that base would contain. Switch between split and unified views, expand or collapse every file, and show or hide the file tree.

Each piece of work gets its own lane: an isolated worktree and branch the agent starts with its lane tool, so parallel work never shares a checkout. Lanes are made with lane, Luke Edwards’ copy-on-write worktrees, so a new one starts with its dependencies already in place.

08Land it as a pull request

Ask the agent to open a pull request. The details sidebar, from the toggle at the right of the header, shows the channel’s summary, its changes, the branch and its newest pull request with check status. It also lists subagents, links, the host, the model and what the channel has cost.

The Diff header offers the next Git step, carried out by asking the chat’s agent: Commit, Push, Rebase, Create PR, Update PR, Address review, Ready for review, Merge or Close PR. Failed checks show up in the chat, with an offer to fix them.

Issues (⌘3) and PRs (⌘4) list the project’s GitHub items, and only appear for a project with a GitHub repository. Open in a channel starts a channel whose agent picks up that issue or continues that pull request.

09Work with your team

Your tailnet is your team: everyone on it who runs Ace, with no accounts to create. The Channels sidebar (⌘2) lists your channels, then a section for each teammate across all their hosts. Open a teammate’s channel and it works like your own; its tab reads channel · host. You see teammates’ channels in projects you can access: GitHub projects your login can read, or ones shared with you. Share project…, in the Channels sidebar’s menu, shares one with the team or a person.

On your own channels, Agent access decides whether teammates can ask the agent, or only read along and post. It starts off for a new channel, and turning it on asks first: agents run on your machine with your permissions, so only let people you’d trust with the machine onto your tailnet. Channel desktop tools, in the same header, lets agents operate this Mac’s apps; it also starts off.

With a team directory, faces on each channel row and beside the project show who’s here; people without Ace focused are dimmed as away. The chat shows who’s typing, and @ suggests the channel’s members. A teammate’s run names who asked for it and whose Mac and key ran it. Agents can hand work to another channel on the same host, and the message shows which channel sent it.

A phone or another computer opens the web app and connects to your host by its tailnet address; Settings → Ace Helper shows it as a QR code.

11Archive when you’re done

Hover a channel and choose Archive channel, or right-click it to pin, rename, see its info or move it. Archive inactive on the Channels header archives this host’s channels with no activity for six hours; those fold into an Inactive group on their own. Pinned channels stay at the top in their own group.

Archived channels keep their whole history, and you can open and read them. To work in one again, choose Unarchive channel. To remove one for good, choose Delete channel on the archived row; ace backup keeps a copy first, and ace restore brings one back as a new channel.

12Settings and Ace Helper

Open settings with ⌘,. General has theme and default model; Providers has keys; Team creates, joins or leaves your team’s directory and lists its hosts; Beta turns on cloud compute. Under This Mac, Ace Helper shows the helper, Tailscale and tool checks, the QR code and installs the ace command; Computer use grants the permissions desktop tools need; Updates switches between Stable and Canary. In a browser, Ace Helper reads Host.

Ace Helper keeps hosting your channels after the window closes, so teammates can still reach them.

13Keyboard shortcuts

APP

COMPOSER

TABS