Skip to content

Concepts overview

You can be productive with gdc after the Quickstart, but a handful of ideas make everything else easier to understand. This page is the map; each concept has its own page with the detail.

The big picture

When you give gdc a task, it runs a loop:

  1. It sends your request, together with the recent conversation, to a model (your chosen LLM).
  2. The model replies — either with an answer, or by asking to use a tool (read a file, edit code, run a command, search).
  3. Before any action with side effects, gdc checks it against your permissions. If the action needs your approval, gdc asks you.
  4. gdc runs the approved tool, feeds the result back to the model, and the loop repeats until the task is done.

Everything that happens is recorded in a session so you can resume, inspect, or audit it later.

You ─▶ gdc ─▶ model ──▶ "use a tool"
                │            │
                │      permission check ──▶ (ask you if needed)
                │            │
                └──◀── tool result ◀── run the tool

The core ideas

  • Operating modes

    The interactive terminal app, the headless command line, single-shot checks, and plan mode — when to use each.

  • Tools

    The concrete actions the agent can take on your behalf: read, write, edit, run commands, search, fetch the web, and more.

  • Permissions

    How gdc decides what to allow, ask about, or deny — and how to shape those rules. Everything fails closed.

  • Profiles & output styles

    Presets that change which tools are available and how the agent phrases its replies.

  • Sessions & projects

    Persistent, resumable conversations, scoped to the project you're working in.

  • Memory

    Durable notes gdc can carry across sessions.

  • Model providers

    Which model backends gdc supports and why open, local models come first.

A minimal vocabulary

Term Meaning
Model / provider The LLM gdc talks to, reached over an OpenAI-compatible endpoint.
Tool An action the agent can take (read a file, run a command, …).
Permission A rule that allows, asks about, or denies a tool action.
Session One saved conversation, including every message and tool run.
Profile A preset that sets which tools are visible and how the agent behaves.
Project The working directory (and its subfolders) gdc scopes to.

A fuller list is in the Glossary.