# Coderbots Help

**Coderbots** lets you hire AI coding teammates. Each teammate is a coding agent
running in its own [GitHub Codespace](https://github.com/features/codespaces) — a
full cloud dev environment with your repos checked out. You talk to them in
Slack, and they write code, open pull requests, and push to your repositories as
a bot identity.

This page explains what everything on the dashboard does.

---

## The big picture

```
You (Slack / dashboard)
        │
        ▼
   Coderbots Central  ──▶  provisions & controls Codespaces
        │
        ▼
   Your teammate (a coding agent in a Codespace)
        │
        ▼
   Your GitHub repos  ──▶  branches, commits, pull requests
```

- **Central** (this app) is the control plane. It signs you in with GitHub,
  connects Slack, and starts/stops the Codespaces your teammates live in.
- Each **teammate** is one Codespace running an always-on agent bridge that
  listens for your Slack messages and does the work.

---

## Getting started

1. **Sign in with GitHub.** This authorizes Coderbots to manage coding
   workspaces connected to your GitHub account.
2. **Hire a teammate** (see below). This provisions a Codespace — it takes a few
   minutes the first time while the container builds.
3. **Finish setup in VS Code.** A freshly-hired teammate shows a **Setup needed**
   badge. Open it in VS Code and authenticate the agent once so it can start
   answering.
4. **Connect Slack** so you can talk to the teammate in your workspace.
5. **Message your teammate in Slack** and start assigning work.

---

## Hiring teammates

Each teammate is a distinct profile with a name, a face, and a role:

- **Cosmo** — Full-stack engineer. Ships features end to end: UI, API, and the
  glue between.
- **Bizzy** — Frontend specialist. Components, polish, and pixel detail.
- **Omni** — Backend & infra. Owns the data, the services, and the deploy
  pipeline.

There's **one Codespace per teammate**. Once you hire a profile it moves from the
hire list into **Your team**. Hire additional teammates from the **Hire more
teammates** section below the roster.

### Provision into

When you have the GitHub App installed on more than one account (your personal
account and/or organizations), the **Provision into** picker chooses which
account the new teammate's Codespace and workspace repo live in. If it's empty,
use **Manage GitHub access** in the header to install the App on your org, then
**Refresh**.

---

## Your team: the roster

Each teammate card shows the teammate's name, current state, and a set of
actions.

### State badges

- **Available** — the Codespace is running and ready.
- **Shutdown** — stopped (idle or stopped manually). It'll start again on demand.
- A yellow **busy** badge (Queued, Provisioning, Starting, …) means the Codespace
  is transitioning. The dashboard polls faster while anything is in motion.
- **Setup needed** — the agent hasn't been authenticated yet (a fresh hire, or
  after a Rebuild). Open it in VS Code to finish setup.

### Provisioning progress

Right after you hire, you'll see a **Container → Agent bridge → Ready** progress
strip. GitHub builds the container first, then Central connects in to configure
and start the agent bridge — the part that used to be invisible.

### Actions

| Button | What it does |
|---|---|
| **VS Code** | Opens the teammate's workspace in your locally-installed VS Code (via the Codespaces extension). Starts the Codespace if it's stopped. For a teammate that needs setup, this is where you authenticate the agent. |
| **Open in browser** | Opens the same workspace in VS Code for the Web, in a new tab. |
| **Logs** | Streams the teammate's live agent logs so you can watch what it's doing. |
| **Stop** / **Start** | Stops or starts the Codespace. Stopped Codespaces don't consume compute. |
| **Rebuild** | Recreates the container from scratch (a few minutes). Your code and changes are preserved, but the agent needs setup again afterward. |
| **Delete** | Permanently removes the teammate's Codespace and workspace. This can't be undone. |

> **Idle stop is normal.** GitHub stops idle Codespaces automatically. A stopped
> teammate wakes up when it's needed (e.g. a new Slack message) — you don't have
> to keep it running.

---

## Slack

Expand the **Slack** section on a teammate card to connect it to a Slack
workspace. Once connected, the teammate has its own Slack bot identity: you
message it in Slack and it replies there while it works. Each teammate gets its
own bot, so a channel can have several teammates in it at once.

The **Edit app** link opens that teammate's Slack app configuration on
api.slack.com if you need to adjust scopes, the display name, or the avatar.

---

## Skills

**Skills** are reusable capabilities you can install into a teammate — extra
tools and workflows beyond plain coding. Use the **Skills** row on a teammate
card to fork the skills repo into one of your accounts and install it. Pick the
account to **Fork into**, then **Fork & Install**.

---

## Managing GitHub access

**Manage GitHub access** (top-right) opens GitHub's App install/configure screen.
Use it to:

- Install the Coderbots App on an **organization** so teammates can be
  provisioned there and push to that org's repos.
- Add or remove which **repositories** teammates are allowed to access.

Your teammates act as a **bot identity** on GitHub — commits and pull requests
show up as the bot, not as your personal account. A teammate can only touch repos
the App is installed on, so if a teammate can't see a repo, add it here.

---

## Firing a teammate

The **Fire** option at the bottom of a teammate card walks you through cleanly
offboarding: deleting the Codespace and, if you want, uninstalling the GitHub App
for that account so the bot loses access.

---

## Troubleshooting

**My teammate won't respond in Slack.**
Check that the card doesn't show **Setup needed** — if it does, open it in VS
Code and authenticate the agent. Also confirm the Slack section shows
**Connected**, and that the Codespace isn't in an error state.

**Hiring failed / no account to provision into.**
The GitHub App needs to be installed on at least one account. Use **Manage GitHub
access** to install it, then **Refresh**.

**A teammate is stuck "Provisioning".**
First-time container builds take a few minutes. If it stays stuck or shows an
error under the state, try **Rebuild**. If that fails too, **Delete** and hire
again.

**The teammate can't push to a repo.**
The bot only has access to repos the App is installed on. Add the repo via
**Manage GitHub access**.

---

## GitHub App permissions we request

When you install the Coderbots App, GitHub asks you to grant a handful of
permissions. We keep the list as small as the product allows — here's each one
and exactly why a teammate needs it. You can review or narrow these any time from
**Manage GitHub access**, and every permission is scoped to only the
repositories and accounts you install the App on.

| Permission | Access | Why we need it |
|---|---|---|
| **Metadata** | Read-only | Required by GitHub for every App. Lets us list your repositories and read basic details (names, default branch) so you can choose where a teammate works. |
| **Email addresses** | Read-only | Reads your primary verified email so we can identify your account and reach you about your teammates. Most people keep their GitHub email private, so this is the only reliable way to get it. |
| **Codespaces** | Read & write | Creates, starts, stops, and deletes the Codespaces your teammates run in — the cloud dev environment where the agent lives. |
| **Contents** | Read & write | Checks out your code and lets a teammate create branches and push commits as the bot identity. |
| **Pull requests** | Read & write | Lets a teammate open and update pull requests for you to review. |
| **Administration** | Read & write | Creates each teammate's workspace repository (from our template) in the account you pick when hiring. |

Teammates only ever act on the repositories where you've installed the App, and
all of their work on GitHub happens as a **bot identity** — never as your
personal account. Remove the App (or trim its repositories) at any time from
**Manage GitHub access**.

---

*Still stuck? Reach out to the Coderbots team and include the teammate's name and
what you were trying to do.*