Operating modes

gdc can be used in a few different ways depending on whether you want an interactive session, a scriptable one-shot run, or a quick connectivity check. This page explains each so you can pick the right one.

Interactive terminal (the everyday mode)

Run gdc-tui to open a full-screen chat interface in your terminal. You type requests, watch the agent work in a live transcript, and answer approval prompts inline. It keeps a history of your sessions and supports slash commands, file references, background jobs, and more.

This is the mode most people use most of the time.

gdc-tui

→ Interactive terminal guide

Headless command line (scripts & automation)

Run gdc print "<task>" to drive the same agent loop without a UI. The agent's reply streams to standard output; progress and tool activity go to standard error, so you can capture just the answer in a pipeline. Each run is saved like any other session.

gdc print "summarise what changed in the last commit"

This is the mode for CI jobs, shell scripts, and batch work. Combine it with --auto-approve for fully unattended runs (in trusted environments only).

→ Headless CLI guide

Single-shot check (no tools)

Run gdc chat "<prompt>" for a single question-and-answer with no tools and no saved history. It's the fastest way to confirm your model backend is reachable and responding.

gdc chat "say hello"

Use it to sanity-check connectivity before starting real work.

Plan mode (look before you leap)

Plan mode is a way of running the agent, not a separate program. In plan mode the agent can only research — read files and search — and write its plan to a dedicated folder. It cannot edit your code or run commands until you approve the plan. This lets you review the approach before anything changes.

You can start in plan mode and switch to acting once you're satisfied.

gdc print --profile plan "plan how to add a health-check endpoint"

→ Plan mode guide

Server mode (shared / remote use)

gdc serve runs gdc as a background server. Most people never run it directly — the terminal app starts one for you automatically. You run it explicitly when you want a shared or remote deployment: several people or machines connecting to one gdc instance, or the terminal app connecting to gdc running on another host.

→ Admin guide

Choosing a mode

You want to…	Use
Work interactively, day to day	gdc-tui
Run a task from a script or CI	gdc print
Check that your model is reachable	gdc chat
Review an approach before any changes	plan mode (--profile plan)
Host gdc for remote or shared use	gdc serve

A note on approvals

Interactive modes ask you before sensitive actions. Headless gdc print denies actions that would need approval unless you pass --auto-approve, so an unattended run never silently does something you didn't sanction. See Permissions.