GitLab Duo Chat (Agentic)

Tier: Premium, Ultimate
Add-on: GitLab Duo Core, Pro, or Enterprise
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Status: Beta

Model information

Default LLM: Anthropic Claude Haiku 4.5
Available on GitLab Duo with self-hosted models

Version history

VS Code introduced on GitLab.com in GitLab 18.1 as an experiment with a flag named duo_agentic_chat. Disabled by default.
VS Code enabled on GitLab Self-Managed in GitLab 18.2.
GitLab UI introduced on GitLab.com and GitLab Self-Managed in GitLab 18.2 with flags named duo_workflow_workhorse and duo_workflow_web_chat_mutation_tools. Both flags are enabled by default.
Feature flag duo_agentic_chat enabled by default in GitLab 18.2.
JetBrains IDEs introduced in GitLab 18.2.
Changed to beta in GitLab 18.2.
Visual Studio for Windows introduced in GitLab 18.3.
Added to GitLab Duo Core in GitLab 18.3.
Feature flags duo_workflow_workhorse and duo_workflow_web_chat_mutation_tools removed in GitLab 18.4.
Introduced GitLab Duo Agent Platform on GitLab Self-Managed (both with self-hosted models and cloud-connected GitLab models) in GitLab 18.4 as an experiment with a feature flag named self_hosted_agent_platform. Disabled by default.
GitLab Duo Agent Platform on GitLab Self-Managed changed from experiment to beta in GitLab 18.5.
Updated default LLM to Claude Sonnet 4.5 in GitLab 18.6.
Feature flag self_hosted_agent_platform enabled in GitLab 18.7.
Updated default LLM to Claude Haiku 4.5 in GitLab 18.7.

The availability of this feature is controlled by feature flags. For more information, see the history.

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

Version history

Ability for Chat to remember your most recent conversation added in GitLab 18.4.
New navigation and GitLab Duo sidebar introduced on GitLab.com in GitLab 18.6 with a flag named paneled_view. Enabled by default.
Classic navigation instructions removed in GitLab 18.7.

The availability of the new navigation and GitLab Duo sidebar is controlled by a feature flag. For more information, see the history.

Prerequisites:

Ensure you meet the prerequisites.

To use Chat in the GitLab UI:

On the top bar, select Search or go to and find your project.
On the GitLab Duo sidebar, select either New GitLab Duo Chat ({pencil-square}) or Current GitLab Duo Chat ({duo-chat}). A Chat conversation opens in the GitLab Duo sidebar on the right side of your screen.
Under the chat text box, turn on the Agentic mode (Beta) toggle.
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.
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:

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

Then, to use GitLab Duo Chat:

On the left sidebar, select GitLab Duo Agent Platform (Beta) ({duo-agentic-chat}).
Select the Chat tab.
Select Refresh page if prompted.
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:

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

Then, to use GitLab Duo Chat:

On the left sidebar, select GitLab Duo Agent Platform (Beta) ({duo-agentic-chat}).
Select the Chat tab.
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:

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

Then, to use GitLab Duo Chat:

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

View the chat history

Version history

Chat history introduced on IDEs in GitLab 18.2.
Added for GitLab UI in GitLab 18.3.

To view your chat history:

In the GitLab UI, on the GitLab Duo sidebar, select GitLab Duo Chat history ({history}).
In your IDE, in the upper-right corner of the message box, select Chat history ({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

Version history

Multiple conversations introduced in GitLab 18.3.

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.

Open GitLab Duo Chat in the GitLab UI or your IDE.
Enter your question and press Enter or select Send.
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 ({pencil-square}).
  - 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 ({plus}).
Enter your question and press Enter or select Send.
To view all of your conversations, look at your chat history.
To switch between conversations, in your chat history, select the appropriate conversation.
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

Version history

Ability to delete a conversation introduced in GitLab 18.2.

In the GitLab UI or your IDE, select the chat history.
In the history, select Delete this chat ({remove}).

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

Create custom rules

Version history

Custom rules added in GitLab 18.2.
User-level custom rules added in GitLab 18.7.

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.

Conversations that existed before you created any custom rules do not follow those rules.

Create user-level custom rules

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

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

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

Save the file.
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.

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

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

Save the file.
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

Version history

Introduced in GitLab 18.7.

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 version v6.60 or later.
For a JetBrains IDE, install and configure the GitLab plugin for JetBrains version 3.26.0 or later.

Conversations that existed before you created any AGENTS.md files do not follow those instructions.

Create a user-level `AGENTS.md` file

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

Create the file in your user configuration directory:
- 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

Add instructions to the file. For example:

- I am still learning Rust, explain all Rust code at a beginner level
- Be brief in your explanations

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

You must do this every time you change the file.

Create workspace-level `AGENTS.md` files

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

In your project root, create a file named AGENTS.md.

Add instructions to the file. For example:

# Project Guidelines

This is a Ruby on Rails application using PostgreSQL.

- Follow Rails conventions for file organization
- Use RSpec for testing
- All API endpoints should be documented with OpenAPI

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

You must do this every time you change the 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.

The difference between `AGENTS.md` and `chat-rules.md`

You can use both AGENTS.md and chat-rules.md to provide instructions for GitLab Duo Chat. Choose which one to use based on your needs:

Use chat-rules.md to define instructions for GitLab only.
Use AGENTS.md to define instructions for GitLab and other AI coding tools that support the AGENTS.md specification.
Use AGENTS.md to define context-specific instructions for projects in nested directories within your workspace.

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

Select a model

Offering: GitLab.com, GitLab Self-Managed
Status: Beta

Version history

Introduced in GitLab 18.4 as a beta feature with a flag called ai_user_model_switching. Disabled by default.
Enabled in GitLab 18.4.
Available on GitLab Self-Managed in GitLab 18.6.
Added to VS Code and JetBrains IDEs in GitLab 18.6.
Feature flag ai_user_model_switching removed in GitLab 18.7.

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:

The Owner of the top-level group has not selected a model for the GitLab Duo Agent Platform. If a model has been selected for the group, you cannot change the model for Chat.
You must be using Chat in the top-level group. You cannot change the model if you access Chat in the organization.

Self-managed

The administrator has not selected a model for the instance. If a model has been selected for the instance, you cannot change the model for Chat.
Your instance must be connected to the GitLab AI gateway.

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) ({duo-agentic-chat}).
2. Select the Chat tab.
3. Select a model from the dropdown list.

Select an agent

Version history

Introduced in GitLab 18.4.
Added to VS Code and JetBrains IDEs in GitLab 18.5.

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:

In the GitLab UI or your IDE, open a new conversation in GitLab Duo Chat.
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.
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

Version history

Introduced in GitLab 18.7.

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

Capability	GitLab Duo Chat (Classic)	GitLab Duo Chat (Agentic)
Ask general programming questions	Yes	Yes
Get answers about an open file in the editor	Yes	Yes. Provide the path of the file in your question.
Provide context about specified files	Yes. Use `/include` to add a file to the conversation.	Yes. Provide the path of the file in your question.
Autonomously search project contents	No	Yes
Autonomously create files and change files	No	Yes. Ask it to change files. Note, it may overwrite changes that you have made manually and have not committed, yet.
Retrieve issues and MRs without specifying IDs	No	Yes. Search by other criteria. For example, an MR or issue's title or assignee.
Combine information from multiple sources	No	Yes
Analyze pipeline logs	Yes. Requires GitLab Duo Enterprise add-on.	Yes
Restart a conversation	Yes. Use `/new` or `/reset`.	Yes. Use `/new` or, if in the UI, `/reset`.
Delete a conversation	Yes, in the chat history.	Yes, in the chat history
Create issues and MRs	No	Yes
Use Git read-only commands	No	Yes
Use Git write commands	No	Yes, UI only
Run Shell commands	No	Yes, IDEs only
Run MCP tools	No	Yes, IDEs only

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.

Blog: GitLab Duo Chat gets agentic AI makeover

GitLab Duo Chat (Agentic)

Model information

Version history

Use GitLab Duo Chat

Use GitLab Duo Chat in the GitLab UI

Version history

Use GitLab Duo Chat in VS Code

Use GitLab Duo Chat in JetBrains IDEs

Use GitLab Duo Chat in Visual Studio

View the chat history

Version history

Have multiple conversations

Version history

Delete a conversation

Version history

Create custom rules

Version history

Create user-level custom rules

Create workspace-level custom rules

Update custom rules

Create AGENTS.md instruction files

Version history

Create a user-level AGENTS.md file

Create workspace-level AGENTS.md files

Use AGENTS.md in monorepos and subdirectories

The difference between AGENTS.md and chat-rules.md

Select a model

Version history

Self-managed

Select an agent

Version history

Prompt caching

Version history

Turn off prompt caching

Chat feature comparison

Troubleshooting

Feedback

Related topics

Create `AGENTS.md` instruction files

Create a user-level `AGENTS.md` file

Create workspace-level `AGENTS.md` files

Use `AGENTS.md` in monorepos and subdirectories

The difference between `AGENTS.md` and `chat-rules.md`