GitLab Duo Chat (Agentic)

GitLab Duo Chat (Agentic) is an enhanced version of GitLab Duo Chat (Classic). This new Chat can autonomously perform actions on your behalf, to help you answer complex questions more comprehensively.

While the classic Chat answers questions based on a single context, the agentic Chat searches, retrieves, and combines information from multiple sources across your GitLab projects to provide more thorough and relevant answers.

GitLab Duo Chat (Agentic) can:

• Search projects to find relevant issues, merge requests, and other artifacts using keyword-based search (not semantic search).
• Access files in your local project without manually specifying file paths.
• Create and edit files in multiple locations.
• Retrieve resources like issues, merge requests, and CI/CD pipelines.
• Analyze multiple sources to provide complete answers. Use Model Context Protocol to connect to external data sources and tools.
• Provide customized responses by using your customized rules.
• Create commits, when you use Chat in the GitLab UI.

For an overview, see GitLab Duo Chat (Agentic).

Use GitLab Duo Chat

You can use GitLab Duo Chat in:

• The GitLab UI.
• VS Code.
• A JetBrains IDE.
• Visual Studio for Windows.

Use GitLab Duo Chat in the GitLab UI

Prerequisites:

• Ensure you meet the prerequisites.

To use Chat in the GitLab UI:

1. On the top bar, select Search or go to and find your project.
2. On the GitLab Duo sidebar, select either New GitLab Duo Chat ( ) or Current GitLab Duo Chat ( ). A Chat conversation opens in the GitLab Duo sidebar on the right side of your screen.
3. Under the chat text box, turn on the Agentic mode (Beta) toggle.
4. Enter your question in the chat text box and press Enter or select Send.
   • You can provide additional context for your chat.
   • It might take a few seconds for the interactive AI chat to produce an answer.
5. Optional. You can:
   • Ask a follow-up question.
   • Start another conversation.

If you reload the webpage you are on, or go to another webpage, Chat remembers your most recent conversation, and that conversation is still active in the Chat drawer.

Use GitLab Duo Chat in VS Code

Prerequisites:

• Install and configure the GitLab Workflow extension for VS Code version 6.15.1 or later.
• Ensure you meet the other prerequisites.

Turn on GitLab Duo Chat:

1. In VS Code, go to Settings > Settings.
2. Search for agent platform.
3. Under GitLab > Duo Agent Platform: Enabled, select the Enable GitLab Duo Agent Platform checkbox.

Then, to use GitLab Duo Chat:

1. On the left sidebar, select GitLab Duo Agent Platform (Beta) ( ).
2. Select the Chat tab.
3. Select Refresh page if prompted.
4. In the message box, enter your question and press Enter or select Send.

Use GitLab Duo Chat in JetBrains IDEs

Prerequisites:

• Install and configure the GitLab plugin for JetBrains version 3.11.1 or later.
• Ensure you meet the other prerequisites.

Turn on GitLab Duo Chat:

1. In your JetBrains IDE, go to Settings > Tools > GitLab Duo.
2. Under GitLab Duo Agent Platform (Beta), select the Enable GitLab Duo Agent Platform checkbox.
3. Restart your IDE if prompted.

Then, to use GitLab Duo Chat:

1. On the left sidebar, select GitLab Duo Agent Platform (Beta) ( ).
2. Select the Chat tab.
3. In the message box, enter your question and press Enter or select Send.

Use GitLab Duo Chat in Visual Studio

Prerequisites:

• Install and configure the GitLab extension for Visual Studio version 0.60.0 or later.
• Ensure you meet the other prerequisites.

Turn on GitLab Duo Chat:

1. In Visual Studio, go to Tools > Options > GitLab.
2. Under GitLab, select General.
3. For Enable Agentic Duo Chat (experimental), select True, and then OK.

Then, to use GitLab Duo Chat:

1. Select Extensions > GitLab > Open Agentic Chat.
2. In the message box, enter your question and press Enter.

View the chat history

To view your chat history:

• In the GitLab UI, on the GitLab Duo sidebar, select GitLab Duo Chat history ( ).

• In your IDE, in the upper-right corner of the message box, select Chat history ( ).

In the GitLab UI, all of the conversations in your chat history are visible.

In your IDE, the last 20 conversations are visible. Issue 1308 proposes to change this.

Have multiple conversations

You can have an unlimited number of simultaneous conversations with GitLab Duo Chat.

Your conversations synchronize across GitLab Duo Chat in the GitLab UI and your IDE.

1. Open GitLab Duo Chat in the GitLab UI or your IDE.

2. Enter your question and press Enter or select Send.

3. Create a new Chat conversation:

   • In the GitLab UI, you can do either of the following:
     • On the GitLab Duo sidebar, select New GitLab Duo Chat ( ).
     • In the message box, type /new and press Enter or select Send. A new Chat conversation replaces the previous one.
   • In your IDE, in the upper-right corner of the message box, select New chat ( ).

4. Enter your question and press Enter or select Send.

5. To view all of your conversations, look at your chat history.

6. To switch between conversations, in your chat history, select the appropriate conversation.

7. IDE only: To search for a specific conversation in the chat history, in the Search chats text box, enter your search term.

Because of LLM context window limits, conversations are truncated to 200,000 tokens (roughly 800,000 characters) each.

Delete a conversation

1. In the GitLab UI or your IDE, select the chat history.
2. In the history, select Delete this chat ( ).

Individual conversations expire and are automatically deleted after 30 days of inactivity.

Customize GitLab Duo Chat in your IDE

Customize how GitLab Duo Chat behaves in your IDE by providing instructions that reflect your coding style, team practices, and project requirements.

GitLab Duo Chat supports two approaches:

• Custom rules in chat-rules.md: For GitLab only. Best for personal preferences and team standards.
• Shared rules in AGENTS.md: For GitLab and other AI tools that support the specification. Best for project context, monorepo organization, and directory-specific conventions.

You can use both files simultaneously. GitLab Duo Chat applies instructions from all available rule files.

Create custom rules

Use custom rules to specify instructions for GitLab Duo Chat to follow for every conversation in your IDE.

You can create custom rules at two levels:

• User-level rules: Apply to all of your projects and workspaces.
• Workspace-level rules: Apply only to a specific project or workspace.

If both user-level and workspace-level rules exist, GitLab Duo Chat applies both to conversations.

Prerequisites:

• For VS Code, install and configure the GitLab Workflow extension for VS Code version 6.32.2 or later.
• For a JetBrains IDE, install and configure the GitLab plugin for JetBrains version 3.12.2 or later.
• For Visual Studio, install and configure the GitLab extension for Visual Studio version 0.60.0 or later.

Create user-level custom rules

User-level custom rules apply to all of your projects and workspaces.

1. Create a custom rules file in your user configuration directory:

   • If you have set the GLAB_CONFIG_DIR environment variable, create the file at: $GLAB_CONFIG_DIR/chat-rules.md
   • Otherwise, create the file in your platform’s default configuration directory:
     • macOS or Linux:
       • If you use the XDG_CONFIG_HOME environment variable, create the file at: $XDG_CONFIG_HOME/gitlab/duo/chat-rules.md
       • Otherwise, create the file within your home directory at: ~/.gitlab/duo/chat-rules.md
     • Windows: %APPDATA%\GitLab\duo\chat-rules.md

2. Add custom rules to the file. For example:

   - Don't put comments in the generated code
   - Be brief in your explanations
   - Always use single quotes for JavaScript strings

3. Save the file.

4. To apply the new custom rules, start a new GitLab Duo conversation.

   You must do this every time you change the custom rules.

Create workspace-level custom rules

Workspace-level custom rules apply only to a specific project or workspace.

1. In your IDE workspace, create a custom rules file: .gitlab/duo/chat-rules.md.

2. Add custom rules to the file. For example:

   - Don't put comments in the generated code
   - Be brief in your explanations
   - Always use single quotes for JavaScript strings

3. Save the file.

4. To apply the new custom rules, start a new GitLab Duo conversation.

   You must do this every time you change the custom rules.

For more information, see the Custom rules in GitLab Duo Agentic Chat blog.

Update custom rules

To update your custom rules, edit and save the custom rules file. Then, start a new GitLab Duo conversation to apply the updated rules.

You cannot use Chat to edit your custom rules file directly.

To manage who must approve any changes to custom rules, use Code Owners.

Create AGENTS.md instruction files

Use AGENTS.md files to provide instructions for GitLab Duo Chat to follow during conversations in your IDE. Unlike custom rules, these instructions are also available for other AI coding tools to use.

This feature follows the AGENTS.md specification, an emerging standard for providing context and instructions to AI coding assistants.

You can create AGENTS.md files at multiple levels:

• User-level: Apply to all of your projects and workspaces.
• Workspace-level: Apply only to a specific project or workspace.
• Subdirectory-level: Apply only to a specific project within a monorepo or within a project with distinct components.

GitLab Duo Chat combines available instructions from user-level and workspace-level AGENTS.md files for all conversations. If a task requires working with files in a directory that contains an additional AGENTS.md file, Chat applies those instructions as well.

Prerequisites:

• For VS Code, install and configure the GitLab Workflow extension for VS Code 6.60 or later.
• For a JetBrains IDE, install and configure the GitLab plugin for JetBrains 3.26.0 or later.

Create a user-level AGENTS.md file

User-level AGENTS.md files apply to all of your projects and workspaces.

1. In your user configuration directory, create an AGENTS.md file:

   • If you have set the GLAB_CONFIG_DIR environment variable, create the file at: $GLAB_CONFIG_DIR/AGENTS.md
   • Otherwise, create the file in your platform’s default configuration directory:
     • macOS or Linux:
       • If you use the XDG_CONFIG_HOME environment variable, create the file at: $XDG_CONFIG_HOME/gitlab/duo/AGENTS.md
       • Otherwise, create the file within your home directory at: ~/.gitlab/duo/AGENTS.md
     • Windows: %APPDATA%\GitLab\duo\AGENTS.md

2. Add instructions to the file. For example:

   Personal preferences

   # My personal coding preferences
   
   - Always explain code changes in simple terms for beginners
   - Use descriptive variable names
   - Add comments for complex logic
   - Prefer functional programming patterns when appropriate

   Team standards

   # Team coding standards
   
   - Follow our company's style guide for all code
   - Use TypeScript strict mode
   - Write unit tests for all new functions
   - Document all public APIs with JSDoc

   Monorepo context

   # Monorepo context
   
   - This is a monorepo with multiple services
   - Frontend code is in /apps/web
   - Backend services are in /services
   - Shared libraries are in /packages
   - Follow the architecture decision records in /docs/adr

   Security guidelines

   # Security review guidelines
   
   - Always validate user input
   - Use parameterized queries for database operations
   - Implement proper authentication and authorization
   - Follow OWASP security best practices
   - Never log sensitive information

3. Save the file.

4. To apply the instructions, start a new GitLab Duo conversation.

   You must do this every time you change the AGENTS.md file.

Create workspace-level AGENTS.md files

Workspace-level AGENTS.md files apply only to a specific project or workspace.

1. In the root of your project workspace, create an AGENTS.md file.

2. Add instructions to the file. For example:

   # Project-specific guidelines
   
   - This project uses React with TypeScript
   - Follow the component structure in /src/components
   - Use our custom hooks from /src/hooks
   - State management uses Redux Toolkit

3. Save the file.

4. To apply the instructions, start a new GitLab Duo conversation.

   You must do this every time you change the AGENTS.md file.

Use AGENTS.md in monorepos and subdirectories

For monorepos or projects with distinct components, you can place AGENTS.md files in subdirectories to provide context-specific instructions for different parts of your codebase.

When GitLab Duo Chat discovers additional AGENTS.md files in subdirectories, it reads the relevant file before editing files in that directory. For example:

/my-project
  AGENTS.md              # Root instructions (included in all conversations)
  /frontend
    AGENTS.md            # Frontend-specific instructions
  /backend
    AGENTS.md            # Backend-specific instructions

In this example:

• The root AGENTS.md is always included in conversations.
• When GitLab Duo edits files in /frontend, it reads /frontend/AGENTS.md first.
• When GitLab Duo edits files in /backend, it reads /backend/AGENTS.md first.

This approach helps ensure GitLab Duo follows the appropriate conventions for each part of your project.

To use AGENTS.md in a subdirectory:

1. In a subdirectory of your project, create an AGENTS.md file.

2. Add instructions specific to that directory. For example, for a backend service:

   # Backend service guidelines
   
   - This service uses Node.js with Express
   - Follow RESTful API conventions
   - Use async/await for asynchronous operations
   - Validate all inputs with Joi schemas

3. Save the file.

4. To apply the instructions, start a new GitLab Duo conversation that involves files in that directory.

   You must do this every time you change the AGENTS.md file.

Select a model

When you use Chat in the GitLab UI, VS Code, or a JetBrains IDE, you can select the model to use for conversations.

If you open a previous chat from the chat history and continue that conversation, Chat uses the model that you previously selected.

If you select a new model when in an existing conversation, Chat creates a new conversation.

Prerequisites:

To select a model:

• In the GitLab UI:

  1. Under the chat text box, ensure that the Agentic mode (Beta) toggle is turned on.
  2. Select a model from the dropdown list.

• In your IDE:

  1. On the left sidebar, select GitLab Duo Agent Platform (Beta) ( ).
  2. Select the Chat tab.
  3. Select a model from the dropdown list.

Select an agent

When you use Chat in a project in the GitLab UI, VS Code, or a JetBrains IDE, you can select a specific agent for Chat to use.

Prerequisites:

• In your project, an agent from the AI Catalog must be enabled.
• You must be a member of the project the agent is enabled in.
• For VS Code, install and configure the GitLab Workflow extension for VS Code version 6.49.12 or later.
• For a JetBrains IDE, install and configure the GitLab plugin for JetBrains version 3.22.0 or later.

To select an agent:

1. In the GitLab UI or your IDE, open a new conversation in GitLab Duo Chat.
2. In the dropdown list, select an agent. If you have not set up any agents, there is no dropdown list, and Chat uses the default GitLab Duo agent.
3. Enter your question and press Enter or select Send.

After you create a conversation with an agent:

• The conversation remembers the agent you selected. You cannot select a different agent for that conversation.
• If you use the chat history to go back to the same conversation, it uses the same agent.
• If you go back to a conversation and the associated agent is no longer available, you cannot continue that conversation.

Prompt caching

Prompt caching is enabled by default to improve GitLab Duo Chat (Agentic) latency. When prompt caching is enabled, chat prompt data is temporarily stored in memory by the model vendor (Anthropic or VertexAI). Prompt caching significantly improves latency by avoiding the re-processing of cached prompt and input data.

Turn off prompt caching

You can turn off prompt caching for top-level groups in the GitLab Duo settings. This also turns off prompt caching for Code Suggestions.

Chat feature comparison

Troubleshooting

When working with GitLab Duo Chat, you might encounter issues.

For information on resolving these issues, see Troubleshooting.

Feedback

Because this is a beta feature, your feedback is valuable in helping us improve it. Share your experiences, suggestions, or issues in issue 542198.

Related topics

• Blog: GitLab Duo Chat gets agentic AI makeover