Interactive terminal (TUI)¶
The terminal app is the everyday way to use gdc: a full-screen chat interface with a live transcript, inline approvals, session history, and keyboard-driven navigation. This page is a tour. For the complete key list, see Keyboard shortcuts.
Launching¶
From inside a project:
With no options, gdc-tui runs everything it needs on its own, against a
private database for the current project. You don't have to start a
server. (If you do run a shared server, connect to it with
gdc-tui --bind <host:port> — see the Admin guide.)
The layout¶
- Transcript — the scrolling conversation: your messages, the agent's replies, and the tools it runs, in order. It sticks to the bottom as new content arrives.
- Input box — where you type. Press Enter to send.
- Status bar — shows your current model, profile, and endpoint.
Talking to the agent¶
Type a request and press Enter. While the agent is working you can keep typing your next message — it's queued and sent when the current turn finishes. Press Shift+Enter to add a newline within a message.
Use Up and Down to bring back things you typed before, and to step through any queued messages.
Referencing files¶
Type @ to reference a file by path. An autocomplete list appears; keep
typing to filter, and press Tab to accept. This is the easy way to
point the agent at a specific file.
Running a shell command yourself¶
Prefix a line with ! to run a shell command directly, without asking
the agent:
Slash commands¶
Type / at the start of the input to open the command menu. The most
useful commands:
| Command | What it does |
|---|---|
/new |
Start a fresh session. |
/sessions |
Open the list of this project's sessions. |
/clear |
Start fresh, keeping the current session as history. |
/compact |
Summarise the conversation so far and continue with the summary (frees up room in long sessions). |
/profile <name> |
Switch the active profile. |
/model <name> |
Switch the model for your next turn. |
/fork |
Branch the conversation from an earlier point (see below). |
/share |
Export the session as Markdown into the current folder. |
/dump |
Write the full transcript to a file. |
/theme dark / /theme light |
Switch the colour theme. |
/vim |
Toggle vim-style editing in the input box. |
/config |
Open the settings screen. |
/help |
Show the keyboard-shortcut overlay. |
/delete |
Delete the current session (asks first). |
The full parsed list is available by typing / and browsing the popup.
Approving actions¶
When the agent wants to do something that needs your approval, an inline prompt replaces the input box:
- A — allow once
- R — toggle remember (save the choice for this project)
- D or Esc — deny
Answering the agent's questions¶
Sometimes the agent needs a decision from you and presents a set of options. Move between questions with Tab, move within a question with Up/Down, pick with Enter, and submit on the final tab. You can also type a custom answer in the Other field.
Background jobs¶
Long-running commands don't have to block the conversation.
- Press Ctrl+B to move the currently-running command to the background; the conversation continues and the result arrives when it finishes.
- Press Ctrl+J to open the jobs list — backgrounded commands and any active subagents — where you can inspect or stop them.
- Press Ctrl+W to drill into a running subagent and watch its work.
→ Tools
Forking a conversation¶
/fork lets you branch from an earlier message — useful when you want to
try a different direction without losing the original. Enter fork mode,
move the cursor to the message you want to branch from, and press
Enter to create the branch.
Reviewing the raw log¶
Press Ctrl+O to open a full-log overlay for the current session — handy when you want to scroll back through everything without the transcript's formatting.
Editing like vim¶
If you're comfortable with vim, /vim turns the input box into a modal
editor with the usual motions and operators (h j k l, w b e, dd,
yy, p, :w to submit, and so on). Toggle it off the same way.
Themes and notifications¶
Switch between light and dark with /theme, or set a default in
configuration. You can also control
whether gdc flashes the screen, shows toasts, or rings the terminal bell
when something needs your attention.
Exiting¶
Press Ctrl+C twice (within two seconds) to quit. A half-typed message cancels the first press, so you won't exit by accident.