Permissions

Permissions are how gdc keeps you in control of what the agent does. Every action with a side effect — running a command, writing outside your project — is checked before it runs. This page explains the model so you can trust it and shape it to your needs.

Allow, ask, or deny

Every tool action resolves to one of three decisions:

• Allow — run it without interrupting you.
• Ask — pause and prompt you to approve or reject it.
• Deny — refuse it outright.

Reading and searching your project are allowed by default. Running shell commands and writing outside the current project default to ask, so you see them before they happen.

Fail closed

gdc is designed to fail closed: when anything is uncertain — an error while evaluating a rule, or an "ask" that can't be answered because nobody is watching — the answer is deny, never "allow anyway". An unattended run therefore can't silently do something you didn't sanction.

This is why headless gdc print denies actions that would need approval unless you explicitly pass --auto-approve.

Approving actions interactively

In the terminal app, an action that needs approval shows an inline prompt:

• Allow once — permit just this action.
• Remember — permit it and save the choice so gdc won't ask again for the same kind of action in this project.
• Deny — reject it.

Remembered approvals are saved per project. You can review and undo them at any time:

gdc permissions list           # what you've allowed in this project
gdc permissions revoke bash jq # take back a specific approval

→ Managing sessions & data

Shaping the rules yourself

You can set your own allow and deny rules in configuration so gdc stops asking about things you've already decided.

~/.gdc/config.toml

[permissions.bash]
allow = ["jq", "rg"]     # never ask about these commands
deny  = ["aws"]          # always refuse these

[permissions.path]
allow = ["~/work/scratch/**"]   # let the agent write here, outside the project
deny  = ["~/.aws/**"]           # never touch these paths

Rules apply to the leading command name for shell commands, and to file paths (as glob patterns) for file access.

Deny always wins

Your rules are added on top of a built-in safety baseline. Where an allow and a deny both match, deny wins — you can loosen and tighten the defaults, but you can't accidentally allow something the baseline forbids.

Restricting the whole tool set

Sometimes the safest control isn't per-action but per-session: use a profile that only exposes the tools you want. For example, a review profile can make the agent read-only, with no ability to run commands or edit files at all.

In short

• Reads are free; changes are gated.
• When in doubt, gdc denies.
• You approve interactively, and can remember choices per project.
• You can pre-approve or forbid specific commands and paths in config.
• A profile can cap which tools exist in the first place.