--- title: "Installation & onboarding" description: "Install the Cadence desktop app, sign in with GitHub, and pick which repos it should track." url: "https://teamcadence.ai/docs/installation/" --- ## Install the desktop app Cadence ships as a menubar/tray app for macOS, Windows, and Linux. Download it from your [dashboard](https://dash.teamcadence.ai/) after signing up, or from the link your admin sent you. The app doesn't open a full window - it lives in your menubar (macOS) or system tray (Windows/Linux). Left-click the icon to open the popover; right-click for Quit and other utility actions. ## Onboarding The first time you launch Cadence, it walks you through five steps: 1. **Sign in** - Cadence uses GitHub OAuth only, no separate password. Clicking "Sign in with GitHub" opens your system browser; once you approve, the app picks the session back up automatically. 2. **Choose an org** - pick which of your GitHub orgs Cadence should track. You can only track one org per install. If your org doesn't have the Cadence GitHub App installed yet, you'll be prompted to install it (needed for commit/PR linking - see [Orgs & repos](/docs/concepts/orgs-and-repos/)). 3. **Repo discovery** - Cadence scans your machine for AI-agent session logs (Claude Code, Codex, etc.), works out which local folders they were run in, and matches those against your org's repos. You don't add repos by hand; if a repo shows up as missing, use **Locate** to point Cadence at it directly. On macOS, Cadence will ask for folder-access permission if your repos live under Documents, Desktop, or Downloads. 4. **Backfill** - Cadence offers to import your last 90 days of session history for the repos you just enabled, so your dashboards aren't empty on day one. This can take a few minutes depending on how much history it finds. 5. **Done** - Cadence drops into the background. From here on, new sessions are picked up automatically. ## After onboarding Once set up, the app runs a background check every 30 seconds: it looks for new or updated session logs, resolves them to a repo, and - if that repo is enabled and matches your tracked org - uploads the session. You don't need to do anything per session. The menubar icon tells you the current state at a glance: | Icon state | Meaning | | --- | --- | | Idle | No activity, nothing to upload | | Syncing (animated) | Actively uploading a session | | Paused | You've paused monitoring from the tray menu | | Attention | Something needs you - expired sign-in, a failed upload, or a repo permission issue | An orange dot on the icon means Cadence noticed something worth a look - usually a "drift" nudge on a session that looks stuck or frustrated. See [Overview & tray](/docs/desktop/overview/) for the full popover reference. ## Installing the CLI The `cadence` CLI ships inside the desktop app rather than as a separate download. Install it from the app's overflow menu → **Install CLI**. This places a `cadence` binary on your `PATH` (`~/.local/bin/cadence` on macOS/Linux, a shim under `%LOCALAPPDATA%\Cadence\bin` on Windows) and shares your existing sign-in, so there's no separate login step. See the [CLI overview](/docs/cli/overview/). ## Uninstalling or pausing You can pause monitoring at any time from the tray menu without uninstalling - Cadence stops scanning for sessions but keeps your history and settings. Quit the app the normal way for your OS to stop it completely; nothing is uploaded while it isn't running.
Docs/Installation & onboarding
Installation & onboarding
Install the Cadence desktop app, sign in with GitHub, and pick which repos it should track.
Install the desktop app
Cadence ships as a menubar/tray app for macOS, Windows, and Linux. Download it from your dashboard after signing up, or from the link your admin sent you.
The app doesn’t open a full window - it lives in your menubar (macOS) or system tray (Windows/Linux). Left-click the icon to open the popover; right-click for Quit and other utility actions.
Onboarding
The first time you launch Cadence, it walks you through five steps:
- Sign in - Cadence uses GitHub OAuth only, no separate password. Clicking “Sign in with GitHub” opens your system browser; once you approve, the app picks the session back up automatically.
- Choose an org - pick which of your GitHub orgs Cadence should track. You can only track one org per install. If your org doesn’t have the Cadence GitHub App installed yet, you’ll be prompted to install it (needed for commit/PR linking - see Orgs & repos).
- Repo discovery - Cadence scans your machine for AI-agent session logs (Claude Code, Codex, etc.), works out which local folders they were run in, and matches those against your org’s repos. You don’t add repos by hand; if a repo shows up as missing, use Locate to point Cadence at it directly. On macOS, Cadence will ask for folder-access permission if your repos live under Documents, Desktop, or Downloads.
- Backfill - Cadence offers to import your last 90 days of session history for the repos you just enabled, so your dashboards aren’t empty on day one. This can take a few minutes depending on how much history it finds.
- Done - Cadence drops into the background. From here on, new sessions are picked up automatically.
After onboarding
Once set up, the app runs a background check every 30 seconds: it looks for new or updated session logs, resolves them to a repo, and - if that repo is enabled and matches your tracked org - uploads the session. You don’t need to do anything per session.
The menubar icon tells you the current state at a glance:
| Icon state | Meaning |
|---|---|
| Idle | No activity, nothing to upload |
| Syncing (animated) | Actively uploading a session |
| Paused | You’ve paused monitoring from the tray menu |
| Attention | Something needs you - expired sign-in, a failed upload, or a repo permission issue |
An orange dot on the icon means Cadence noticed something worth a look - usually a “drift” nudge on a session that looks stuck or frustrated. See Overview & tray for the full popover reference.
Installing the CLI
The cadence CLI ships inside the desktop app rather than as a separate download. Install it from the app’s overflow menu → Install CLI. This places a cadence binary on your PATH (~/.local/bin/cadence on macOS/Linux, a shim under %LOCALAPPDATA%\Cadence\bin on Windows) and shares your existing sign-in, so there’s no separate login step. See the CLI overview.
Uninstalling or pausing
You can pause monitoring at any time from the tray menu without uninstalling - Cadence stops scanning for sessions but keeps your history and settings. Quit the app the normal way for your OS to stop it completely; nothing is uploaded while it isn’t running.