Agents
The two agent CLIs GitDB Desktop runs, how to sign in to each, and the model, effort and permission options the app offers.
GitDB Desktop runs two agent CLIs. The app marks each with a small badge:
| CLI | Badge | Made by |
|---|---|---|
| Claude Code | CC | Anthropic |
| Codex CLI | CX | OpenAI |
Install at least one of them first — see Install GitDB Desktop.
Session settings
Every choice about how the agent runs lives in one place: the Session settings button at the bottom left of the message box. Its face summarizes what's in force — the CLI badge, the model and effort, and the permission mode — and clicking it opens a panel with these sections:
- Start with (a new thread) or Run the next turn with (an existing thread) — the CLI.
- Role sub-agents — only when starting a new thread in a GitDB repository.
- Model and Effort.
- Permission mode.
- Codex account — for Codex CLI.
A pick keeps the panel open, so you can set everything in one visit. Press Escape or click outside to close it.
Choosing the CLI
Each CLI's row shows its state. On a new thread that's the version the app found and whether it's ready — logged in for Claude Code, installed for Codex CLI (Codex reports its sign-in separately, below). On an existing thread the row says what the next turn will do, such as continuing the live session or resuming the earlier one. A CLI that isn't installed can't be picked; its row shows the install command for your system.
The first time, new threads start on Codex CLI. After that, the app remembers the CLI you last picked for a new thread.
Whether a thread can switch CLIs later depends on its workspace — see Threads and sessions.
Signing in
Claude Code
Sign in to Claude Code in a terminal:
claude loginGitDB Desktop reads Claude Code's sign-in state when you open the Code view. If you aren't signed in, the status bar shows claude · sign-in needed, and the Claude Code row in Session settings says "not logged in — run claude login". You can still pick Claude Code — the app doesn't block it — but sign in before you rely on it.
Codex CLI
You sign in to Codex from inside the app. Open Session settings with Codex CLI selected and look at the Codex account section:
- If Codex isn't running yet, click Connect codex. ("It starts by itself on your first codex turn — connect now to sign in, pick a model or see your limits first.")
- If Codex has no account, click Sign in to codex ("Codex has no account on this machine. Sign in to ChatGPT to run turns on this arm."). Your browser opens so you can sign in to ChatGPT.
- While you finish in the browser, the section shows Signing in…, with Open the sign-in page again (if the browser didn't come to the front) and Cancel sign-in.
- Once you're signed in, the section names your account — your ChatGPT email, "OpenAI API key", or "Amazon Bedrock" — and offers Sign out, which signs out "every codex thread on this machine".
The status bar shows codex · logged in once Codex reports your account, or codex · sign-in needed if it needs one.
Model
| Claude Code | Codex CLI | |
|---|---|---|
| Panel heading | Model (global — every Claude Code session) | Model (this thread) |
| Where the list comes from | Claude Code itself | Codex itself — until Codex is running, you can type a model name yourself |
| CLI default row | Always offered | Only when starting a new thread |
| Custom… | Type any model id | Type any model id |
On Claude Code, the model is a global setting. It's saved in Claude Code's own settings, so it applies to every Claude Code session — including the claude you run in a terminal. The panel notes that the change is "Confirmed on the next reply".
On Codex CLI, the model belongs to the thread. The panel explains that it is used "when this thread next starts or resumes. A running turn keeps the model it started on."
Effort
- Claude Code: Low, Medium, High, Extra High, Max.
- Codex CLI: the levels your chosen model supports, each with Codex's own description. Before Codex has listed its models, the panel shows the full set of named levels.
Permission mode
Permission modes decide which agent actions need your approval. The two CLIs have different modes.
Claude Code
Permission mode (global — every Claude Code session):
| Mode | What it does |
|---|---|
| Plan | read-only — no edits, no commands |
| Default | ask before each tool |
| Auto | let Claude Code decide what needs asking |
| Accept edits | file edits go through without asking |
| Don't ask | no prompts this session |
| Bypass permissions | every tool runs unasked |
A new mode goes to every running Claude Code session right away. Default, Auto and Accept edits are also remembered for next time; the other three are marked "this session only" and last only as long as the sessions running now.
Codex CLI
Permission mode (this thread) — the section appears once the thread exists:
| Mode | What it does |
|---|---|
| Read only | no edits, no commands — asks for everything else |
| Auto | edits inside the workspace; asks to leave it |
| Granular | workspace edits, plus per-permission asks |
| Guardian approvals | a reviewer agent answers the asks |
| Full access | no sandbox, nothing asked |
Until you pick one, a thread uses its workspace's default: Read only in a GitDB repository and Auto in a local folder. The panel notes: "The mode belongs to this thread and is remembered. Codex reads it when the thread's process next starts or resumes — a turn that is already running keeps the mode it started on."
When an agent needs your approval, a prompt appears — see Permission and approval prompts.
Role sub-agents
When you start a new thread in a GitDB repository, Session settings offers Role sub-agents (this new thread):
- Off — "one agent works alone"
- Architect · Coder · Reviewer · Tester — "role sub-agents, each on its own GitDB branch"
The panel explains the rules: "Fixed when the thread is created. Each role commits to its own branch before it hands back. On Claude Code every role uses its own agent credential — one agent seat each; on Codex the roles run on this connection's credential."
A thread with role sub-agents shows a swarm tag in the message box. The option isn't offered for local folders or for threads that already exist.
Threads and sessions
How threads work in GitDB Desktop — workspaces, the three-session limit, Stop versus End session, rewinding and forking, queued messages, and switching CLIs.
Slash commands
How the / menu works on Claude Code and Codex CLI threads, the commands GitDB Desktop runs itself, and the Claude Code commands it refuses.