# Start guide

> Set up your first project, write your first ticket and watch an agent take it from a plan to a merged pull request.

This guide takes you from a new By Dawn account to your first finished ticket. You'll create a project, connect the repo
your code lives in, give an agent somewhere to run, then write a ticket and follow the agent as it plans the work,
builds it and opens a pull request for you to review. It takes about fifteen minutes, most of it the agent's.

If you haven't signed in yet, start with [Sign in](https://docs.bydawn.com/sign-in/). For the words By Dawn uses, see [Concepts](https://docs.bydawn.com/concepts/).

## How it works

In By Dawn, you describe the work and an agent does it. Each ticket runs as a **mission**: the agent plans first and
asks you to approve the plan, then builds it in its own copy of your repo, then opens a pull request. It stops to ask
whenever a step needs a person, and you answer from the ticket or your [Inbox](https://docs.bydawn.com/inbox/).

## 1. Set up your workspace

The first time you open By Dawn, **Set up your workspace** walks you through these steps. Choose **Let's set it up**. If
you skipped it, reopen it from the account menu (your initials, at the top right) with **Setup guide**.

The setup guide is for whoever creates the organization, or its admins. If you were invited, your team has done this
already: go to [Write your first ticket](#3-write-your-first-ticket).

1. **Create your first project.** A project is one board of work. Give it a **Project name** and, if you like, a
   **Description**. Choose **Coding project** if its tickets change code, which is what this guide covers. Then
   choose **Create project**.

   By Dawn gives the project a short prefix for its tickets' IDs, such as `SAW` in `SAW-123`.

2. **Add repositories.** Agents work in your repos, so a coding project needs at least one. Choose where your code
   is hosted: **GitHub**, **Azure DevOps** or **Other git host**, then pick the repos this project's tickets touch.
   Connecting GitHub installs By Dawn's GitHub app, which only an owner of your GitHub organization can do. If that isn't
   you, By Dawn gives you a link to send to one. Starting from nothing? Choose
   **Starting fresh — no repo yet**, and By Dawn can create one on GitHub for you.

3. **How you work.** The defaults are fine to start with. **Plan in cycles** turns on time-boxed cycles, which you
   can change later in **Settings › This project**. **How tickets start** picks how a ticket's mission
   starts, and you can still choose differently on each ticket.

4. **Agents: where tickets run.** An agent needs a computer to run on. See the next section.

5. **Invite your team**, by email, if you want company. You can do it later too.

6. **Create your first ticket** (in the desktop app, **Queue your first ticket**), or skip it and follow step 3
   below.

After the guide, a **Getting started** list in the sidebar tracks what's left: **Add a repo**, **Pair a machine**,
**Start a first mission**, **Turn on cycles** and **Invite a teammate**.

## 2. Give agents somewhere to run

Agents run Claude Code, on a computer you choose, with that computer's Claude sign-in. By Dawn never holds your Claude
sign-in itself.

- **In the desktop app**, there's nothing to set up: tickets run on your computer, each in its own copy of the repo.
  The computer needs Claude Code signed in. See [Download By Dawn](https://docs.bydawn.com/download/).
- **In the web app**, pair a machine: your laptop, a workstation or a server. Choose **Pair a machine** in the guide,
  or **Pair a machine** in **Getting started** and then **Add remote agent**, and follow the steps in
  [Pair a machine](https://docs.bydawn.com/remote-agents/#pair-a-machine). The last step signs the
  machine in to Claude.

Until a machine is online, tickets wait in line. Nothing is lost.

## 3. Write your first ticket

On the board, type into **What do you want to build?** at the bottom and press `↵`. A sentence is enough
to start. `⌘N` jumps there from anywhere (`⌘⌥N` in the web app), and a column's **+**
does the same for that column. For more room, choose **Advanced ›**, which opens the full composer:

- the title, and a description: acceptance criteria, links and anything the agent should know
- **Status**, **Priority**, **Epic**, **Cycle**, **Labels**, **Estimate** and **Assignee**

Then choose **Create ticket**, or press `⌘↵`. The ticket lands in the first column, usually **Backlog**,
or in the column whose **+** you chose.

A ticket goes to the current project, and to its repo if it has only one. With several repos, the agent works out
which ones the ticket needs.

## 4. Start the agent

Open the ticket. Before it starts, the ticket shows how its mission will run. Choose how it starts:

| Choice | The agent |
| --- | --- |
| **Plan + build** | writes a plan, asks you to approve it, then builds it. The first default; after that, By Dawn starts on the one you used last |
| **Plan first** | writes a plan and stops, so you start the build yourself |
| **Build now** | builds straight away, without a plan to approve |

Below that, a preset decides how thorough the mission is (**Auto**, **Quick**, **Standard** or **Thorough**), and the
line under the start button says how many steps it will run and how many will wait for you. Then choose the start
button: **Start plan + build**, **Start planning** or **Start building**.

The card moves to the building column (**Building** or **Running**, depending on your board), and the ticket's
**Feed** shows the agent at work. The other tabs let you watch it in more detail: **Terminal**, **Browser**, **Code** and **Changes**.
You can also drag a card onto the building column to start it.

See [Start a ticket](https://docs.bydawn.com/start-a-ticket/) for every choice on the way, and [Missions and templates](https://docs.bydawn.com/missions/) for what a
mission is made of.

## 5. Approve the plan

When the plan is ready, the ticket shows **Approve the plan** and the [Inbox](https://docs.bydawn.com/inbox/) shows **Review plan**. Read the
plan on the ticket, then:

- **Approve plan** to let the agent build it,
- **Request changes** to say what should change and **Send back**, or
- **Reject** to stop.

If the agent has a question on the way, the feed shows it marked **Needs you**. Choose **Answer** to reply. See
[Checkpoints and debriefs](https://docs.bydawn.com/mission-checkpoints/) for every kind of stop.

## 6. Review the pull request

When the agent finishes, it opens a pull request and the card moves to **Review**. Open the **Changes** tab to read
the code. The pull request's header has **Comment**, where you can also approve, and, for org admins, **Merge**. You
can also review on GitHub as usual. See [Pull requests](https://docs.bydawn.com/pull-requests/).

Once the pull request is merged, By Dawn moves the card to the done column. That's your first ticket finished.

## FAQ

**Do I need the desktop app?**

No. In the web app, a paired machine runs your agents. The desktop app lets your own computer run them too, without
pairing. See [Download By Dawn](https://docs.bydawn.com/download/).

**My ticket won't start. Why?**

Usually because no machine is online. The card says **No machine online to run this** or **Waiting for your machine —
it is offline**. The ticket waits in line and starts on its own as soon as a machine comes online, so turn the machine
on, or pair one.

**Can I use By Dawn for work that isn't code?**

Yes. Choose **Not a coding project** when you create the project. It gets a board for research, docs, planning or
design, with no repos.

**Does every ticket need a plan?**

No. **Build now** skips it. Plans pay off on bigger tickets, where it's cheaper to fix the approach before the code
is written.

## Next

- [Concepts](https://docs.bydawn.com/concepts/): projects, tickets, missions and agents, and how they fit together.
- [Inbox](https://docs.bydawn.com/inbox/): where the agent asks for you.
- [Keyboard shortcuts](https://docs.bydawn.com/keyboard-shortcuts/): get around faster.

Source: https://docs.bydawn.com/start/