ACE/Docs/Introduction

The ACE guide

Turn an idea into work you can review and use.

ACE brings AI agents, conversations and project work into one desktop app. Describe what you want, shape it with your team, and follow the work through planning, building and review.

Updated . This guide covers production ACE and the latest ACE Dev previews. Preview notes identify features still awaiting production release.

Meet ACE

Who ACE is for

ACE is for creators building their first app, founders testing an idea, and developers who want help implementing and reviewing software. You give the work a goal, provide useful context and decide what a successful result looks like.

You can start with a conversation, give a single agent a focused assignment, or coordinate a team with different roles. Projects keep the conversations, files, tasks and review history together.

The latest ACE Dev also brings email drafts and documents onto the same Tasks board. Each task has a clear finish line, from an accepted document to a confirmed GitHub merge.

Getting started

Install ACE and connect an AI account

  1. Get the macOS or Windows installer from the download page, install ACE and open it.
  2. Sign in with your ACE account and complete any access steps shown in the app.
  3. Open Settings > Connected Tools. Follow the setup guide for the AI provider you want to use. It checks the required tool and account connection.
  4. Return to Home and choose an available model in the Assistant composer. Check the account and funding source shown with it.
  5. Describe a new project, open a saved project, or use New project for guided setup.
Your ACE account and your AI account
ACE access and AI usage are separate. A supported provider connection may use your subscription allowance, API billing or a local model. Connecting GitHub is a separate step when you want to import repositories or deliver changes there.

A practical walkthrough

Complete your first task

Start with one small result you can inspect. For an existing app, try: “Add a search field to the customer list. Match names, show a useful empty state, and check it at a narrow window width.”

  1. Open the project and choose Tasks > New task. Write the assignment and say how you will check it.
  2. Choose the project team or an enabled agent. Use the planning, implementation and review workflow when you want help through each stage. Check the timing and automatic progression before creating it.
  3. Open the card to follow activity, read the plan and inspect recorded checks. If it waits in Inbox, use Start. Answer any request for information or approval.
  4. For coding work, open its Build conversation and Changes. Inspect the diff and run the app preview where available. Ask for changes if the result misses your brief.
  5. Review the final outcome. Use Apply changes when you want to integrate reviewed work locally, or the GitHub delivery action when you intend to merge. Confirm the destination and read the resulting status.
Make the finish line explicit
“Pass review,” “apply the changes locally,” and “merge into GitHub” describe different outcomes. In ACE Dev, New task lets you choose a finish line directly. Review the checks and the result before treating the work as complete.

Start with a conversation

Home and Ace Assistant

Home combines Ace Assistant with your saved projects. Choose New Project or an existing project beside the composer, choose a connected model, and describe the work in your own words.

For example: “Set up a team to build a simple booking app. Have one agent plan it and another review the implementation.” Ace can propose the team, model choices, workflow connections and run limits.

Open Review team, models and limits to inspect the proposal. Tell Ace what to change, then use the confirmation tick when the setup is right. Confirmation applies the saved plan and opens its canvas. A saved setup, a started run and a saved schedule each have their own status.

The microphone turns speech into an editable draft. Check the text before sending. You can reopen Ace Assistant inside a project to inspect or adjust its setup.

ACE Dev preview
ACE Dev can also set up an existing GitHub project from a repository URL supplied to the Assistant. Review the repository and proposed team before confirming the import.

Keep work together

Projects and workspaces

A project holds your team, conversations, Tasks board and files. Use guided setup to start a new project, open an existing local repository, or choose a repository from your connected GitHub account.

Tasks, Ideate and Build are three views of the same project. Build conversations have their own execution workspace and branch, so you can inspect an assignment’s changes before applying them to the source project.

ACE Dev preview
In ACE Dev, opening a project takes you to Tasks. The left project rail keeps Tasks, Ideate, Build, Ace Assistant, preview, GitHub, appearance and Settings together. Earlier production releases use the Ideate / Build / Tasks control in the header.

Your source files remain in normal local Git repositories. Opening another conversation or seeing a task reach Review does not automatically merge its branch into your project.

Follow the work

The Tasks board

Use Tasks to see what is waiting, running, ready for review and finished. Open any card for its assignment, worker, activity, notes and evidence. Search, labels and Needs attention help you find the work that needs a decision.

ACE Dev preview
ACE Dev uses the stage names Plan and Work and adds App, Email and Document task types. Production releases may still show Ideate and Build as the stage names and offer coding tasks without the type selector.
Inbox
Capture work before starting it. Scheduled tasks and accepted suggestions wait here until they are ready to run.
Plan
Clarify the assignment, constraints and checks. Earlier releases call this stage Ideate.
Work
The assigned agent produces the result. Coding work runs in its own Build workspace. Earlier releases call this stage Build.
Review
Inspect the result and its checks, request changes, or take the final action.
Done
The task reached its finish line. Read the outcome on the card to see whether work was reviewed, applied, accepted, sent or merged.
App
Produces changes in a Build workspace. Its finish line can be code review, verified local application or a confirmed GitHub merge.
Email
Produces a draft with recipients, subject and message. Review and edit it, ask for changes, then accept the draft or send through the connected Gmail account, depending on its finish line.
Document
Produces a Markdown document. Review or edit it, then accept it into the selected project folder. Acceptance does not overwrite an existing file.

In ACE Dev, New task proposes the type, destination and final step from your prompt. Adjust them before starting, or set defaults for each type. You can change an inactive task’s stage, but moving a card to Done is not a substitute for reaching its finish line.

Pause prevents future automatic stages while an active run finishes. Use Stop run to stop active work. Close without verification records a closure; it does not certify a successful result.

Think with your team

Ideate

Use Ideate to explore a problem, compare options and agree on a brief with your agents. The canvas shows the team and its workflow; the chat keeps the conversation together. Switch between full chat and the canvas with the layout control.

Give the team references, constraints and a definition of done. For a booking app, that might include who can book, what happens when a slot is full, and how you will check the result.

Open a message’s thread to follow its work or reply without losing your place in the main conversation. The Activity panel shows actual project activity. Generated images can appear in the completed answer and Generated Assets.

Team memory keeps useful shared notes for the board. Open it to confirm, correct or forget a note, or change how new notes are saved. Automatically saved notes are labelled unverified.

When the brief is ready, choose Send to Build on the message. Review the assignment and agent before sending. The linked Build chat keeps the source context, and its results can return to Ideate for review and follow-up.

Implement and inspect

Build and review

Each Build chat has one assigned agent and its own coding workspace. Choose New chat, write the assignment, then choose Start now or Add to queue. You can also arrive here from a Tasks card or an Ideate handoff.

  1. Follow the conversation and open its work details when you need to inspect commands, files or an interruption.
  2. Open Changes to inspect the file list, diff, review state and next action. Use Preview to inspect the running app when available.
  3. Request review or continue the chat with a correction. A review of an earlier run does not approve later changes.
  4. Use the offered local integration or GitHub merge action after the required checks pass. Verify the named repository and branch before delivery.

Conflicts, failed checks and requested changes keep work in Review with an explanation. A GitHub delivery is complete when ACE records the confirmed merge. Locally applied changes and a passed review have their own outcomes.

Shape the team

Teams and workflows

The Ideate canvas lets you configure agent roles, model choices, reference documents and connections between workflow steps. Start with a clear lead and add a reviewer or specialist when the assignment needs one.

Document nodes add reference material. Connections describe how agents collaborate, review or hand work to one another. Configure loops and review conditions for work that needs several passes, then inspect the actual result and recorded checks.

Smart Actions connects a settled Ideate brief to Build. Manual, Assisted and Autopilot settings control handoff and follow-up behavior. Review the settings before enabling automatic transitions; automatic merge is a separate choice with its own destination and verification requirements.

A useful brief names the output, the boundaries, the checks and the final action. For example: “Build the booking form, verify the full-slot error, and leave the reviewed changes ready for me to apply.”

Choose how agents run

Models and connections

Open Settings > Connected Tools to install, connect or repair a provider. Use the ready models shown in the picker; availability depends on the provider, account and execution route.

Subscription allowance
A supported connected subscription can power eligible model runs. The provider’s allowance and account limits still apply.
API billing
A provider API connection or optional OpenRouter route uses its own billing or credits. Check the funding source shown with the model.
Local model
Supported local models use a service on your computer, such as Ollama. Keep the service running and select a model it has available.

Claude, Codex and Gemini have different setup and execution requirements. Additional providers appear where supported. A successful account login does not make every model or provider route executable; follow the readiness message in ACE.

Gemini uses Gemini CLI for supported API, Code Assist Standard and Enterprise, and Google Cloud connections, with OpenRouter where configured. Antigravity task execution remains unavailable because its CLI does not yet support safe per-run discovery isolation. Signing in alone does not enable it.

The Assistant has its own model selector. Project agents have their own model and role configuration. Check both when you change providers or accounts.

Give agents useful capabilities

Skills, plugins and bundles

Open the library from Agent Config to browse Skills, Plugins and Bundles. Skills supply instructions for a kind of work. Plugins connect tools and services. Bundles collect related skills and plugin connections.

  1. Choose a skill or review an imported bundle before installing it.
  2. Complete the connection steps for any plugin you need.
  3. Enable the relevant components for the agent in Agent Config.
  4. Give the agent an assignment that explains how the capability should be used, and inspect its result.

Installing a bundle does not finish its service connections or automatically enable every component for every agent. External services keep their own access requirements.

Repeat useful work

Schedules and automation

In New task, choose Once, now, a schedule, or the next verified completion of another task in the project. Check the timezone and next occurrence before saving. Task schedules run while ACE is open and skip occurrences missed while it is closed.

Automatic progression moves an eligible task through its configured stages. Project and task pause controls stop future stages; running work can finish. The project’s capacity setting limits simultaneous Build agents. A scheduled task waits while its previous run still needs resolution.

You can also ask Ace Assistant to schedule a team workflow. Review the saved schedule and its execution device. Assistant settings shows whether this desktop installation supports background runs. Background schedules still need an awake, online, signed-in device; follow the displayed execution status.

Automatic progress and final actions
In ACE Dev, automatic sending, document acceptance, local application or merging requires the task to allow that final step, automatic progression to be on, no task or project pause, and Full access at the time of the action. Otherwise the result waits in Review. Recipient, destination and verification checks still apply.

Bring requests into the board

Email intake

From the Inbox column menu, connect Gmail, search for a message, inspect its preview and import it as a task. Importing one email saves it to Inbox without starting an agent. The task retains the source account and message details; attachments are excluded.

ACE Dev preview
Automatic intake is available in ACE Dev. Enable it for a project, choose a Gmail search filter and describe the reports that belong there. Checks run while ACE is open. Review the recent decisions and any connection errors in Email intake.

In ACE Dev, you can separately enable automatic investigation of clear bug reports. Uncertain reports wait in Inbox. Delivery defaults to keeping the verified fix for review; opening or merging a pull request requires an explicit destination and delivery choice.

In ACE Dev, email tasks can prepare replies for review. If Gmail does not confirm a send or save, the task shows Check Gmail. Check the mailbox before marking it complete or trying again, so an uncertain delivery does not become a duplicate.

Find worthwhile next steps

Suggestions

ACE Dev preview
Suggestions and discovery are available in ACE Dev. Open Suggestions beside Inbox and give ACE a responsibility: what to watch, why it matters and what useful work would look like.

Software health looks at the project’s GitHub issues, checks and recorded verification. Sponsor enquiries looks at Gmail threads matching your search. Saving a responsibility does not scan anything; choose Scan now or explicitly enable Watch automatically.

Read each suggestion’s evidence, proposed action and completion criteria. Choose Add to Inbox, Later or Dismiss. Accepting a suggestion creates a task for you to start; it does not begin execution. Suggested tasks retain a review step for their final action.

Automatic watching runs while ACE is open and respects project pause. Use Pause watching to stop future scans or Cancel scan to stop the active one. A scan can finish without finding worthwhile work.

Choose how much to delegate

Approvals and control

ACE Dev preview
ACE Dev has one approval choice in Settings > General > Safety & permissions. Earlier production releases show the previous safety and permission controls.
Ask for approval
Agents work within the project’s bounded access and ask before broader access or external actions.
Approve for me
Supported Codex and Claude execution routes review actions automatically. An action can still need your approval; other providers explain their supported choices.
Full access
Allows filesystem, network and external actions without approval prompts. Explicit restrictions in your assignment still apply.

Open a pending request to read the action and its context before approving or denying it. Closing the notification does not settle the task’s decision. Review settings, workflow verification and the task’s final action continue to determine what happens next.

Understand the boundaries

Security and privacy

Projects, generated files and workspaces live on your computer. Cloud model runs send prompts and selected context to the connected provider. Plugins and delivery actions can send information to their connected services.

Keep credentials out of prompts and project files. Review provider and plugin access before including sensitive material, and inspect changes before applying or delivering them.

Secrets
Settings > Secrets stores named environment variables for agent runs and previews. On macOS, values use a Keychain-held encryption key when available; without a usable Keychain, ACE uses an owner-only plaintext vault. Agent context receives names, and eligible provider processes receive values as environment variables. ACE scrubs exact values from events and saved run output, but split values can briefly appear in live output and transformed values may evade scrubbing. Guarded runs exclude secrets, and local Ollama runs do not receive their names or values. Scope secrets to the work that needs them.

In ACE Dev, Settings > Feedback > Send error reports automatically controls automatic diagnostic reports. Review that setting when choosing what information to share with support.

Stay current

Updates and release channels

Open Settings > Updates to check content updates and desktop updates. Earlier Settings layouts call this area Control Plane. Read the update status and let active work finish before restarting when prompted.

Content updates
Update the interface and local server used by your installed app. Use Check for Content Updates, then follow the restart prompt when an update is ready.
Desktop updates
Update the installed application itself, including native integrations and the updater. Follow the download or install action shown in ACE.
ACE and ACE Dev
Production ACE receives the production release channel. ACE Dev receives the development channel. A preview feature can appear in ACE Dev before it is released to production.

Updating this website does not update your installed app. Check your app’s release channel and update status if a documented control is missing.

Get moving again

Troubleshooting

Start with the message on the affected task, connection or update. It tells you which part needs attention and often offers a recovery action.

A model is missing or cannot start
Open Settings > Connected Tools. Complete setup or reconnect the provider, then select an available model and retry. A provider account, subscription limit or API balance can prevent a run even when ACE is signed in.
Work is waiting for you
Open the task or its approval request and read the reason. Approve, deny or revise the assignment. If an approval has expired, return to the owning task for its recovery action.
A task failed
Open its details, inspect the error and recorded checks, fix the connection or project issue, then use Retry when offered. Keep using the existing task so its saved work and history stay together.
The result is still in Review
Check the requested finish line and outstanding checks. A finished conversation does not prove that changes were applied or a pull request merged. Use the available final action after review.
Email shows Check Gmail
In ACE Dev, an uncertain Gmail result pauses delivery. Check Gmail before choosing Mark as sent, Mark as saved, Send again or Save again. ACE does not automatically repeat an uncertain send.
A schedule did not run
Check its timezone and next occurrence, project and task pause controls, and whether this device was awake, online and running ACE. Task schedules skip occurrences missed while ACE is closed.
A repository will not open
Confirm the folder is a Git repository or that the connected GitHub account can access the repository. Check the displayed error for local permissions or clone failures.
The preview will not load
Open the run or terminal output and check for missing dependencies, a failed start command or an occupied port. A saved code change still needs a running app to preview.
Sign-in or access needs attention
Finish sign-in using the ACE account that owns your access. Retry the browser-to-app handoff, or restart sign-in if the link expired. An AI provider login is separate from your ACE account.
Your screen differs from this guide
Check Settings > Updates and the release notes. Features marked ACE Dev preview are ahead of the production app. Older Settings layouts may show these update controls under Control Plane.

If the issue continues, use Settings > Feedback. Include the action you took, what you expected, the visible error and whether you use ACE or ACE Dev. Remove credentials and unrelated private content from any details you provide.

Technical reference

How ACE runs

ACE is a desktop application with a local runtime. The desktop shell handles native integration and updates. The runtime serves the interface, manages workspaces, runs connected model tools and records task activity and verification.

Git-backed workspaces isolate coding assignments. Live events keep conversations and task status updated. Connected providers perform model execution, while plugins supply additional tools. Hosted account and access services handle sign-in and ACE access separately.

Development and production runtime releases are separate from deployment of the hosted website. Your installed app receives updates from its own release channel.