Connect GitHub
Sign In
Click Sign in with GitHub on the launch screen. This opens your browser to authorize the Quarterback GitHub App.
Permissions
Quarterback requests the following GitHub permissions:
- Read access to repository metadata and contents
- Read access to your profile (username, email)
Quarterback does not request write access to your repositories. All code changes are made locally on your machine through the desktop app.
Install the GitHub App
After signing in, install the Quarterback GitHub App on the GitHub accounts or organizations that contain the repos you want to work with.
When you install the app (or update its repo access), GitHub notifies Quarterback automatically. Your repos appear in the platform within seconds — no manual import needed.
Organization Access
If your repositories belong to a GitHub organization, the org owner may need to approve the Quarterback GitHub App before you can access those repos.
To check or request access:
- Go to GitHub Settings > Applications > Authorized GitHub Apps
- Find Quarterback in the list
- If org access is pending, click Request or ask your org admin to approve
Map Repos to Local Directories
Once your repos appear in Quarterback, you need to tell the desktop app where each repo lives on your machine. This mapping is how Athena knows where to read files, run commands, and make changes.
- Open Settings > Repos in the desktop app
- You’ll see a list of repos accessible to you in the current org
- Click Browse next to a repo
- Select the local directory where you have that repo cloned
Quarterback verifies the mapping by checking the directory’s git remotes. You’ll see one of three states:
| Status | Meaning |
|---|---|
| Verified (checkmark) | Path is set and git remote matches the repo |
| Mismatch (warning) | Path is set but git remote doesn’t match — double-check you selected the right directory |
| Not configured | No local path set yet |
The header shows a count like “3/5 configured” so you can see at a glance how many repos still need paths.
Local paths are stored on your machine only (~/.qb/repo-paths.json) and are never sent to the server.
Why Local Paths Matter
When you create a context, you select one or more repos. The first repo’s local path becomes the context’s working directory — that’s where Athena reads files, runs shell commands, and writes code.
If a repo doesn’t have a local path configured, you won’t be able to select it when creating a context.
Multiple Organizations
You can belong to multiple Quarterback organizations. After signing in, use the organization switcher in the top-left to move between orgs. Each org has its own repos, members, and billing.
Next Steps
Once your repos are mapped, you’re ready to start your first session.