Getting started

Grace gives your AI agent the instructions chosen for your project. An expert instruction is called a talent: for example, knowing how to write a test or follow your application's architecture.

By the end of this guide, your AI agent will be able to consult these talents before working.

1. Find your project

Sign in to Grace using the method specified by your team. From the home page, open the project you want to work on. Check its name before continuing.

On the sign-in page, choose your language from the flag dropdown next to the theme control. Once signed in, you can change it in your profile settings; your choice is saved to your account for future visits and new notifications.

Which path should you follow?

This diagram summarizes the path through Grace; it is not a screenshot.

flowchart TD
  login["1. Sign in"] -->|"Choose your space"| org["2. Your organization"]
  org -->|"Open your project"| project["3. Your project"]
  classDef step fill:#efecfe,stroke:#5948dc,color:#14151c
  class login,org,project step

• Step in the workflow
• Action to move to the next step

You have succeeded when your project is open in the correct organization.

I cannot find my project, or my organization is awaiting approval

Check with an administrator on your team that you joined the right organization. If it is awaiting approval, follow the instructions on the waiting screen: reconnecting your AI agent will not grant this access.

2. Check the active talents

In your project, the Grace preparation banner immediately shows the number of active talents and blocking dependencies. Your team chooses what the AI agent needs to know; you do not need to install everything.

A talent may need another talent to work: this is a dependency. If Grace reports a missing one, select its row to see which talent needs it and whether it exists in the catalog. Use Install [number] dependencies when Grace offers the grouped action. If the dependency is absent from the catalog, open the affected talent and work with the person configuring your project to fix its reference.

You can continue when the required talents are active and any reported dependencies have been addressed.

There are no talents yet

Ask the person configuring your project to choose suitable talents. Grace also offers an AI-agent workflow to analyze the repository; it requires human approval before installing the proposed selection.

To understand the available choices, see talents.

3. Connect your AI agent

Open the project's connection guide in Grace.

1. Under AI agent, choose your tool, then select your Operating system.
2. After making both choices, copy Connect in one command at the root of the repository. Grace provides a sh command for macOS and Linux, or PowerShell for Windows. It also prepares review profiles for Claude Code and Codex. The manual steps remain visible directly below so you can check or prepare each file separately.
3. Follow the Authenticate and verify Grace step for your AI agent. It gives you the terminal command or interface action, then the check that proves the Grace tools are available.

MCP is how your AI agent communicates with Grace.

For other tools, use the file name shown after you make your selection.

The automatic command writes only to the current project. Because Windsurf offers only global MCP configuration, Grace does not install it automatically and retains the manual steps.

You have succeeded when your AI agent shows Grace as connected and makes its tools available. The mere presence of the configuration file does not prove the connection works.

4. Complete a first task

Ask your AI agent for a small change whose expected result you know. For example, this sample prompt is in French:

Consulte les talents Grace adaptés, puis ajoute un test pour ce comportement. Explique ce que tu as vérifié.

What should the AI agent do?

The expected workflow connects preparation, work, and verification.

flowchart TD
  prepare["Consult relevant talents"] -->|"Apply instructions"| work["Make the change"]
  work -->|"Check the result"| check["Present evidence"]
  classDef step fill:#efecfe,stroke:#5948dc,color:#14151c
  class prepare,work,check step

• AI agent action
• Order of actions

This diagram shows the expected workflow, not a task that has already been completed.

You have succeeded when the AI agent has consulted the relevant talents and presents the results of its checks. Calling Grace alone does not prove the code is correct.

A talent can provide useful conventions without review rules. Grace flags this during preparation: the agent still applies those conventions, but does not request an unnecessary detailed review. The global plan is still consulted, even if this applies to every talent. If the rules have changed in the meantime, the updated plan takes precedence. Your organization's talent instructions must still be checked; no review rules does not mean compliance.

Which calls might I see in my AI agent?

grace_prepare_task provides the selected instructions and a resolutionId, the identifier for the prepared scope. grace_review then provides the review plan. The AI agent must apply it to its changes and run the requested checks: Grace does not automatically read its local code.

If you get stuck

Next: connect a project or understand MCP tools.