gratefulagents

Agent runs

Start a run

A run is one agent session. Start a run from Home or from a project. Automations such as GitHub, Linear, Cron, and Slack can also create runs from their configured sources.

Start from Home

  1. Go to Home.
  2. Enter the task in the composer.
  3. Choose a project if the project picker is available.
  4. Optional: select Options and enter a model override.
  5. Press Enter or select Start.

If no project is selected, Home uses your personal project (shown in the app as “Personal workspace”) when one is available. When Home creates or finds that personal project, it also ensures a Grateful Agents project exists beside it. That project opens the public platform and SDK repositories in a read-only issue-intake mode, so you can describe a product bug or feature request and have the agent file it in the correct repository. It does not implement changes or open pull requests.

Example tasks:

Investigate why checkout totals are sometimes rounded incorrectly. Explain the likely cause before editing.
Implement the settings UI from issue #142, run the affected tests, and prepare a PR.

Start from a project

  1. Go to Projects.
  2. Open a project.
  3. Type the request in the composer at the top of Overview (the New run button in the header focuses it).
  4. Press Enter or select Start.

The composer is the same one as on Home, pinned to the project. To change something for this run only, open the sliders Options button. It shows a receipt of what the run will use — Model (with the project’s default named), Repository and branch, Runtime, Overseer, and Advanced (credential Secrets, namespace) — and you expand a row only to override it. The button shows how many overrides are active; Reset all clears them. Overrides never change the project or future runs.

Choose an effective mode

The project or its source selects the run’s initial mode. Modes are configurable workspace templates, so the displayed name and behavior can differ between projects. Do not infer write access, network access, tool access, or a particular execution style from a mode name alone.

After the run starts, use the session’s / command menu to see the mode transitions that are available to that run. A requested transition can be denied. See Interactive, plan, autopilot, stop, retry.

What happens next

The app opens the run session after creation. Until the agent produces its first output, the session shows a Starting up checklist with the elapsed time and the current startup stage: Run queued, Starting sandbox, Preparing workspace, then Agent is working. Once the composer is enabled, you can message the agent and review activity in the session tabs.