Skip to content

Quickstart

This guide gets you from a fresh install to your first completed task in a few minutes. You'll connect a model, launch the interactive terminal app, and ask gdc to do something in a real project.

1. Start a model backend

gdc needs a model to talk to. The quickest way is a local runner. Pick one:

ollama serve &
# A coding-focused model works well for tool use:
ollama pull qwen2.5-coder:14b-instruct

Ollama listens on http://localhost:11434/v1.

llama-server -m your-model.gguf --port 8000 &

The endpoint is http://localhost:8000/v1.

In the LM Studio app, load a model and click Start Server (default port 1234). The endpoint is http://localhost:1234/v1.

See Model providers for hosted options and more detail.

2. Tell gdc how to reach the model

You can pass the endpoint and model on the command line every time, or save them once in a configuration file. Saving them is easier:

~/.gdc/config.toml
[provider]
base_url = "http://localhost:11434/v1"
model    = "qwen2.5-coder:14b-instruct"
# api_key = "sk-..."   # only needed for hosted endpoints

Now every gdc command uses these settings by default. (You can still override them per run — see below.)

3. Launch the interactive app

From inside a project you want to work on:

cd ~/my-project
gdc-tui

The full-screen app opens. Type a request and press Enter:

list the source files in this project and summarise what it does

You'll see the agent's reply stream in, along with the tools it uses to read your files.

Approving actions

When gdc wants to run a shell command or write outside the current project, it pauses and asks. Press A to allow it once, R to remember your choice, or D to deny. See Permissions.

Try a change:

add a --version flag to the CLI and update the README

gdc will read the relevant files, propose edits, ask before running anything sensitive, and apply the changes.

When you're done, press Ctrl+C twice to exit.

4. (Optional) Run a task without the UI

For scripts and automation, use the headless command instead. It streams the answer to standard output:

gdc print "list the rust files in this repo"

To let an unattended run approve its own actions, add --auto-approve (only in environments you trust):

gdc print --auto-approve "run the test suite and fix any failing test"

See Headless CLI for the full workflow.

5. Review what happened

Every run is saved. List recent sessions in the current project and open one:

gdc sessions list
gdc sessions show <session-id>

Overriding settings for one run

Any setting in your config can be overridden on the command line:

gdc --base-url http://localhost:8000/v1 --model my-model \
    print "explain the error handling in src/app.rs"

Where to go next

  • Concepts — the ideas behind gdc, so the rest of the docs make sense.
  • Interactive terminal — a full tour of the app.
  • Plan mode — have gdc plan a change before it touches anything.