Customize the GitLab Duo CLI

Tier: Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

The GitLab Duo CLI supports the following customizations:

Use hooks to run custom commands at specific points in the GitLab Duo CLI lifecycle.
Use custom slash commands to better align the CLI with your workflow or use case.
Use custom instructions set for the GitLab Duo Agent Platform to match your workflow, coding standards, or project requirements.

Hooks

Status: Experiment

Use hooks to run custom commands at specific points in the GitLab Duo CLI lifecycle.

For example, you can inject additional context into every new chat session by running a script that gathers information about your environment.

The GitLab Duo CLI supports hooks at two levels:

User-level (global): Apply to all of your projects.
Project-level: Apply only to a specific project. Project-level hooks are disabled by default to prevent running arbitrary code from checked-out repositories.

When both user-level and project-level hooks.json files exist, the CLI merges the hooks and runs the user-level ones first.

For security reasons, sensitive environment variables (GITLAB_TOKEN, GITLAB_OAUTH_TOKEN, CI_JOB_TOKEN) are excluded from hook processes.

Hook execution

When a hook runs, the GitLab Duo CLI:

Sends a JSON object to the command’s standard input with session metadata:

{
  "session_id": "abc-123",
  "cwd": "/path/to/project",
  "transcript_path": "",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

Sets environment variables DUO_SESSION_ID and DUO_PROJECT_DIR for the hook process.
Collects the command’s standard output as additional context for the session.

The hook can return plain text on standard output, or a JSON object:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Your context string here"
  }
}

If the hook exits with a non-zero status or times out, it is logged as a warning but does not block the session from starting.

Create hooks

The GitLab Duo CLI supports the SessionStart event, which runs when a new session starts or an existing session resumes.

To create a hook:

Create a hooks.json file:
- For a user-level hook:
  - On Linux or macOS, create the file at ~/.gitlab/duo/hooks.json.
  - On Windows, create the file at %APPDATA%\GitLab\duo\hooks.json.
- For a project-level hook, create the file in the root of your project: <project>/.gitlab/duo/hooks.json.

Define your hooks in the file.

Create a matcher group for each SessionStart event source that should trigger the hook (startup or resume).

Each matcher group has an optional regex matcher value and an array of command hooks:

Field	Description
`matcher`	Optional. Regex tested against the event source (`startup` or `resume` for `SessionStart`). Omit to match all.
`hooks[].type`	Must be `"command"`.
`hooks[].command`	A shell command to execute.
`hooks[].timeout`	Optional. Timeout in seconds. Default: 30.

For example:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/.my-coding-preferences.md",
            "timeout": 10
          }
        ]
     }
    ]
  }
}

If you have project-level hooks, enable them when you start the GitLab Duo CLI:
glab duo cli --enable-project-hooks
duo --enable-project-hooks
Alternatively, set the environment variable:
```
export GITLAB_ENABLE_PROJECT_HOOKS=true
```

Custom slash commands

Create custom slash commands for prompts you use frequently.

The GitLab Duo CLI supports custom slash commands at two levels:

User-level: Apply to all of your projects.
Project-level: Apply only to a specific project.

If a user-level command and a project-level command share the same name, the project-level command takes precedence. Custom slash commands cannot override built-in slash commands or Agent Skills slash commands.

Create a custom slash command

To create a custom slash command, you create a Markdown file.

The filename is the command name, and the file content is the prompt.

For example, a file named daily.md creates the /daily command:

Create a commands directory:
- For a project-level command, create the directory in the root of your project: <project>/.agents/commands/.
- For a user-level command, use one of the following locations:
  - To keep your commands with your other GitLab Duo customization files:
    - On Linux or macOS, create the directory at ~/.gitlab/duo/commands/.
    - On Windows, create the directory at %APPDATA%\GitLab\duo\commands\.
    - If you have set GLAB_CONFIG_DIR or XDG_CONFIG_HOME, use $GLAB_CONFIG_DIR/commands/ or $XDG_CONFIG_HOME/gitlab/duo/commands/. If both are set, GLAB_CONFIG_DIR takes priority.
  - To share commands with other AI tools:
    - On Linux or macOS, create the directory at ~/.agents/commands/.
    - On Windows, create the directory at %USERPROFILE%\.agents\commands\.
In the directory, create a Markdown file. Use the command name as the filename. Command names must start with a letter or number, and can contain only letters, numbers, hyphens, and underscores.
Add the prompt to the file.
Optional. Add a description field in YAML front matter at the top of the file. The description appears next to the command in the slash command menu.
For example, a /daily command defined in daily.md:
```
---
description: Prepare a daily report
---

Use `glab todo list` to fetch my open TODO items. Give me a concise morning report ranked by priority.
```
Restart the GitLab Duo CLI. The CLI discovers custom slash commands when it starts.

Use a custom slash command

In interactive mode, enter the slash command at the prompt and press Enter. The GitLab Duo CLI sends the file content as the prompt.

Any text you enter after the command name is added to the end of the prompt.

Use additional text to customize what the custom slash command does.

For example, /daily prioritize my milestone deliverables.