---
title: SCM Providers
description: Pull request status, CI checks, and extensible plugin support for GitHub, GitLab, and more.
---

import { Image } from 'astro:assets';
import commitSidebar from '../../../assets/screenshots/commit-sidebar.png';

Claudette shows pull request state and CI check results for every workspace, right in the sidebar. No in-app sign-in required — it wraps the CLI tools you already have authenticated (`gh`, `glab`).

## What You See

**Sidebar badges** — each workspace displays a git icon indicating its PR state:

- **Open** — arrow icon, colored by CI status (green = passing, yellow = running, red = failing)
- **Draft** — dashed circle icon
- **Merged** — merge icon in purple
- **Closed** — closed-PR icon, muted
- **No PR** — dashed circle icon, muted

**PR status banner** — a color-coded banner appears above the right sidebar tabs showing the PR number (clickable), a status icon, and a human-readable label like "Ready to merge" or "CI failed."

**SCM tab** — the right sidebar includes a dedicated SCM tab with:

- PR title, author, base branch, and a link to open in your browser
- A list of CI checks with individual pass/fail/pending status
- **Create PR** and **Merge PR** buttons for common actions without leaving the app

<Image src={commitSidebar} alt="Claudette sidebar showing workspace list with PR state badges and the SCM tab open with CI check results" loading="lazy" />

## How It Works

Claudette auto-detects your SCM provider by matching `git remote get-url origin` against known hostname patterns (e.g., `github.com`, `gitlab.com`). A background polling loop fetches PR and CI data every 30 seconds across all active workspaces — no manual refresh needed.

All data is cached in memory, keyed by repository and branch. Concurrent CLI calls are capped at 4 to avoid overwhelming your machine.

## Requirements

| Provider | CLI tool | Auth |
|----------|----------|------|
| GitHub | [`gh`](https://cli.github.com/) | `gh auth login` |
| GitLab | [`glab`](https://gitlab.com/gitlab-org/cli) | `glab auth login` |

If the CLI isn't installed or authenticated, the SCM tab shows a helpful status message instead of failing silently.

## Auto-Archive on Merge

Enable [**Settings > General > Archive on merge**](/claudette/features/settings/#general) to automatically archive a workspace when its PR is detected as merged. The sidebar cleans itself up without manual intervention.

## Auto-Fix on CI Failure

Enable [**Settings > Git > Auto-fix CI failures**](/claudette/features/settings/#git) to automatically create a new agent session when a workspace's CI changes from passing or running to failed. Claudette waits until checks have finished, applies the per-workspace cooldown, then opens a session with a prompt containing failed check names, links, branch and PR context, and failed log output when the provider supports it.

The bundled GitHub provider uses `gh run view --log-failed`; the bundled GitLab provider uses `glab ci trace`. Custom SCM plugins can opt in by declaring and implementing the `ci_failure_logs` operation. If a provider does not support log fetching, the auto-fix session is still created with the check list and URLs.

## Custom Plugins

SCM providers are **Lua plugins** that live in `~/.claudette/plugins/<name>/`. Each plugin has a `plugin.json` manifest declaring which CLI it wraps, which hostnames it handles, and which operations it supports.

GitHub and GitLab ship as bundled plugins — they're seeded to disk on first launch and kept up to date automatically. If you've customized a bundled plugin, your changes are preserved.

The plugin sandbox enforces strict security:

- **CLI allowlist** — plugins can only invoke the executables declared in their manifest
- **30-second timeout** — per CLI invocation
- **No filesystem or network access** — all I/O goes through the host API

## Environment Provider Plugins

The same Lua plugin runtime powers a second plugin kind: **env-provider**. Each env-provider activates when the workspace's worktree contains the file or signal it watches for, then prepares the environment for processes Claudette spawns inside the worktree (terminals, agent subprocesses, [MCP servers](/claudette/features/mcp-servers/)).

Bundled env-providers:

| Plugin | Activates when | Required CLI |
|---|---|---|
| `env-direnv` | The worktree has an `.envrc` | [`direnv`](https://direnv.net/) |
| `env-mise` | The worktree has a `mise.toml`, `.mise.toml`, or `.tool-versions` | [`mise`](https://mise.jdx.dev/) |
| `env-dotenv` | The worktree has a `.env` file | None (parsed in-process) |
| `env-nix-devshell` | The worktree has a `flake.nix` with a default devshell | [`nix`](https://nixos.org/) |

Toggle individual providers in **Settings > Plugins**. Each plugin's manifest declares any user-configurable settings, including per-provider timeout caps for slow cold starts.

For direnv, Claudette keeps the `direnv allow` safeguard content-aware. When you approve a blocked `.envrc`, Claudette records that file's SHA-256 digest and can auto-allow future worktrees only when their `.envrc` content matches an approved digest. Editing `.envrc` changes the digest, so the next resolve prompts again before agents or terminals receive that environment.

For Nix devshells, terminals and agent harnesses do not consume direnv's shell/profile-derived environment. When `env-nix-devshell` detects a `flake.nix` or `shell.nix`, Claudette enters the workspace through `nix develop` directly: terminals run plain `nix develop`, and agents run as `nix develop --command <agent> ...`. This keeps the Nix devshell independent from `env-direnv`, even in repos whose `.envrc` also says `use flake`.

If a bundled provider's required CLI isn't installed (e.g. `nix` missing on a non-Nix host), Claudette marks it **not installed** in the Environment panel and silently skips it on every workspace spawn — no toast, no error. The toggle is locked in this state. CLI availability is probed once at startup, so if you install the underlying tool while Claudette is running, restart the app to pick up the change.

When Claudette **creates** a new workspace, the [repo setup script](/claudette/features/per-repo-settings/#setup-script) (if any) runs first with the system shell environment — deliberately, so a setup script can prime env-provider state itself (`direnv allow`, `mise trust && mise install`, generate a `.env` from a template, `nix flake check`) before any provider tries to read it. Claudette then resolves the env-providers, and only after that does the workspace appear as ready. Selecting an **existing** workspace performs the same env warmup but skips the setup script (it already ran on create). In both cases, terminal tabs, agent subprocesses, and MCP servers wait for warmup before spawning. Non-Nix providers are applied as a merged environment; Nix devshell terminals and agents enter through `nix develop` directly.

The merged environment is cached per worktree and invalidated when watched files such as `.envrc`, `mise.toml`, `.env`, or `flake.lock` change. New terminals spawn with the refreshed env. Persistent agent subprocesses re-check the env before each turn and restart when provider output or provider evaluation metadata changes, so the next agent turn sees the updated shell environment. Already-running terminal shells keep their original process environment.

Drop your own env-provider into `~/.claudette/plugins/<name>/` (one `plugin.json` + one `init.lua`) and Claudette discovers it at startup.
