Skip to documentation
Updated Read as Markdown

Quickstart

On this page

AI agents: read the complete documentation index. Append .md to any docs URL for its Markdown version.

Go from a new Chief account to your first finished milestone. Chief plans and reviews the work; an agent runs it through the relay on your computer. Start with a small code task so you can see the full loop.

Before you start

  • A Chief account: sign up or sign in. If sign-up asks for an invite code, use the code supplied with your invitation.
  • A Mac, Linux computer, or Windows computer where you can leave the relay running.
  • At least one CLI agent installed and signed in on that computer. In Chief, open Tutorial and follow Install at least one CLI agent. The agent must be ready before Chief can plan or execute work; your provider's subscription or API billing still applies.
  • An existing project folder, or a full path where Chief can create a new one. The path must be on the computer running the relay, even if you use Chief from your phone.

1. Install and start the relay

Open a terminal on the computer where your projects and agents will run. Use the command for your operating system.

macOS or Linux

curl -fsSL https://cdn.chiefisnext.com/relay/install | bash && export PATH="$HOME/.local/bin:$PATH"
chief-relay

Windows PowerShell

irm https://cdn.chiefisnext.com/relay/install.ps1 | iex
chief-relay

The installer downloads the native chief-relay binary. Keep the terminal and relay running while Chief is working. On subsequent sessions, start it again with chief-relay; you do not need to reinstall it.

Expected result: the relay starts and opens a browser to authorize this computer. If the browser does not open, copy the verification URL printed in the terminal into your browser.

2. Pair the relay with your account

  1. Sign in to the Chief account you want this computer connected to.
  2. On the authorization page, compare the device code with the one shown in your terminal.
  3. Select Approve Device.
  4. Return to Chief and wait for Relay Connected in the upper-left corner of the sidebar.
  5. Open Tutorial and check that at least one CLI agent is installed and signed in. Follow its setup guidance if it is not ready. Choose a ready provider for Chief and Agents in your project.

Expected result: Chief shows Relay Connected and a ready agent. The relay connects Chief to the CLI agents on this computer; it does not require uploading your repository to create a project.

3. Create a project

  1. In Chief's sidebar, select Add project. On a narrow screen, open Projects first.
  2. Enter a Project name, such as My first Chief project.
  3. Choose Chief's role for the work you want help with. Keep the default for this coding walkthrough.
  4. Set Local path to the full path of an existing folder, such as /Users/you/code/my-app on macOS, /home/you/code/my-app on Linux, or C:\Users\you\code\my-app on Windows. You can also enter a new folder path to start from scratch. Replace the example with your actual path.
  5. Select Add project and let Chief assess the project. Chief may ask questions to understand what you want to achieve.

Expected result: the project opens with its chat and Tasks panel. Answer any setup questions and describe one clear goal.

4. Ask for a small first milestone

Send a concrete request in the project chat. For an existing code project, try:

Propose one small milestone to improve this project's README:
add clear local setup instructions using the commands this project already uses.
Done means the instructions match the repo and any relevant checks pass.
Keep the change limited to documentation.

Chief proposes milestones toward your goal. A milestone is a unit of work with an objective and a definition of done; the UI also calls these tasks. Check the Tasks panel for a Proposed card. If Chief asks a question first, answer it in chat.

Expected result: a proposed task describes the README improvement. Review its title and summary and open Details, when present, to read its definition of done. Use Revise to request a change or No to decline a proposal.

5. Approve and watch the milestone

  1. Check that the proposal matches the change you want and that its selected provider is ready.
  2. Select Go on the proposed task card to approve it and start the agent. A proposal waiting on dependencies may show Queue instead. For this first run, choose a small independent task. Approve all approves multiple proposals, so use the individual card for this walkthrough.
  3. Stay in Tasks to follow the running task's status. Expand its card for details and use View log when available to read the agent's output.
  4. Keep the relay running and the computer awake while the agent works. You can keep watching Chief from another device.
  5. When the agent finishes, Chief reviews the result. Open History to read the completed task and its summary; inspect the changed files in your project folder as well.

Expected result: the milestone reaches Done, its result explains what changed, and the README contains the requested setup instructions. A blocked or failed run needs attention before it can finish; follow the guidance below.

Troubleshooting

The relay is offline

Start chief-relay on the paired computer and keep its terminal open. Check your network connection. Tutorial shows the last-seen device and restart guidance when a paired relay is offline. If the authorization code expired before approval, restart the relay to begin authorization again.

The command is not found

On macOS or Linux, run export PATH="$HOME/.local/bin:$PATH" in the terminal where you start the relay. On Windows, open a new PowerShell window after installation and run chief-relay again. If installation failed, read its terminal error and resolve it before retrying.

No agent is ready, or a provider check times out

Open Tutorial, install a supported CLI agent and complete its sign-in steps on the relay computer. Start the relay again if it was running before installation. If a health check times out, retry the check and follow its guidance; a timeout alone does not mean your credentials expired.

The project path cannot be checked

Confirm the path is absolute and belongs to the relay computer. Start the relay, verify its permissions for that folder, and select Retry path check in the project form. A path on your phone or another computer will not identify the relay's local project.

The milestone is blocked, failed, or waiting on you

Read the task details and log. Check You for manager tasks: Chief may need a decision, credential or review. Resolve the specific request in Chief before continuing. For a failed task, fix the reported cause and use Retry when offered. A dependency must finish before dependent work can run.

You reached a usage limit

Follow the limit message in Chief. Review Pricing for Chief's plan limits, and check your agent provider's usage separately. Resume once capacity is available.

Next steps

Learn how goals guide milestones and their definitions of done. Check manager tasks when Chief needs your input. Use Activity to follow project events and Summaries to catch up on progress.

Choose or switch agents, enable auto mode for bounded automatic approvals, or ask for scheduled work. To work from an assistant or Discord, see public integrations. If setup or a run fails, follow Troubleshooting.