# Contributing to Gobi Documentation
Source: https://docs.gourmand.dev/CONTRIBUTING

Welcome to the Gobi documentation! We're excited that you want to contribute. This guide will help you get started with our documentation workflow and tools.

## 🚀 Quick Start

### Prerequisites

1. **Node.js** (v20 or higher)
2. **Git** for version control
3. **GitHub CLI** - Install from [cli.github.com](https://cli.github.com/)

### Setup Steps

1. **Fork and clone the repository**

   ```bash  theme={null}
   # Fork the repository (this will also clone it locally)
   gh repo fork gourmand/gobi
   cd gobi/docs
   ```

2. **Install dependencies**

   ```bash  theme={null}
   npm install
   ```

3. **Start the local development server**
   ```bash  theme={null}
   npm run dev
   ```
   Your docs will be available at `http://localhost:3000`

## 💬 Creating Discussions and Issues

Before creating any issues, we ask that you start with a GitHub Discussion. This helps us organize feedback and determine the best path forward.

### Starting a Discussion

<Steps>
  <Step title="Go to GitHub Discussions">
    Visit the [Gobi GitHub Discussions](https://github.com/gourmand/gobi/discussions) page.
  </Step>

  <Step title="Choose the right category">
    Select the **Docs** category for documentation improvements, corrections, or suggestions.
  </Step>

  <Step title="Provide detailed information">
    Include the following in your discussion:

    * Clear description of the issue or suggestion
    * Steps to reproduce (if applicable)
    * Expected vs. actual behavior
    * Screenshots or code examples when helpful
    * Your environment (OS, IDE, Gobi version)
  </Step>
</Steps>

### Issue Escalation Process

<Info>
  **Important**: All issues should start as discussions. The Gobi team will determine if and when a discussion should be escalated to a GitHub issue.
</Info>

The Gobi team will review discussions and may:

* Provide a solution or clarification directly in the discussion
* Ask for additional information or testing
* Convert the discussion to an issue if it requires code changes or is a confirmed bug
* Close the discussion if it's resolved or not actionable

### When Discussions Become Issues

A discussion will typically be converted to an issue when:

* A bug in the documentation is confirmed
* A new feature or significant documentation change is approved
* Community consensus supports the proposed change
* Technical implementation is required

## 🤖 AI-Powered Documentation with Gobi

We strongly encourage using Gobi's AI assistance to maintain consistency and quality in our documentation. Here are three ways to set this up:

### Option 1: Use the Pre-Built Documentation Agent (Recommended)

The easiest way to get started is using our pre-configured documentation agent:

<Steps>
  <Step title="Install the agent from Gobi Hub">
    Visit [the Docs Assistant - Mintlify in the Hub](https://hub.gourmand.dev/gobi/docs-mintlify) and click "Install" to add it to your Gobi setup. This agent comes pre-configured with all our documentation standards.

    <Info>
      Learn more about Gobi Configs in our [config documentation](/guides/understanding-configs).
    </Info>
  </Step>

  <Step title="Use the agent">
    <Tabs>
      <Tab title="Command Line">
        ```bash  theme={null}
        # Install the Gobi CLI if you haven't already
        npm install -g @gourmanddev/cli

        # Use the agent from the command line
        cn "Create a new guide for using the Gobi CLI with Linear" --config gourmand/docs-mintlify
        ```
      </Tab>

      <Tab title="IDE">
        1. Open Gobi in your IDE
        2. Select the "Docs Assistant - Mintlify" agent from the model dropdown
        3. Ask it to help you create or edit documentation

        Example prompts:

        * "Create a new guide for using the Gobi CLI with Linear"
        * "Update the getting-started guide with the new installation process"
        * "Format this documentation according to Mintlify standards"
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Tip>
  You can also remix this config to customize it for your specific needs. Learn how to create your own remix in our [remix config documentation](/hub/configs/create-a-config#how-to-remix-a-config).
</Tip>

### Option 2: Create Your Own Custom Agent

If you want more control or customization, you can create your own documentation agent:

<Steps>
  <Step title="Create a new config">
    Follow our [config creation guide](/hub/configs/create-a-config) to set up your own config.
  </Step>

  <Step title="Add the Gobi Docs MCP">
    Install from Gobi Hub: [https://hub.gourmand.dev/gourmand/gobi-docs-mcp](https://hub.gourmand.dev/gourmand/gobi-docs-mcp)

    This MCP provides context about Gobi's documentation structure and standards.
  </Step>

  <Step title="Add Mintlify formatting rules">
    Install from Gobi Hub: [https://hub.gourmand.dev/mintlify/technical-writing-rule](https://hub.gourmand.dev/mintlify/technical-writing-rule)

    This rule ensures proper Mintlify component formatting.
  </Step>

  <Step title="Use your custom agent">
    <Tabs>
      <Tab title="Command Line">
        ```bash  theme={null}
        # Install the Gobi CLI if you haven't already
        npm install -g @gourmanddev/cli

        # Use your agent from the command line
        cn --config your-org/your-agent-name "Create a new guide for API authentication"
        ```
      </Tab>

      <Tab title="IDE">
        1. Open Gobi in your IDE
        2. Select your custom agent from the model dropdown
        3. Ask it to help you create or edit documentation

        Example prompts:

        * "Help me format this documentation according to Mintlify standards"
        * "Create a troubleshooting section for this feature"
      </Tab>
    </Tabs>
  </Step>
</Steps>

## 📝 Documentation Standards

### Mintlify Component Guidelines

When using Mintlify components, follow these formatting rules:

#### Cards and Info Boxes

```mdx  theme={null}
<Card title="Best Practice" icon="lightbulb">

Always include blank lines and proper indentation:

- Use 2-space indentation
- Add blank lines after opening tags
- Format lists as bullet points

</Card>
```

#### Warning and Note Components

```mdx  theme={null}
<Warning>

Important information should be formatted clearly:

- Each point on its own line
- Consistent indentation
- Clear, concise language

</Warning>
```

### Writing Style

1. **Be concise**: Get to the point quickly
2. **Use examples**: Show, don't just tell
3. **Include code blocks**: Provide working examples
4. **Add visuals**: Screenshots and diagrams help understanding
5. **Test your changes**: Ensure all links and code examples work

<Warning>
  If you are creating a new guide, please test the steps yourself to ensure accuracy.
</Warning>

## 🔧 Common Tasks

### Adding a New Guide

1. Create a new `.mdx` file in the guides directory
2. Add frontmatter:
   ```mdx  theme={null}
   ---
   title: "Your Guide Title"
   description: "Brief description of what this guide covers"
   ---
   ```
3. Use the Gobi agent to help format your content
4. Update `docs.json` to include your new page in the navigation

<Tip>
  We have both guides and cookbooks. Use guides for step-by-step instructions and cookbooks for creating agents for the CLI.
</Tip>

### Updating Existing Documentation

1. Use the Gobi agent with prompts like:
   * "Update the installation guide with the new npm package"
   * "Add a troubleshooting section for connection issues"
2. The agent will maintain consistent formatting automatically

### Adding Code Examples

Use language-specific code blocks:

````mdx  theme={null}
```typescript
// Your TypeScript code here
const example = "Hello, Gobi!";
```
````

## 🐛 Testing Your Changes

1. **Local preview**: In the docs directory, run `npm run dev` and check your changes
2. **Link validation**: Ensure all internal and external links work
3. **Format check**: Use the Gobi agent to validate Mintlify formatting
4. **Build test**: Run `npm run build` to ensure no build errors

## 📤 Submitting Your Contribution

1. **Create a feature branch**

   ```bash  theme={null}
   git checkout -b docs/your-feature-name
   ```

2. **Commit your changes**

   ```bash  theme={null}
   git add .
   git commit -m "docs: describe your changes"
   ```

3. **Push and create a Pull Request**

   ```bash  theme={null}
   # Push to your fork and create a PR
   git push origin docs/your-feature-name
   gh pr create --web
   ```

<Tip>
  The `gh pr create` command will automatically:

  * Push your branch to your fork
  * Create a pull request to the main repository
  * Allow you to add a title, description, and reference issues
  * Open the PR in your browser if using `--web`
</Tip>

## 💡 Tips for Success

* **Use the Gobi agent**: It knows our documentation standards and will save you time
* **Preview frequently**: Check your changes in the local dev server
* **Ask questions**: Open an issue or discussion if you need clarification
* **Small PRs are better**: Focus on one topic or fix per PR
* **Update examples**: Ensure code examples reflect the latest API

## 🆘 Getting Help

* **Start a Discussion**: Use [GitHub Discussions](https://github.com/gourmand/gobi/discussions) for documentation issues, suggestions, or questions
* **Gobi agent questions**: Check the [Gobi Hub page](https://hub.gourmand.dev/gobi/docs-mintlify)
* **Discord community**: Join our Discord for real-time help
* **Existing docs**: Review similar pages for formatting examples

***

Thank you for contributing to Gobi! Your efforts help make our documentation better for everyone. To learn more about contibuting to other parts of the project, check out our [main CONTRIBUTING guide](https://github.com/gourmand/gobi/blob/main/CONTRIBUTING.md) 🎉


# Guides
Source: https://docs.gourmand.dev/cli/guides





# Install Gobi CLI
Source: https://docs.gourmand.dev/cli/install

Get Gobi CLI installed and configured for command-line AI coding assistance and automation

<iframe width="100%" height="400" src="https://www.youtube.com/embed/vm9RcP9xM4o" title="Install Gobi CLI" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

<Info>
  Make sure you have [Node.js 18 or higher
  installed](https://nodejs.org/en/download/).
</Info>

## Installation

Install Gobi CLI globally using npm:

```bash  theme={null}
npm i -g @gourmanddev/cli
```

## Two Ways to Use Gobi CLI

<Info>
  **Quick Overview**: Gobi CLI works in two modes - TUI for interactive
  conversations or headless for automated commands.
</Info>

<Tabs>
  <Tab title="TUI Mode">
    **Interactive development sessions**

    Start a conversation with AI in your terminal:

    ```bash  theme={null}
    cn
    > @src/app.js Generate unit tests for this component
    ```

    Perfect for exploration, debugging, and iterative development.
  </Tab>

  <Tab title="Headless Mode">
    **Automation and scripting**

    Single commands that return results:

    ```bash  theme={null}
    cn -p "Generate a commit message for current changes"
    cn -p "Review the last 5 commits for issues"
    ```

    Perfect for CI/CD, git hooks, and automated workflows.
  </Tab>
</Tabs>

## Setup

<Tabs>
  <Tab title="cn TUI Mode">
    For interactive development and exploration:

    <Steps>
      <Step title="Login to Gobi CLI">
        ```bash  theme={null}
        cn login
        ```

        This will open your browser to authenticate with Gobi Hub.
      </Step>

      <Step title="Test TUI Mode">
        Start an interactive session:

        ```bash  theme={null}
        cn
        ```

        Try asking a question:

        ```
        > Tell me about the CLI
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="cn Headless Mode">
    For automation workflows and scripting:

    <Steps>
      <Step title="Get API Key for Automation">
        For automation workflows, get an API key:

        1. Visit [Gobi Hub API Keys](https://hub.gourmand.dev/settings/api-keys)
        2. Click **"+ New API Key"**
        3. Copy the API key immediately (you won't see it again!)
        4. Login using your Gobi account
      </Step>

      <Step title="Add Secrets for Workflows">
        Store secure credentials for CLI workflows:

        1. Visit [Gobi Hub Secrets](https://hub.gourmand.dev/settings/secrets)
        2. Add your API keys and sensitive data
        3. Reference in configurations with `${{ secrets.SECRET_NAME }}`
      </Step>

      <Step title="Test Headless Mode">
        Try headless mode for automation:

        ```bash  theme={null}
        cn -p "Generate a conventional commit message for the current git changes"
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## What's Next?

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/cli/quick-start">
    Learn basic usage with practical examples
  </Card>

  <Card title="Create your first workflow" icon="gear" href="/guides/posthog-github-continuous-ai">
    Build automated workflows with Gobi CLI
  </Card>
</CardGroup>

## Getting Help

If you encounter issues:

* Ask for help in [our discussions](https://github.com/gourmand/gobi/discussions)
* Report bugs on [GitHub](https://github.com/gourmand/gobi)


# Gobi CLI (cn) Overview
Source: https://docs.gourmand.dev/cli/overview

Command-line interface for automated coding tasks, scripting, and headless development workflows with Gobi's AI coding capabilities

<Frame>
  <img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/cn-demo.gif?s=ddde6a7d2225ae03a2c489daf29324ba" data-og-width="1588" width="1588" data-og-height="1080" height="1080" data-path="images/cn-demo.gif" data-optimize="true" data-opv="3" />
</Frame>

**Gobi enables developers to ship faster with Continuous AI.**

<Tip>
  Build features from descriptions. Debug and fix issues. Navigate any codebase.
  Automate tedious tasks.
</Tip>

## Get started in 30 seconds

Prerequisites:

* [Node.js 18 or newer](https://nodejs.org/en/download/)
* A [Gobi Hub](https://hub.gourmand.dev) account (recommended) or local configuration

```bash npm theme={null}
# Install Gobi CLI
npm install -g @gourmanddev/cli

# Navigate to your project

cd your-awesome-project

# Start coding with Gobi

cn

# You'll be prompted to set up on first use

```

That's it! You're ready to start automating with Gobi CLI.

[Gobi with CLI Quickstart →](/cli/quick-start)

## Two Ways to Use Gobi CLI

Gobi CLI offers two distinct modes designed for different workflows:

### TUI Mode: Interactive Development

**Perfect for exploration, debugging, and iterating on AI workflows**

```bash  theme={null}
cn
> @src/components/UserProfile.js Review this component for security issues
> Generate comprehensive unit tests
> Suggest performance improvements
```

* **Interactive conversations** with your codebase
* **Iterate and refine** prompts and approaches
* **Explore and understand** complex codebases
* **Perfect for experimentation** and learning

### Headless Mode: Production Automation

**Perfect for CI/CD, automation, and reliable workflows**

```bash  theme={null}
cn -p "Generate a conventional commit message for staged changes"
cn -p "Review pull request changes for security vulnerabilities"
cn -p "Update documentation based on recent code changes"
```

* **Single-command execution** for automation
* **Reliable, repeatable results** for production use
* **CI/CD and pipeline integration**
* **Git hooks and automated workflows**

### Development Workflow: TUI → Headless

<Tip>
  **Pro Tip**: Start in TUI mode to iterate on your AI agent. Once
  you have a workflow that works reliably, deploy it as a Continuous AI
  automation.
</Tip>

1. **Experiment in TUI mode** to perfect your agent
2. **Test different approaches** interactively until you get consistent results
3. **Convert successful workflows** to automated Continuous AI commands
4. **Deploy in production** with confidence in your proven approach

## Why developers love Gobi CLI

* **Works in your terminal**: Not another chat window. Not another IDE. Gobi CLI meets you where you already work, with the tools you already love.
* **Takes action**: Gobi CLI can directly edit files, run commands, and create commits. Need more? Check out our [MCPs](/customize/deep-dives/mcp).
* **Automate tasks**: Create issues from PostHog data, automatically assign labels to issues, and more. Do all this in a single command from your developer machines, or automatically in CI.
* **Flexible development flow**: Start interactive, then automate proven workflows.

## Key Capabilities

### Context Engineering

* Use `@` to reference files and provide context
* Use `/` to run slash commands for specific tasks
* Access the same context providers as IDE extensions

### Tool Integration

* File editing and creation
* Terminal command execution
* Codebase understanding and analysis
* Git integration
* Web search and documentation access

### Model Flexibility

* Switch between models with `/model` command
* Use any model configured in your `config.yaml`
* Access Gobi Hub models and configurations

## Gobi Hub Integration

Gobi CLI integrates seamlessly with [Gobi Hub](https://hub.gourmand.dev) for:

### API Access

Get an API key for automation workflows:

1. Visit [Gobi Hub API Keys](https://hub.gourmand.dev/settings/api-keys)
2. Create a new API key
3. Use with `cn login` or in your automation scripts

### Secrets Management

Store secure credentials for CLI workflows:

1. Visit [Gobi Hub Secrets](https://hub.gourmand.dev/settings/secrets)
2. Add your API keys and sensitive data
3. Reference in configurations with `${{ secrets.SECRET_NAME }}`

### Configuration Sync

* Cloud-managed configurations automatically sync
* Share configurations across team members
* Version control for your AI workflows

## Common Use Cases

### TUI Mode Examples

**Interactive development and exploration:**

<CodeGroup>
  ```bash Codebase Exploration theme={null}
  # Start interactive session
  cn
  > @src/components Find all unused React components
  > /explain How does authentication work in this codebase?
  > @auth/ What security patterns are used here?
  ```

  ```bash Iterative Debugging theme={null}
  # Debug issues interactively
  cn
  > @tests/auth.test.js This test is failing, help me understand why
  > @src/auth/middleware.js Let's examine this middleware
  > /debug What could be causing the timeout error?
  ```

  ```bash Workflow Development theme={null}
  # Develop and test automation workflows
  cn
  > @package.json @CHANGELOG.md Generate a release notes template
  > # Test and refine the approach
  > # Once working, convert to: cn -p "Generate release notes"
  ```
</CodeGroup>

### Headless Mode Examples

**Production automation and scripting:**

<CodeGroup>
  ```bash Git Automation theme={null}
  # Generate commit messages
  cn -p "Generate a conventional commit message for the current changes"

  # Code review automation

  cn -p "Review the current git changes for bugs and suggest improvements"

  ```

  ```bash CI/CD Integration theme={null}
  # In your pipeline scripts
  cn -p "Analyze test failures and suggest fixes"

  # Automated documentation updates
  cn -p "@README.md Update this documentation based on recent changes"
  ```

  ```bash Issue Management theme={null}
  # Create GitHub issues from PostHog data
  cn -p "@posthog-data.json Create GitHub issues for UX problems found in this session data"

  # Automated security audits
  cn -p "Scan the codebase for potential security vulnerabilities"
  ```
</CodeGroup>

## Next steps

<CardGroup cols={3}>
  <Card title="CLI Quickstart" href="/cli/quick-start">
    Learn basic commands and common workflows
  </Card>

  <Card title="Installation Guide" href="/cli/install">
    Install Gobi CLI and set up your environment
  </Card>

  <Card title="CLI Workflows" href="/guides/overview#continuous-ai">
    Task-specific tutorials and examples
  </Card>
</CardGroup>


# Gobi CLI Quick Start
Source: https://docs.gourmand.dev/cli/quick-start

Get hands-on experience with Gobi CLI through practical examples and common use cases

Get hands-on experience with Gobi CLI through practical development workflows.

<Tabs>
  <Tab title="TUI Mode">
    TUI Mode (`cn` command) is for **large development tasks** that require
    agentic workflows with human oversight. Perfect for complex refactors,
    feature implementation, or one-off automation tasks that need monitoring and
    iteration.
  </Tab>

  <Tab title="Headless Mode">
    Headless Mode (`-p` flag) is for **reliable, repeatable tasks** that no
    longer need constant supervision. Perfect for CI/CD pipelines, git hooks,
    and automated workflows you've already tested and refined.
  </Tab>
</Tabs>

## TUI Mode: Large Development Tasks

Make sure you have [Gobi CLI installed](/cli/install) and are in a project directory.

### Example: Implementing a New Feature

```bash  theme={null}
# Navigate to your project directory
cd your-awesome-project

# Start TUI Mode for complex development work
cn
```

**Example workflow for adding authentication:**

```
> I need to add JWT authentication to this Express app. Let me start by showing you the current structure.

> @src/app.js @package.json Here's my current setup. Can you implement JWT auth with middleware, login/register routes, and user model?

> [Agent analyzes codebase and implements auth system]
> [You review changes, test, and provide feedback]
> [Agent iterates based on your input until the feature is complete]
```

### Example: Complex Refactoring

```bash  theme={null}
cn
```

**Refactoring a monolithic component:**

```
> @src/components/Dashboard.jsx This component is 800 lines and does too much. Help me break it into smaller, reusable components.

> [Agent analyzes component structure]
> [Proposes component breakdown strategy]
> [You approve approach]
> [Agent implements the refactor with proper props and state management]
> [You test and request adjustments]
```

### When to Use TUI Mode

✅ **Large development tasks** that need oversight\
✅ **Complex refactors** requiring multiple steps\
✅ **New feature implementation** with unknowns\
✅ **One-off automation tasks** you haven't done before\
✅ **Debugging complex issues** that need exploration

## Headless Mode: Automated Workflows

Once you've refined a workflow in TUI Mode, convert it to Continuous AI for automation.

### Example: From REPL → Continuous AI

**Step 1: Develop in TUI Mode**

```bash  theme={null}
cn
> @package.json @CHANGELOG.md Generate release notes for version 2.1.0
> [Test and refine the prompt until it works perfectly]
```

**Step 2: Convert to Continuous AI**

```bash  theme={null}
# Now use the refined workflow in automation
cn -p "Generate release notes for the current version based on package.json and recent commits"
```

### Common Continuous AI Workflows

```bash  theme={null}
# Git automation
cn -p "Generate a conventional commit message for staged changes"
cn -p "Review the last 3 commits for potential issues"

# Code quality
cn -p "Fix all TypeScript errors in the src/ directory"
cn -p "Update outdated dependencies and fix breaking changes"

# Documentation
cn -p "@README.md Update documentation based on recent changes"
cn -p "Generate API documentation from JSDoc comments"

# CI/CD integration
cn -p "Analyze test failures and create GitHub issue with findings"
cn -p "Update version numbers and create release branch"
```

### When to Use Headless Mode

✅ **Proven workflows** you've tested in TUI Mode\
✅ **Repetitive tasks** that no longer need oversight\
✅ **CI/CD automation** in pipelines\
✅ **Git hooks** for automated checks\
✅ **Scheduled tasks** that run unattended

### Available Slash Commands

Common slash commands available in CLI:

* `/clear` - Clear the chat history
* `/compact` - Summarize chat history into a compact form
* `/config` - Switch configuration or organization
* `/exit` - Exit the chat
* `/fork` - Start a forked chat session from the current history
* `/help` - Show help message
* `/info` - Show session information
* `/init` - Create an AGENTS.md file
* `/login` - Authenticate with your account
* `/logout` - Sign out of your current session
* `/mcp` - Manage MCP server connections
* `/model` - Switch between available chat models
* `/resume` - Resume a previous chat session
* `/whoami` - Check who you're currently logged in as

<Info>Use `/help` to see all available commands.</Info>

## The Development Workflow

<Info>
  **Recommended Approach**: Start complex tasks in TUI Mode to iterate and
  refine your approach. Once you have a reliable workflow, convert it to
  Headless Mode for automation.
</Info>

### Workflow Pattern

1. **🔬 Experiment in TUI Mode**

   * Try complex development tasks with human oversight
   * Iterate on prompts and approaches until they work reliably
   * Test edge cases and refine the agent's behavior

2. **⚡ Automate with Continuous AI**
   * Convert proven REPL workflows to single commands
   * Deploy in CI/CD, git hooks, or scheduled tasks
   * Run with confidence knowing the approach is tested

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Your First Workflow" href="/guides/posthog-github-continuous-ai">
    Build an automated PostHog to GitHub issues workflow
  </Card>

  <Card title="Continuous AI Guide" href="/guides/continuous-ai">
    Learn to build and deploy AI-powered development workflows
  </Card>
</CardGroup>


# MCP servers
Source: https://docs.gourmand.dev/customization/mcp-tools

Learn how to use Model Context Protocol (MCP) blocks in Gobi to integrate external tools, connect databases, and extend your development environment.

Model Context Protocol (MCP) servers let Gobi connect to external tools, systems, and databases by running MCP servers.

These servers make it possible to:

* **Enable integration** with external tools and systems
* **Create extensible interfaces** for custom capabilities
* **Support complex interactions** with your development environment
* **Allow partners** to contribute specialized functionality
* **Connect to databases** to understand schema and data models during development

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/mcp-blocks-overview-c9a104f9b586779c156f9cf34da197c2.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=6281f08e366c2fcd339f4982c80cb70d" alt="MCP servers overview" data-og-width="3156" width="3156" data-og-height="2112" height="2112" data-path="images/customization/images/mcp-blocks-overview-c9a104f9b586779c156f9cf34da197c2.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/mcp-blocks-overview-c9a104f9b586779c156f9cf34da197c2.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=996457708c64361acbfa0172c3f3fc13 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/mcp-blocks-overview-c9a104f9b586779c156f9cf34da197c2.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=88f79061e5345d22562ffa772c88af41 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/mcp-blocks-overview-c9a104f9b586779c156f9cf34da197c2.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=d77822833fba87c644229b11b3e2b016 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/mcp-blocks-overview-c9a104f9b586779c156f9cf34da197c2.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=19dfcc6686aaf856ddebd6cf7a37d6d3 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/mcp-blocks-overview-c9a104f9b586779c156f9cf34da197c2.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=214aa3f7bdabf1047afdc0a6febde83e 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/mcp-blocks-overview-c9a104f9b586779c156f9cf34da197c2.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=f91fd15e1c1b6b426ec9eca7043b0577 2500w" />

## Learn More About MCP servers

Learn more in the [MCP deep dive](/customize/deep-dives/mcp), and view [`mcpServers`](/reference#mcpservers) in the YAML Reference for more details.


# Models
Source: https://docs.gourmand.dev/customization/models

Models form the foundation of the entire agent experience, offering different specialized capabilities:

export const ModelRecommendations = ({role = "all"}) => {
  const parseMarkdownLinks = text => {
    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const parts = [];
    let lastIndex = 0;
    let match;
    let key = 0;
    while ((match = regex.exec(text)) !== null) {
      if (match.index > lastIndex) {
        const beforeText = text.slice(lastIndex, match.index);
        if (beforeText) {
          parts.push(<span key={key++}>{beforeText}</span>);
        }
      }
      const [, linkText, url] = match;
      parts.push(<a key={key++} href={url} target="_blank" rel="noopener noreferrer" style={{
        color: "#0066cc",
        textDecoration: "underline"
      }}>
          {linkText}
        </a>);
      lastIndex = regex.lastIndex;
    }
    if (lastIndex < text.length) {
      const remainingText = text.slice(lastIndex);
      if (remainingText) {
        parts.push(<span key={key++}>{remainingText}</span>);
      }
    }
    return parts.length > 0 ? parts : text;
  };
  const modelRecs = {
    agent_plan: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[Devstral (27B)](https://hub.gourmand.dev/ollama/devstral)", "[Kimi K2 (1T)](https://hub.gourmand.dev/openrouter/kimi-k2)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)", "[GLM 4.5 (355B)](https://hub.gourmand.dev/openrouter/glm-4-5)", "[GLM 4.5 Air (106B)](https://hub.gourmand.dev/openrouter/glm-4-5-air)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed models are slightly better than open models"
    },
    chat_edit: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed and open models have pretty similar performance"
    },
    autocomplete: {
      open: ["[QwenCoder2.5 (1.5B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)", "[QwenCoder2.5 (7B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)"],
      closed: ["[Codestral](https://hub.gourmand.dev/mistral/codestral)", "[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are slightly better than open models"
    },
    apply: {
      open: ["N/A"],
      closed: ["[Relace Instant Apply](https://hub.gourmand.dev/relace/instant-apply)", "[Morph Fast Apply](https://hub.gourmand.dev/morphllm/morph-v2)"],
      notes: "Open models are not good enough for this model role"
    },
    embed: {
      open: ["[Nomic Embed Text](https://hub.gourmand.dev/ollama/nomic-embed-text-latest)", "Qwen3 Embedding"],
      closed: ["[Voyage Code 3](https://hub.gourmand.dev/voyageai/voyage-code-3)", "[Morph Embeddings](https://hub.gourmand.dev/morphllm/morph-embedding-v2)", "Codestral Embed"],
      notes: "Closed models are slightly better than open models"
    },
    rerank: {
      open: ["zerank-1", "zerank-1-small", "Qwen3 Reranker"],
      closed: ["[Voyage Rerank 2.5](https://hub.gourmand.dev/voyageai/rerank-2-5)", "Relace Code Rerank", "[Morph Rerank](https://hub.gourmand.dev/morphllm/morph-rerank-v2)"],
      notes: "Open models are beginning to emerge for this model role"
    },
    next_edit: {
      open: ["[Instinct](https://hub.gourmand.dev/gobi/instinct)"],
      closed: ["[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are better than open models"
    }
  };
  let rolesToShow = [];
  if (!role || role === "all") {
    rolesToShow = Object.keys(modelRecs);
  } else {
    const key = role.toLowerCase().replace(/\s|\//g, "_").replace(/-/g, "_");
    if (modelRecs[key]) {
      rolesToShow = [key];
    }
  }
  if (rolesToShow.length === 0) {
    return <div>No recommendations found for role: {role}</div>;
  }
  return <table style={{
    width: "100%",
    borderCollapse: "collapse",
    marginTop: "1rem"
  }}>
      <thead>
        <tr>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Model role
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best open models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best closed models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Notes
          </th>
        </tr>
      </thead>
      <tbody>
        {rolesToShow.map(roleKey => {
    const rec = modelRecs[roleKey];
    if (!rec) return null;
    return <tr key={roleKey}>
              <td style={{
      fontWeight: 600,
      verticalAlign: "top",
      padding: "8px"
    }}>
                {roleKey.replace(/_/g, " ").replace(/\b\w/g, l => l.toUpperCase())}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.open.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.closed.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.notes}
              </td>
            </tr>;
  })}
      </tbody>
    </table>;
};

* **[Chat](/customize/model-roles/chat)**: Power conversational interactions about code and provide detailed guidance
* **[Edit](/customize/model-roles/edit)**: Handle complex code transformations and refactoring tasks
* **[Apply](/customize/model-roles/apply)**: Execute targeted code modifications with high accuracy
* **[Autocomplete](/customize/model-roles/autocomplete)**: Provide real-time suggestions as developers type
* **[Embedding](/customize/model-roles/embeddings)**: Transform code into vector representations for semantic search
* **[Reranker](/customize/model-roles/reranking)**: Improve search relevance by ordering results based on semantic meaning

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/model-blocks-overview-36c30e7e01928d7a9b5b26ff1639c34b.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=b8561677ba3ce9b6ee8d79542f39232f" alt="Models Overview" data-og-width="3156" width="3156" data-og-height="2112" height="2112" data-path="images/customization/images/model-blocks-overview-36c30e7e01928d7a9b5b26ff1639c34b.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/model-blocks-overview-36c30e7e01928d7a9b5b26ff1639c34b.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=3c465ddaea4433a1a1af85f5f9c13a4c 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/model-blocks-overview-36c30e7e01928d7a9b5b26ff1639c34b.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=d3832f50691e50075bcbcd214f5c527b 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/model-blocks-overview-36c30e7e01928d7a9b5b26ff1639c34b.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=25fce89105a79292d2f4811ae93e3cef 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/model-blocks-overview-36c30e7e01928d7a9b5b26ff1639c34b.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=5f9283c59a912d527ce7f0bcd61f96f7 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/model-blocks-overview-36c30e7e01928d7a9b5b26ff1639c34b.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=f424dc1d85d93df9637f98b44fc7f005 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/model-blocks-overview-36c30e7e01928d7a9b5b26ff1639c34b.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=e13193edff21a19eb06ad8b676c43a8c 2500w" />

## Recommended Models

### Best Models by Role

<ModelRecommendations role="all" />

## Learn More About Models

Gobi supports [many model providers](/customize/model-providers/top-level/openai), including Anthropic, OpenAI, Gemini, Ollama, Amazon Bedrock, Azure, xAI, and more. Models can have various roles like `chat`, `edit`, `apply`, `autocomplete`, `embed`, and `rerank`.

Read more about [model roles](/customize/model-roles), [model capabilities](/customize/deep-dives/model-capabilities) and view [`models`](/reference#models) in the YAML Reference.

### Example Model Setup Instructions

# Frontier Models

[Claude 4 Sonnet](https://hub.gourmand.dev/anthropic/claude-4-sonnet) from Anthropic

1. Get your API key from [Anthropic](https://console.anthropic.com/)
2. Add [Claude 4 Sonnet](https://hub.gourmand.dev/anthropic/claude-4-sonnet) to a config on Gobi Hub
3. Add `ANTHROPIC_API_KEY` as a [User Secret](https://docs.gourmand.dev/hub/secrets/secret-types#user-secrets) on Gobi Hub [here](https://hub.gourmand.dev/settings/secrets)
4. Click `Reload config` in the config selector in the Gobi IDE extension

[Qwen Coder 3 480B](https://hub.gourmand.dev/openrouter/qwen3-coder) from Qwen

1. Get your API key from [OpenRouter](https://openrouter.ai/settings/keys)
2. Add [Qwen Coder 3 480B](https://hub.gourmand.dev/openrouter/qwen3-coder)  a config on Gobi Hub
3. Add `OPENROUTER_API_KEY` as a [User Secret](https://docs.gourmand.dev/hub/secrets/secret-types#user-secrets) on Gobi Hub [here](https://hub.gourmand.dev/settings/secrets)
4. Click `Reload config` in the config selector in the Gobi IDE extension

[GPT-5](https://hub.gourmand.dev/openai/gpt-5) from OpenAI

1. Get your API key from [OpenAI](https://platform.openai.com)
2. Add [GPT-5](https://hub.gourmand.dev/openai/gpt-5)  a config on Gobi Hub
3. Add `OPENAI_API_KEY` as a [User Secret](https://docs.gourmand.dev/hub/secrets/secret-types#user-secrets) on Gobi Hub [here](https://hub.gourmand.dev/settings/secrets)
4. Click `Reload config` in the config selector in the Gobi IDE extension

[Kimi K2](https://hub.gourmand.dev/openrouter/kimi-k2) from Moonshot AI

1. Get your API key from [OpenRouter](https://openrouter.ai/settings/keys)
2. Add [Kimi K2](https://hub.gourmand.dev/openrouter/kimi-k2)  a config on Gobi Hub
3. Add `OPENROUTER_API_KEY` as a [User Secret](https://docs.gourmand.dev/hub/secrets/secret-types#user-secrets) on Gobi Hub [here](https://hub.gourmand.dev/settings/secrets)
4. Click `Reload config` in the config selector in the Gobi IDE extension

[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro) from Google

1. Get your API key from [Google AI Studio](https://aistudio.google.com)
2. Add [Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)  a config on Gobi Hub
3. Add `GEMINI_API_KEY` as a [User Secret](https://docs.gourmand.dev/hub/secrets/secret-types#user-secrets) on Gobi Hub [here](https://hub.gourmand.dev/settings/secrets)
4. Click `Reload config` in the config selector in the Gobi IDE extension

[Grok Code Fast 1](https://hub.gourmand.dev/xai/grok-code-fast-1) from xAI

1. Get your API key from [xAI](https://console.x.ai/)
2. Add [Grok Code Fast 1](https://hub.gourmand.dev/xai/grok-code-fast-1)  a config on Gobi Hub
3. Add `XAI_API_KEY` as a [User Secret](https://docs.gourmand.dev/hub/secrets/secret-types#user-secrets) on Gobi Hub [here](https://hub.gourmand.dev/settings/secrets)
4. Click `Reload config` in the config selector in the Gobi IDE extension

[Devstral Medium](https://hub.gourmand.dev/mistral/devstral-medium) from Mistral AI

1. Get your API key from [Mistral AI](https://console.mistral.ai/)
2. Add [Devstral Medium](https://hub.gourmand.dev/mistral/devstral-medium)  a config on Gobi Hub
3. Add `MISTRAL_API_KEY` as a [User Secret](https://docs.gourmand.dev/hub/secrets/secret-types#user-secrets) on Gobi Hub [here](https://hub.gourmand.dev/settings/secrets)
4. Click `Reload config` in the config selector in the Gobi IDE extension

[gpt-oss-120b](https://hub.gourmand.dev/openrouter/gpt-oss-120b) from OpenAI

1. Get your API key from [OpenRouter](https://openrouter.ai/settings/keys)
2. Add [gpt-oss-120b](https://hub.gourmand.dev/openrouter/gpt-oss-120b)  a config on Gobi Hub
3. Add `OPENROUTER_API_KEY` as a [User Secret](https://docs.gourmand.dev/hub/secrets/secret-types#user-secrets) on Gobi Hub [here](https://hub.gourmand.dev/settings/secrets)
4. Click `Reload config` in the config selector in the Gobi IDE extension

### Local Models

These models can be run on your computer if you have enough VRAM.

Their limited tool calling and reasoning capabilities will make it challenging to use agent mode.

[Qwen3 Coder 30B](https://hub.gourmand.dev/ollama/qwen3-coder-30b)

1. Add [Qwen3 Coder 30B](https://hub.gourmand.dev/ollama/qwen3-coder-30b)  a config on Gobi Hub
2. Run the model with [Ollama](https://docs.gourmand.dev/guides/ollama-guide#using-ollama-with-gobi-a-developers-guide)
3. Click `Reload config` in the config selector in the Gobi IDE extension

[gpt-oss-20b](https://hub.gourmand.dev/ollama/gpt-oss-20b)

1. Add [gpt-oss-20b](ttps://hub.gourmand.dev/ollama/gpt-oss-20b)  a config on Gobi Hub
2. Run the model with [Ollama](https://docs.gourmand.dev/guides/ollama-guide#using-ollama-with-gobi-a-developers-guide)
3. Click `Reload config` in the config selector in the Gobi IDE extension

[Devstral Small 27B](https://hub.gourmand.dev/ollama/devstral)

1. Add [Devstral Small](https://hub.gourmand.dev/ollama/devstral)  a config on Gobi Hub
2. Run the model with [Ollama](https://docs.gourmand.dev/guides/ollama-guide#using-ollama-with-gobi-a-developers-guide)
3. Click `Reload config` in the config selector in the Gobi IDE extension

[Qwen2.5-Coder 7B](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b) from Qwen

1. Add [Qwen2.5-Coder 7B](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)  a config on Gobi Hub
2. Run the model with [Ollama](https://docs.gourmand.dev/guides/ollama-guide#using-ollama-with-gobi-a-developers-guide)
3. Click `Reload config` in the config selector in the Gobi IDE extension

[Gemma 3 4B](https://hub.gourmand.dev/ollama/gemma3-4b) from Google

1. Add [Gemma 3 4B](https://hub.gourmand.dev/ollama/gemma3-4b)  a config on Gobi Hub
2. Run the model with [Ollama](https://docs.gourmand.dev/guides/ollama-guide#using-ollama-with-gobi-a-developers-guide)
3. Click `Reload config` in the config selector in the Gobi IDE extension

[Qwen2.5-Coder 1.5B](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b) from Qwen

1. Add [Qwen2.5-Coder 1.5B](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)  a config on Gobi Hub
2. Run the model with [Ollama](https://docs.gourmand.dev/guides/ollama-guide#using-ollama-with-gobi-a-developers-guide)
3. Click `Reload config` in the config selector in the Gobi IDE extension


# Customization Overview
Source: https://docs.gourmand.dev/customization/overview

Learn how to customize Gobi with model providers, slash commands, and tools

Gobi can be deeply customized to fit your specific development workflow and preferences. This guide covers the main ways you can customize Gobi to enhance your coding experience.

## Change Your Model Provider

Gobi allows you to choose your favorite or even add multiple model providers. This allows you to use different models for different tasks, or to try another model if you're not happy with the results from your current model. Gobi supports all of the popular model providers, including OpenAI, Anthropic, Microsoft/Azure, Mistral, and more. You can even self host your own model provider if you'd like. Learn more about [model providers](/customize/model-providers/top-level/openai).

## Select Different Models for Specific Tasks

Different Gobi features can use different models. We call these *model roles*. For example, you can use a different model for Chat mode than you do for Autocomplete. Learn more about [model roles](/customize/model-roles).

## Create a Slash Command

Slash commands allow you to easily add custom prompts to Gobi. Learn more about [slash commands](/customize/deep-dives/prompts).

## Call External Tools and Functions

Unchain your LLM with the power of tools using [Agent mode](/ide-extensions/agent/quick-start). Add custom tools using [MCP Servers](/customization/mcp-tools)

Whatever you choose, you'll probably start by editing your configuration.

## Edit Your Configuration

You can easily access your configuration from the Gobi Chat sidebar. Open the sidebar by pressing `cmd/ctrl` + `L` (VS Code) or `cmd/ctrl` + `J` (JetBrains) and click the Agent selector above the main chat input. Then, you can hover over an agent and click the `new window` (hub agents) or `gear` (local agents) icon.

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/configure-gobi-a5c8c79f3304c08353f3fc727aa5da7e.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=21ed13252adce7831a6fe7400d998268" alt="configure" data-og-width="750" width="750" data-og-height="514" height="514" data-path="images/customization/images/configure-gobi-a5c8c79f3304c08353f3fc727aa5da7e.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/configure-gobi-a5c8c79f3304c08353f3fc727aa5da7e.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=5914ec720218d175e846a034c747d0a5 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/configure-gobi-a5c8c79f3304c08353f3fc727aa5da7e.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=b79f4333904a5cdd4b299a9f44006d47 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/configure-gobi-a5c8c79f3304c08353f3fc727aa5da7e.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=b0421728a2dc96713ce169444a3774b3 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/configure-gobi-a5c8c79f3304c08353f3fc727aa5da7e.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=9ff08c7c1374321cc26ce389cd76c431 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/configure-gobi-a5c8c79f3304c08353f3fc727aa5da7e.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=6e9ff39f1a4f996b78ef153a267121c9 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/configure-gobi-a5c8c79f3304c08353f3fc727aa5da7e.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=c91acade72efaa5fdba8f56cb96c760d 2500w" />

## Manage Your Configuration

* See [Editing Hub Configurations](/hub/configs/edit-a-config) for more details on managing your hub configuration
* See the [Config Deep Dive](/reference) for more details on local configurations


# Prompts
Source: https://docs.gourmand.dev/customization/prompts

These are the specialized instructions that shape how models respond:

* **Define interaction patterns** for specific tasks or frameworks
* **Encode domain expertise** for particular technologies
* **Ensure consistent guidance** aligned with organizational practices
* **Can be shared and reused** across multiple assistants
* **Act as automated code reviewers** that ensure consistency across teams

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/prompts-blocks-overview-17194d870840576f9a0dde548f2c70ec.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=5c4e413e41cb18d600ee1cb620d3aada" alt="Prompts Overview" data-og-width="3156" width="3156" data-og-height="2112" height="2112" data-path="images/customization/images/prompts-blocks-overview-17194d870840576f9a0dde548f2c70ec.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/prompts-blocks-overview-17194d870840576f9a0dde548f2c70ec.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=a1945910b0739a81f14b9ab3d2195497 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/prompts-blocks-overview-17194d870840576f9a0dde548f2c70ec.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=ad5f2da35d2a0e6e700fe9a71dea2142 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/prompts-blocks-overview-17194d870840576f9a0dde548f2c70ec.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=3902aaab003c89c42708e35173502a3c 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/prompts-blocks-overview-17194d870840576f9a0dde548f2c70ec.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=3cda9f513b43cfbdebdbb45f32213a8f 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/prompts-blocks-overview-17194d870840576f9a0dde548f2c70ec.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=697146ca85b4ab6662068d6cd784277b 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customization/images/prompts-blocks-overview-17194d870840576f9a0dde548f2c70ec.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=79aa02bf71e9686eaaec1a8f1cfddfe6 2500w" />

## Learn More

* [Explore prompts](https://hub.gourmand.dev/?type=prompts) on the Hub
* Learn more in the [prompts deep dive](/customize/deep-dives/prompts)
* View [`prompts`](/reference#prompts) in the YAML Reference for more details


# Rules
Source: https://docs.gourmand.dev/customization/rules

Rules allow you to provide specific instructions that guide how the AI agent behaves when working with your code. Instead of the AI making assumptions about your coding standards, architecture patterns, or project-specific requirements, you can explicitly define guidelines that ensure consistent, contextually appropriate responses.

Think of these as the guardrails for your AI coding agents:

* **Enforce company-specific coding standards** and security practices
* **Implement quality checks** that match your engineering culture
* **Create paved paths** for developers to follow organizational best practices

By implementing rules, you transform the AI from a generic coding agent into a knowledgeable team member that understands your project's unique requirements and constraints.

## How Rules Work

Your agent detects rules and applies the specified rules while in [Agent](/ide-extensions/agent/quick-start), [Chat](/ide-extensions/chat/quick-start), and [Edit](/ide-extensions/edit/quick-start) modes.

## Where to Manage Rules

<Columns cols={2}>
  <Card title="Local Rules (.gobi/rules)" icon="folder">
    * Create files in `.gobi/rules` folder
    * Automatically appear with Hub assistants
    * Edit directly in your file system
    * Version controlled alongside your code
    * Best for project-specific rules (e.g., "remember to generate migrations after modifying the db")
  </Card>

  <Card title="Hub Rules" icon="cloud">
    * Manage on [Gobi Hub](https://hub.gourmand.dev)
    * Reference in config.yaml with `uses:`
    * Share with team and community
    * Easy to include in multiple agents
    * Best for organization-wide rules (e.g., "always use X library for Y task")
  </Card>
</Columns>

<Info>
  **Quick Setup**: Start with local rules for immediate use, then promote commonly used rules to the Hub for sharing and reuse.
</Info>

Learn more in the [rules deep dive](/customize/deep-dives/rules), and view [`rules`](/reference#rules) in the YAML Reference for more details.


# Settings
Source: https://docs.gourmand.dev/customization/settings

Configure Gobi through VS Code's streamlined settings interface

<img src="https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/gobi-settings-card-layout.png?fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=5742fd762e27d8a5f1634294fa8c6904" alt="Gobi Settings Panel - Card-based Layout" data-og-width="996" width="996" data-og-height="1732" height="1732" data-path="images/gobi-settings-card-layout.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/gobi-settings-card-layout.png?w=280&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=06773be91178e45c3e9d3deb15300fb3 280w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/gobi-settings-card-layout.png?w=560&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=37513633e979ad11cc9de818caf65999 560w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/gobi-settings-card-layout.png?w=840&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=8b6c16b8670865861e64b564a3725ca2 840w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/gobi-settings-card-layout.png?w=1100&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=dfe0264e3a9e2eb5beeba15b52b9a41c 1100w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/gobi-settings-card-layout.png?w=1650&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=d76319e63eb45b2ddac8c2e6f64319b3 1650w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/gobi-settings-card-layout.png?w=2500&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=bd9b04c6eca23d7bb0520221f8c1becf 2500w" />

The new settings experience introduces a **card-based layout** that reduces visual clutter while maintaining powerful functionality. Every setting is more discoverable and easier to modify, whether you're on an ultrawide monitor or a small laptop screen.

## Quick Access

<CardGroup cols={3}>
  <Card title="Settings Icon" icon="gear">
    Click the gear in the Gobi sidebar
  </Card>

  <Card title="VS Code Settings" icon="sliders">
    File → Preferences → Settings → Extensions → Gobi
  </Card>

  <Card title="Config File" icon="code">
    Edit `config.yml` directly for advanced options
  </Card>
</CardGroup>

<Tip>
  Use the toolbar buttons for quick access to specific settings: - **Rules**
  (pencil icon) - Custom coding preferences - **Tools** (wrench icon) - Manage
  integrations - **Models** (cube icon) - Configure AI providers
</Tip>

## Core Settings

<Tabs>
  <Tab title="Interface">
    <AccordionGroup>
      <Accordion title="Display Options" icon="display">
        | Setting          | Description                   |
        | ---------------- | ----------------------------- |
        | Session Tabs     | Manage multiple chat sessions |
        | Code Wrapping    | Auto-wrap long code lines     |
        | Markdown Display | Show raw markdown vs rendered |
        | Chat Scrollbar   | Toggle scrollbar visibility   |
      </Accordion>

      <Accordion title="Behavior" icon="wand-magic-sparkles">
        | Setting           | Description                           |
        | ----------------- | ------------------------------------- |
        | Auto-accept Diffs | Apply code changes automatically      |
        | Tool Rejection    | Gobi after tool rejection             |
        | Auto-naming       | Generate session titles automatically |
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="Autocomplete">
    Configure code completions:

    <img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-settings.png?fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=d9f286b508ebe705ce1411083fe470d8" alt="Gobi Autocomplete Settings" data-og-width="568" width="568" data-og-height="328" height="328" data-path="images/autocomplete-settings.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-settings.png?w=280&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=499db665ef432e22c93afdded797f60e 280w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-settings.png?w=560&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=df882ff5deecfd3806a4a25bc07cdf42 560w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-settings.png?w=840&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=85efe5f2758505ff0c8146bd8e4ff77d 840w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-settings.png?w=1100&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=19c07ce40a22f9155e27c2a7a896c3a0 1100w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-settings.png?w=1650&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=1b3faecbd189cb7abd6e645824945694 1650w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-settings.png?w=2500&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=a7b62a43098c38e84f949aa429959aa2 2500w" />

    <Note>
      Autocomplete models need to be added to your config to enable selecting an autocomplete model. If none is available, you will be linked to the docs showing recommended models. See our [model recommendations](/customize/model-roles/autocomplete) for the best autocomplete models.
    </Note>

    <img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-model-selection.png?fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=f3151620947b1079d885ed2c4b090d06" alt="Autocomplete Model Selection" data-og-width="566" width="566" data-og-height="480" height="480" data-path="images/autocomplete-model-selection.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-model-selection.png?w=280&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=d76b9a6c6659d458d7e7a85ee607b518 280w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-model-selection.png?w=560&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=0ca05bb50088ce10f517affc8782a592 560w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-model-selection.png?w=840&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=611aa606c71166ff6b81f8e580d9e513 840w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-model-selection.png?w=1100&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=3ee1b30919b6e6dd87d9cca801fa4ef3 1100w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-model-selection.png?w=1650&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=3bb7add327896dc5d92a4ce44738aeb9 1650w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-model-selection.png?w=2500&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=40d61099f7fbdc36ec9ab21067da25c6 2500w" />

    <Info>
      To better understand how to set up configs and models, see our [Understanding Configs guide](/guides/understanding-configs).
    </Info>
  </Tab>

  <Tab title="Indexing">
    Control how Gobi understands your codebase:

    <img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/indexing-settings.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=bc045db12067612c2073415ecbe9426d" alt="Gobi Indexing Settings" data-og-width="990" width="990" data-og-height="640" height="640" data-path="images/indexing-settings.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/indexing-settings.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=bd02bee08fe4a57a606bb82d4df6b161 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/indexing-settings.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=c2ec605c571d5486248de5ff7d086f52 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/indexing-settings.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=66b96d01151f995e6548409e1cb9a244 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/indexing-settings.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=e704ab18d2f0fdc6262338fe430744d0 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/indexing-settings.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=925d8faaf7b38650de19ec9db9d67d8d 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/indexing-settings.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=e92a14b97a13e5ca68af20150131e917 2500w" />

    <Steps>
      <Step title="Enable Indexing">
        Toggle codebase indexing in the settings panel
      </Step>

      <Step title="Monitor Progress">
        Watch real-time status in the UI
      </Step>

      <Step title="Verify Coverage">
        Check which files are indexed via the status indicator
      </Step>
    </Steps>

    <Note>
      Indexing enables Gobi to understand your entire codebase structure, significantly improving context awareness and suggestions.
    </Note>
  </Tab>

  <Tab title="Experimental">
    <Warning>
      These features are in beta and may change or have stability issues.
    </Warning>

    | Feature                          | Purpose                                                                                 |
    | -------------------------------- | --------------------------------------------------------------------------------------- |
    | Add Current File by Default      | The currently open file is added as context in every new conversation                   |
    | Enable experimental tools        | Enables access to experimental tools that are still in development                      |
    | Only use system message tools    | Gobi will not attempt to use native tool calling and will only use system message tools |
    | @Codebase: use tool calling only | @codebase context provider will only use tool calling for code retrieval                |
    | Stream after tool rejection      | Streaming will gobi after the tool call is rejected                                     |
  </Tab>
</Tabs>

## Model & Assistant Selection

<img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/assistant-selector-dropdown.png?fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=2026adc5fa296705a0c61d32163bf8a5" alt="New assistant dropdown with cleaner icons and improved organization display" data-og-width="860" width="860" data-og-height="1040" height="1040" data-path="images/assistant-selector-dropdown.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/assistant-selector-dropdown.png?w=280&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=6341ea0bd3d911b6131fad6573e5c280 280w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/assistant-selector-dropdown.png?w=560&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=9919dc110d8232e7cacd29e50afecc80 560w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/assistant-selector-dropdown.png?w=840&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=a75814d39757a19c1116a192f2c41f23 840w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/assistant-selector-dropdown.png?w=1100&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=69881c66b578c50b7e1018f0e164c899 1100w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/assistant-selector-dropdown.png?w=1650&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=9f88af9ddef7203bc6b1ab180881fcc0 1650w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/assistant-selector-dropdown.png?w=2500&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=1f9a1c6d378d94bafe319e048b9fb28d 2500w" />

The refined assistant selector features:

* **Organization badges** for easy provider identification
* **Smart error handling** that sorts problematic configurations while keeping them selectable
* **Keyboard navigation** for quick model switching

## Privacy & Data

<CardGroup cols={3}>
  <Card title="Local Processing" icon="lock">
    All code analysis happens locally unless explicitly shared
  </Card>

  <Card title="Telemetry Control" icon="chart-line">
    Opt in/out of anonymous usage statistics
  </Card>

  <Card title="Session Management" icon="database">
    Sessions auto-save and restore between IDE restarts
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Model Connection Issues" icon="plug">
    * Verify API keys in `config.yml` - Check network connectivity - Confirm
      endpoint URLs are correct
  </Accordion>

  <Accordion title="Tool Loading Failures" icon="wrench">
    * Review MCP server configurations - Check tool permissions - Verify tool
      dependencies are installed
  </Accordion>

  <Accordion title="Indexing Problems" icon="magnifying-glass">
    * Check file permissions
    * Review `.gitignore` patterns
    * Verify sufficient disk space
  </Accordion>
</AccordionGroup>

<Info>
  Still having issues? Check our comprehensive [troubleshooting
  guide](/troubleshooting) or visit the [FAQs](/faqs) for more solutions.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Models" icon="robot" href="/customization/models">
    Set up your AI providers
  </Card>

  <Card title="Add Tools" icon="wrench" href="/customization/mcp-tools">
    Extend Gobi with MCP tools
  </Card>

  <Card title="Custom Rules" icon="pencil" href="/customization/rules">
    Define coding preferences
  </Card>

  <Card title="Prompts" icon="message" href="/customization/prompts">
    Customize AI behavior
  </Card>
</CardGroup>


# Gobi Autocomplete Setup and Configuration Guide
Source: https://docs.gourmand.dev/customize/deep-dives/autocomplete

Step-by-step guide to setting up and configuring autocomplete in Gobi, including Codestral, Ollama, and IDE settings.

export const ModelRecommendations = ({role = "all"}) => {
  const parseMarkdownLinks = text => {
    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const parts = [];
    let lastIndex = 0;
    let match;
    let key = 0;
    while ((match = regex.exec(text)) !== null) {
      if (match.index > lastIndex) {
        const beforeText = text.slice(lastIndex, match.index);
        if (beforeText) {
          parts.push(<span key={key++}>{beforeText}</span>);
        }
      }
      const [, linkText, url] = match;
      parts.push(<a key={key++} href={url} target="_blank" rel="noopener noreferrer" style={{
        color: "#0066cc",
        textDecoration: "underline"
      }}>
          {linkText}
        </a>);
      lastIndex = regex.lastIndex;
    }
    if (lastIndex < text.length) {
      const remainingText = text.slice(lastIndex);
      if (remainingText) {
        parts.push(<span key={key++}>{remainingText}</span>);
      }
    }
    return parts.length > 0 ? parts : text;
  };
  const modelRecs = {
    agent_plan: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[Devstral (27B)](https://hub.gourmand.dev/ollama/devstral)", "[Kimi K2 (1T)](https://hub.gourmand.dev/openrouter/kimi-k2)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)", "[GLM 4.5 (355B)](https://hub.gourmand.dev/openrouter/glm-4-5)", "[GLM 4.5 Air (106B)](https://hub.gourmand.dev/openrouter/glm-4-5-air)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed models are slightly better than open models"
    },
    chat_edit: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed and open models have pretty similar performance"
    },
    autocomplete: {
      open: ["[QwenCoder2.5 (1.5B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)", "[QwenCoder2.5 (7B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)"],
      closed: ["[Codestral](https://hub.gourmand.dev/mistral/codestral)", "[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are slightly better than open models"
    },
    apply: {
      open: ["N/A"],
      closed: ["[Relace Instant Apply](https://hub.gourmand.dev/relace/instant-apply)", "[Morph Fast Apply](https://hub.gourmand.dev/morphllm/morph-v2)"],
      notes: "Open models are not good enough for this model role"
    },
    embed: {
      open: ["[Nomic Embed Text](https://hub.gourmand.dev/ollama/nomic-embed-text-latest)", "Qwen3 Embedding"],
      closed: ["[Voyage Code 3](https://hub.gourmand.dev/voyageai/voyage-code-3)", "[Morph Embeddings](https://hub.gourmand.dev/morphllm/morph-embedding-v2)", "Codestral Embed"],
      notes: "Closed models are slightly better than open models"
    },
    rerank: {
      open: ["zerank-1", "zerank-1-small", "Qwen3 Reranker"],
      closed: ["[Voyage Rerank 2.5](https://hub.gourmand.dev/voyageai/rerank-2-5)", "Relace Code Rerank", "[Morph Rerank](https://hub.gourmand.dev/morphllm/morph-rerank-v2)"],
      notes: "Open models are beginning to emerge for this model role"
    },
    next_edit: {
      open: ["[Instinct](https://hub.gourmand.dev/gobi/instinct)"],
      closed: ["[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are better than open models"
    }
  };
  let rolesToShow = [];
  if (!role || role === "all") {
    rolesToShow = Object.keys(modelRecs);
  } else {
    const key = role.toLowerCase().replace(/\s|\//g, "_").replace(/-/g, "_");
    if (modelRecs[key]) {
      rolesToShow = [key];
    }
  }
  if (rolesToShow.length === 0) {
    return <div>No recommendations found for role: {role}</div>;
  }
  return <table style={{
    width: "100%",
    borderCollapse: "collapse",
    marginTop: "1rem"
  }}>
      <thead>
        <tr>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Model role
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best open models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best closed models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Notes
          </th>
        </tr>
      </thead>
      <tbody>
        {rolesToShow.map(roleKey => {
    const rec = modelRecs[roleKey];
    if (!rec) return null;
    return <tr key={roleKey}>
              <td style={{
      fontWeight: 600,
      verticalAlign: "top",
      padding: "8px"
    }}>
                {roleKey.replace(/_/g, " ").replace(/\b\w/g, l => l.toUpperCase())}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.open.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.closed.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.notes}
              </td>
            </tr>;
  })}
      </tbody>
    </table>;
};

## Model Recommendations for Autocomplete

<ModelRecommendations role="autocomplete" />

## How to Set Up Autocomplete in Gobi with Codestral (Recommended)

If you want to have the best autocomplete experience, we recommend using Codestral, which is available through the [Mistral API](https://console.mistral.ai/). To do this, obtain an API key and add it to your config:

<Tabs>
  <Tab title="Hub">
    [Mistral Codestral model block](https://hub.gourmand.dev/mistral/codestral)
  </Tab>

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Codestral
        provider: mistral
        model: codestral-latest
        apiKey: <YOUR_CODESTRAL_API_KEY>
        roles:
          - autocomplete
    ```
  </Tab>

  <Tab title="JSON">
    ```json title="config.json" theme={null}
    {
      "tabAutocompleteModel": {
        "title": "Codestral",
        "provider": "mistral", 
        "model": "codestral-latest",
        "apiKey": "<YOUR_CODESTRAL_API_KEY>"
      }
    }
    ```
  </Tab>
</Tabs>

<Tip>
  **Codestral API Key**: The API keys for Codestral and the general Mistral APIs
  are different. If you are using Codestral, you probably want a Codestral API
  key, but if you are sharing the key as a team or otherwise want to use
  `api.mistral.ai`, then make sure to set `"apiBase":
    "https://api.mistral.ai/v1"` in your `tabAutocompleteModel`.
</Tip>

## How to Set Up Autocomplete in Gobi with Ollama (Local Model)

If you'd like to run your autocomplete model locally, we recommend using Ollama. To do this, first download the latest version of Ollama from [here](https://ollama.ai). Then, run the following command to download our recommended model:

```bash  theme={null}
ollama run qwen2.5-coder:1.5b
```

Then, add the model to your configuration:

<Tabs>
  <Tab title="Hub">
    [Ollama Qwen 2.5 Coder 1.5B model block](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)
  </Tab>

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Qwen 1.5b Autocomplete Model
        provider: ollama
        model: qwen2.5-coder:1.5b
        roles:
          - autocomplete
    ```
  </Tab>

  <Tab title="JSON">
    ```json title="config.json" theme={null}
    {
      "tabAutocompleteModel": {
        "title": "Qwen 1.5b Autocomplete Model",
        "provider": "ollama", 
        "model": "qwen2.5-coder:1.5b",
      }
    }
    ```
  </Tab>
</Tabs>

Once the model has been downloaded, you should begin to see completions in VS Code.

<Note>
  Typically, thinking-type models are not recommended as they generate more
  slowly and are not suitable for scenarios that require speed.
</Note>

However, if you use any thinking-switchable models, you can configure these models for autocomplete functions by turning off the thinking mode.

For example:

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Qwen3 without Thinking for Autocomplete
        provider: ollama
        model: qwen3:4b # qwen3 is a thinking-switchable model
        roles:
          - autocomplete
        requestOptions:
          extraBodyProperties:
            think: false # turning off the thinking
    ```
  </Tab>
</Tabs>

Then, in the gobi panel, select this model as the default model for autocomplete.

## Autocomplete Configuration Options in Gobi

### Autocomplete Models Available on the Gobi Hub

Explore autocomplete model configurations on [the hub](https://hub.gourmand.dev/explore/models?roles=autocomplete)

### Customize Autocomplete User Settings in the Gobi Extension

The following settings can be configured for autocompletion in the IDE extension User Settings Page:

* `Multiline Autocompletions`: Controls multiline completions for autocomplete. Can be set to `always`, `never`, or `auto`. Defaults to `auto`
* `Disable autocomplete in files`: List of comma-separated glob pattern to disable autocomplete in matching files. E.g., "\_/.md, \*/.txt"

### How to Configure Autocomplete with `config.json` (Deprecated Format)

#### YAML Configuration

The `config.yaml` format offers model-level configuration using the `autocompleteOptions` field. See the [YAML Reference](/reference#models) for more details.

```yaml  theme={null}
models:
  - name: Codestral
    provider: mistral
    model: codestral-latest
    roles:
      - autocomplete
    autocompleteOptions:
      disable: false
      maxPromptTokens: 1024
      debounceDelay: 250
      modelTimeout: 150
      maxSuffixPercentage: 0.2
      prefixPercentage: 0.3
      onlyMyCode: true
```

#### JSON Configuration (Deprecated)

The `config.json` configuration format offers configuration options through `tabAutocompleteOptions`. See the [JSON Reference](/reference/json-reference#tabautocomplete-options) for more details.

## Autocomplete FAQs and Troubleshooting in Gobi

### I want better completions, should I use GPT-4?

Perhaps surprisingly, the answer is no. The models that we suggest for autocomplete are trained with a highly specific prompt format, which allows them to respond to requests for completing code (see examples of these prompts [here](https://github.com/gourmand/gobi/blob/main/core/autocomplete/templating/AutocompleteTemplate.ts)). Some of the best commercial models like GPT-4 or Claude are not trained with this prompt format, which means that they won't generate useful completions. Luckily, a huge model is not required for great autocomplete. Most of the state-of-the-art autocomplete models are no more than 10b parameters, and increasing beyond this does not significantly improve performance.

### Autocomplete Not Working – How to Fix It

Follow these steps to ensure that everything is set up correctly:

1. Make sure you have the "Enable Tab Autocomplete" setting checked (in VS Code, you can toggle by clicking the "Gobi" button in the status bar, and in JetBrains by going to Settings -> Tools -> Gobi).
2. Make sure you have downloaded Ollama.
3. Run `ollama run qwen2.5-coder:1.5b` to verify that the model is downloaded.
4. Make sure that any other completion providers are disabled (e.g. Copilot), as they may interfere.
5. Check the output of the logs to find any potential errors: <kbd>cmd/ctrl</kbd> + <kbd>shift</kbd> + <kbd>P</kbd> -> "Toggle Developer Tools" -> "Console" tab in VS Code, \~/.gobi/logs/core.log in JetBrains.
6. Check VS Code settings to make sure that `"editor.inlineSuggest.enabled"` is set to `true` (use <kbd>cmd/ctrl</kbd> + <kbd>,</kbd> then search for this and check the box)
7. If you are still having issues, please let us know in our [Discord](https://discord.gg/TODO) and we'll help as soon as possible.

### Why Are My Completions Only Single-Line?

To ensure that you receive multi-line completions, you can set `"multilineCompletions": "always"` in `tabAutocompleteOptions`. By default, it is `"auto"`. If you still find that you are only seeing single-line completions, this may be because some models tend to produce shorter completions when starting in the middle of a file. You can try temporarily moving text below your cursor out of your active file, or switching to a larger model.

### How to Set a Trigger Key for Autocomplete Suggestions

In VS Code, if you don't want to be shown suggestions automatically you can:

1. Set `"editor.inlineSuggest.enabled": false` in VS Code settings to disable automatic suggestions
2. Open "Keyboard Shortcuts" (cmd/ctrl+k, cmd/ctrl+s) and search for `editor.action.inlineSuggest.trigger`
3. Click the "+" icon to add a new keybinding
4. Press the key combination you want to use to trigger suggestions (e.g. <kbd>cmd/ctrl</kbd> + <kbd>space</kbd>)
5. Now whenever you want to see a suggestion, you can press your key binding (e.g. <kbd>cmd/ctrl</kbd> + <kbd>space</kbd>) to trigger suggestions manually

### Shortcut for Accepting One Line at a Time in Autocomplete

This is a built-in feature of VS Code, but it's just a bit hidden. Follow these settings to reassign the keyboard shortcuts in VS Code:

1. Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>, type the command: `Preferences: Open Keyboard Shortcuts`, and enter the keyboard shortcuts settings page.
2. Search for `editor.action.inlineSuggest.acceptNextLine`.
3. Set the key binding to <kbd>Tab</kbd>.
4. Set the trigger condition (when) to `inlineSuggestionVisible && !editorReadonly`.
   This will make multi-line completion (including gobi and from VS Code built-in or other plugin snippets) still work, and you will see multi-line completion. However, Tab will only fill in one line at a time. Any unnecessary code can be canceled with <kbd>Esc</kbd>.
   If you need to apply all the code, just press <kbd>Tab</kbd> multiple times.

### How to Turn Off Autocomplete in Gobi (VS Code and JetBrains)

#### VS Code

Click the "Gobi" button in the status panel at the bottom right of the screen. The checkmark will become a "cancel" symbol and you will no longer see completions. You can click again to turn it back on.

Alternatively, open VS Code settings, search for "Gobi" and uncheck the box for "Enable Tab Autocomplete".

You can also use the default shortcut to disable autocomplete directly using a chord: press and hold <kbd>ctrl/cmd</kbd> + <kbd>K</kbd> (gobi holding <kbd>ctrl/cmd</kbd>) and press <kbd>ctrl/cmd</kbd> + <kbd>A</kbd>. This will turn off autocomplete without navigating through settings.

#### JetBrains

Open Settings -> Tools -> Gobi and uncheck the box for "Enable Tab Autocomplete".

#### Feedback

If you're turning off autocomplete, we'd love to hear how we can improve! Please let us know in our [Discord](https://discord.gg/TODO) or file an issue on GitHub.


# How to Configure Gobi
Source: https://docs.gourmand.dev/customize/deep-dives/configuration

Learn how to access and manage Gobi configurations through Hub or local YAML files

You can easily access your configuration from the Gobi Chat sidebar. Open the sidebar by pressing <kbd>cmd/ctrl</kbd> + <kbd>L</kbd> (VS Code) or <kbd>cmd/ctrl</kbd> + <kbd>J</kbd> (JetBrains) and click the Agent selector above the main chat input. Then, you can hover over an agent and click the `new window` (hub agents) or `gear` (local agents) icon.

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=a320ac89603934bd55aea06a9e33bbe2" alt="configure" data-og-width="750" width="750" data-og-height="514" height="514" data-path="images/configure-gobi.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=af5f992b067017bfa49d479469858e6f 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=c4a36deb917e59ac95b12bd17a14cb42 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=333a094e82359f1a9296bcb0353b60e2 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=0a7866b929a3babe2ac537d8019f87d5 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=43279bb07b641d19084f2bc34f6ae86b 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=72f6f94585b2ed9528dcb0f83e3ba1c0 2500w" />

## How to Manage Hub Configs

Hub Configs can be managed in [the Hub](https://hub.gourmand.dev). See [Editing a config](/hub/configs/edit-a-config)

## How to Configure Local Configs with YAML

Local user-level configuration is stored and can be edited in your home directory in `config.yaml`:

* `~/.gobi/config.yaml` (MacOS / Linux)
* `%USERPROFILE%\.gobi\config.yaml` (Windows)

To open this `config.yaml`, you need to open the configs dropdown in the top-right portion of the chat input. On that dropdown beside the "Local Config" option, select the cog icon. It will open the local `config.yaml`.

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=944f96f540277b89efb50f653abc9ad1" alt="local-config-open-steps" data-og-width="778" width="778" data-og-height="484" height="484" data-path="images/local-config-open-steps.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=65695a6de18c4888688ae8ef688ad972 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=dc6fed29115963949125e5bcc018e736 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=16df4500230f0b2ced52df66bbab0e97 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=4cd793b4dfaa656eb691b878a236776f 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=1b0ecbfb543f06e76e08ec72fcdf588b 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=3aa1a4ca8c5aa49fcdf06ab199a9c2e0 2500w" />

When editing this file, you can see the available options suggested as you type, or check the reference below. When you save a config file from the IDE, Gobi will automatically refresh to take into account your changes. A config file is automatically created the first time you use Gobi, and always automatically generated with default values if it doesn't exist.

See the full reference for `config.yaml` [here](/reference).

## Legacy Configuration Methods (Deprecated)

<Info>
  View the `config.json` migration guide [here](/reference/yaml-migration)
</Info>

* [`config.json`](/reference) - The original configuration format which is stored in a file at the same location as `config.yaml`
* [`.gobirc.json`](#how-to-use-gobircjson-for-workspace-configuration) - Workspace-level configuration
* [`config.ts`](#how-to-use-configts-for-advanced-configuration) - Advanced configuration (probably unnecessary) - a TypeScript file in your home directory that can be used to programmatically modify (*merged*) the `config.json` schema:
  * `~/.gobi/config.ts` (MacOS / Linux)
  * `%USERPROFILE%\.gobi\config.ts` (Windows)

### How to Use `.gobirc.json` for Workspace Configuration

The format of `.gobirc.json` is the same as `config.json`, plus one *additional* property `mergeBehavior`, which can be set to either "merge" or "overwrite". If set to "merge" (the default), `.gobirc.json` will be applied on top of `config.json` (arrays and objects are merged). If set to "overwrite", then every top-level property of `.gobirc.json` will overwrite that property from `config.json`.

Example

```json title=".gobirc.json" theme={null}
{
  "tabAutocompleteOptions": {
    "disable": true
  },
  "mergeBehavior": "overwrite"
}
```

### How to Use `config.ts` for Advanced Configuration

`config.yaml` or `config.json` can handle the vast majority of necessary configuration, so we recommend using it whenever possible. However, if you need to programmatically extend Gobi configuration, you can use a `config.ts` file, placed at `~/.gobi/config.ts` (MacOS / Linux) or `%USERPROFILE%\.gobi\config.ts` (Windows).

`config.ts` must export a `modifyConfig` function, like:

<Warning>
  The `slashCommands` array shown below is deprecated. For creating custom slash
  commands, use [prompt files](./prompts) instead.
</Warning>

```ts title="config.ts" theme={null}
export function modifyConfig(config: Config): Config {
  config.slashCommands?.push({
    name: "commit",
    description: "Write a commit message",
    run: async function* (sdk) {
      // The getDiff function takes a boolean parameter that indicates whether
      // to include unstaged changes in the diff or not.
      const diff = await sdk.ide.getDiff(false); // Pass false to exclude unstaged changes
      for await (const message of sdk.llm.streamComplete(
        `${diff}\n\nWrite a commit message for the above changes. Use no more than 20 tokens to give a brief description in the imperative mood (e.g. 'Add feature' not 'Added feature'):`,
        new AbortController().signal,
        {
          maxTokens: 20,
        },
      )) {
        yield message;
      }
    },
  });
  return config;
}
```


# Context Providers
Source: https://docs.gourmand.dev/customize/deep-dives/custom-providers

Context Providers allow you to type '@' and see a dropdown of content that can all be provided to the model as context.

Context Providers allow you to type '@' and see a dropdown of content that can all be provided to the model as context.

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customize/images/context-provider-example-0c96ff77286fa970b23dddfdc1fa986a.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=92446a3096e6f3bb55e6b86daea06105" alt="Context Items" data-og-width="914" width="914" data-og-height="428" height="428" data-path="images/customize/images/context-provider-example-0c96ff77286fa970b23dddfdc1fa986a.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customize/images/context-provider-example-0c96ff77286fa970b23dddfdc1fa986a.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=f0809458e15fe77fd624a0c20ac70bda 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customize/images/context-provider-example-0c96ff77286fa970b23dddfdc1fa986a.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=b000ce5250e9d013332dd1896140f511 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customize/images/context-provider-example-0c96ff77286fa970b23dddfdc1fa986a.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=779edc53553be53d85ad5cd66e2aa555 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customize/images/context-provider-example-0c96ff77286fa970b23dddfdc1fa986a.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=11c6ddf7590a5e63d3cd69e90ee4313c 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customize/images/context-provider-example-0c96ff77286fa970b23dddfdc1fa986a.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=d986c2908a431b5a1d0abb61a851e5b8 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/customize/images/context-provider-example-0c96ff77286fa970b23dddfdc1fa986a.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=4ad418437215019405bc0726bb35cf8a 2500w" />

## Built-in Context Providers

You can add any built-in context-providers in your config file as shown below:

### `@File`

Reference any file in your current workspace.

```yaml config.yaml theme={null}
context:
  - provider: file
```

### `@Code`

Reference specific functions or classes from throughout your project.

```yaml config.yaml theme={null}
context:
  - provider: code
```

### `@Git Diff`

Reference all of the changes you've made to your current branch. This is useful if you want to summarize what you've done or ask for a general review of your work before committing.

```yaml config.yaml theme={null}
context:
  - provider: diff
```

### `@Current File`

Reference the currently open file.

```yaml config.yaml theme={null}
context:
  - provider: currentFile
```

### `@Terminal`

Reference the last command you ran in your IDE's terminal and its output.

```yaml config.yaml theme={null}
context:
  - provider: terminal
```

### `@Open`

Reference the contents of all of your open files. Set `onlyPinned` to `true` to only reference pinned files.

```yaml config.yaml theme={null}
context:
  - provider: open
    params:
      onlyPinned: true
```

### `@Clipboard`

Reference recent clipboard items

```yaml config.yaml theme={null}
context:
  - provider: clipboard
```

### `@Tree`

Reference the structure of your current workspace.

```yaml config.yaml theme={null}
context:
  - provider: tree
```

### `@Problems`

Get Problems from the current file.

```yaml config.yaml theme={null}
context:
  - provider: problems
```

### `@Debugger`

Reference the contents of the local variables in the debugger. Currently only available in VS Code.

```yaml config.yaml theme={null}
context:
  - provider: debugger
    params:
      stackDepth: 3
```

Uses the top *n* levels (defaulting to 3) of the call stack for that thread.

### `@Repository Map`

Reference the outline of your codebase. By default, signatures are included along with file in the repo map.

`includeSignatures` params can be set to false to exclude signatures. This could be necessary for large codebases and/or to reduce context size significantly. Signatures will not be included if indexing is disabled.

```yaml config.yaml theme={null}
context:
  - provider: repo-map
    params:
      includeSignatures: false # default true
```

Provides a list of files and the call signatures of top-level classes, functions, and methods in those files. This helps the model better understand how a particular piece of code relates to the rest of the codebase.

In the submenu that appears, you can select either `Entire codebase`, or specify a subfolder to generate the repostiory map from.

This context provider is inpsired by [Aider's repository map](https://aider.chat/2023/10/22/repomap.html).

### `@Operating System`

Reference the architecture and platform of your current operating system.

```yaml config.yaml theme={null}
context:
  - provider: os
```

### `@HTTP`

The HttpContextProvider makes a POST request to the url passed in the configuration. The server must return 200 OK with a ContextItem object or an array of ContextItems.

```yaml config.yaml theme={null}
context:
  - provider: http
    params:
      url: "https://api.example.com/v1/users"
      headers:
        - Authorization: "Bearer <token>"
```

The receiving URL should expect to receive the following parameters:

POST parameters

```json  theme={null}
{  query: string,  fullInput: string}
```

The response 200 OK should be a JSON object with the following structure:

Response

```
[  {    "name": "",    "description": "",    "content": ""  }]// OR{  "name": "",  "description": "",  "content": ""}
```

### Model Context Protocol

The [Model Context Protocol](https://modelcontextprotocol.io/introduction) is a standard proposed by Anthropic to unify prompts, context, and tool use. Gobi supports any MCP server with the MCP context provider. Read their [quickstart](https://modelcontextprotocol.io/quickstart) to learn how to set up a local server and then set up your configuration like this:

```yaml config.yaml theme={null}
mcpServers:
  - name: My MCP Server
    command: uvx
    args:
      - mcp-server-sqlite
      - --db-path
      - /Users/NAME/test.db
```

You'll then be able to type "@" and see "MCP" in the context providers dropdown.

## Deprecated Context Providers

<Note>
  To provide conext beyond the built-in context providers, we now recommend
  using [MCP Servers](/customization/mcp-tools)
</Note>

View the [deprecated context providers](/reference/deprecated-context-providers) for documentation on:

* [`@Codebase`](/reference/deprecated-codebase) - Use the [codebase awareness guide](/guides/codebase-documentation-awareness) instead
* [`@Folder`](/reference/deprecated-codebase) - Use the [codebase awareness guide](/guides/codebase-documentation-awareness) instead
* [`@Docs`](/reference/deprecated-docs) - Use the [documentation awareness guide](/guides/codebase-documentation-awareness) instead
* `@Greptile` - Query Greptile index
* `@Commits` - Reference git commits
* `@Discord` - Reference Discord messages
* `@Jira` - Reference Jira issues
* `@Gitlab Merge Request` - Reference GitLab MRs
* `@Google` - Google search results
* `@Database` - Database schemas
* `@Issue` - GitHub issues
* `@Url` - URL content
* `@Search` - Codebase search
* `@Web` - Web search results


# How to Collect and Manage Development Data in Gobi
Source: https://docs.gourmand.dev/customize/deep-dives/development-data

Collecting data on how you build software

When you use Gobi, you automatically collect data on how you build software. By default, this development data is saved to `.gobi/dev_data` on your local machine.

You can read more about how development data is generated as a byproduct of LLM-aided development and why we believe that you should start collecting it now: [It’s time to collect data on how you build software](https://blog.gourmand.dev/its-time-to-collect-data-on-how-you-build-software)

## How to Configure Custom Data Destinations

You can also configure custom destinations for your data, including remote HTTP endpoints and local file directories.

Data destinations should be configured directly in the `data` section of your `config.yaml` file. See more details about adding `data` configuration in the [YAML specification](/reference#data).

When sending development data to your own HTTP endpoint, it will receive an event JSON blob at the given `schema` version. You can view event names, schema versions, and fields [here in the source code](https://github.com/gourmand/gobi/tree/main/packages/config-yaml/src/schemas/data).


# How to Set Up Model Context Protocol (MCP) in Gobi
Source: https://docs.gourmand.dev/customize/deep-dives/mcp

MCP use and customization

As AI systems get better, they're still held back by their training data and
can't access real-time information or specialized tools. The [Model Context
Protocol](https://modelcontextprotocol.io/introduction) (MCP) fixes this by
letting AI models connect with outside data sources, tools, and environments.
This allows smooth sharing of information and abilities between AI systems and
the wider digital world. This standard, created by Anthropic to bring together
prompts, context, and tool use, is key for building truly useful AI experiences
that can be set up with custom tools.

## How MCP Works in Gobi

Currently custom tools can be configured using the Model Context
Protocol standard to unify prompts, context, and tool use.

MCP Servers can be added to hub configs using `mcpServers` blocks. You can
explore available MCP server blocks
[here](https://hub.gourmand.dev/explore/mcp).

<Info>MCP can only be used in the **agent** mode.</Info>

## Quick Start: How to Set Up Your First MCP Server

Below is a quick example of setting up a new MCP server for use in your config:

1. Create a folder called `.gobi/mcpServers` at the top level of your workspace
2. Add a file called `playwright-mcp.yaml` to this folder
3. Write the following contents and save

```yaml title=".gobi/mcpServers/playwright-mcp.yaml" theme={null}
name: Playwright mcpServer
version: 0.0.1
schema: v1
mcpServers:
  - name: Browser search
    command: npx
    args:
      - "@playwright/mcp@latest"
```

Now test your MCP server by prompting the following command:

```
Open the browser and navigate Hacker News. Save the top 10 headlines in a hn.txt file.
```

The result will be a generated file called `hn.txt` in the current working directory.

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mcp-playwright.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=3c3e4f73a3b40bb2e3ae4d00b404bf5c" alt="playwright mcp" data-og-width="1074" width="1074" data-og-height="896" height="896" data-path="images/mcp-playwright.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mcp-playwright.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=63c6b9c7668e1714ff01fa67febb0894 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mcp-playwright.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=79d4b190570fd6f8760d65fef7db1eb0 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mcp-playwright.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=8fa23d560d2421dd368343d6e589e801 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mcp-playwright.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=0fc05c5c1290a8c32257e8618863b933 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mcp-playwright.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=527c77540ffe3fd8d871c9f0801d0de0 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mcp-playwright.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=c58b91b481b8f7a5ed53d03b42b97e93 2500w" />

## How to Set Up Gobi Documentation Search with MCP

You can set up an MCP server to search the Gobi documentation directly from your config. This is particularly useful for getting help with Gobi configuration and features.

For complete setup instructions, troubleshooting, and usage examples, see the [Gobi MCP Reference](/reference/gobi-mcp).

## Using JSON MCP Format from Claude, Cursor, Cline, etc

<Info>
  If you're coming from another tool that uses JSON MCP format configuration files (like Claude Desktop, Cursor, or Cline), you can copy those JSON config files directly into your `.gobi/mcpServers/` directory (note the plural "Servers") and Gobi will automatically pick them up.

  For example, place your JSON MCP config file at `.gobi/mcpServers/mcp.json` in your workspace.
</Info>

## How to Configure MCP Servers

To set up your own MCP server, read the [MCP
quickstart](https://modelcontextprotocol.io/quickstart) and then [create an
`mcpServers`
block](https://hub.gourmand.dev/new?type=block\&blockType=mcpServers) or add a local MCP
server block to your [config file](./configuration.md):

```yaml title="config.yaml" theme={null}
# ...
mcpServers:
  - name: SQLite MCP
    command: npx
    args:
      - "-y"
      - "mcp-sqlite"
      - "/path/to/your/database.db"
# ...
```

<Note>
  When creating a standalone block file in `.gobi/mcpServers/`, remember to include the required metadata fields (`name`, `version`, `schema`) as shown in the Quick Start example above.
</Note>

### How to Configure MCP Server Properties

MCP blocks follow the established syntax for blocks, with a few additional properties specific to MCP servers.

* `name`: A display name for the MCP server.
* `type`: The type of the MCP server: `sse`, `stdio`, `streamable-http`
* `command`: The command to run to start the MCP server.
* `args`: Arguments to pass to the command.
* `env`: Secrets to be injected into the command as environment variables.

### How to Choose MCP Transport Types

MCP now supports remote server connections through HTTP-based transports, expanding beyond the traditional local stdio transport method. This enables integration with cloud-hosted MCP servers and distributed architectures.

#### How to Use Server-Sent Events Transport (`sse`)

For real-time streaming communication, use the SSE transport:

```yaml  theme={null}
# ...
mcpServers:
  - name: Name
    type: sse
    url: https://....
# ...
```

#### How to Use Standard Input/Output (`stdio`)

For local MCP servers that communicate via standard input and output:

```yaml  theme={null}
# ...
mcpServers:
  - name: Name
    type: stdio
    command: npx
    args:
      - "@modelcontextprotocol/server-sqlite"
      - "/path/to/your/database.db"
# ...
```

#### How to Use Streamable HTTP Transport

For standard HTTP-based communication with streaming capabilities:

```yaml  theme={null}
# ...
mcpServers:
  - name: Name
    type: streamable-http
    url: https://....
# ...
```

These remote transport options allow you to connect to MCP servers hosted on remote infrastructure, enabling more flexible deployment architectures and shared server resources across multiple clients.

For detailed information about transport mechanisms and their use cases, refer to the official MCP documentation on [transports](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse).

### How to Work with Secrets in MCP Servers

With some MCP servers you will need to use API keys or other secrets. You can leverage locally stored environments secrets
as well as access hosted secrets in the Gobi Hub. To leverage Hub secrets, you can use the `inputs` property in your MCP env block instead of `secrets`.

```yaml  theme={null}
# ...
mcpServers:
  - name: Supabase MCP
    command: npx
    args:
      - -y
      - "@supabase/mcp-server-supabase@latest"
      - --access-token
      - ${{ secrets.SUPABASE_TOKEN }}
    env:
      SUPABASE_TOKEN: ${{ secrets.SUPABASE_TOKEN }}
  - name: GitHub
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${{ secrets.GITHUB_PERSONAL_ACCESS_TOKEN }}
# ...
```


# How to Configure Model Capabilities in Gobi
Source: https://docs.gourmand.dev/customize/deep-dives/model-capabilities

Understanding and configuring model capabilities for tools and image support

Gobi needs to know what features your models support to provide the best experience. This guide explains how model capabilities work and how to configure them.

## What Are Model Capabilities?

Model capabilities tell Gobi what features a model supports:

* **`tool_use`** - Whether the model can use tools and functions
* **`image_input`** - Whether the model can process images

Without proper capability configuration, you may encounter issues like:

* Agent mode being unavailable (requires tools)
* Tools not working at all
* Image uploads being disabled

## How Gobi Detects Model Capabilities

Gobi uses a two-tier system for determining model capabilities:

### How Automatic Detection Works (Default)

Gobi automatically detects capabilities based on your provider and model name. For example:

* **OpenAI**: GPT-4 and GPT-3.5 Turbo models support tools
* **Anthropic**: Claude 3.5+ models support both tools and images
* **Ollama**: Most models support tools, vision models support images
* **Google**: All Gemini models support function calling

This works well for popular models, but may not cover custom deployments or newer models.

For implementation details, see:

* [toolSupport.ts](https://github.com/gourmand/gobi/blob/main/core/llm/toolSupport.ts) - Tool capability detection logic
* [@gourmanddev/llm-info](https://www.npmjs.com/package/@gourmanddev/llm-info) - Image support detection

### How to Configure Capabilities Manually

You can add capabilities to models that Gobi doesn't automatically detect in your `config.yaml`.

<Note>
  You cannot override autodetection - you can only add capabilities. Gobi
  will always use its built-in knowledge about your model in addition to any
  capabilities you specify.
</Note>

```yaml  theme={null}
models:
  - name: my-custom-gpt4
    provider: openai
    apiBase: https://my-deployment.com/v1
    model: gpt-4-custom
    capabilities:
      - tool_use
      - image_input
```

## When to Add Capabilities Manually

Add capabilities when:

1. **Using custom deployments** - Your API endpoint serves a model with different capabilities than the standard version
2. **Using newer models** - Gobi doesn't yet recognize a newly released model
3. **Experiencing issues** - Autodetection isn't working correctly for your setup
4. **Using proxy services** - Some proxy services modify model capabilities

## How to Configure Model Capabilities (Examples)

### How to Add Basic Tool Support

Add tool support for a model that Gobi doesn't recognize:

```yaml  theme={null}
models:
  - name: custom-model
    provider: openai
    model: my-fine-tuned-gpt4
    capabilities:
      - tool_use
```

<Info>
  The `tool_use` capability is for native tool/function calling support. The
  model must actually support tools for this to work.
</Info>

<Warning>
  **Experimental**: System message tools are available as an experimental
  feature for models without native tool support. These are not automatically
  used as a fallback and must be explicitly configured. Most models are trained
  for native tools, so system message tools may not work as well.
</Warning>

### How to Handle Models with Limited Capabilities

Explicitly set no capabilities (autodetection will still apply):

```yaml  theme={null}
models:
  - name: limited-claude
    provider: anthropic
    model: claude-4.0-sonnet
    capabilities: [] # Empty array doesn't disable autodetection
```

<Warning>
  An empty capabilities array does not disable autodetection. Gobi will
  still detect and use the model's actual capabilities. To truly limit a model's
  capabilities, you would need to use a model that doesn't support those
  features.
</Warning>

### How to Enable Multiple Capabilities

Enable both tools and image support:

```yaml  theme={null}
models:
  - name: multimodal-gpt
    provider: openai
    model: gpt-4-vision-preview
    capabilities:
      - tool_use
      - image_input
```

## Common Configuration Scenarios

Some providers and custom deployments may require explicit capability configuration:

* **OpenRouter**: May not preserve the original model's capabilities
* **Custom API endpoints**: May have different capabilities than standard models
* **Local models**: May need explicit capabilities if using non-standard model names

Example configuration:

```yaml  theme={null}
models:
  - name: custom-deployment
    provider: openai
    apiBase: https://custom-api.company.com/v1
    model: custom-gpt
    capabilities:
      - tool_use # If supports function calling
      - image_input # If supports vision
```

## How to Troubleshoot Capability Issues

For troubleshooting capability-related issues like Agent mode being unavailable or tools not working, see the [Troubleshooting guide](/troubleshooting#agent-mode-is-unavailable-or-tools-aren’t-working).

## Best Practices for Model Capabilities

1. **Start with autodetection** - Only override if you experience issues
2. **Test after changes** - Verify tools and images work as expected
3. **Keep Gobi updated** - Newer versions improve autodetection

Remember: Setting capabilities only adds to autodetection. Gobi will still use its built-in knowledge about your model in addition to your specified capabilities.

## Model Capability Support

This matrix shows which models support tool use and image input capabilities. Gobi auto-detects these capabilities, but you can override them if needed.

### OpenAI

| Model         | Tool Use | Image Input | Context Window |
| :------------ | -------- | ----------- | -------------- |
| o3            | Yes      | No          | 128k           |
| o3-mini       | Yes      | No          | 128k           |
| GPT-4o        | Yes      | Yes         | 128k           |
| GPT-4 Turbo   | Yes      | Yes         | 128k           |
| GPT-4         | Yes      | No          | 8k             |
| GPT-3.5 Turbo | Yes      | No          | 16k            |

### Anthropic

| Model             | Tool Use | Image Input | Context Window |
| :---------------- | -------- | ----------- | -------------- |
| Claude 4 Sonnet   | Yes      | Yes         | 200k           |
| Claude 3.5 Sonnet | Yes      | Yes         | 200k           |
| Claude 3.5 Haiku  | Yes      | Yes         | 200k           |

### Google

| Model            | Tool Use | Image Input | Context Window |
| :--------------- | -------- | ----------- | -------------- |
| Gemini 2.5 Pro   | Yes      | Yes         | 2M             |
| Gemini 2.0 Flash | Yes      | Yes         | 1M             |

### Mistral

| Model           | Tool Use | Image Input | Context Window |
| :-------------- | -------- | ----------- | -------------- |
| Devstral Medium | Yes      | No          | 32k            |
| Mistral         | Yes      | No          | 32k            |

### DeepSeek

| Model             | Tool Use | Image Input | Context Window |
| :---------------- | -------- | ----------- | -------------- |
| DeepSeek V3       | Yes      | No          | 128k           |
| DeepSeek Coder V2 | Yes      | No          | 128k           |
| DeepSeek Chat     | Yes      | No          | 64k            |

### xAI

| Model                     | Tool Use | Image Input | Context Window |
| :------------------------ | -------- | ----------- | -------------- |
| Grok Code Fast 1          | Yes      | Yes         | 256k           |
| Grok 4 Fast Reasoning     | Yes      | Yes         | 2M             |
| Grok 4 Fast Non-Reasoning | Yes      | Yes         | 2M             |
| Grok 4                    | Yes      | Yes         | 256k           |
| Grok 3                    | Yes      | Yes         | 131k           |
| Grok 3 Mini               | Yes      | Yes         | 131k           |

### Moonshot AI

| Model   | Tool Use | Image Input | Context Window |
| :------ | -------- | ----------- | -------------- |
| Kimi K2 | Yes      | Yes         | 128k           |

### Qwen

| Model             | Tool Use | Image Input | Context Window |
| :---------------- | -------- | ----------- | -------------- |
| Qwen Coder 3 480B | Yes      | No          | 128k           |

### Ollama (Local Models)

| Model          | Tool Use | Image Input | Context Window |
| :------------- | -------- | ----------- | -------------- |
| Qwen 3 Coder   | Yes      | No          | 32k            |
| Qwen 2.5 VL    | No       | Yes         | 128k           |
| Devstral Small | Yes      | No          | 32k            |
| Llama 3.1      | Yes      | No          | 128k           |
| Llama 3        | Yes      | No          | 8k             |
| Mistral        | Yes      | No          | 32k            |
| Codestral      | Yes      | No          | 32k            |
| Gemma 3 4B     | Yes      | Yes         | 128k           |

### Notes

* **Tool Use**: Function calling support (tools are required for Agent mode)
* **Image Input**: Processing images
* **Context Window**: Maximum number of tokens the model can process in a single request

***

**Is your model missing or incorrect?** Help improve this documentation! You can edit this page on GitHub using the link below.


# How to Create and Manage Prompts in Gobi
Source: https://docs.gourmand.dev/customize/deep-dives/prompts

Prompts are used to kick off tasks for Agent mode, Plan mode, and Chat mode

Prompts are included as user messages and are especially useful as instructions for repetitive and/or complex tasks.

## Slash commands

By setting `invokable` to `true`, you make the markdown file a prompt, which will be available when you type <kbd>/</kbd> in Chat, Plan, and Agent mode.

```md title="explain-invokable.md" theme={null}
---
name: Explain invokable
description: Explains what happens when you set invokable to true
invokable: true
---

Explain that when `invokable` is set to `true`, a slash command becomes available in the IDE extensions and CLI
```

These slash commands can be combined with other instructions, including highlighted code, to provide additional context.

## Example: `Create Supabase functions` prompt

Here is a prompt that generates high-quality PostgreSQL functions that adhere to best practices:

```md title="supabase-create-functions.md" theme={null}
---
name: Create Supabase functions
description: Guidelines for writing Supabase database functions
invokable: true
---

# Database: Create functions

You're a Supabase Postgres expert in writing database functions. Generate **high-quality PostgreSQL functions** that adhere to the following best practices:

## General Guidelines

1. **Default to `SECURITY INVOKER`:**

   - Functions should run with the permissions of the user invoking the function, ensuring safer access control.
   - Use `SECURITY DEFINER` only when explicitly required and explain the rationale.

2. **Set the `search_path` Configuration Parameter:**

   - Always set `search_path` to an empty string (`set search_path = '';`).
   - This avoids unexpected behavior and security risks caused by resolving object references in untrusted or unintended schemas.
   - Use fully qualified names (e.g., `schema_name.table_name`) for all database objects referenced within the function.

3. **Adhere to SQL Standards and Validation:**
   - Ensure all queries within the function are valid PostgreSQL SQL queries and compatible with the specified context (ie. Supabase).

...
```

<Info>You can read the rest of the `Create Supabase functions` prompt [here](http://hub.gourmand.dev/supabase/create-functions)</Info>

If you are using a local `config.yaml`, you can add it to your config like this:

```md title="config.yaml" theme={null}
...

prompts:
  - uses: supabase/create-functions

...
```

If you are using Gobi Hub, you can add it to your config by selecting "Use Rule" [here](https://hub.gourmand.dev/supabase/create-functions)

To use this prompt, you can open Chat / Agent / Edit, type <kbd>/</kbd>, select the prompt, and type out any additional instructions you'd like to add.

## Using a prompt with `cn (TUI mode)`

You can run this command to start [cn](../../guides/cli) with the [Create Supabase functions](http://hub.gourmand.dev/supabase/create-functions) prompt.

```
cn --prompt supabase/create-functions "I need a function that checks for the health status"
```

Alternatively, you can start [cn](../../guides/cli) and then type <kbd>/</kbd> to manually invoke the prompt yourself.

## Using a prompt to kick off a Continuous AI workflow with \`cn (Headless mode)

You can kick off Continuous AI workflows using a prompt with [cn](../../guides/cli) by adding the `-p` flag.

For example, say you are building a SaaS application and must repeatedly create custom Supabase validation functions for each new feature that accepts user input.

These functions require you to interpret business requirements, implement complex cross-table logic (like checking user permissions, tier limits, and time-based restrictions), and make judgment calls about edge cases.

Each function is unique enough that it can't be templated or scripted. This is where kicking off a Continuous AI workflow to get you started can be quite helpful.

Here is a command that you could run whenever you have a new feature:

```
 cn -p --prompt supabase/create-functions "I need a function for the new feature on my current branch similar to my existing database functions"
```

<Info>You can see the entire `Create Supabase functions` prompt [here](http://hub.gourmand.dev/supabase/create-functions)</Info>

When you run this workflow, [cn](../../guides/cli) will checkout your current branch, explore the new and existing code, and then draft a function for you.

You will then be able to review the implementation and improve it before you merge the new feature.


# How to Create and Manage Rules in Gobi
Source: https://docs.gourmand.dev/customize/deep-dives/rules

Rules are used to provide system message instructions to the model for Agent mode, Chat mode, and Edit mode requests

Rules provide instructions to the model for [Agent mode](../../ide-extensions/agent/quick-start), [Chat](../../ide-extensions/chat/quick-start), and [Edit](../../ide-extensions/edit/quick-start) requests.

<Info>
  Rules are not included in [autocomplete](./autocomplete) or
  [apply](../model-roles/apply).
</Info>

## How Rules Work in Gobi

You can view the current rules by clicking the pen icon above the main toolbar:

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/notch-rules.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=42c744a5bef1f2a58f22da60429f0343" alt="rules input toolbar section" data-og-width="986" width="986" data-og-height="534" height="534" data-path="images/notch-rules.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/notch-rules.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=b2df84ea965be54cf5860907b699df4c 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/notch-rules.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=7e27febf206c85fa7953713b561fee07 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/notch-rules.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=188b4bd073287f0acd6e3f07b118699e 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/notch-rules.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=28ffb383a00076791d09ffaa0a7f7c54 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/notch-rules.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=a2dea42d678e7adbce9d812a271eff78 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/notch-rules.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=8bde442a6cfdca2b084062ac82ee58d3 2500w" />

To form the system message, rules are joined with new lines, in the order they appear in the toolbar. This includes the base chat system message ([see below](#how-to-customize-chat-system-message)).

## Understanding Hub vs Local Rules Integration

<Warning>
  **Important:** Rules created in different locations behave differently and have different synchronization patterns.
</Warning>

Gobi supports two types of rules with different behaviors:

<Columns cols={2}>
  <Card title="Local Rules" icon="folder">
    * **Location**: `.gobi/rules` folder in your workspace
    * **Visibility**: Automatically visible when using Hub assistants
    * **Creation**: Add rules button in VSCode or manual file creation
    * **File Management**: Creates actual `.md` files you can edit directly
  </Card>

  <Card title="Hub Rules" icon="cloud">
    * **Location**: Stored on Gobi Hub, referenced in config.yaml
    * **Visibility**: Only appear when referenced in assistant configuration
    * **Creation**: Created directly on Hub or copied from local rules
    * **File Management**: No local files created, managed through Hub interface
  </Card>
</Columns>

### How Rules Are Applied

When using Gobi, rules are loaded in this order:

1. **Hub assistant rules** (if using a Hub-based assistant)
2. **Referenced Hub rules** (via `uses:` in config.yaml)
3. **Local workspace rules** (from `.gobi/rules` folder)
4. **Global rules** (from `~/.gobi/rules` folder)

<Info>
  **TL;DR**: Local rules show up automatically when using Hub assistants. Hub rules show up automatically when referenced in your config.
</Info>

## Quick Start: How to Create Your First Rule File

Below is a quick example of setting up a new rule file:

1. Create a folder called `.gobi/rules` at the top level of your workspace
2. Add a file called `pirates-rule.md` to this folder.
3. Write the following contents to `pirates-rule.md` and save.

```md title=".gobi/rules/pirates-rule.md" theme={null}
---
name: Pirate rule
---

- Talk like a pirate.
```

Now test your rules by asking a question about a file in chat.

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/pirate-rule-test.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=97c548f044979ce1a3a19300c8d0d009" alt="pirate rule test" data-og-width="976" width="976" data-og-height="466" height="466" data-path="images/pirate-rule-test.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/pirate-rule-test.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=70f8073f6bae025b5eeef0e5fcd736b7 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/pirate-rule-test.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=fa08410085a72ff05400dd36917b503f 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/pirate-rule-test.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=1449febbcffe56435644aadffe3ce5f2 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/pirate-rule-test.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=3a1f184cbedf29e4108f11e708e6b618 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/pirate-rule-test.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=d77eb7e28e885045f4e0408610fd4d64 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/pirate-rule-test.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=220a94866cf45092ecd538f7e7ee997f 2500w" />

## How to Create Rules Blocks

### Creating Local Rules

Rules can be added locally using the "Add Rules" button.

<img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/add-local-rules.png?fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=73035e165145fdf9947bca59dac4ce30" alt="add local rules button" data-og-width="558" width="558" data-og-height="466" height="466" data-path="images/add-local-rules.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/add-local-rules.png?w=280&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=b697300bcf9a8ac2fbaa8e52a606bdbd 280w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/add-local-rules.png?w=560&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=291164fea3f29bc93a147e157df0d046 560w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/add-local-rules.png?w=840&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=a093d4f315875d4f5d86c673f39a4fab 840w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/add-local-rules.png?w=1100&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=2fdc77eb10ca49b789042665a0bbd87a 1100w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/add-local-rules.png?w=1650&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=c04d5ab331cef6f51f8f967e38ee18aa 1650w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/add-local-rules.png?w=2500&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=5f5de6af7f53721af0e38704636975a6 2500w" />

<Info>
  **Automatically create local rule blocks**: When in Agent mode, you can prompt the agent to create a rule for you using the `create_rule_block` tool if enabled.

  For example, you can say "Create a rule for this", and a rule will be created for you in `.gobi/rules` based on your conversation.
</Info>

### Creating Hub Rules

Rules can also be created and managed on the Gobi Hub:

1. **Browse existing rules**: [Explore available rules](https://hub.gourmand.dev)
2. **Create new rules**: [Create your own](https://hub.gourmand.dev/new?type=block\&blockType=rules) in the Hub
3. **Copy from local rules**: Copy/paste content from your `.gobi/rules` files to create Hub rules

### Working Between Hub and Local Rules

<Tabs>
  <Tab title="Hub to VSCode">
    To use Hub rules in your local setup:

    1. Reference them in your `config.yaml`:
       ```yaml  theme={null}
       rules:
         - uses: username/my-hub-rule
       ```
    2. The rule will automatically appear in your rules toolbar
    3. **Note**: No local file is created - the rule exists only on the Hub
  </Tab>

  <Tab title="VSCode to Hub">
    To move local rules to the Hub:

    1. Copy the content from your `.gobi/rules/rule-name.md` file
    2. Go to [Create new rule](https://hub.gourmand.dev/new?type=block\&blockType=rules)
    3. Paste the content and configure the rule
    4. Optionally, remove the local file and reference the Hub rule in your config

    <Warning>
      **Current Limitation**: There's no automatic sync from local to Hub. You must manually copy/paste rule content.
    </Warning>
  </Tab>
</Tabs>

### How to Configure Rule Properties and Syntax

<Info>
  Rules were originally defined in YAML format (demonstrated below), but we
  introduced Markdown for easier editing. While both are still supported, we
  recommend Markdown.
</Info>

Rules blocks can be simple text, written in YAML configuration files, or as Markdown (`.md`) files. They can have the following properties:

* `name` (**required** for YAML): A display name/title for the rule
* `globs` (optional): When files are provided as context that match this glob pattern, the rule will be included. This can be either a single pattern (e.g., `"**/*.{ts,tsx}"`) or an array of patterns (e.g., `["src/**/*.ts", "tests/**/*.ts"]`).
* `regex` (optional): When files are provided as context and their content matches this regex pattern, the rule will be included. This can be either a single pattern (e.g., `"^import .* from '.*';$"`) or an array of patterns (e.g., `["^import .* from '.*';$", "^export .* from '.*';$"]`).
* `description` (optional): A description for the rule. Agents may read this description when `alwaysApply` is false to determine whether the rule should be pulled into context.
* `alwaysApply`: Determines whether the rule is always included. Behavior is described below:
  * `true`: Always included, regardless of file context
  * `false`: Included if globs exist AND match file context, or the agent decides to pull the rule into context based on its description
  * `undefined` (default behavior): Included if no globs exist OR globs exist and match

<Tabs>
  <Tab title="Markdown">
    ```md title="doc-standards.md" theme={null}
    ---
    name: Documentation Standards
    globs: docs/**/*.{md,mdx}
    alwaysApply: false
    description: Standards for writing and maintaining Gobi Docs
    ---

    # Gobi Docs Standards

    - Follow Mintlify documentation standards
    - Include YAML frontmatter with title, description, and keywords
    - Use consistent heading hierarchy starting with h2 (##)
    - Include relevant Admonition components for tips, warnings, and info
    - Use descriptive alt text for images
    - Include cross-references to related documentation
    - Reference other docs with relative paths
    - Keep paragraphs concise and scannable
    - Use code blocks with appropriate language tags

    ```
  </Tab>

  <Tab title="YAML">
    ```yaml title="doc-standards.yaml" theme={null}
    name: Documentation Standards
    version: 1.0.0
    schema: v1

    rules:
      - name: Documentation Standards
        globs: docs/**/*.{md,mdx}
        alwaysApply: false
        rule: >
          - Follow Mintlify documentation standards
          - Include YAML frontmatter with title, description, and keywords
          - Use consistent heading hierarchy starting with h2 (##)
          - Include relevant Admonition components for tips, warnings, and info
          - Use descriptive alt text for images
          - Include cross-references to related documentation
          - Reference other docs with relative paths
          - Keep paragraphs concise and scannable
          - Use code blocks with appropriate language tags
    ```
  </Tab>
</Tabs>

### How to Set Up Project-Specific Rules

You can create project-specific rules by adding a `.gobi/rules` folder to the root of your project and adding new rule files.

Rules files are loaded in lexicographical order, so you can prefix them with numbers to control the order in which they are applied. For example: `01-general.md`, `02-frontend.md`, `03-backend.md`.

### Example: How to Create TypeScript-Specific Rules

```md title=".gobi/rules/typescript.md" theme={null}
---
name: TypeScript Best Practices
globs: ["**/*.ts", "**/*.tsx"]
---

# TypeScript Rules

- Always use TypeScript interfaces for object shapes
- Use type aliases sparingly, prefer interfaces
- Include proper JSDoc comments for public APIs
- Use strict null checks
- Prefer readonly arrays and properties where possible
- modularize components into smaller, reusable pieces
```

## Troubleshooting Rules

### Issue: Rules Created in Different Places Don't Sync

**Problem**: You created rules in the Hub but don't see them in VSCode, or vice versa.

**Solution**:

* **Hub rules** only appear when referenced in your config.yaml using the `uses:` syntax
* **Local rules** automatically appear when using Hub assistants
* There's currently no automatic bidirectional sync

### Issue: "Edit" Links Point to Wrong Location

**Problem**: When you click "Edit" on a rule in VSCode, it tries to open the Hub even though the rule is local, or shows an incorrect URL.

**Root Cause**: This happens when you have a mix of local and Hub rules, and Gobi can't properly determine where each rule originates.

**Workaround**:

1. **For local rules**: Navigate directly to `.gobi/rules/` folder and edit the `.md` file
2. **For Hub rules**: Go directly to your assistant page on [Gobi Hub](https://hub.gourmand.dev) and edit from there
3. Keep track of which rules are local vs Hub-based to avoid confusion

<Info>
  **Known Issue**: This link accuracy problem is tracked in [Linear issue CON-3084](https://linear.app/gobi/issue/CON-3084) and will be fixed in a future update.
</Info>

### Issue: Rules Don't Appear in Assistant

**Problem**: Your rules exist but don't show up in the rules toolbar.

**Check These**:

1. **File location**: Ensure local rules are in `.gobi/rules/` (not `.gobi/rule/`)
2. **File format**: Rules should be `.md` files with proper YAML frontmatter
3. **Config reference**: Hub rules must be referenced in `config.yaml`
4. **Assistant type**: Ensure you're using the correct assistant (local vs Hub)

### How to Customize Chat System Message

Gobi includes a simple default system message for [Agent mode](../../ide-extensions/agent/quick-start) and [Chat](../../ide-extensions/chat/quick-start) requests, to help the model provide reliable codeblock formats in its output.

This can be viewed in the rules section of the toolbar (see above), or in the source code [here](https://github.com/gourmand/gobi/blob/main/core/llm/constructMessages.ts#L4).

Advanced users can override this system message for a specific model if needed by using `chatOptions.baseSystemMessage`. See the [`config.yaml` reference](/reference#models).


# Ask Sage
Source: https://docs.gourmand.dev/customize/model-providers/more/asksage



<Tip>
  **Discover Ask Sage models [here](https://hub.gourmand.dev/?q=Ask%20Sage)**
</Tip>

<Info>
  You can get an API key from the [Ask Sage](https://www.asksage.ai/).
</Info>

## Overview

Ask Sage provides secure, government-compliant access to LLMs. This guide explains how to set up and configure Ask Sage models, including support for DoD certificates.

## 1. Prerequisites

* **Ask Sage Account:**\
  Sign up or log in at [Ask Sage Platform](https://chat.asksage.ai/).

* **API Key:**\
  Follow the [API Key Documentation](https://docs.asksage.ai/docs/api-documentation/api-documentation.html) to generate your key.

## 2. Configuration

Add your Ask Sage model to your Gobi configuration file.

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: GPT-4 gov
        provider: askSage
        model: gpt4-gov
        apiBase: https://api.asksage.ai/server/
        apiKey: <YOUR_ASK_SAGE_API_KEY>
    ```
  </Tab>

  <Tab title="JSON">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "GPT-4 gov",
          "provider": "askSage",
          "model": "gpt4-gov",
          "apiBase": "https://api.asksage.ai/server/",
          "apiKey": "<YOUR_ASK_SAGE_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## 3. Using DoD Certificates

For secure environments, specify your DoD CA bundle path:

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: GPT-4 gov
        provider: askSage
        model: gpt4-gov
        apiBase: https://api.asksage.ai/server/
        apiKey: <YOUR_ASK_SAGE_API_KEY>
        requestOptions:
          caBundlePath: /path/to/dod/certificates
    ```
  </Tab>

  <Tab title="JSON">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "GPT-4 gov",
          "provider": "askSage",
          "model": "gpt4-gov",
          "apiBase": "https://api.asksage.ai/server/",
          "apiKey": "<YOUR_ASK_SAGE_API_KEY>",
          "requestOptions": {
            "caBundlePath": "/path/to/dod/certificates"
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

Replace `/path/to/dod/certificates` with your actual CA bundle file path.

***

## 4. Final Steps

* Save your configuration file.
* Restart Gobi to apply changes.

Your Ask Sage model will now be available in Gobi.

## 5. Usage

Supported features:

* **Chat:** Interact and iterate on code in the sidebar.
* **Edit:** Modify code in place.

## 6. Support

* Refer to [Ask Sage Docs](https://docs.asksage.ai/docs/api-documentation/api-documentation.html) for more details.
* Email the Ask Sage support team for assistance at [support@asksage.ai](mailto:support@asksage.ai).

***


# DeepInfra
Source: https://docs.gourmand.dev/customize/model-providers/more/deepinfra

Configure DeepInfra with Gobi to access low-cost inference for open-source models like Mixtral-8x7B-Instruct, including API setup instructions

<Tip>
  **Discover Deep Infra models [here](https://hub.gourmand.dev/deepinfra)**
</Tip>

<Info>
  Get an API key from the [Deep Infra](https://deepinfra.com/)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: deepinfra
        model: <MODEL_ID>
        apiKey: <YOUR_DEEPINFRA_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "deepinfra",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_DEEPINFRA_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/deepinfra/qwen-qwen2.5-coder-32b-instruct?view=config)**
</Info>


# DeepSeek
Source: https://docs.gourmand.dev/customize/model-providers/more/deepseek



<Tip>
  **Discover DeepSeek models [here](https://hub.gourmand.dev/?q=DeepSeek)**
</Tip>

<Info>
  You can get an API key from the [DeepSeek Console](https://www.deepseek.com/).
</Info>

## Confiugration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: deepseek
        model: <MODEL_ID>
        apiKey: <YOUR_DEEPSEEK_API_KEY>
    ```
  </Tab>

  <Tab title="JSON">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "deepseek",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_DEEPSEEK_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>


# How to Configure Groq with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/more/groq



<Info>
  Get your API key from the [Groq Console](https://console.groq.com/docs/models)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: groq
        model: <MODEL_ID>
        apiKey: <YOUR_GROQ_API_KEY>"
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "groq",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_GROQ_API_KEY>"",
        }
      ]
    }
    ```
  </Tab>
</Tabs>


# Hugging Face
Source: https://docs.gourmand.dev/customize/model-providers/more/huggingfaceinferenceapi



<Info>
  Get started with [Hugging Face Inference Endpoints](https://endpoints.huggingface.co/)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: huggingface-inference-api
        model: <MODEL_ID>
        apiKey: <YOUR_HF_TOKEN>
        apiBase: <YOUR_HF_INFERENCE_API_ENDPOINT_URL>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "huggingface-inference-api",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_HF_TOKEN>",
          "apiBase": "<YOUR_HF_INFERENCE_API_ENDPOINT_URL>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>


# Llama.cpp
Source: https://docs.gourmand.dev/customize/model-providers/more/llamacpp



<Info>
  Get started with [Llama.cpp](https://github.com/ggml-org/llama.cpp?tab=readme-ov-file#quick-start)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: llama.cpp
        model: <MODEL_ID>
        apiBase: http://localhost:8080
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "llama.cpp",
          "model": "<MODEL_ID>"
          "apiBase": "http://localhost:8080"
        }
      ]
    }
    ```
  </Tab>
</Tabs>


# Llama Stack
Source: https://docs.gourmand.dev/customize/model-providers/more/llamastack



<Info>
  Get started with [Lllama Stack](https://llama-stack.readthedocs.io/en/latest/getting_started/index.html)
</Info>

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: llamastack
        model: <MODEL_ID>
        apiBase: http://<LLAMA_STACK_ENDPOINT>/v1/openai/v1/
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "llamastack",
          "model": "<MODEL_ID>",
          "apiBase": "http://<LLAMA_STACK_ENDPOINT>/v1/openai/v1/"
        }
      ]
    }
    ```
  </Tab>
</Tabs>


# Mistral
Source: https://docs.gourmand.dev/customize/model-providers/more/mistral



<Tip>
  **Discover Mistral models [here](https://hub.gourmand.dev/mistral)**
</Tip>

<Info>
  Get an API key from the [Mistral Dashboard](https://console.mistral.ai)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: mistral
        model: <MODEL_ID>
        apiKey: <YOUR_MISTRAL_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "mistral",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_MISTRAL_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/mistral/codestral?view=config)**
</Info>

<Note>
  The API key for `codestral.mistral.ai` is different from `api.mistral.ai`.
  If you are using a Codestral API key, you should set the `apiBase` to `https://codestral.mistral.ai/v1`.
  Otherwise, we will default to using `https://api.mistral.ai/v1`.
</Note>


# NVIDIA
Source: https://docs.gourmand.dev/customize/model-providers/more/nvidia



<Info>
  Get an API key from the [NVIDIA](https://docs.nvidia.com/nim/large-language-models/latest/getting-started.html#option-1-from-api-catalog)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: nvidia
        model: <MODEL_ID>
        apiKey: <YOUR_NVIDIA_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "nvidia",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_NVIDIA_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>


# Together AI
Source: https://docs.gourmand.dev/customize/model-providers/more/together



<Tip>
  **Discover Together AI models [here](https://hub.gourmand.dev/togetherai)**
</Tip>

<Info>
  Get an API key from the [Together AI](https://api.together.ai)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: together
        model: <MODEL_ID>
        apiKey: <YOUR_TOGETHER_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "together",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_TOGETHER_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/togetherai/qwen3-coder-480b-a35b-instruct-fp8?view=config)**
</Info>


# xAI
Source: https://docs.gourmand.dev/customize/model-providers/more/xAI



<Tip>**Discover xAI models [here](https://hub.gourmand.dev/xai)**</Tip>

<Info>Get an API key from the [xAI Console](https://console.x.ai/)</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: xai
        model: <MODEL_ID>
        apiKey: <YOUR_XAI_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "xai",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_XAI_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration
  [here](https://hub.gourmand.dev/xai/grok-code-fast-1?view=config)**
</Info>


# Model Providers Overview
Source: https://docs.gourmand.dev/customize/model-providers/overview

Gobi supports a wide range of AI model providers to power different features like chat, code editing, autocompletion, and embeddings. This overview helps you navigate through the available options and find the right provider for your needs.

## Popular Model Providers

These are the most commonly used model providers that offer a wide range of capabilities:

| Provider                                                       | Description                                                                     | Capabilities                                |
| :------------------------------------------------------------- | :------------------------------------------------------------------------------ | :------------------------------------------ |
| [Anthropic](/customize/model-providers/top-level/anthropic)    | Providers of Claude models, known for long context windows and strong reasoning | Chat, Edit, Apply, Embeddings               |
| [OpenAI](/customize/model-providers/top-level/openai)          | Creators of GPT models with strong coding capabilities                          | Chat, Edit, Apply, Embeddings               |
| [Azure](/customize/model-providers/top-level/azure)            | Microsoft's cloud platform offering OpenAI models                               | Chat, Edit, Apply, Embeddings               |
| [Amazon Bedrock](/customize/model-providers/top-level/bedrock) | AWS service offering access to various foundation models                        | Chat, Edit, Apply, Embeddings               |
| [Ollama](/customize/model-providers/top-level/ollama)          | Run open-source models locally with a simple interface                          | Chat, Edit, Apply, Embeddings, Autocomplete |
| [Google Gemini](/customize/model-providers/top-level/gemini)   | Google's multimodal AI models                                                   | Chat, Edit, Apply, Embeddings               |
| [DeepSeek](/customize/model-providers/more/deepseek)           | Specialized code models with strong performance                                 | Chat, Edit, Apply                           |
| [Mistral](/customize/model-providers/more/mistral)             | High-performance open models with commercial offerings                          | Chat, Edit, Apply, Embeddings               |
| [xAI](/customize/model-providers/more/xAI)                     | Grok models from xAI                                                            | Chat, Edit, Apply                           |
| [Vertex AI](/customize/model-providers/top-level/vertexai)     | Google Cloud's machine learning platform                                        | Chat, Edit, Apply, Embeddings               |
| [Inception](/customize/model-providers/top-level/inception)    | On-premises open-source model runners                                           | Chat, Edit, Apply                           |

## Additional Model Providers

Beyond the top-level providers, Gobi supports many other options:

### Hosted Services

| Provider                                                                                          | Description                                                      |
| :------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------- |
| [Groq](/customize/model-providers/more/groq)                                                      | Ultra-fast inference for various open models                     |
| [Together AI](/customize/model-providers/more/together)                                           | Platform for running a variety of open models                    |
| [DeepInfra](/customize/model-providers/more/deepinfra)                                            | Hosting for various open source models                           |
| [OpenRouter](/customize/model-providers/top-level/openrouter)                                     | Gateway to multiple model providers                              |
| [Tetrate Agent Router Service](/customize/model-providers/top-level/tetrate_agent_router_service) | Gateway with intelligent routing across multiple model providers |
| [Cohere](/customize/model-providers/more/cohere)                                                  | Models specialized for semantic search and text generation       |
| [NVIDIA](/customize/model-providers/more/nvidia)                                                  | GPU-accelerated model hosting                                    |
| [Cloudflare](/customize/model-providers/more/cloudflare)                                          | Edge-based AI inference services                                 |
| [HuggingFace](/customize/model-providers/more/huggingfaceinferenceapi)                            | Platform for open source models                                  |

### Local Model Options

| Provider                                                   | Description                                   |
| :--------------------------------------------------------- | :-------------------------------------------- |
| [LM Studio](/customize/model-providers/top-level/lmstudio) | Desktop app for running models locally        |
| [llama.cpp](/customize/model-providers/more/llamacpp)      | Optimized C++ implementation for running LLMs |
| [LlamaStack](/customize/model-providers/more/llamastack)   | Stack for running Llama models locally        |
| [llamafile](/customize/model-providers/more/llamafile)     | Self-contained executable model files         |

### Enterprise Solutions

| Provider                                               | Description                           |
| :----------------------------------------------------- | :------------------------------------ |
| [SambaNova](/customize/model-providers/more/SambaNova) | Enterprise AI platform                |
| [Watson x](/customize/model-providers/more/watsonx)    | IBM's enterprise AI platform          |
| [Sagemaker](/customize/model-providers/more/sagemaker) | AWS machine learning platform         |
| [Nebius](/customize/model-providers/more/nebius)       | Cloud-based machine learning platform |

## How to Choose a Model Provider

When selecting a model provider, consider:

1. **Hosting preference**: Do you need local models for offline use or privacy, or are you comfortable with cloud services?
2. **Performance requirements**: Different providers offer varying levels of speed, quality, and context length.
3. **Specific capabilities**: Some models excel at code generation, others at embeddings or reasoning tasks.
4. **Pricing**: Costs vary significantly between providers, from free local options to premium cloud services.
5. **API key requirements**: Most cloud providers require API keys that you'll need to configure.

## Configuration Format

You can add models to your `config.yaml` file like this:

```yaml  theme={null}
models:
  - name: Claude 4 Sonnet
    provider: anthropic # Choose provider from the lists above
    model: claude-sonnet-4-20250514 # Specific model name
    apiKey: ${{ secrets.OPENAI_API_KEY }}
    roles:
      - chat
      - edit
      - apply
```

For more detailed configuration, visit the specific provider pages linked above.


# How to Configure Anthropic Claude Models with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/top-level/anthropic



<Tip>
  **Discover Anthropic models [here](https://hub.gourmand.dev/anthropic)**
</Tip>

<Info>
  Get an API key from the [Anthropic Console](https://console.anthropic.com/account/keys)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: anthropic
        model: <MODEL_ID>
        apiKey: <YOUR_ANTHROPIC_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "anthropic",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_ANTHROPIC_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/anthropic/claude-4-sonnet?view=config)**
</Info>

## How to Enable Prompt Caching with Claude

Anthropic supports [prompt caching with Claude](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching), which allows Claude models to cache system messages and conversation history between requests to improve performance and reduce costs.

To enable caching of the system message and the turn-by-turn conversation, update your model configuration as follows:

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: anthropic
        model: <MODEL_ID>
        apiKey: <YOUR_ANTHROPIC_API_KEY>
        roles:
          - chat
        defaultCompletionOptions:
          promptCaching: true
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "cacheBehavior": {
            "cacheSystemMessage": true,
            "cacheConversation": true
          },
          "title": "<MODEL_NAME>",
          "provider": "anthropic",
          "model": "<MODEL_ID>",
          "defaultCompletionOptions": {
            "promptCaching": true
          },
          "apiKey": "<YOUR_ANTHROPIC_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>


# How to Configure Azure AI Foundry with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/top-level/azure



<Info>
  Create an Azure AI Foundry resource in the [Azure Portal](https://portal.azure.com)
</Info>

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <Model_NAME>
        provider: azure
        model: <MODEL_ID>
        apiBase: <YOUR_DEPLOYMENT_BASE>
        apiKey: <YOUR_AZURE_API_KEY> # If you use subscription key, try using Azure gateway to rename it apiKey
        env:
          deployment: <YOUR_DEPLOYMENT_NAME>
          apiType: azure-foundry # Or "azure-openai" if using OpenAI models
          apiVersion: 2023-07-01-preview # Azure API version
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [{
          "title": "<MODEL_NAME>",
          "provider": "azure",
          "model": "<MODEL_ID>",
          "apiBase": "<YOUR_DEPLOYMENT_BASE>",
          "deployment": "<YOUR_DEPLOYMENT_NAME>",
          "apiKey": "<YOUR_AZURE_API_KEY>", // If you use subscription key, try using Azure gateway to rename it apiKey
          "apiType": "azure-foundry" // Or "azure-openai" if using OpenAI models
      }]
    }
    ```
  </Tab>
</Tabs>

## Azure OpenAI Service (Alternative)

<Info>
  Get access to the Azure OpenAI service [here](https://azure.microsoft.com/en-us/products/ai-services/openai-service)
</Info>

Azure OpenAI Service requires a handful of additional parameters to be configured, such as a deployment name and API base URL.

To find this information in *Azure AI Foundry*, first select the model that you would like to connect. Then visit *Endpoint* > *Target URI*.

For example, a Target URI of `https://just-an-example.openai.azure.com/openai/deployments/gpt-4o-july/chat/completions?api-version=2023-03-15-preview` would map to the following:

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        model: <MODEL_ID>
        provider: azure
        apiBase: https://just-an-example.openai.azure.com
        apiKey: <YOUR_AZURE_API_KEY>
        env:
          apiVersion: <API_VERSION>
          deployment: <MODEL_DEPLOYMENT>
          apiType: azure-openai
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "title": "<MODEL_NAME>",
      "model": "<MODEL_ID>",
      "provider": "azure",
      "apiBase": "https://just-an-example.openai.azure.com",
      "deployment": "<MODEL_DEPLOYMENT>",
      "apiVersion": "<API_VERSION>",
      "apiKey": "<YOUR_AZURE_API_KEY>",
      "apiType": "azure-openai"
    }
    ```
  </Tab>
</Tabs>


# How to Configure Amazon Bedrock with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/top-level/bedrock



<Tip>
  **Discover Amazon Bedrock models [here](https://hub.gourmand.dev/amazon)**
</Tip>

<Info>
  Get started with [Amazon Bedrock](https://aws.amazon.com/bedrock/)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: bedrock
        model: <MODEL_ID>
        env:
          region: us-east-1
          profile: bedrock
        roles:
          - chat
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "bedrock",
          "model": "<MODEL_ID>",
          "region": "us-east-1",
          "profile": "bedrock"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/amazon/us-anthropic-claude-sonnet-4-20250514-v1?view=config)**
</Info>

## How to Enable Prompt Caching with Amazon Bedrock

Bedrock allows Claude models to cache tool payloads, system messages, and chat
messages between requests. Enable this behavior by adding
`promptCaching: true` under `defaultCompletionOptions` in your model
configuration.

```yaml title="config.yaml" theme={null}
models:
  - name: <MODEL_NAME>
    provider: bedrock
    model: <MODEL_ID>
    defaultCompletionOptions:
      promptCaching: true
```

Prompt caching is not supported in JSON configuration files, so use the YAML syntax above to enable it.

## How to Set Up Authentication for Amazon Bedrock

Authentication will be through temporary or long-term credentials in
`~/.aws/credentials` under a configured profile (e.g. "bedrock").

```title="~/.aws/credentials  theme={null}
[bedrock]
aws_access_key_id = abcdefg
aws_secret_access_key = hijklmno
aws_session_token = pqrstuvwxyz # Optional: means short term creds.
```

You can also use an AWS `accessKeyId` and `secretAccessKey` for authentication instead of a local credentials profile.

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: bedrock
        model: <MODEL_ID>
        env:
          region: us-east-1
          accessKeyId: ${{ secrets.AWS_ACCESS_KEY_ID }} # can also enter key inline here for local assistants
          secretAccessKey: ${{ secrets.AWS_SECRET_ACCESS_KEY }} # can also enter key inline here for local assistants
        roles:
          - chat
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "bedrock",
          "model": "<MODEL_ID>",
          "region": "us-east-1",
          "accessKeyId": "<YOUR_ACCESS_KEY_ID>",
          "secretAccessKey": "<YOUR_SECRET_ACCESS_KEY>" 
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## How to Configure Custom Imported Models with Amazon Bedrock

To setup Bedrock using custom imported models, add the following to your config file:

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: bedrockimport
        model: <MODEL_ID>
        env:
          region: us-west-2
          profile: bedrock
          modelArn: arn:aws:bedrock:us-west-2:XXXXX:imported-model/XXXXXX
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "bedrockimport",
          "model": "<MODEL_ID>",
          "modelArn": "arn:aws:bedrock:us-west-2:XXXXX:imported-model/XXXXXX", 
          "region": "us-west-2",
          "profile": "bedrock"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

Authentication will be through temporary or long-term credentials in
\~/.aws/credentials under a configured profile (e.g. "bedrock").

```title="~/.aws/credentials  theme={null}
[bedrock]
aws_access_key_id = abcdefg
aws_secret_access_key = hijklmno
aws_session_token = pqrstuvwxyz # Optional: means short term creds.
```


# How to Configure Gemini with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/top-level/gemini



<Tip>
  **Discover Google models [here](https://hub.gourmand.dev/?q=Gemini)**
</Tip>

<Info>
  Get an API key from [Google AI Studio](https://aistudio.google.com/)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: gemini
        model: <MODEL_ID>
        apiKey: <YOUR_GEMINI_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>", 
          "provider": "gemini",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_GEMINI_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/google/gemini-2.5-pro?view=config)**
</Info>


# How to Configure Inception with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/top-level/inception



<Tip>
  **Discover Inception models [here](https://hub.gourmand.dev/inceptionlabs)**
</Tip>

<Info>
  Get an API key from [Inception Platform](https://platform.inceptionlabs.ai/dashboard/api-keys)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: inception
        model: <MODEL_ID>
        apiKey: <INCEPTION_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "inception",
          "model": "<MODEL_ID>",
          "apiKey": "<INCEPTION_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/inceptionlabs/mercury-coder?view=config)**
</Info>


# LM Studio
Source: https://docs.gourmand.dev/customize/model-providers/top-level/lmstudio



<Tip>
  **Discover LM Studio models [here](https://hub.gourmand.dev/lmstudio)**
</Tip>

<Info>
  Get started with [LM Studio](https://lmstudio.ai/download)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: lmstudio
        model: <MODEL_ID>
        apiBase: http://<MY_ENDPOINT>/v1 # if running a remote instance of LM Studio
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "lmstudio",
          "model": "<MODEL_ID>",
          "apiBase": "http://<MY_ENDPOINT>/v1" // if running a remote instance of LM Studio
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Note>
  The default `apiBase` is `http://localhost:1234/v1`
</Note>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/lmstudio/qwen-qwen3-coder-30b?view=config)**
</Info>


# How to Configure Ollama with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/top-level/ollama



<Tip>
  **Discover Ollama models [here](https://hub.gourmand.dev/lmstudio)**
</Tip>

<Info>
  Get started with [Ollama](https://ollama.com/download)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: ollama
        model: <MODEL_ID>
        apiBase: http://<my endpoint>:11434 # if running a remote instance of Ollama
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "ollama",
          "model": "<MODEL_ID>"
          "apiBase": "http://<my endpoint>:11434" // if running a remote instance of Ollama
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/ollama/qwen3-coder-30b?view=config)**
</Info>

## How to Configure Model Capabilities in Ollama

Ollama models usually have their capabilities auto-detected correctly. However, if you're using custom model names or experiencing issues with tools/images not working, you can explicitly set capabilities:

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <CUSTOM_MODEL_NAME>
        provider: ollama
        model: <CUSTOM_MODEL_ID>
        capabilities:
          - tool_use      # Enable if your model supports function calling
          - image_input   # Enable for vision models
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<CUSTOM_MODEL_NAME>",
          "provider": "ollama",
          "model": "<CUSTOM_MODEL_ID>",
          "capabilities": {
            "tools": true, // Enable if your model supports function calling
            "uploadImage": true // Enable for vision models
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Note>
  Many Ollama models support tool use by default. Vision models often also support image input
</Note>


# How to Configure OpenAI Models with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/top-level/openai



<Tip>
  **Discover OpenAI models [here](https://hub.gourmand.dev/openai)**
</Tip>

<Info>
  Get an API key from the [OpenAI Console](https://platform.openai.com/account/api-keys)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: openai
        model: <MODEL_ID>
        apiKey: <YOUR_OPENAI_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "openai",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_OPENAI_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/openai/gpt-5?view=config)**
</Info>

## OpenAI API compatible providers

OpenAI API compatible providers include

* [KoboldCpp](https://github.com/lostruins/koboldcpp)
* [text-gen-webui](https://github.com/oobabooga/text-generation-webui/tree/main/extensions/openai#setup--installation)
* [FastChat](https://github.com/lm-sys/FastChat/blob/main/docs/openai_api.md)
* [LocalAI](https://localai.io/basics/getting_started/)
* [llama-cpp-python](https://github.com/abetlen/llama-cpp-python#web-server)
* [TensorRT-LLM](https://github.com/NVIDIA/trt-llm-as-openai-windows?tab=readme-ov-file#examples)
* [vLLM](https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html)
* [BerriAI/litellm](https://github.com/BerriAI/litellm)
* [Tetrate Agent Router Service](https://router.tetrate.ai)

If you are using an OpenAI API compatible providers, you can change the `apiBase` like this:

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <OPENAI_API_COMPATIBLE_PROVIDER_MODEL>
        provider: openai
        model: <MODEL_NAME>
        apiBase: http://localhost:8000/v1
        apiKey: <YOUR_CUSTOM_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<OPENAI_API_COMPATIBLE_PROVIDER_MODEL>",
          "provider": "openai",
          "model": "<MODEL_NAME>",
          "apiKey": "<YOUR_CUSTOM_API_KEY>",
          "apiBase": "http://localhost:8000/v1"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

### How to Force Legacy Completions Endpoint Usage

To force usage of `completions` instead of `chat/completions` endpoint you can set:

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <OPENAI_API_COMPATIBLE_PROVIDER_MODEL>
        provider: openai
        model: <MODEL_NAME>>
        apiBase: http://localhost:8000/v1
        useLegacyCompletionsEndpoint: true
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<OPENAI_API_COMPATIBLE_PROVIDER_MODEL>",
          "provider": "openai",
          "model": "<MODEL_NAME>",
          "apiBase": "http://localhost:8000/v1",
          "useLegacyCompletionsEndpoint": true
        }
      ]
    }
    ```
  </Tab>
</Tabs>


# How to Configure OpenRouter with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/top-level/openrouter



<Tip>
  **Discover Inception models [here](https://hub.gourmand.dev/inceptionlabs)**
</Tip>

<Info>
  Get an API key from [OpenRouter](https://openrouter.ai/keys)
</Info>

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: openrouter
        model: <MODEL_ID>
        apiBase: https://openrouter.ai/api/v1
        apiKey: <YOUR_OPEN_ROUTER_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "openrouter",
          "model": "<MODEL_ID>",
          "apiBase": "https://openrouter.ai/api/v1",
          "apiKey": "<YOUR_OPEN_ROUTER_API_KEY>"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Info>
  **Check out a more advanced configuration [here](https://hub.gourmand.dev/openrouter/qwen3-coder?view=config)**
</Info>

## Optional configuration

OpenRouter allows you configure provider preferences, model routing configuration, and more. You can set these via `requestOptions`.

For example, to prevent extra long prompts from being compressed, you can explicitly turn off [Transforms](https://openrouter.ai/docs/features/message-transforms):)

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: openrouter
        model: <MODEL_ID>
        requestOptions:
          extraBodyProperties:
            transforms: []
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "openrouter",
          "model": "<MODEL_ID>",
          "requestOptions": {
            "extraBodyProperties": {
              "transforms": []
            }
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## Model Capabilities

OpenRouter models may require explicit capability configuration because the proxy doesn't always preserve the function calling support of the original model.

<Info>
  Gobi automatically uses system message tools for models that don't support
  native function calling, so Agent mode should work even without explicit
  capability configuration. However, you can still override capabilities if
  needed.
</Info>

If you're experiencing issues with Agent mode or tools not working, you can add the capabilities field:

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: openrouter
        model: <MODEL_ID>
        apiBase: https://openrouter.ai/api/v1
        apiKey: <YOUR_OPEN_ROUTER_API_KEY>
        capabilities:
          - tool_use      # Enable function calling for Agent mode
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "openrouter",
          "model": "<MODEL_ID>",
          "apiBase": "https://openrouter.ai/api/v1",
          "apiKey": "<YOUR_OPEN_ROUTER_API_KEY>",
          "capabilities": {
            "tools": true, // Enable function calling for Agent mode
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<Note>
  Not all models support function calling. Check the [OpenRouter models page](https://openrouter.ai/models) for specific model capabilities.
</Note>


# Tetrate Agent Router Service
Source: https://docs.gourmand.dev/customize/model-providers/top-level/tetrate_agent_router_service



The **Tetrate Agent Router Service** provides a unified Gateway for accessing various AI models with fast inference capabilities.

This gateway acts as an intelligent router that can distribute requests across multiple model providers, offering enterprise-grade reliability and performance optimization.

<Tip>
  Want to get started quickly? Sign up for the [Tetrate Agent Router Service](https://router.tetrate.ai/) to get an API key, then use [Tetrate on Gobi Hub](https://hub.gourmand.dev/tetrate) to get started fast.
</Tip>

## Setup

<Steps>
  <Step title="Sign in or sign up">
    Visit the [Agent Router Service portal](https://router.tetrate.ai/) and create an account to get your API key

    <img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-sign-in.png?fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=1f965319a4bf4c050ff65dd82b24a357" alt="Tetrate sign in page" style={{width: '250px', maxWidth: '100%'}} data-og-width="824" width="824" data-og-height="1168" height="1168" data-path="customize/model-providers/assets/tetrate-sign-in.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-sign-in.png?w=280&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=2758f6e52ca8c3f63a103021eb095674 280w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-sign-in.png?w=560&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=1ba4dee05c2b06ac4c3886ab6c69a6af 560w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-sign-in.png?w=840&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=0b92fbe0709b75e7c3c93a69357df713 840w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-sign-in.png?w=1100&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=4c7f1f3e561708ca31587f0da54eb9e4 1100w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-sign-in.png?w=1650&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=a43cb2691acbe8cb71b6c5dfaea0be68 1650w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-sign-in.png?w=2500&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=45d10e5a05bfe9450ccaa160be22b208 2500w" />
  </Step>

  <Step title="Get your API key">
    Go to the [API keys page](https://router.tetrate.ai/api-keys) to get your key

    <img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-get-api-key.png?fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=e444e0eabbf9d3ad11d1be4cc1aa93b7" alt="Tetrate get API key" style={{width: '250px', maxWidth: '100%'}} data-og-width="500" width="500" data-og-height="722" height="722" data-path="customize/model-providers/assets/tetrate-get-api-key.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-get-api-key.png?w=280&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=24e25156a4a90151ccd3cb137f524a58 280w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-get-api-key.png?w=560&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=bd3c336b1f2e892a1829f00aaf4ea357 560w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-get-api-key.png?w=840&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=66e6347c710e84d3d3700e4a1d7e0626 840w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-get-api-key.png?w=1100&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=3469413b13078f52d0eba34eaae9a28e 1100w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-get-api-key.png?w=1650&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=56b25c2a6c57afc8f0b23de5d4cd61d1 1650w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-get-api-key.png?w=2500&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=77d47fe7e00ede1fa376a9c19d5d2a85 2500w" />
  </Step>

  <Step title="Configure Gobi">
    * Choose a configuration method below.
    * If you use the Gobi VS Code extension, install version `>=1.2.3`.
  </Step>
</Steps>

### Quickstart with Gobi Hub

Fastest way: use preconfigured models from Tetrate on Gobi Hub

<Steps>
  <Step title="Browse models">
    Open [Tetrate on Gobi Hub](https://hub.gourmand.dev/tetrate) and pick a model (e.g., [Claude Sonnet 4](https://hub.gourmand.dev/tetrate/claude-sonnet-4))
  </Step>

  <Step title="Use or remix">
    Click "Use Model", or "Remix" to change the model ID if needed
  </Step>

  <Step title="Add your API key">
    Add your API key to Gobi. See [adding secrets in Gobi Hub](/hub/secrets/secret-types) and [managing local secrets in the FAQ](/faqs#managing-local-secrets-and-environment-variables)

    <Tip>
      Add it as a Gobi Hub secret named `TETRATE_API_KEY` to reuse across projects.
    </Tip>
  </Step>
</Steps>

<img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-remix.png?fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=adf8a7599800f509b506f708b9629fc7" alt="Remix a model from Tetrate on Gobi Hub" data-og-width="1648" width="1648" data-og-height="1160" height="1160" data-path="customize/model-providers/assets/tetrate-remix.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-remix.png?w=280&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=f2624b82329d049d6820a75c0e9ada84 280w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-remix.png?w=560&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=cc415372b1f3c29afea92032e81657c3 560w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-remix.png?w=840&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=f17a79a84c263d3accc29cb46c73e146 840w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-remix.png?w=1100&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=44a0d6e42cd1ca2bb1fd7febcee6477d 1100w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-remix.png?w=1650&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=8a952285023e12ab63ae53ab0515b17d 1650w, https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/customize/model-providers/assets/tetrate-remix.png?w=2500&fit=max&auto=format&n=cY6wRTl5s2wbpiM-&q=85&s=7b0ff0c5678d34a3015df14ea81459de 2500w" />

<Info>
  If a model is missing, remix a similar one and set the `model` field to the target ID.
</Info>

### Configuration Methods

<CardGroup cols={1}>
  <Card title="In Local Agent Configuration" icon="folder" vertical>
    Use a Tetrate model block from the Hub or define it directly in your local agent configuration.
  </Card>

  <Card title="Gobi Hub" icon="cloud" vertical>
    Use a Tetrate model block from the Hub or define your own on the Hub.
  </Card>

  <Card title="Using Local Model Blocks" icon="file-lines" vertical>
    Create a local model block for reuse across agents without publishing it to the Hub.
  </Card>
</CardGroup>

### Configuration Examples

<Info>
  **Click a tab** to see an example.
</Info>

<Tabs>
  <Tab title="In Local Agent Configuration">
    **When to use**: Simple local setups (like using the VS Code extension) when you don't need shared or published blocks.

    Use a Tetrate model block from the Hub in your local agent configuration:

    ```yaml title="~/.gobi/config.yaml" theme={null}
    name: Local Agent
    version: 1.0.0
    schema: v1
    models:
      - uses: tetrate/claude-sonnet-4
        with:
          TETRATE_API_KEY: ${{ secrets.TETRATE_API_KEY }}
    context:
      - provider: code
      - provider: docs
      - provider: diff
      - provider: terminal
      - provider: problems
      - provider: folder
      - provider: codebase
    ```

    Or define the model directly:

    ```yaml title="~/.gobi/config.yaml" theme={null}
    name: Local Agent
    version: 1.0.0
    schema: v1
    models:
      - name: Claude Sonnet 4
        provider: tars
        model: claude-4-sonnet-20250514
        apiKey: ${{ secrets.TETRATE_API_KEY }}
        roles:
          - chat
          - edit
          - apply
        capabilities:
          - tool_use
    context:
      - provider: code
      - provider: docs
      - provider: diff
      - provider: terminal
      - provider: problems
      - provider: folder
      - provider: codebase
    ```
  </Tab>

  <Tab title="Gobi Hub">
    **When to use**: Share configurations across teams or contribute to the community.

    **The Model Block:**

    ```yaml title="tetrate/claude-sonnet-4" theme={null}
    name: Claude Sonnet 4
    version: 1.0.14
    schema: v1
    models:
      - name: Claude Sonnet 4 - Tetrate
        provider: tars
        model: claude-4-sonnet-20250514
        apiKey: ${{ inputs.TETRATE_API_KEY }}
        roles:
          - chat
          - edit
          - apply
        capabilities:
          - tool_use
    ```

    View the model block `tetrate/claude-sonnet-4` on the [Gobi Hub](https://hub.gourmand.dev/tetrate/claude-sonnet-4).

    **Reference it in your Agent configuration:**

    ```yaml title="my-agent" theme={null}
    name: My Agent
    version: 1.0.0
    schema: v1
    models:
      - uses: tetrate/claude-sonnet-4
        with:
          TETRATE_API_KEY: ${{ secrets.TETRATE_API_KEY }}
    context:
      - uses: gourmand/diff-context
      - uses: gourmand/terminal-context
      - uses: gourmand/file-context
    ```

    <Tip>
      To customize, see the [model block creation guide](/hub/configs/create-a-block).
    </Tip>
  </Tab>

  <Tab title="Using Local Model Blocks">
    **When to use**: Reuse configurations across agents and keep them local or in GitHub (not on Gobi Hub).

    **The Local Model Block:**

    <Info>
      Name the file `my-claude-4-model.yaml` so you can reference it in the Agent.
    </Info>

    ```yaml title="~/.gobi/models/my-claude-4-model.yaml" theme={null}
    name: Claude Sonnet 4
    version: 1.0.1
    schema: v1
    models:
      - name: Claude Sonnet 4
        provider: tars
        model: claude-4-sonnet-20250514
        apiKey: ${{ inputs.TETRATE_API_KEY }}
        roles:
          - chat
          - edit
          - apply
        capabilities:
          - tool_use
    ```

    Reference it as `my-claude-4-model` in your Agent configuration:

    ```yaml title="~/.gobi/agents/simple-agent.yaml" theme={null}
    name: Simple Agent
    version: 1.0.0
    schema: v1
    models:
      - uses: my-claude-4-model
        with:
          TETRATE_API_KEY: ${{ secrets.TETRATE_API_KEY }}
    context:
      - uses: gourmand/diff-context
      - uses: gourmand/terminal-context
      - uses: gourmand/file-context
    ```

    <Tip>
      Learn more about [model blocks](/reference#models) and [local blocks](/reference#local-blocks).
    </Tip>
  </Tab>
</Tabs>

***

## Troubleshooting Common Issues

<CardGroup cols={2}>
  <Card title="Invalid API key" icon="key" vertical>
    Verify your API key is active and has no extra spaces.
  </Card>

  <Card title="Model not found" icon="ban" href="https://router.tetrate.ai/models" vertical>
    Confirm the model ID matches the Tetrate catalog.
  </Card>

  <Card title="Slow responses" icon="code" vertical>
    Check your network or try a less-loaded model. Contact Tetrate support if issues persist.
  </Card>

  <Card title="Configuration not loading" icon="file-lines" vertical>
    Validate YAML syntax and review error messages in Gobi. If using Hub, ensure the block is published.
  </Card>
</CardGroup>

***

## Join the Community

Connect with Tetrate and other builders for help and discussion.

<CardGroup cols={1}>
  <Card title="Join the Tetrate Community" icon="slack" href="https://join.slack.com/t/tetrate-agent-router/shared_invite/zt-399tv7hjm-6YMXztGywTOQrMIolvEBNg">
    Get answers, insights, and best practices for secure, scalable infrastructure
  </Card>
</CardGroup>


# How to Configure Vertex AI with Gobi
Source: https://docs.gourmand.dev/customize/model-providers/top-level/vertexai



<Info>
  Enable the [Vertex AI API](https://console.cloud.google.com/marketplace/product/google/aiplatform.googleapis.com)
  and set up [Google Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc)
</Info>

## Configuration

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: vertexai
        model: <MODEL_ID>
        env:
          projectId: <PROJECT_ID>
          region: us-east5
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "vertexai",
          "model": "<MODEL_ID>",
          "projectId": "[PROJECT_ID]",
          "region": "us-east5"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

## How to Enable Vertex AI Express Mode

You can use Vertex AI in [express mode](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview) by only providing an API Key. Only some Gemini models are supported in express mode for now.

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: <MODEL_NAME>
        provider: vertexai
        model: <MODEL_ID>
        apiKey: <YOUR_GOOGLE_CLOUD_API_KEY>
    ```
  </Tab>

  <Tab title="JSON (Deprecated)">
    ```json title="config.json" theme={null}
    {
      "models": [
        {
          "title": "<MODEL_NAME>",
          "provider": "vertexai",
          "model": "<MODEL_ID>",
          "apiKey": "<YOUR_GOOGLE_CLOUD_API_KEY>",
        }
      ]
    }
    ```
  </Tab>
</Tabs>


# Intro to Roles
Source: https://docs.gourmand.dev/customize/model-roles/00-intro

Apply model role

Models in Gobi can be configured to be used for various roles in the extension.

* [`chat`](./chat.mdx): Used for chat conversations in the extension sidebar
* [`autocomplete`](./autocomplete): Used for autocomplete code suggestions in the editor
* [`edit`](./edit.mdx): Used to generate code based on edit prompts
* [`apply`](./apply.mdx): Used to decide how to apply edits to a file
* [`embed`](./embeddings.mdx): Used to generate embeddings used for vector search (@Codebase and @Docs context providers)
* [`rerank`](./reranking.mdx): Used to rerank results from vector search

These roles can be specified for a `config.yaml` model block using `roles`. See the [YAML Specification](/reference#models) for more details.

<Info>
  For recommendations on which models work best for each role, see our [comprehensive model recommendations](/customization/models#recommended-models).
</Info>

## Selecting model roles

You can control which of the models in your config for a given role will be currently used for that role. Above the main input, click the 3 dots and then the cube icon to expand the `Models` section. Then you can use the dropdowns to select an active model for each role.

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/settings-model-roles.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=0c38733fdd4e832a50735c8d83981465" alt="Settings Active Models Section" data-og-width="415" width="415" data-og-height="347" height="347" data-path="images/settings-model-roles.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/settings-model-roles.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=91e17e3b0a212d87da17afbb27816b76 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/settings-model-roles.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=744ee65de2f65d6727d939c29de21adb 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/settings-model-roles.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=2953004df6497344ef89061306d97dda 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/settings-model-roles.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=e121df433e3999e486c0db363b1d4ec0 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/settings-model-roles.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=88945f5d0bafe55161c94746da8c0602 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/settings-model-roles.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=3e45d48f3d53f17d4d7b2ab38de07621 2500w" />

<Info>
  `roles` are not explicitly defined within `config.json` (deprecated) - they
  are infered by the top level keys like `embeddingsProvider`
</Info>


# Apply Role
Source: https://docs.gourmand.dev/customize/model-roles/apply

Apply model role

When editing code, Chat and Edit model output often doesn't clearly align with existing code. A model with the `apply` role is used to generate a more precise diff to apply changes to a file.

## Recommended Apply models

<Info>
  For the latest Apply model recommendations, see our [comprehensive model recommendations](/customization/models#recommended-models).
</Info>

We recommend [Morph Fast Apply](https://morphllm.com) or [Relace's Instant Apply model](https://hub.gourmand.dev/relace/instant-apply) for the fastest Apply experience. You can sign up for Morph's free tier [here](https://morphllm.com/dashboard) or get a Relace API key [here](https://app.relace.ai/settings/api-keys).

However, most Chat models can also be used for applying code changes. We recommend smaller/cheaper models for the task, such as Claude 3.5 Haiku.

<Info>
  Explore all apply models in [the
  Hub](https://hub.gourmand.dev/explore/models?roles=apply)
</Info>

## Prompt templating

You can customize the prompt template used for applying code changes by setting the `promptTemplates.apply` property in your model configuration. Gobi uses [Handlebars syntax](https://handlebarsjs.com/guide/) for templating.

Available variables for the apply template:

* `{{{original_code}}}` - The original code before changes
* `{{{new_code}}}` - The new code after changes

Example:

```yaml  theme={null}
models:
  - name: My Custom Apply Template
    provider: anthropic
    model: claude-3-5-sonnet-latest
    promptTemplates:
      apply: |
        Original: {{{original_code}}}
        New: {{{new_code}}}

        Please generate the final code without any markers or explanations.
```


# Autocomplete Role in Gobi Models
Source: https://docs.gourmand.dev/customize/model-roles/autocomplete

Learn how the autocomplete role works in Gobi, which models to use, and how to customize prompt templates for inline code suggestions.

export const ModelRecommendations = ({role = "all"}) => {
  const parseMarkdownLinks = text => {
    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const parts = [];
    let lastIndex = 0;
    let match;
    let key = 0;
    while ((match = regex.exec(text)) !== null) {
      if (match.index > lastIndex) {
        const beforeText = text.slice(lastIndex, match.index);
        if (beforeText) {
          parts.push(<span key={key++}>{beforeText}</span>);
        }
      }
      const [, linkText, url] = match;
      parts.push(<a key={key++} href={url} target="_blank" rel="noopener noreferrer" style={{
        color: "#0066cc",
        textDecoration: "underline"
      }}>
          {linkText}
        </a>);
      lastIndex = regex.lastIndex;
    }
    if (lastIndex < text.length) {
      const remainingText = text.slice(lastIndex);
      if (remainingText) {
        parts.push(<span key={key++}>{remainingText}</span>);
      }
    }
    return parts.length > 0 ? parts : text;
  };
  const modelRecs = {
    agent_plan: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[Devstral (27B)](https://hub.gourmand.dev/ollama/devstral)", "[Kimi K2 (1T)](https://hub.gourmand.dev/openrouter/kimi-k2)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)", "[GLM 4.5 (355B)](https://hub.gourmand.dev/openrouter/glm-4-5)", "[GLM 4.5 Air (106B)](https://hub.gourmand.dev/openrouter/glm-4-5-air)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed models are slightly better than open models"
    },
    chat_edit: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed and open models have pretty similar performance"
    },
    autocomplete: {
      open: ["[QwenCoder2.5 (1.5B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)", "[QwenCoder2.5 (7B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)"],
      closed: ["[Codestral](https://hub.gourmand.dev/mistral/codestral)", "[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are slightly better than open models"
    },
    apply: {
      open: ["N/A"],
      closed: ["[Relace Instant Apply](https://hub.gourmand.dev/relace/instant-apply)", "[Morph Fast Apply](https://hub.gourmand.dev/morphllm/morph-v2)"],
      notes: "Open models are not good enough for this model role"
    },
    embed: {
      open: ["[Nomic Embed Text](https://hub.gourmand.dev/ollama/nomic-embed-text-latest)", "Qwen3 Embedding"],
      closed: ["[Voyage Code 3](https://hub.gourmand.dev/voyageai/voyage-code-3)", "[Morph Embeddings](https://hub.gourmand.dev/morphllm/morph-embedding-v2)", "Codestral Embed"],
      notes: "Closed models are slightly better than open models"
    },
    rerank: {
      open: ["zerank-1", "zerank-1-small", "Qwen3 Reranker"],
      closed: ["[Voyage Rerank 2.5](https://hub.gourmand.dev/voyageai/rerank-2-5)", "Relace Code Rerank", "[Morph Rerank](https://hub.gourmand.dev/morphllm/morph-rerank-v2)"],
      notes: "Open models are beginning to emerge for this model role"
    },
    next_edit: {
      open: ["[Instinct](https://hub.gourmand.dev/gobi/instinct)"],
      closed: ["[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are better than open models"
    }
  };
  let rolesToShow = [];
  if (!role || role === "all") {
    rolesToShow = Object.keys(modelRecs);
  } else {
    const key = role.toLowerCase().replace(/\s|\//g, "_").replace(/-/g, "_");
    if (modelRecs[key]) {
      rolesToShow = [key];
    }
  }
  if (rolesToShow.length === 0) {
    return <div>No recommendations found for role: {role}</div>;
  }
  return <table style={{
    width: "100%",
    borderCollapse: "collapse",
    marginTop: "1rem"
  }}>
      <thead>
        <tr>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Model role
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best open models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best closed models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Notes
          </th>
        </tr>
      </thead>
      <tbody>
        {rolesToShow.map(roleKey => {
    const rec = modelRecs[roleKey];
    if (!rec) return null;
    return <tr key={roleKey}>
              <td style={{
      fontWeight: 600,
      verticalAlign: "top",
      padding: "8px"
    }}>
                {roleKey.replace(/_/g, " ").replace(/\b\w/g, l => l.toUpperCase())}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.open.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.closed.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.notes}
              </td>
            </tr>;
  })}
      </tbody>
    </table>;
};

An "autocomplete model" is an LLM that is trained on a special format called fill-in-the-middle (FIM). This format is designed to be given the prefix and suffix of a code file and predict what goes between. This task is very specific, which on one hand means that the models can be smaller (even a 3B parameter model can perform well). On the other hand, this means that Chat models, though larger, will often perform poorly even with extensive prompting.

In Gobi, autocomplete models are used to display inline [Autocomplete](../../ide-extensions/autocomplete/quick-start) suggestions as you type. Autocomplete models are designated by adding the `autocomplete` to the model's `roles` in `config.yaml`.

## Recommended Autocomplete models

<ModelRecommendations role="autocomplete" />

Visit the [Autocomplete Deep Dive](../deep-dives/autocomplete) for detailed setup instructions and configuration options.

## Prompt templating

You can customize the prompt template used when autocomplete happens by setting the `promptTemplates.autocomplete` property in your model configuration. Gobi uses [Handlebars syntax](https://handlebarsjs.com/guide/) for templating.

Available variables for the apply template:

* `{{{prefix}}}` - the code before your cursor
* `{{{suffix}}}` - the code after your cursor
* `{{{filename}}}` - the name of the file your cursor currently is
* `{{{reponame}}}` - the name of the folder where the codebase is
* `{{{language}}}` - the name of the programming language in full (ex. Typescript)

Example:

```yaml  theme={null}
models:
  - name: My Custom Autocomplete Template
    provider: ollama
    model: qwen2.5-coder:1.5b
    promptTemplates:
      autocomplete: |
        `
        globalThis.importantFunc = importantFunc
        <|fim_prefix|>{{{prefix}}}<|fim_suffix|>{{{suffix}}}<|fim_middle|>
        `
```


# Chat Role
Source: https://docs.gourmand.dev/customize/model-roles/chat

Chat model role

export const ModelRecommendations = ({role = "all"}) => {
  const parseMarkdownLinks = text => {
    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const parts = [];
    let lastIndex = 0;
    let match;
    let key = 0;
    while ((match = regex.exec(text)) !== null) {
      if (match.index > lastIndex) {
        const beforeText = text.slice(lastIndex, match.index);
        if (beforeText) {
          parts.push(<span key={key++}>{beforeText}</span>);
        }
      }
      const [, linkText, url] = match;
      parts.push(<a key={key++} href={url} target="_blank" rel="noopener noreferrer" style={{
        color: "#0066cc",
        textDecoration: "underline"
      }}>
          {linkText}
        </a>);
      lastIndex = regex.lastIndex;
    }
    if (lastIndex < text.length) {
      const remainingText = text.slice(lastIndex);
      if (remainingText) {
        parts.push(<span key={key++}>{remainingText}</span>);
      }
    }
    return parts.length > 0 ? parts : text;
  };
  const modelRecs = {
    agent_plan: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[Devstral (27B)](https://hub.gourmand.dev/ollama/devstral)", "[Kimi K2 (1T)](https://hub.gourmand.dev/openrouter/kimi-k2)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)", "[GLM 4.5 (355B)](https://hub.gourmand.dev/openrouter/glm-4-5)", "[GLM 4.5 Air (106B)](https://hub.gourmand.dev/openrouter/glm-4-5-air)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed models are slightly better than open models"
    },
    chat_edit: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed and open models have pretty similar performance"
    },
    autocomplete: {
      open: ["[QwenCoder2.5 (1.5B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)", "[QwenCoder2.5 (7B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)"],
      closed: ["[Codestral](https://hub.gourmand.dev/mistral/codestral)", "[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are slightly better than open models"
    },
    apply: {
      open: ["N/A"],
      closed: ["[Relace Instant Apply](https://hub.gourmand.dev/relace/instant-apply)", "[Morph Fast Apply](https://hub.gourmand.dev/morphllm/morph-v2)"],
      notes: "Open models are not good enough for this model role"
    },
    embed: {
      open: ["[Nomic Embed Text](https://hub.gourmand.dev/ollama/nomic-embed-text-latest)", "Qwen3 Embedding"],
      closed: ["[Voyage Code 3](https://hub.gourmand.dev/voyageai/voyage-code-3)", "[Morph Embeddings](https://hub.gourmand.dev/morphllm/morph-embedding-v2)", "Codestral Embed"],
      notes: "Closed models are slightly better than open models"
    },
    rerank: {
      open: ["zerank-1", "zerank-1-small", "Qwen3 Reranker"],
      closed: ["[Voyage Rerank 2.5](https://hub.gourmand.dev/voyageai/rerank-2-5)", "Relace Code Rerank", "[Morph Rerank](https://hub.gourmand.dev/morphllm/morph-rerank-v2)"],
      notes: "Open models are beginning to emerge for this model role"
    },
    next_edit: {
      open: ["[Instinct](https://hub.gourmand.dev/gobi/instinct)"],
      closed: ["[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are better than open models"
    }
  };
  let rolesToShow = [];
  if (!role || role === "all") {
    rolesToShow = Object.keys(modelRecs);
  } else {
    const key = role.toLowerCase().replace(/\s|\//g, "_").replace(/-/g, "_");
    if (modelRecs[key]) {
      rolesToShow = [key];
    }
  }
  if (rolesToShow.length === 0) {
    return <div>No recommendations found for role: {role}</div>;
  }
  return <table style={{
    width: "100%",
    borderCollapse: "collapse",
    marginTop: "1rem"
  }}>
      <thead>
        <tr>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Model role
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best open models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best closed models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Notes
          </th>
        </tr>
      </thead>
      <tbody>
        {rolesToShow.map(roleKey => {
    const rec = modelRecs[roleKey];
    if (!rec) return null;
    return <tr key={roleKey}>
              <td style={{
      fontWeight: 600,
      verticalAlign: "top",
      padding: "8px"
    }}>
                {roleKey.replace(/_/g, " ").replace(/\b\w/g, l => l.toUpperCase())}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.open.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.closed.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.notes}
              </td>
            </tr>;
  })}
      </tbody>
    </table>;
};

A "chat model" is an LLM that is trained to respond in a conversational format. Because they should be able to answer general questions and generate complex code, the best chat models are typically large, often 405B+ parameters.

In Gobi, these models are used for normal [Chat](../../ide-extensions/chat/quick-start). The selected chat model will also be used for [Edit](../../ide-extensions/edit/quick-start) and [Apply](./apply.mdx) if no `edit` or `apply` models are specified, respectively.

## Recommended Chat models

<ModelRecommendations role="chat_edit" />

## Best overall experience

For the best overall Chat experience, you will want to use a 400B+ parameter model or one of the frontier models.

### Claude Opus 4.1 and Claude Sonnet 4 from Anthropic

Our current top recommendations are Claude Opus 4.1 and Claude Sonnet 4 from [Anthropic](../model-providers/top-level/anthropic).

<Tabs>
  <Tab title="Hub">
    View the [Claude Opus 4.1 model block](https://hub.gourmand.dev/anthropic/claude-4-1-opus) or [Claude Sonnet 4 model block](https://hub.gourmand.dev/anthropic/claude-4-sonnet) on the hub.
  </Tab>

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Claude Opus 4.1
        provider: anthropic
        model: claude-4-1-opus
        apiKey: <YOUR_ANTHROPIC_API_KEY>
    ```
  </Tab>
</Tabs>

### Gemma from Google DeepMind

If you prefer to use an open-weight model, then the Gemma family of Models from Google DeepMind is a good choice. You will need to decide if you use it through a SaaS model provider, e.g. [Together](../model-providers/more/together), or self-host it, e.g. [Ollama](../model-providers/top-level/ollama).

<Tabs>
  <Tab title="Hub">
    <Tabs>
      <Tab title="Ollama">
        Add the [Ollama Gemma 3 27B block](https://hub.gourmand.dev/ollama/gemma3-27b) from the hub
      </Tab>

      <Tab title="Together">
        Add the [Together Gemma 2 27B Instruct block](https://hub.gourmand.dev/togetherai/gemma-2-instruct-27b) from the hub
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="YAML">
    <Tabs>
      <Tab title="Ollama">
        ```yaml title="config.yaml" theme={null}
        models:
          - name: "Gemma 3 27B"
            provider: "ollama"
            model: "gemma3:27b"
        ```
      </Tab>

      <Tab title="Together">
        ```yaml title="config.yaml" theme={null}
        models:
          - name: "Gemma 3 27B"
            provider: "together"
            model: "google/gemma-2-27b-it"
            apiKey: <YOUR_TOGETHER_API_KEY>
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

### GPT-4o from OpenAI

If you prefer to use a model from [OpenAI](../model-providers/top-level/openai), then we recommend GPT-4o.

<Tabs>
  <Tab title="Hub">
    Add the [OpenAI GPT-4o block](https://hub.gourmand.dev/openai/gpt-4o) from the hub
  </Tab>

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: GPT-4o
        provider: openai
        model: ''
        apiKey: <YOUR_OPENAI_API_KEY>
    ```
  </Tab>
</Tabs>

### Grok-2 from xAI

If you prefer to use a model from [xAI](../model-providers/more/xAI), then we recommend Grok-2.

<Tabs>
  <Tab title="Hub">
    Add the [xAI Grok-2 block](https://hub.gourmand.dev/xai/grok-2) from the hub
  </Tab>

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Grok-2
        provider: xAI
        model: grok-2-latest
        apiKey: <YOUR_XAI_API_KEY>
    ```
  </Tab>
</Tabs>

### Gemini 2.0 Flash from Google

If you prefer to use a model from [Google](../model-providers/top-level/gemini), then we recommend Gemini 2.0 Flash.

<Tabs>
  <Tab title="Hub">
    Add the [Gemini 2.0 Flash block](https://hub.gourmand.dev/google/gemini-2.0-flash) from the hub
  </Tab>

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Gemini 2.0 Flash
        provider: gemini
        model: gemini-2.0-flash
        apiKey: <YOUR_GEMINI_API_KEY>
    ```
  </Tab>
</Tabs>

## Local, offline experience

For the best local, offline Chat experience, you will want to use a model that is large but fast enough on your machine.

### Llama 3.1 8B

If your local machine can run an 8B parameter model, then we recommend running Llama 3.1 8B on your machine (e.g. using [Ollama](../model-providers/top-level/ollama) or [LM Studio](../model-providers/top-level/lmstudio)).

<Tabs>
  <Tab title="Hub">
    <Tabs>
      <Tab title="Ollama">
        Add the [Ollama Llama 3.1 8b block](https://hub.gourmand.dev/ollama/llama3.1-8b) from the hub
      </Tab>

      {/* <Tab title="LM Studio">
          Add the [LM Studio Llama 3.1 8b block](https://hub.gourmand.dev/explore/models) from the hub
          </Tab> */}
    </Tabs>
  </Tab>

  <Tab title="YAML">
    <Tabs>
      <Tab title="Ollama">
        ```yaml title="config.yaml" theme={null}
        models:
          - name: Llama 3.1 8B
            provider: ollama
            model: llama3.1:8b
        ```
      </Tab>

      <Tab title="LM Studio">
        ```yaml title="config.yaml" theme={null}
        models:
          - name: Llama 3.1 8B
            provider: lmstudio
            model: llama3.1:8b
        ```
      </Tab>

      <Tab title="Msty">
        ```yaml title="config.yaml" theme={null}
        models:
          - name: Llama 3.1 8B
            provider: msty
            model: llama3.1:8b
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

### DeepSeek Coder 2 16B

If your local machine can run a 16B parameter model, then we recommend running DeepSeek Coder 2 16B (e.g. using [Ollama](../model-providers/top-level/ollama) or [LM Studio](../model-providers/top-level/lmstudio)).

<Tabs>
  {/* <Tab title="Hub">
      <Tabs>
      <Tab title="Ollama">
      Add the [Ollama Deepseek Coder 2 16B block](https://hub.gourmand.dev/explore/models) from the hub
      </Tab>
      <Tab title="LM Studio">
      Add the [LM Studio Deepseek Coder 2 16B block](https://hub.gourmand.dev/explore/models) from the hub
      </Tab>
      </Tabs>
    </Tab> */}

  <Tab title="YAML">
    <Tabs>
      <Tab title="Ollama">
        ```yaml title="config.yaml" theme={null}
        models:
          - name: DeepSeek Coder 2 16B
            provider: ollama
            model: deepseek-coder-v2:16b
        ```
      </Tab>

      <Tab title="LM Studio">
        ```yaml title="config.yaml" theme={null}
        models:
          - name: DeepSeek Coder 2 16B
            provider: lmstudio
            model: deepseek-coder-v2:16b
        ```
      </Tab>

      <Tab title="Msty">
        ```yaml title="config.yaml" theme={null}
        models:
          - name: DeepSeek Coder 2 16B
            provider: msty
            model: deepseek-coder-v2:16b
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Other experiences

There are many more models and providers you can use with Chat beyond those mentioned above. Read more [here](../model-roles/chat.mdx)


# Edit Role
Source: https://docs.gourmand.dev/customize/model-roles/edit

Edit model role

export const ModelRecommendations = ({role = "all"}) => {
  const parseMarkdownLinks = text => {
    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const parts = [];
    let lastIndex = 0;
    let match;
    let key = 0;
    while ((match = regex.exec(text)) !== null) {
      if (match.index > lastIndex) {
        const beforeText = text.slice(lastIndex, match.index);
        if (beforeText) {
          parts.push(<span key={key++}>{beforeText}</span>);
        }
      }
      const [, linkText, url] = match;
      parts.push(<a key={key++} href={url} target="_blank" rel="noopener noreferrer" style={{
        color: "#0066cc",
        textDecoration: "underline"
      }}>
          {linkText}
        </a>);
      lastIndex = regex.lastIndex;
    }
    if (lastIndex < text.length) {
      const remainingText = text.slice(lastIndex);
      if (remainingText) {
        parts.push(<span key={key++}>{remainingText}</span>);
      }
    }
    return parts.length > 0 ? parts : text;
  };
  const modelRecs = {
    agent_plan: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[Devstral (27B)](https://hub.gourmand.dev/ollama/devstral)", "[Kimi K2 (1T)](https://hub.gourmand.dev/openrouter/kimi-k2)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)", "[GLM 4.5 (355B)](https://hub.gourmand.dev/openrouter/glm-4-5)", "[GLM 4.5 Air (106B)](https://hub.gourmand.dev/openrouter/glm-4-5-air)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed models are slightly better than open models"
    },
    chat_edit: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed and open models have pretty similar performance"
    },
    autocomplete: {
      open: ["[QwenCoder2.5 (1.5B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)", "[QwenCoder2.5 (7B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)"],
      closed: ["[Codestral](https://hub.gourmand.dev/mistral/codestral)", "[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are slightly better than open models"
    },
    apply: {
      open: ["N/A"],
      closed: ["[Relace Instant Apply](https://hub.gourmand.dev/relace/instant-apply)", "[Morph Fast Apply](https://hub.gourmand.dev/morphllm/morph-v2)"],
      notes: "Open models are not good enough for this model role"
    },
    embed: {
      open: ["[Nomic Embed Text](https://hub.gourmand.dev/ollama/nomic-embed-text-latest)", "Qwen3 Embedding"],
      closed: ["[Voyage Code 3](https://hub.gourmand.dev/voyageai/voyage-code-3)", "[Morph Embeddings](https://hub.gourmand.dev/morphllm/morph-embedding-v2)", "Codestral Embed"],
      notes: "Closed models are slightly better than open models"
    },
    rerank: {
      open: ["zerank-1", "zerank-1-small", "Qwen3 Reranker"],
      closed: ["[Voyage Rerank 2.5](https://hub.gourmand.dev/voyageai/rerank-2-5)", "Relace Code Rerank", "[Morph Rerank](https://hub.gourmand.dev/morphllm/morph-rerank-v2)"],
      notes: "Open models are beginning to emerge for this model role"
    },
    next_edit: {
      open: ["[Instinct](https://hub.gourmand.dev/gobi/instinct)"],
      closed: ["[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are better than open models"
    }
  };
  let rolesToShow = [];
  if (!role || role === "all") {
    rolesToShow = Object.keys(modelRecs);
  } else {
    const key = role.toLowerCase().replace(/\s|\//g, "_").replace(/-/g, "_");
    if (modelRecs[key]) {
      rolesToShow = [key];
    }
  }
  if (rolesToShow.length === 0) {
    return <div>No recommendations found for role: {role}</div>;
  }
  return <table style={{
    width: "100%",
    borderCollapse: "collapse",
    marginTop: "1rem"
  }}>
      <thead>
        <tr>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Model role
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best open models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best closed models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Notes
          </th>
        </tr>
      </thead>
      <tbody>
        {rolesToShow.map(roleKey => {
    const rec = modelRecs[roleKey];
    if (!rec) return null;
    return <tr key={roleKey}>
              <td style={{
      fontWeight: 600,
      verticalAlign: "top",
      padding: "8px"
    }}>
                {roleKey.replace(/_/g, " ").replace(/\b\w/g, l => l.toUpperCase())}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.open.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.closed.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.notes}
              </td>
            </tr>;
  })}
      </tbody>
    </table>;
};

It's often useful to select a different model to respond to Edit instructions than for Chat instructions, as Edits are often more code-specific and may require less conversational readability.

In Gobi, you can add `edit` to a model's roles to specify that it can be used for Edit requests. If no edit models are specified, the selected `chat` model is used.

```yaml title="config.yaml" theme={null}
models:
  - name: Claude 4 Sonnet
    provider: anthropic
    model: claude-3-5-sonnet-latest
    apiKey: <YOUR_ANTHROPIC_API_KEY>
    roles:
      - edit
```

Explore edit models in [the hub](https://hub.gourmand.dev/explore/models?roles=edit). Generally, our recommendations for Edit overlap with recommendations for Chat.

## Model Recommendations

<ModelRecommendations role="chat_edit" />

## Prompt templating

You can customize the prompt template used for editing code by setting the `promptTemplates.edit` property in your model configuration. Gobi uses [Handlebars syntax](https://handlebarsjs.com/guide/) for templating.

Available variables for the edit template:

* `{{{userInput}}}` - The user's edit request/instruction
* `{{{language}}}` - The programming language of the code
* `{{{codeToEdit}}}` - The code that's being edited
* `{{{prefix}}}` - Content before the edit area
* `{{{suffix}}}` - Content after the edit area
* `{{{supportsCompletions}}}` - Whether the model supports completions API
* `{{{supportsPrefill}}}` - Whether the model supports prefill capability

Example:

```yaml  theme={null}
models:
  - name: My Custom Edit Template
    provider: openai
    model: gpt-4o
    promptTemplates:
      edit: |
        `Here is the code before editing:
        \`\`\`{{{language}}}
        {{{codeToEdit}}}
        \`\`\`

        Here is the edit requested:
        "{{{userInput}}}"

        Here is the code after editing:`
```


# Embed Role
Source: https://docs.gourmand.dev/customize/model-roles/embeddings

Embed model role

An "embeddings model" is trained to convert a piece of text into a vector, which can later be rapidly compared to other vectors to determine similarity between the pieces of text. Embeddings models are typically much smaller than LLMs, and will be extremely fast and cheap in comparison.

In Gobi, embeddings are generated during indexing and then used by [codebase awareness](/guides/codebase-documentation-awareness) to perform similarity search over your codebase.

You can add `embed` to a model's `roles` to specify that it can be used to embed.

<Info>
  \[Built-in model (VS Code only)] `transformers.js` is used as a built-in
  embeddings model in VS Code. In JetBrains, there currently is no built-in
  embedder.
</Info>

## Recommended embedding models

<Info>
  See our [comprehensive model recommendations](/customization/models#recommended-models) for the best embedding models comparison.
</Info>

If you have the ability to use any model, we recommend `voyage-code-3`, which is listed below along with the rest of the options for embeddings models.

If you want to generate embeddings locally, we recommend using `nomic-embed-text` with [Ollama](../model-providers/top-level/ollama#embeddings-model).

### Voyage AI

After obtaining an API key from [here](https://www.voyageai.com/), you can configure like this:

<Tabs>
  <Tab title="Hub">
    [Voyage Code 3 Embedder Block](https://hub.gourmand.dev/voyageai/voyage-code-3)
  </Tab>

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Voyage Code 3
        provider: voyage
        model: voyage-code-3
        apiKey: <YOUR_VOYAGE_API_KEY>
        roles: 
          - embed
    ```
  </Tab>

  <Tab title="JSON">
    ```json title="config.json" theme={null}
    {
      "embeddingsProvider": {
        "provider": "voyage",
        "model": "voyage-code-3",
        "apiKey": "<YOUR_VOYAGE_API_KEY>"
      }
    }
    ```
  </Tab>
</Tabs>

### Ollama

See [here](../model-providers/top-level/ollama#embeddings-model) for instructions on how to use Ollama for embeddings.

### Transformers.js (currently VS Code only)

[Transformers.js](https://huggingface.co/docs/transformers.js/index) is a JavaScript port of the popular [Transformers](https://huggingface.co/transformers/) library. It allows embeddings to be calculated entirely locally. The model used is `all-MiniLM-L6-v2`, which is shipped alongside the Gobi extension.

<Tabs>
  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: default-transformers
        provider: transformers.js
        roles:
          - embed
    ```
  </Tab>

  <Tab title="JSON">
    ```json title="config.json" theme={null}
    {
      "embeddingsProvider": {
        "provider": "transformers.js"
      }
    }
    ```
  </Tab>
</Tabs>

### Text Embeddings Inference

[Hugging Face Text Embeddings Inference](https://huggingface.co/docs/text-embeddings-inference/en/index) enables you to host your own embeddings endpoint. You can configure embeddings to use your endpoint as follows:

<Tabs>
  {/* <Tab title="Hub">
    [HuggingFace Text Embedder Block](https://hub.gourmand.dev/)
    </Tab> */}

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Huggingface TEI Embedder
        provider: huggingface-tei
        apiBase: http://localhost:8080
        apiKey: <YOUR_TEI_API_KEY>
        roles: [embed]
    ```
  </Tab>

  <Tab title="JSON">
    ```json title="config.json" theme={null}
    {
      "embeddingsProvider": {
        "provider": "huggingface-tei",
        "apiBase": "http://localhost:8080",
        "apiKey": "<YOUR_TEI_API_KEY>"
      }
    }
    ```
  </Tab>
</Tabs>

### OpenAI

See [here](../model-providers/top-level/openai#how-to-configure-openai-embeddings-models) for instructions on how to use OpenAI for embeddings.

### Cohere

See [here](../model-providers/more/cohere#embeddings-model) for instructions on how to use Cohere for embeddings.

### Gemini

See [here](../model-providers/top-level/gemini#how-to-configure-gemini-embeddings-models) for instructions on how to use Gemini for embeddings.

### Vertex

See [here](../model-providers/top-level/vertexai#how-to-configure-vertex-ai-embeddings-models) for instructions on how to use Vertex for embeddings.

### Mistral

See [here](../model-providers/more/mistral#how-to-configure-mistral-embeddings-models) for instructions on how to use Mistral for embeddings.

### NVIDIA

See [here](../model-providers/more/nvidia#embeddings-model) for instructions on how to use NVIDIA for embeddings.

### Bedrock

See [here](../model-providers/top-level/bedrock#how-to-configure-amazon-bedrock-embeddings-models) for instructions on how to use Bedrock for embeddings.

### WatsonX

See [here](../model-providers/more/watsonx#embeddings-model) for instructions on how to use WatsonX for embeddings.

### LMStudio

See [here](../model-providers/top-level/lmstudio#embeddings-model) for instructions on how to use LMStudio for embeddings.


# Rerank Role
Source: https://docs.gourmand.dev/customize/model-roles/reranking

Rerank model role

A "reranking model" is trained to take two pieces of text (often a user question and a document) and return a relevancy score between 0 and 1, estimating how useful the document will be in answering the question. Rerankers are typically much smaller than LLMs, and will be extremely fast and cheap in comparison.

In Gobi, rerankers are designated using the `rerank` role and used by [codebase awareness](/guides/codebase-documentation-awareness) in order to select the most relevant code snippets after vector search.

## Recommended reranking models

<Info>
  For a comparison of all reranking models including open and closed options, see our [comprehensive model recommendations](/customization/models#recommended-models).
</Info>

If you have the ability to use any model, we recommend `rerank-2` by Voyage AI, which is listed below along with the rest of the options for rerankers.

### Voyage AI

Voyage AI offers the best reranking model for code with their `rerank-2` model. After obtaining an API key from [here](https://www.voyageai.com/), you can configure a reranker as follows:

<Tabs>
  <Tab title="Hub">
    ```yaml title="config.yaml" theme={null}
    models:
      - uses: voyageai/rerank-2
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: My Voyage Reranker
        provider: voyage
        apiKey: <YOUR_VOYAGE_API_KEY>
        model: rerank-2
        roles:
          - rerank
    ```
  </Tab>
</Tabs>

### Cohere

See Cohere's documentation for rerankers [here](https://docs.cohere.com/docs/rerank-2).

<Tabs>
  {/* <Tab title="Hub">
    [Cohere Reranker English v3](https://hub.gourmand.dev/)
    </Tab> */}

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Cohere Reranker
        provider: cohere
        model: rerank-english-v3.0
        apiKey: <YOUR_COHERE_API_KEY>
        roles:
          - rerank
    ```
  </Tab>
</Tabs>

### LLM

If you only have access to a single LLM, then you can use it as a reranker. This is discouraged unless truly necessary, because it will be much more expensive and still less accurate than any of the above models trained specifically for the task. Note that this will not work if you are using a local model, for example with Ollama, because too many parallel requests need to be made.

<Tabs>
  {/* <Tab title="Hub">
    [GPT-4o LLM Reranker Block](https://hub.gourmand.dev/)
    </Tab> */}

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: LLM Reranker
        provider: openai
        model: gpt-4o
        roles:
          - rerank
    ```
  </Tab>
</Tabs>

### Text Embeddings Inference

[Hugging Face Text Embeddings Inference](https://huggingface.co/docs/text-embeddings-inference/en/index) enables you to host your own [reranker endpoint](https://huggingface.github.io/text-embeddings-inference/#/Text%20Embeddings%20Inference/rerank). You can configure your reranker as follows:

<Tabs>
  {/* <Tab title="Hub">
    [HuggingFace TEI Reranker block](https://hub.gourmand.dev/)
    </Tab> */}

  <Tab title="YAML">
    ```yaml title="config.yaml" theme={null}
    models:
      - name: Huggingface-tei Reranker
        provider: huggingface-tei
        model: tei
        apiBase: http://localhost:8080
        apiKey: <YOUR_TEI_API_KEY>
        roles:
          - rerank
    ```
  </Tab>
</Tabs>


# Overview
Source: https://docs.gourmand.dev/customize/overview

Explore Gobi's advanced capabilities for power users and complex development scenarios.

## Context Integration

Specialized context features for codebase understanding and documentation integration.

[Browse Context Features →](/guides/understanding-configs)

## Deep Dives

Detailed technical explanations of Gobi's internal workings and advanced configuration options.

[Read Deep Dives →](/customize/deep-dives/configuration)

## Model Providers

Configure and optimize different AI model providers for your specific needs and infrastructure.

[Configure Providers →](/customize/model-providers/overview)

## Model Roles

Understand how different models can be assigned specific roles in your development workflow.

[Learn Model Roles →](/customize/model-roles)

## Deep Dives

Detailed technical explanations of Gobi's internal workings and advanced configuration options.

[Read Deep Dives →](/customization/overview#configuration)

## Reference

Complete configuration reference and API documentation.

[View Reference →](/reference)

## Troubleshooting

Solutions to common issues and debugging techniques.

[Get Help →](/troubleshooting)

***

These advanced topics help you get the most out of Gobi in complex development environments.


# Telemetry
Source: https://docs.gourmand.dev/customize/telemetry

Learn about Gobi's anonymous telemetry collection practices, what usage data is collected, and how to opt out if you prefer not to share your usage information

## Overview

The open-source Gobi Extensions collect and report **anonymous** usage information to help us improve our product. This data enables us to understand user interactions and optimize the user experience effectively. You can opt out of telemetry collection at any time if you prefer not to share your usage information.

We utilize [Posthog](https://posthog.com/), an open-source platform for product analytics, to gather and store this data. For transparency, you can review the implementation code [here](https://github.com/gourmand/gobi/blob/main/gui/src/hooks/CustomPostHogProvider.tsx) or read our [official privacy policy](https://gourmand.dev/privacy).

## Tracking Policy

All data collected by the open-source Gobi extensions is anonymized and stripped of personally identifiable information (PII) before being sent to PostHog. We are committed to maintaining the privacy and security of your data.

## What We Track

The following usage information is collected and reported:

* **Suggestion Interactions:** Whether you accept or reject suggestions (excluding the actual code or prompts involved).
* **Model and Command Information:** The name of the model and command used.
* **Token Metrics:** The number of tokens generated.
* **System Information:** The name of your operating system (OS) and integrated development environment (IDE).
* **Pageviews:** General pageview statistics.

## How to Opt Out

You can disable anonymous telemetry by toggling "Allow Anonymous Telemetry" off in the user settings.

Alternatively in VS Code, you can disable telemetry through your VS Code settings by unchecking the "Gobi: Telemetry Enabled" box (this will override the Settings Page settings). VS Code settings can be accessed with `File` > `Preferences` > `Settings` (or use the keyboard shortcut `ctrl` + `,` on Windows/Linux or `cmd` + `,` on macOS).


# FAQs
Source: https://docs.gourmand.dev/faqs

Frequently asked questions about Gobi

## Networking Issues

### Configure Certificates

If you're seeing a `fetch failed` error and your network requires custom certificates, you will need to configure them in your config file. In each of the objects in the `"models"` array, add `requestOptions.caBundlePath` like this:

<Tabs>
  <Tab title="YAML">
    ```yaml  theme={null}
    models:
      - name: My Model
        ...
        requestOptions:
          caBundlePath: /path/to/cert.pem
    ```
  </Tab>

  <Tab title="JSON">
    ```json  theme={null}
    {
      "models": [
        {
          "name": "My Model",
          "...": "...",
          "requestOptions": {
            "caBundlePath": "/path/to/cert.pem"
          }
        }
      ]
    }
    ```
  </Tab>
</Tabs>

You may also set `requestOptions.caBundlePath` to an array of paths to multiple certificates.

***Windows VS Code Users***: Installing the [win-ca](https://marketplace.visualstudio.com/items?itemName=ukoloff.win-ca) extension should also correct this issue.

### VS Code Proxy Settings

If you are using VS Code and require requests to be made through a proxy, you are likely already set up through VS Code's [Proxy Server Support](https://code.visualstudio.com/docs/setup/network#_proxy-server-support). To double-check that this is enabled, use `cmd/ctrl` + `,` to open settings and search for "Proxy Support". Unless it is set to "off", then VS Code is responsible for making the request to the proxy.

### code-server

Gobi can be used in [code-server](https://coder.com/), but if you are running across an error in the logs that includes "This is likely because the editor is not running in a secure context", please see [their documentation on securely exposing code-server](https://coder.com/docs/code-server/latest/guide#expose-code-server).

## Changes to configs not showing in VS Code

If you've made changes to a config (adding, modifying, or removing it) but the changes aren't appearing in the Gobi extension in VS Code, try reloading the VS Code window:

1. Open the command palette (`cmd/ctrl` + `shift` + `P`)
2. Type "Reload Window"
3. Select the reload option

This will restart VS Code and reload all extensions, which should make your config changes visible.

## I installed Gobi, but don't see the sidebar window

By default the Gobi window is on the left side of VS Code, but it can be dragged to right side as well, which we recommend in our tutorial. In the situation where you have previously installed Gobi and moved it to the right side, it may still be there. You can reveal Gobi either by using cmd/ctrl+L or by clicking the button in the top right of VS Code to open the right sidebar.

## I'm getting a 404 error from OpenAI

If you have entered a valid API key and model, but are still getting a 404 error from OpenAI, this may be because you need to add credits to your billing account. You can do so from the [billing console](https://platform.openai.com/settings/organization/billing/overview). If you just want to check that this is in fact the cause of the error, you can try adding \$1 to your account and checking whether the error persists.

## I'm getting a 404 error from OpenRouter

If you have entered a valid API key and model, but are still getting a 404 error from OpenRouter, this may be because models that do not support function calling will return an error to Gobi when a request is sent. Example error: `HTTP 404 Not Found from https://openrouter.ai/api/v1/chat/completions`

## Indexing issues

If you are having persistent errors with indexing, our recommendation is to rebuild your index from scratch. Note that for large codebases this may take some time.

This can be accomplished using the following command: `Gobi: Rebuild codebase index`.

## Agent mode is unavailable or tools aren't working

If Agent mode is grayed out or tools aren't functioning properly, this is likely due to model capability configuration issues.

<Info>
  Gobi uses system message tools as a fallback for models without native tool support, so most models should work with Agent mode automatically.
</Info>

### Check if your model has tool support

1. Not all models support native tool/function calling, but Gobi will automatically use system message tools as a fallback
2. Try adding `capabilities: ["tool_use"]` to your model config to force tool support
3. Verify your provider supports function calling or that system message tools are working correctly

### Tools Not Working

If tools aren't being called:

1. Ensure `tool_use` is in your capabilities
2. Check that your API endpoint actually supports function calling
3. Some providers may use different function calling formats

### Images Not Uploading

If you can't upload images:

1. Add `image_input` to capabilities
2. Ensure your model actually supports vision (e.g., gpt-4-vision, claude-3)
3. Check that your provider passes through image data

### Add capabilities

If Gobi's autodetection isn't working correctly, you can manually add capabilities in your `config.yaml`:

```yaml  theme={null}
models:
  - name: my-model
    provider: openai
    model: gpt-4
    capabilities:
      - tool_use
      - image_input
```

### Verify with provider

Some proxy services (like OpenRouter) or custom deployments may not preserve tool calling capabilities. Check your provider's documentation.

### Verifying Current Capabilities

To see what capabilities Gobi detected for your model:

1. Check the mode selector tooltips - they indicate if tools are available
2. Try uploading an image - if disabled, the model lacks `image_input`
3. Check if Agent mode is available - requires `tool_use`

See the [Model Capabilities guide](/customize/deep-dives/model-capabilities) for complete configuration details.

## Android Studio - "Nothing to show" in Chat

This can be fixed by selecting `Actions > Choose Boot runtime for the IDE` then selecting the latest version, and then restarting Android Studio. [See this thread](https://github.com/gourmand/gobi/issues/596#issuecomment-1789327178) for details.

## I received a "Codebase indexing disabled - Your Linux system lacks required CPU features (AVX2, FMA)" notification

We use LanceDB as our vector database for codebase search features. On x64 Linux systems, LanceDB requires specific CPU features (FMA and AVX2) which may not be available on older processors.

Most Gobi features will work normally, including autocomplete and chat. However, commands that rely on codebase indexing, such as `@codebase`, `@files`, and `@folder`, will be disabled.

For more details about this requirement, see the [LanceDB issue #2195](https://github.com/lancedb/lance/issues/2195).

## Ollama Issues

For a comprehensive guide on setting up and troubleshooting Ollama, see the [Ollama Guide](/guides/ollama-guide).

### Unable to connect to local Ollama instance

If you're getting "Unable to connect to local Ollama instance" errors:

1. **Verify Ollama is running**: Check [http://localhost:11434](http://localhost:11434) in your browser - you should see "Ollama is running"
2. **Start Ollama properly**: Use `ollama serve` (not just `ollama run model-name`)
3. **Check your config**: Ensure your `config.yaml` has the correct setup:

```yaml  theme={null}
models:
  - name: llama3
    provider: ollama
    model: llama3:latest
```

### Connection failed to remote Ollama (EHOSTUNREACH/ECONNREFUSED)

When connecting to Ollama on another machine:

1. **Configure Ollama to listen on all interfaces**:
   * Set environment variable: `OLLAMA_HOST=0.0.0.0:11434`
   * For systemd: Edit `/etc/systemd/system/ollama.service` and add under `[Service]`:
     ```
     Environment="OLLAMA_HOST=0.0.0.0:11434"
     Environment="OLLAMA_ORIGINS=*"
     ```
   * Restart Ollama: `sudo systemctl restart ollama`

2. **Update your Gobi config**:

```yaml  theme={null}
models:
  - name: llama3
    provider: ollama
    apiBase: http://192.168.1.136:11434  # Use your server's IP
    model: llama3:latest
```

3. **Check firewall settings**: Ensure port 11434 is open on the server

### Ollama not working in WSL

For WSL users having connection issues:

#### Windows 11 22H2+ (Recommended)

Create or edit `%UserProfile%\.wslconfig`:

```ini  theme={null}
[wsl2]
networkingMode=mirrored
```

Then restart WSL: `wsl --shutdown`

#### Older Windows/WSL versions

In PowerShell (as Administrator):

```powershell  theme={null}
# Add firewall rules
New-NetFireWallRule -DisplayName 'WSL Ollama' -Direction Inbound -LocalPort 11434 -Action Allow -Protocol TCP
New-NetFireWallRule -DisplayName 'WSL Ollama' -Direction Outbound -LocalPort 11434 -Action Allow -Protocol TCP

# Get WSL IP (run 'ip addr' in WSL to find eth0 IP)
# Then add port proxy (replace <WSL_IP> with your actual IP)
netsh interface portproxy add v4tov4 listenport=11434 listenaddress=0.0.0.0 connectport=11434 connectaddress=<WSL_IP>
```

### Docker container can't connect to host Ollama

When running Gobi or other tools in Docker that need to connect to Ollama on the host:

**Windows/Mac**: Use `host.docker.internal`:

```yaml  theme={null}
models:
  - name: llama3
    provider: ollama
    apiBase: http://host.docker.internal:11434
    model: llama3:latest
```

**Linux**: Use the Docker bridge IP (usually `172.17.0.1`):

```yaml  theme={null}
models:
  - name: llama3
    provider: ollama
    apiBase: http://172.17.0.1:11434
    model: llama3:latest
```

**Docker run command**: Add host mapping:

```bash  theme={null}
docker run -d --add-host=host.docker.internal:host-gateway ...
```

### Parse errors with remote Ollama

If you're getting parse errors with remote Ollama:

1. **Verify the model is installed on the remote**:
   ```bash  theme={null}
   OLLAMA_HOST=192.168.1.136:11434 ollama list
   ```

2. **Install missing models**:
   ```bash  theme={null}
   OLLAMA_HOST=192.168.1.136:11434 ollama pull llama3
   ```

3. **Check URL format**: Ensure you're using `http://` not `https://` for local network addresses

## Local Config

### Managing Local Secrets and Environment Variables

For running Gobi completely offline without internet access, see the [Running Gobi Without Internet guide](/guides/running-gobi-without-internet).

Gobi supports multiple methods for managing secrets locally, searched in this order:

1. **Workspace `.env` files**: Place a `.env` file in your workspace root directory
2. **Workspace Gobi folder**: Place a `.env` file in `<workspace-root>/.gobi/.env`
3. **Global `.env` file**: Place a `.env` file in `~/.gobi/.env` for user-wide secrets
4. **Process environment variables**: Use standard system environment variables

#### Creating `.env` files

Create a `.env` file in one of these locations:

* **Per-workspace**: `<workspace-root>/.env` or `<workspace-root>/.gobi/.env`
* **Global**: `~/.gobi/.env`

Example `.env` file:

```
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
CUSTOM_API_URL=https://api.example.com
```

#### Using secrets in config.yaml

Reference your local secrets using the `secrets` namespace:

```yaml  theme={null}
models:
  - provider: openai
    apiKey: ${{ secrets.OPENAI_API_KEY }}
```

#### Hub-managed secrets

For centralized team secret management, use `${{ inputs.SECRET_NAME }}` syntax in your config.yaml and manage them at [https://hub.gourmand.dev/settings/secrets](https://hub.gourmand.dev/settings/secrets):

```yaml  theme={null}
models:
  - provider: openai
    apiKey: ${{ inputs.OPENAI_API_KEY }}
```

#### Important notes

* **Never commit `.env` files** to version control - add them to `.gitignore`
* The `.env` file uses standard dotenv format (KEY=value, no quotes needed)
* Secrets are loaded when Gobi starts, so restart your IDE after changes
* Local `.env` files take precedence over Hub secrets when both exist

#### Troubleshooting secrets

If your API keys aren't being recognized:

1. Check the `.env` file is in the correct location
2. Ensure there are no quotes around values in the `.env` file
3. Restart your IDE after adding/changing secrets
4. Verify the variable name matches exactly (case-sensitive)
5. Check that your `.env` file has proper line endings (LF, not CRLF on Windows)

### Using Model Addons Locally

You can leverage model addons from the Gobi Hub in your local configurations using the `uses:` syntax. This allows you to reference pre-configured model blocks without duplicating configuration.

#### Requirements

* You must be logged in to Gobi
* Internet connection is required (model addons are fetched from the hub)

#### Usage

In your local `config.yaml`, reference model addons using the format `provider/model-name`:

```yaml  theme={null}
name: My Local Config
version: 0.0.1
schema: v1
models:
  - uses: ollama/llama3.1-8b
  - uses: anthropic/claude-3.5-sonnet
  - uses: openai/gpt-4
```

#### With local configuration

You can combine hub model addons with local models:

```yaml  theme={null}
name: My Local Config
version: 0.0.1
schema: v1
models:
  # Hub model addon
  - uses: anthropic/claude-3.5-sonnet
  
  # Local model configuration
  - name: Local Ollama
    provider: ollama
    model: codellama:latest
    apiBase: http://localhost:11434
```

#### Override addon settings

You can override specific settings from the model addon:

```yaml  theme={null}
models:
  - uses: ollama/llama3.1-8b
    override:
      apiBase: http://192.168.1.100:11434  # Use remote Ollama server
      roles:
        - chat
        - autocomplete
```

This feature allows you to maintain consistent model configurations across teams while still allowing local customization when needed.

## How do I reset the state of the extension?

Gobi stores its data in the `~/.gobi` directory (`%USERPROFILE%\.gobi` on Windows).

If you'd like to perform a clean reset of the extension, including removing all configuration files, indices, etc, you can remove this directory, uninstall, and then reinstall.

## Still having trouble?

You can also join our Discord community [here](https://discord.gg/TODO) for additional support and GitHub Discussions. Alternatively, you can create a GitHub issue [here](https://github.com/gourmand/gobi/issues/new?assignees=\&labels=bug\&projects=\&template=bug-report-%F0%9F%90%9B.md\&title=), providing details of your problem, and we'll be able to help you out more quickly.


# Chrome DevTools Performance Optimization Cookbook
Source: https://docs.gourmand.dev/guides/chrome-devtools-mcp-performance

Measure and optimize web performance with Chrome DevTools MCP, automated performance traces, and Core Web Vitals monitoring using Gobi.

<Card title="Debug Performance Like a Pro" icon="gauge-high">
  Use AI to automatically trace performance, analyze Core Web Vitals, diagnose bottlenecks, and get actionable optimization suggestions directly from Chrome DevTools
</Card>

<Info>
  **Did You Know?** Chrome DevTools MCP brings the full power of browser debugging to your AI workflow:

  * [Performance Traces](https://developer.chrome.com/docs/devtools/performance) with automated analysis
  * [Network Request Monitoring](https://developer.chrome.com/docs/devtools/network) for bottleneck detection
  * [Console Debugging](https://developer.chrome.com/docs/devtools/console) with error pattern recognition
  * [CPU & Network Throttling](https://developer.chrome.com/docs/devtools/performance/reference#throttling) to simulate real-world conditions
  * [Performance Insights](https://developer.chrome.com/docs/devtools/performance-insights) with AI-powered analysis
  * [Screenshot Debugging](https://developer.chrome.com/docs/devtools/device-mode) for visual regression detection

  This guide shows you how to leverage these features through natural language with Gobi CLI!
</Info>

## What You'll Learn

This cookbook teaches you to:

* Run automated [performance traces](https://developer.chrome.com/docs/devtools/performance) to capture runtime metrics
* Analyze [Core Web Vitals](https://web.dev/vitals/) (LCP, FID, CLS, INP) and performance insights
* Diagnose performance bottlenecks using network and console analysis
* Test performance under different network and CPU conditions with [throttling](https://developer.chrome.com/docs/devtools/performance/reference#throttling)
* Automate visual regression testing with [screenshots](https://developer.chrome.com/docs/devtools/device-mode)

## Prerequisites

* Chrome browser installed
* Web project with a running development server (or deployed URL)
* Node.js 20+ installed
* [Gobi CLI](https://docs.gourmand.dev/guides/cli) (`npm i -g @gourmanddev/cli`)
* [Chrome DevTools MCP](https://hub.gourmand.dev) configured

## Quick Setup

For all options, first:

<Steps>
  <Step title="Install Gobi CLI">
    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```
  </Step>
</Steps>

## Chrome DevTools MCP Workflow Options

<Card title="Fastest Path to Success" icon="rocket">
  Skip the manual setup and use our pre-built Chrome DevTools agent that includes
  optimized prompts, rules, and the Chrome DevTools MCP for more consistent results.
</Card>

After completing **Quick Setup** above, you have two paths to get started:

<Tabs>
  <Tab title="⚡ Quick Start (Recommended)">
    **Perfect for:** Immediate results with optimized prompts and built-in performance analysis

    <Steps>
      <Step title="Add the Pre-Built Agent">
        Visit the [Chrome DevTools Continuous Agent](https://hub.gourmand.dev/gobi/chrome-dev-continuous) on Gobi Hub and click **"Install Agent"** or run:

        ```bash  theme={null}
        cn --config gourmand/chrome-dev-continuous
        ```

        This agent includes:

        * **Optimized prompts** for performance analysis and debugging
        * **Built-in rules** for consistent formatting and error handling
        * **[Chrome DevTools MCP](https://hub.gourmand.dev/google/chrome-devtools-mcp)** for reliable browser automation
      </Step>

      <Step title="Run Performance Analysis">
        In the TUI that opens, type:

        ```
        Analyze performance of http://localhost:3000 and provide optimization recommendations
        ```

        That's it! The agent handles Chrome automation automatically.
      </Step>
    </Steps>

    <Info>
      **Why Use the Agent?** Results are more consistent and debugging is easier thanks to the Chrome DevTools MCP integration and pre-tested prompts.
    </Info>
  </Tab>

  <Tab title="🛠️ Manual Setup">
    <Steps>
      <Step title="Add Chrome DevTools MCP to Your Assistant">
        Visit the [Chrome DevTools MCP](https://hub.gourmand.dev/google/chrome-devtools-mcp) on Gobi Hub and add it to your assistant, or add this to your configuration:

        ```yaml  theme={null}
        name: Chrome DevTools MCP
        version: 0.0.1
        schema: v1
        mcpServers:
          - name: Chrome DevTools MCP
            command: npx
            args:
              - chrome-devtools-mcp@latest
        ```

        The MCP will automatically launch Chrome and connect to DevTools when needed.
      </Step>

      <Step title="Verify Setup">
        Test the connection:

        **TUI Mode Prompt:**

        ```
        Open web.dev and take a screenshot
        ```
      </Step>

      <Step title="Run Performance Analysis">
        Navigate to your project directory:

        **TUI Mode Prompt:**

        ```
        Navigate to http://localhost:3000 and record a performance trace. Analyze LCP, FID, and CLS.
        ```
      </Step>
    </Steps>

    <Info>
      **Manual Setup**: While you can configure the MCP manually, the pre-built agent provides optimized prompts and better error handling for performance analysis workflows.
    </Info>
  </Tab>
</Tabs>

<Accordion title="Agent Requirements">
  To use the pre-built agent, you need either:

  * **Gobi CLI Pro Plan** with the models add-on, OR
  * **Your own API keys** added to Gobi Hub secrets
  * **Chrome browser** installed on your system
  * **Node.js 20+** to run the MCP via npx

  The agent will automatically detect and use your configuration.
</Accordion>

***

## Performance Measurement Workflows

The Chrome DevTools MCP enables natural language performance analysis. Here are workflows adapted from real-world use cases:

### Quick Performance Checks

<Card title="Verify Code Changes" icon="check">
  **TUI Mode Prompt:**

  ```
  Verify in the browser that your change works as expected.
  ```
</Card>

<Card title="Debug Broken Images" icon="image">
  **TUI Mode Prompt:**

  ```
  A few images on localhost:8080 are not loading. What's happening?
  ```
</Card>

<Card title="Debug Form Submission Issues" icon="rectangle-list">
  **TUI Mode Prompt:**

  ```
  Why does submitting the form fail after entering an email address?
  ```
</Card>

<Card title="Debug Layout Issues" icon="layer-group">
  **TUI Mode Prompt:**

  ```
  The page on localhost:8080 looks strange and off. Check what's happening there.
  ```
</Card>

<Card title="Performance Optimization" icon="gauge-high">
  **TUI Mode Prompt:**

  ```
  Localhost:8080 is loading slowly. Make it load faster.
  ```
</Card>

<Card title="Check Core Web Vitals" icon="chart-line">
  **TUI Mode Prompt:**

  ```
  Please check the LCP of web.dev.
  ```
</Card>

***

## Performance Analysis Recipes

Now you can use natural language prompts to analyze web performance. The Gobi agent automatically calls the appropriate Chrome DevTools MCP tools.

<Info>
  **Where to run these workflows:**

  * **IDE Extensions**: Use Gobi in VS Code, JetBrains, or other supported IDEs
  * **Terminal (TUI mode)**: Run `cn` to enter interactive mode, then type your prompts
  * **CLI (headless mode)**: Use `cn -p "your prompt"` for headless commands

  **Test in Plan Mode First**: Before running performance measurements, test your prompts in plan mode (see the [Plan Mode Guide](/guides/plan-mode-guide); press **Shift+Tab** to switch modes). This shows you what the agent will do without executing it.
</Info>

### Step 1: Baseline Performance Trace

Establish your current performance baseline:

**TUI Mode Prompt:**

```
Navigate to http://localhost:3000 and record a performance trace with page reload. Analyze the trace and show me the LCP, FID, CLS, and total blocking time.
```

<Info>
  Chrome DevTools Performance Panel automatically tracks:

  * **Core Web Vitals**: LCP, FID, CLS, INP
  * **Loading Performance**: DOMContentLoaded, Load events, First Paint
  * **Runtime Performance**: JavaScript execution time, layout shifts, paint events
  * **Resource Usage**: Memory consumption, CPU utilization
</Info>

### Step 2: Analyze Performance Insights

Deep dive into specific performance issues:

**TUI Mode Prompt:**

```
Record a performance trace for http://localhost:3000 and analyze all Performance Insights. For each insight found, provide detailed information about:
- The specific issue (e.g., DocumentLatency, SlowCSS)
- Root cause analysis
- Affected resources or code
- Recommended optimizations
- Expected impact on Core Web Vitals
```

<Info>
  **Performance Insights**: Chrome DevTools automatically detects common performance issues like:

  * **Render Blocking Resources**: CSS and JavaScript that delay first paint
  * **Layout Shifts**: Elements that move during page load
  * **Long Tasks**: JavaScript execution blocking the main thread
  * **Slow Network Requests**: Resources taking too long to load
  * **Unused CSS/JavaScript**: Dead code increasing bundle size
</Info>

### Step 3: Network Performance Analysis

Identify slow network requests and optimization opportunities:

**TUI Mode Prompt:**

```
Navigate to https://my-site.com and:
1. List all network requests made during page load
2. Identify the 5 slowest requests and their sizes
3. Find any requests over 1MB
4. Detect render-blocking resources
5. Check for inefficient caching (missing cache headers)
6. Suggest specific optimizations for each issue found
```

### Step 4: Throttling Performance Tests

Test performance under real-world network and CPU conditions:

**TUI Mode Prompt:**

```
Test my site's performance under different conditions:

1. Navigate to http://localhost:3000
2. Emulate 4x CPU slowdown and Fast 3G network
3. Record a performance trace with reload
4. Analyze LCP and Total Blocking Time
5. Take a screenshot when page is fully loaded

Then repeat the test with:
- Slow 3G network + 6x CPU slowdown
- Offline network (to test service worker)

Compare results and identify which conditions cause the worst performance degradation."
```

<Info>
  **Available Network Presets**:

  * No throttling
  * Fast 3G (1.6 Mbps down, 0.75 Mbps up)
  * Slow 3G (400 Kbps down, 400 Kbps up)
  * Offline

  **CPU Throttling**: 4x, 6x, or custom slowdown to simulate low-end devices
</Info>

### Step 5: JavaScript Performance Analysis

Identify expensive JavaScript operations:

**TUI Mode Prompt:**

```
Record a performance trace for http://localhost:3000 and:
1. Identify all long tasks (>50ms) blocking the main thread
2. Find the specific JavaScript functions causing these tasks
3. Measure total JavaScript execution time
4. Detect unused JavaScript being loaded
5. Show the call stack for the longest task
6. Recommend code splitting or lazy loading opportunities"
```

## Automated Performance Monitoring

### Step 6: Core Web Vitals Dashboard

Create automated monitoring for Core Web Vitals:

**TUI Mode Prompt:**

```
Create a performance monitoring script that:
1. Opens my site at http://localhost:3000
2. Records a performance trace with reload
3. Extracts Core Web Vitals (LCP, FID, CLS, INP)
4. Checks console for JavaScript errors
5. Takes a screenshot
6. Saves results to performance-report.json with format:
   {
     'timestamp': 'ISO date',
     'lcp': number,
     'fid': number,
     'cls': number,
     'inp': number,
     'errors': array,
     'screenshot': 'path'
   }

Save this as scripts/performance-monitor.js that I can run regularly"
```

### Step 7: Visual Regression Detection

Detect unintended visual changes:

**TUI Mode Prompt:**

```
Set up visual regression testing:
1. Navigate to http://localhost:3000
2. Take full-page screenshots at:
   - Desktop viewport (1920x1080)
   - Tablet viewport (768x1024)
   - Mobile viewport (375x667)
3. Save screenshots to screenshots/baseline/
4. Create a script to compare future screenshots against baseline
5. Highlight any pixel differences over 5%
6. Generate a visual diff report"
```

### Step 8: Performance Budget Enforcement

Set and enforce performance budgets:

**TUI Mode Prompt:**

```
Create a performance budget checker that:

Requirements:
- LCP must be < 2.5 seconds
- FID must be < 100ms
- CLS must be < 0.1
- Total JavaScript < 300KB
- Total page size < 1MB
- No console errors

Implementation:
1. Navigate to http://localhost:3000
2. Record performance trace with reload
3. List all network requests and calculate total sizes
4. Check console messages for errors
5. Validate all metrics against budgets
6. Exit with code 1 if any budget is exceeded
7. Generate a detailed report showing pass/fail for each metric

Save as scripts/performance-budget.js for CI/CD integration"
```

## Continuous Performance Testing with GitHub Actions

This example demonstrates a **Continuous AI workflow** where performance validation runs automatically in your CI/CD pipeline using Chrome DevTools MCP in headless mode.

### Add GitHub Secrets

Navigate to **Repository Settings → Secrets and variables → Actions** and add:

* `GOBI_API_KEY`: Your Gobi API key from [hub.gourmand.dev/settings/api-keys](https://hub.gourmand.dev/settings/api-keys)

### Create Workflow File

This workflow automatically validates web performance on pull requests using the Gobi CLI in headless mode. It records performance traces, extracts Core Web Vitals, and posts a summary report as a PR comment.

Create `.github/workflows/performance-check.yml` in your repository:

```yaml  theme={null}
name: Performance Check

on:
  pull_request:

jobs:
  performance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install Dependencies
        run: |
          npm install -g @gourmanddev/cli
          npm ci

      - name: Build Project
        run: npm run build

      - name: Start Dev Server
        run: |
          npm run dev &
          npx wait-on http://localhost:3000

      - name: Run Performance Tests
        env:
          GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}
        run: |
          cn --config gourmand/chrome-dev-continuous \
             -p "Navigate to http://localhost:3000 and:
             1. Record performance trace with reload
             2. Extract LCP, FID, CLS values
             3. List network requests and calculate total bundle size
             4. Output results as JSON to performance.json" \
             --auto

      - name: Check Performance Budgets
        run: |
          node << 'EOF'
          const fs = require('fs');
          const perf = JSON.parse(fs.readFileSync('performance.json'));

          const budgets = {
            lcp: 2.5,
            fid: 100,
            cls: 0.1,
            bundleSize: 300000
          };

          let failed = false;
          const results = [];

          if (perf.lcp > budgets.lcp) {
            results.push(`❌ LCP: ${perf.lcp}s (budget: ${budgets.lcp}s)`);
            failed = true;
          } else {
            results.push(`✅ LCP: ${perf.lcp}s`);
          }

          if (perf.fid > budgets.fid) {
            results.push(`❌ FID: ${perf.fid}ms (budget: ${budgets.fid}ms)`);
            failed = true;
          } else {
            results.push(`✅ FID: ${perf.fid}ms`);
          }

          if (perf.cls > budgets.cls) {
            results.push(`❌ CLS: ${perf.cls} (budget: ${budgets.cls})`);
            failed = true;
          } else {
            results.push(`✅ CLS: ${perf.cls}`);
          }

          if (perf.bundleSize > budgets.bundleSize) {
            results.push(`❌ Bundle: ${perf.bundleSize}KB (budget: ${budgets.bundleSize}KB)`);
            failed = true;
          } else {
            results.push(`✅ Bundle: ${perf.bundleSize}KB`);
          }

          console.log(results.join('\n'));

          if (failed) {
            process.exit(1);
          }
          EOF

      - name: Comment Performance Results
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const perf = JSON.parse(fs.readFileSync('performance.json'));

            const comment = `## 📊 Performance Report

            | Metric | Value | Budget | Status |
            |--------|-------|--------|--------|
            | LCP | ${perf.lcp}s | 2.5s | ${perf.lcp <= 2.5 ? '✅' : '❌'} |
            | FID | ${perf.fid}ms | 100ms | ${perf.fid <= 100 ? '✅' : '❌'} |
            | CLS | ${perf.cls} | 0.1 | ${perf.cls <= 0.1 ? '✅' : '❌'} |
            | Bundle Size | ${perf.bundleSize}KB | 300KB | ${perf.bundleSize <= 300 ? '✅' : '❌'} |

            ${perf.lcp > 2.5 || perf.fid > 100 || perf.cls > 0.1 || perf.bundleSize > 300
              ? '⚠️ **Performance budgets exceeded. Please optimize before merging.**'
              : '✅ **All performance budgets met!**'}`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });
```

<Info>
  The Chrome DevTools MCP works in headless Chrome environments. Make sure your CI environment has Chrome installed (it's pre-installed on GitHub Actions ubuntu-latest runners).
</Info>

## Advanced Performance Workflows

### Step 9: Competitor Comparison

Compare your site's performance with competitors:

**TUI Mode Prompt:**

```
Compare performance between my site and competitors:

Sites to test:
- http://localhost:3000 (my site)
- https://competitor1.com
- https://competitor2.com

For each site:
1. Navigate to homepage
2. Record performance trace with reload
3. Extract LCP, FID, CLS, Total Blocking Time
4. List network requests and calculate total page size
5. Count JavaScript and CSS files

Create a comparison table showing:
- Site name
- All Core Web Vitals
- Total page size
- Number of requests
- Which site performs best for each metric

Provide specific recommendations for how my site can improve based on what competitors do better."
```

### Step 10: Performance Testing Across Routes

Test performance consistency across your entire site:

**TUI Mode Prompt:**

```
Test performance across all major routes:

Routes to test:
- / (homepage)
- /products
- /products/[id] (pick a sample product)
- /checkout
- /blog

For each route:
1. Navigate to the URL
2. Record performance trace
3. Extract LCP, Total Blocking Time, bundle size
4. Check console for errors
5. Take a screenshot

Generate a report showing:
- Which routes have the worst LCP
- Routes with the most JavaScript errors
- Bundle size variations across routes
- Recommendations for route-specific optimizations"
```

### Step 11: Mobile Performance Analysis

Focus on mobile-specific performance issues:

**TUI Mode Prompt:**

```
Analyze mobile performance for http://localhost:3000:

1. Resize viewport to mobile (375x667)
2. Emulate Slow 3G network + 4x CPU slowdown
3. Record performance trace with reload
4. Analyze Performance Insights for mobile-specific issues
5. Check for:
   - Touch target sizes too small
   - Horizontal scrolling issues
   - Oversized images not optimized for mobile
   - Excessive JavaScript on mobile
6. Take mobile screenshot
7. Provide mobile-specific optimization recommendations"
```

## Performance Troubleshooting

### Debug Performance Regressions

Quickly identify what caused a performance regression:

**TUI Mode Prompt:**

```
Debug performance regression on http://localhost:3000:

1. Record performance trace
2. Analyze all Performance Insights
3. List console errors and warnings
4. Check network requests for:
   - Failed requests
   - Slow requests (>1s)
   - Large requests (>500KB)
5. Identify the top 3 performance bottlenecks
6. For each bottleneck, suggest:
   - Root cause
   - Specific code or resource causing it
   - Step-by-step fix
   - Expected performance improvement"
```

### Performance Issue Quick Reference

| Issue          | Quick Fix Command (in cn TUI)                                              |
| :------------- | :------------------------------------------------------------------------- |
| Slow LCP       | `"Find render-blocking resources and suggest preloading or deferring"`     |
| High CLS       | `"Detect layout shifts and identify unsized images or dynamic content"`    |
| Long Tasks     | `"Find JavaScript tasks over 50ms and suggest code splitting"`             |
| Large Bundles  | `"List all JavaScript files, identify largest ones, suggest lazy loading"` |
| Slow Network   | `"Find requests over 500KB and suggest compression or optimization"`       |
| Console Errors | `"List all console errors and suggest fixes"`                              |

## What You've Built

After completing this guide, you have a complete **AI-powered performance analysis system** that:

* ✅ **Uses natural language** — Simple prompts instead of complex DevTools commands
* ✅ **Analyzes automatically** — AI interprets performance traces and suggests fixes
* ✅ **Runs continuously** — Automated validation in CI/CD pipelines
* ✅ **Ensures quality** — Performance checks prevent regressions from shipping

<Card title="Continuous AI" icon="rocket">
  Your performance workflow now operates at **[Level 2 Continuous AI](https://blog.gourmand.dev/what-is-continuous-ai-a-developers-guide/)** - AI handles routine performance analysis and debugging with human oversight through review and approval of changes.
</Card>

## Chrome DevTools MCP Capabilities

<CardGroup cols={2}>
  <Card title="Performance Tracing" icon="chart-line">
    **Tools Available**

    * `performance_start_trace`: Start recording with auto-reload
    * `performance_stop_trace`: Stop and analyze trace
    * `performance_analyze_insight`: Deep dive into specific issues
  </Card>

  <Card title="Network Debugging" icon="network-wired">
    **Tools Available**

    * `list_network_requests`: See all requests and sizes
    * `get_network_request`: Inspect specific request details
    * `emulate_network`: Test under various network conditions
  </Card>

  <Card title="Console Analysis" icon="terminal">
    **Tools Available**

    * `list_console_messages`: Get all console logs and errors
    * `evaluate_script`: Run JavaScript in page context
    * Automatic error pattern detection
  </Card>

  <Card title="Visual Testing" icon="camera">
    **Tools Available**

    * `take_screenshot`: Capture full or partial page
    * `take_snapshot`: Get accessibility tree snapshot
    * `resize_page`: Test responsive layouts
  </Card>
</CardGroup>

## Performance Best Practices

Key metrics to monitor for optimal web performance:

<CardGroup cols={3}>
  <Card title="Core Web Vitals" icon="gauge-high">
    * LCP \< 2.5s (good)
    * FID \< 100ms (good)
    * CLS \< 0.1 (good)
    * INP \< 200ms (good)
  </Card>

  <Card title="Loading Performance" icon="bolt">
    * Total page size \< 1MB
    * JavaScript \< 300KB
    * Time to Interactive \< 3.8s
    * First Contentful Paint \< 1.8s
  </Card>

  <Card title="Runtime Performance" icon="microchip">
    * No long tasks > 50ms
    * 60 FPS during interactions
    * No memory leaks
    * Efficient event listeners
  </Card>
</CardGroup>

## Advanced Testing Scenarios

### A/B Test Performance Impact

**TUI Mode Prompt:**

```
Compare performance of two implementations:
1. Test variant A at http://localhost:3000?variant=A
2. Test variant B at http://localhost:3000?variant=B
Run each test 5 times and calculate average LCP, FID, CLS
Determine which variant has better performance and by how much
```

### Lighthouse Score Tracking

**TUI Mode Prompt:**

```
Create a script that runs daily performance audits:
1. Navigate to production site
2. Record performance trace
3. Calculate Lighthouse-style performance score based on:
   - FCP (10%)
   - SI (10%)
   - LCP (25%)
   - TTI (10%)
   - TBT (30%)
   - CLS (15%)
4. Track score over time in performance-history.json
5. Alert if score drops below 90
```

### Performance Regression Detection

**TUI Mode Prompt:**

```
Set up automated regression detection:
1. Record baseline performance for main branch
2. Save baseline metrics to baseline-perf.json
3. On each PR, run performance tests
4. Compare PR metrics with baseline
5. Flag regressions over 10% for any metric
6. Generate visual diff report with screenshots
```

## Next Steps

1. **Analyze your first site** - Try the baseline performance trace on your current project
2. **Debug bottlenecks** - Use the network analysis prompt to fix slow requests
3. **Set up CI pipeline** - Add the GitHub Actions workflow to your repo
4. **Test throttling** - Measure performance under real-world network conditions
5. **Monitor trends** - Track Core Web Vitals over time

## Additional Resources

<CardGroup cols={2}>
  <Card title="Chrome DevTools MCP" icon="plug" href="https://github.com/ChromeDevTools/chrome-devtools-mcp">
    Official Chrome DevTools MCP repository
  </Card>

  <Card title="Gobi Hub" icon="circle-nodes" href="https://hub.gourmand.dev">
    Explore more MCP integrations
  </Card>

  <Card title="DevTools Documentation" icon="book" href="https://developer.chrome.com/docs/devtools">
    Complete Chrome DevTools documentation
  </Card>

  <Card title="Web Vitals Guide" icon="gauge-high" href="https://web.dev/vitals/">
    Learn about Core Web Vitals
  </Card>
</CardGroup>


# How to Use Gobi CLI (cn)
Source: https://docs.gourmand.dev/guides/cli

Learn how to use Gobi's command-line interface for context engineering, automated coding tasks, and headless development workflows with customizable models, rules, and tools

<Warning>Gobi CLI (cn) is currently in Beta</Warning>

`cn` is an open-source, modular coding agent for the command line.

It provides a battle-tested agent loop so you can simply plug in your model, rules, and tools.

<img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/cn-demo.gif?s=ddde6a7d2225ae03a2c489daf29324ba" alt="cn" data-og-width="1588" width="1588" data-og-height="1080" height="1080" data-path="images/cn-demo.gif" data-optimize="true" data-opv="3" />

## Quick start

<Info>
  Make sure you have [Node.js 18 or higher
  installed](https://nodejs.org/en/download/).
</Info>

```bash  theme={null}
# Install
npm i -g @gourmanddev/cli

# Interactive mode
cn

# Headless mode
cn -p "Generate a conventional commit name for the current git changes"
```

## How to Use Gobi CLI - Basic Usage

Out of the box, `cn` comes with tools that let it understand your codebase, edit files, run terminal commands, and more (if you approve). You can ask `cn` to:

* Fix failing tests
* Find something in the codebase
* Execute a refactor
* Write a new feature
* And a lot more

Use '@' to give it file context, or '/' to run slash commands.

If you want to resume a previous conversation, run `cn --resume`.

## How to Use Headless Mode (`-p` flag)

In headless mode, `cn` will only output its final response, making it perfect for Unix Philosophy-style scripting and automation. For example, you could pipe your git diff into `cn` to generate a commit message, and write this to a file:

```bash  theme={null}
echo "$(git diff) Generate a conventional commit name for the current git changes" | cn -p > commit-message.txt
```

## How to Configure Gobi CLI

`cn` uses [`config.yaml`](/reference), the exact same configuration file as Gobi. This means that you can log in to [Gobi Hub](/hub/introduction) or use your existing local configuration.

To switch between configurations, you can use the `/config` slash command in `cn`, or you can start it with the `--config` flag (e.g. `cn --config gourmand/default-agent` or `cn --config ~/.gobi/config.yaml`).

### How to Add Custom Models

Learn how to add custom models [here](/customize/overview). Then, you can use the `/model` slash command to switch between them in `cn`.

### How to Configure Rules

`cn` supports [rules](/customize/deep-dives/rules) in the same way as the Gobi IDE extensions. You can also use the `--rule` flag to manually include a rule from the hub. For example, `cn --rule nate/spanish` will tell `cn` to use [this rule](https://hub.gourmand.dev/nate/spanish) to always speak in Spanish.

### How to Configure Tools

`cn` supports MCP tools, which can be configured in the [same way](/customize/deep-dives/mcp) as with the Gobi IDE extensions.

#### How to Set Tool Permissions

`cn` includes a tool permission system to make sure you approve of the agent's actions. It will begin with minimal permissions but as you approve tool calls, it will add policies to `~/.gobi/permissions.yaml` to remember your preferences.

If you want to explicitly allow or deny tools for a single session, you can use the command line flags `--allow`, `--ask`, and `--exclude`. For example:

```bash  theme={null}
# Always allow the Write tool
cn --allow Write()

# Always ask before running curl
cn --ask Bash(curl*)

# Never use the Fetch tool
cn --exclude Fetch
```

## API Key Authentication

For automation in CI or other headless environments, you can use an API key to authenticate with Gobi. First, obtain your personal API key [here](https://hub.gourmand.dev/settings/api-keys). Then, set it as the `GOBI_API_KEY` environment variable. You can now use `cn -p` (headless mode) without needing to log in.

If you wish to run an automation on behalf of your organization you can obtain an organization-scoped API key by going to [your organization's settings](https://hub.gourmand.dev/settings/organizations) -> API Keys.

## Troubleshooting

Run `cn` with the `--verbose` flag to see more detailed logs. These will be output to `~/.gobi/logs/cn.log`.

If you have feedback on the beta, please [share in our Discord](https://discord.com/invite/EfJEfdFnDQ) or [leave feedback in the GitHub discussion](https://github.com/gourmand/gobi/discussions/7307).


# How to Make Agent mode Aware of Codebases and Documentation
Source: https://docs.gourmand.dev/guides/codebase-documentation-awareness

Learn how to give your Agent mode access to codebases and documentation for more context-aware assistance

Agent mode works best when it understands the context of your project. This guide shows you how to give agent mode access to codebases and documentation, making it more helpful and accurate.

## Make agent mode aware of your open codebase

When agent mode understands your current codebase, it can provide more relevant suggestions and answers.

### Let agent mode explore the codebase using tools

Agent mode can use built-in tools to navigate and understand your code:

1. **File exploration tools**: The agent can read files, search for patterns, and understand project structure
2. **Code search**: Use search to find relevant code snippets
3. **Git integration**: Access commit history and understand code evolution

### Create rules to help the agent understand your codebase

Rules guide agent mode's behavior and understanding. Place markdown files in `.gobi/rules` in your project to provide context:

```markdown  theme={null}
# Project Architecture

This is a React application with:

- Components in `/src/components`
- API routes in `/src/api`
- State management using Redux in `/src/store`

## Coding Standards

- Use TypeScript for all new files
- Follow the existing naming conventions
- Write tests for all new features
```

<Tip>
  Place rules files at different levels of your project hierarchy to scope when
  they trigger
</Tip>

Learn more about [rules configuration](/customize/deep-dives/rules).

## Make agent mode aware of other codebases

Sometimes you need agent mode to understand code beyond your current project.

### Public codebases

For open-source projects and public repositories, you have several options:

#### Rules with hyperlinks

Create rules that point to external codebases:

```markdown  theme={null}
# External Dependencies

Our authentication system is based on:

- [Auth.js documentation](https://authjs.dev/)
- [Example implementation](https://github.com/nextauthjs/next-auth-example)

When implementing auth features, reference these patterns.
```

#### GitHub and GitLab CLIs

Enable `gh` or `glab` CLI access for agent mode to interact with repositories.

Add rules to guide CLI usage:

```markdown  theme={null}
# Repository Access

You can use the `gh` CLI to:

- Search for issues: `gh issue list --repo owner/repo`
- View pull requests: `gh pr list --repo owner/repo`
- Clone repositories: `gh repo clone owner/repo`
```

#### DeepWiki MCP

[DeepWiki MCP](https://hub.gourmand.dev/deepwiki/deepwiki-mcp) lets agent mode explore any public GitHub repository.

Once configured, agent mode can explore repositories like:

* "Explore the React repository structure"
* "Find how authentication is implemented in NextAuth.js"

### Internal codebases

For private and internal repositories, you need additional setup:

#### Custom MCP servers

Create an MCP server that has access to your internal repositories.

#### Custom code RAG

For faster retrieval and lower costs with very large internal codebases, consider implementing a [custom code RAG](/guides/custom-code-rag) system. This is an advanced approach that requires more setup but can provide performance benefits at scale.

## Make agent mode aware of relevant documentation

Documentation provides crucial context for agent mode to understand APIs, frameworks, and best practices.

### Public documentation

#### Rules with documentation links

Guide agent mode to relevant documentation:

```markdown  theme={null}
# Documentation Resources

For framework-specific questions, refer to:

- React: https://react.dev/reference/react
- Next.js: https://nextjs.org/docs
- Tailwind CSS: https://tailwindcss.com/docs

Always cite documentation when explaining concepts.
```

#### Context7 MCP

[Context7 MCP](https://hub.gourmand.dev/upstash/context7-mcp) enables agent mode to search and retrieve information from public documentation:

Agent mode can then answer questions like:

* "How do I use React hooks?"
* "What's the syntax for Tailwind CSS animations?"

### Internal documentation

For private documentation and wikis:

#### Rules with internal links

Create rules that reference internal resources:

```markdown  theme={null}
# Internal Documentation

Our team documentation is available at:

- API Documentation: https://internal.docs/api
- Architecture Guide: https://internal.docs/architecture
- Deployment Process: https://internal.docs/deployment

Always follow our internal standards when suggesting code.
```

#### Custom MCP servers for docs

Create an MCP server that accesses your internal documentation.

## Migrating from deprecated context providers

If you were previously using the `@Codebase` or `@Docs` context providers, here's how to migrate to the new approach:

### Migrating from @Codebase

The `@Codebase` context provider has been deprecated. Instead:

1. **Use built-in tools**: Agent mode can now use file exploration and search tools to understand your codebase
2. **Add rules**: Create `.gobi/rules` files to provide context about your project structure
3. **Use MCP servers**: For external codebases, use DeepWiki MCP or custom MCP servers

### Migrating from @Docs

The `@Docs` context provider has been deprecated. Instead:

1. **Use Context7 MCP**: For public documentation, Context7 MCP provides similar functionality
2. **Add documentation links in rules**: Create rules that reference documentation URLs
3. **Use custom MCP servers**: For internal documentation, create an MCP server with access to your docs

The new approach provides better integration with Gobi's Agent mode features and more intelligent context selection.

## Next steps

* Learn more about [MCP servers](/reference/gobi-mcp)
* Explore [rules configuration](/customize/deep-dives/rules)
  * Set up [other custom configurations](/guides/understanding-configs) with specific knowledge domains


# Configuring Models, Rules, and Tools
Source: https://docs.gourmand.dev/guides/configuring-models-rules-tools

Learn how to work with Gobi's configuration system. Understand how to use hub models, rules, and tools, create local configurations, and organize your setup for maximum reusability.

## What Are Models, Rules, and Tools?

Gobi configs are built from three main types of configuration:

<Columns cols={3}>
  <Card title="Models" icon="cube">
    Language models that power different capabilities like chat, autocomplete, and agent mode
  </Card>

  <Card title="Rules" icon="pencil">
    Guidelines and instructions that shape how the AI behaves and responds
  </Card>

  <Card title="Tools" icon="server">
    MCP tools that provide additional capabilities like database access, web search, or custom functions
  </Card>
</Columns>

There are two places where you can define these configurations:

<Columns cols={2}>
  <Card title="Local" icon="computer">
    Custom configurations you create and manage in your workspace or globally
  </Card>

  <Card title="Hub" icon="cloud">
    Pre-built models, rules, and tools from the Gobi community that you can import and use immediately
  </Card>
</Columns>

## Local

Local configurations let you create custom models, rules, and tools that automatically apply to multiple configs, reducing duplication and ensuring consistency across your setup.

<Columns cols={2}>
  <Card title="Global" icon="globe">
    Applied to all configs across all workspaces. Ideal for personal preferences, universal coding standards, or tools you use everywhere.
  </Card>

  <Card title="Workspace" icon="folder-open">
    Applied automatically to all configs when working in a specific project.

    Perfect for project-specific setups like TypeScript rules for web apps or the Playwright MCP tool.
  </Card>
</Columns>

## Hub

Gobi hub uses a slug in the format of `owner/item-name` to resolve blocks.

For example, to use the [Claude 4 Sonnet model](https://hub.gourmand.dev/anthropic/claude-4-sonnet), you'd reference it as `anthropic/claude-4-sonnet`.

Import from the hub using the `uses` syntax alongside your custom configurations:

```yaml config.yaml highlight={6} theme={null}
name: Team Config
version: 1.0.0
schema: v1

models:
  - uses: anthropic/claude-4-sonnet
    with:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # Use a hub secret
```

### Organization

Organize your local configurations using these directories:

<Columns cols={3}>
  <Card title="Models" icon="cube">
    `.gobi/models`
  </Card>

  <Card title="Rules" icon="pencil">
    `.gobi/rules`
  </Card>

  <Card title="Tools" icon="server">
    `.gobi/mcpServers`
  </Card>
</Columns>

## Working with Secrets

Models, and many MCP servers, require a secret for things like API keys.

On the hub, you can configure secrets when adding a model or MCP server.

This will use mustache notation to pass the secret, eg `${{ secrets.SECRET_NAME }}`

When configuring a local model or MCP server, you can use the same mustache notation for secrets which read from:

<Columns cols={2}>
  <Card title="Global" icon="globe">
    `.env` file in `~/.gobi/.env`
  </Card>

  <Card title="Workspace" icon="folder-open">
    `.env` file at your project root
  </Card>
</Columns>

<Info>
  **When to use `secrets.` vs `inputs.`**

  For most use cases, **use `${{ secrets.SECRET_NAME }}`** directly in your configuration. This is the recommended approach for both personal and organizational workflows.

  Use `${{ inputs.INPUT_NAME }}` only when you need flexibility to:

  * Allow users to customize which secret a block uses without editing the block itself
  * Change the secret name without modifying the block configuration
  * Create reusable blocks where different users may have differently-named secrets

  This pattern is inspired by GitHub Actions, where inputs provide an abstraction layer between block definitions and user-specific values. For most scenarios, directly referencing `secrets.` keeps configuration simpler and more straightforward.
</Info>

## Overriding Properties

You can directly override properties using the `override` syntax:

```yaml title="config.yaml" highlight={10-13} theme={null}
name: myprofile/custom-config
version: 1.0.0
schema: v1

models:
  - uses: myprofile/custom-model
    with:
      ANTHROPIC_API_KEY: ${{ secrets.MY_ANTHROPIC_API_KEY }}
      TEMP: 0.9
    override:
      roles:
        - chat
```

## Advanced

### Inputs

Models and MCP server authors can configure inputs that require the user to provide a secret value by defining a `${{ inputs.SECRET_NAME }}` value.

For example, here is how you could require that the user provide a value for the `apiKey` property on a model:

```yaml title="config.yaml" highlight={8} theme={null}
name: myprofile/custom-model
version: 1.0.0
schema: v1

models:
  - name: My Favorite Model
    # ... other model properties ...
    apiKey: ${{ inputs.SECRET_NAME }}
```

Users then map their secret to this input using a `${{ secrets.SECRET_NAME }}` value that maps to a property name which matches the required input, e.g. `SECRET_NAME`.

```yaml title="config.yaml" highlight={8} theme={null}
name: myprofile/custom-config
version: 1.0.0
schema: v1

models:
  - uses: myprofile/custom-model
    with:
      SECRET_NAME: ${{ secrets.SECRET_NAME }}
```

## Next Steps

Now that you understand how models, rules, and tools work, explore:

* **[Config Reference](/reference)**: Detailed documentation of all available properties
* **[Gobi Hub](https://hub.gourmand.dev)**: Browse community models, rules, and tools
* **[Custom Context Providers](/customize/deep-dives/custom-providers)**: Create advanced context integrations
* **[Model Roles](/customize/model-roles/intro)**: Understanding how different models work together


# Continuous AI: A Developer's Guide
Source: https://docs.gourmand.dev/guides/continuous-ai

Learn how to integrate intelligent automation into development workflows, making AI assistance as natural as syntax highlighting. Implement systematic AI workflows that compound productivity gains over time.

Continuous AI is the integration of intelligent automation directly into development workflows, making AI assistance as natural and reliable as syntax highlighting or code completion. Its purpose is to amplify developer intent at every stage of the coding process.

Think of it this way: DevOps automated the mechanical aspects of software delivery—building, testing, deploying. Continuous AI automates the intelligence aspects—understanding context, making suggestions, adapting to patterns, and learning from developer feedback.

## Why Continuous AI Matters Now

The same market forces that made DevOps inevitable are now driving Continuous AI adoption:

<CardGroup>
  <Card title="Developer Behavior is Shifting" icon="chart-line">
    Engineering teams are rapidly adopting AI tools, with many seeing
    significant productivity improvements in their workflows.
  </Card>

  <Card title="Economic Pressure" icon="dollar-sign">
    AI-assisted coding is contributing measurable increases in developer output,
    creating competitive advantages for early adopters.
  </Card>

  <Card title="Tooling Maturity" icon="wrench">
    Unlike DevOps, Continuous AI can be implemented incrementally on existing
    development stacks without major infrastructure changes.
  </Card>
</CardGroup>

The teams that implement systematic AI workflows first create advantages that compound over time.

## The Continuous AI Maturity Model

Teams typically progress through three stages when adopting Continuous AI:

<Accordion title="Level 1: Manual AI Assistance">
  You prompt the AI when you remember, and it completes the task. This is great for quick productivity boosts but remains highly manual and inconsistent.

  **Example**: Using AI to draft a function or suggest a test case only when you think to ask for it.

  **Gobi Implementation**: Using [Chat](/ide-extensions/chat/quick-start) or [Edit](/ide-extensions/edit/quick-start) mode for one-off coding tasks.
</Accordion>

<Accordion title="Level 2: Workflow Automation">
  AI handles routine tasks with human oversight. This is where teams start seeing compounding gains.

  **Examples**:

  * AI adds missing documentation during PR review
  * Automatic code formatting and style corrections
  * Generated unit tests for new functions
  * Updated issue tracking when branches are merged

  **Gobi Implementation**: Using [Gobi CLI](/guides/cli) with custom rules and integrations into CI/CD pipelines.
</Accordion>

<Accordion title="Level 3: Zero-Intervention Workflows">
  AI autonomously completes processes end-to-end without human input, but only for very specific, low-risk workflows.

  **Examples**:

  * AI merges safe dependency updates after automated tests pass
  * Automatic documentation updates when code changes
  * Self-healing test suites that fix themselves based on failure patterns

  **Gobi Implementation**: Fully automated [agents](/ide-extensions/agent/quick-start) with strict permissions and safety guardrails.
</Accordion>

## Building Your Continuous AI Workflow

### Start with Level 1 → Level 2: Pick One Workflow

Don't try to automate everything at once. Choose a specific daily friction point:

```bash  theme={null}
# Example: Automated code review comments
git diff | cn -p "review this diff and suggest improvements following our team standards"

# Example: Generate missing tests
cn -p "create unit tests for the functions in src/auth.js"

# Example: Update documentation
cn -p "update the README with the new API endpoints from the recent changes"
```

### Configure Team-Wide Intelligence

The most effective Continuous AI is tuned to your codebase, standards, and practices:

```yaml config.yaml theme={null}
rules:
  - name: code-review
    description: "Review code following team standards"
    rule: "Review following our TypeScript style guide and security practices"
    context:
      - "docs/style-guide.md"
      - "security-checklist.md"
```

### Implement Progressive Permissions

Use Gobi CLI's permission system to gradually expand AI capabilities:

```yaml ~/.gobi/permissions.yaml theme={null}
permissions:
  - allow: "Bash(git*)" # Git commands are safe
  - ask: "Write(**/*.ts)" # Ask before modifying TypeScript files
  - deny: "Bash(rm*)" # Never allow deletions
```

### Measure What Matters: Intervention Rate

Track how often you need to correct AI output. Lower intervention rates mean higher trust and compounding productivity gains.

## Real-World Implementation Patterns

<AccordionGroup>
  <Accordion title="Pattern 1: The Async Triage Bot">
    Imagine setting up an AI agent that checks new GitHub issues every morning and leaves the first helpful response. This lightens the load for maintainers and ensures community members feel heard quickly.
  </Accordion>

  <Accordion title="Pattern 2: The PR Review Agent">
    AI can automatically review new pull requests for security, performance, and style issues. The reviewer still has the final say, but the agent highlights common problems and speeds up the feedback loop.
  </Accordion>

  <Accordion title="Pattern 3: The Documentation Guardian">
    Whenever code changes, AI can scan for mismatches in documentation and suggest updates. This keeps docs current without relying on developers to remember every detail.
  </Accordion>
</AccordionGroup>

## Best Practices for Sustainable Continuous AI

<CardGroup>
  <Card title="Human-AI Collaboration" icon="handshake">
    AI should amplify human intelligence, not replace it. Always validate AI
    suggestions rather than blindly accepting them.
  </Card>

  <Card title="Start Small, Scale Thoughtfully" icon="seedling">
    Begin with low-risk, high-value automations. Gradually expand as you build
    trust and understanding.
  </Card>

  <Card title="Customize for Your Context" icon="cog">
    Generic AI suggestions are often wrong or irrelevant. Configure AI to
    understand your specific patterns and requirements.
  </Card>

  <Card title="Build Safety Guardrails" icon="shield">
    Use permission systems, code review processes, and testing to ensure AI
    actions are safe and reversible.
  </Card>
</CardGroup>

## Common Pitfalls to Avoid

<Warning>
  **Over-automation**: Don't automate processes you don't fully understand
</Warning>

<Warning>
  **Ignoring Context**: AI works best when it understands your codebase and team
  practices
</Warning>

<Warning>
  **Skipping Safety**: Always implement proper permissions and review processes
</Warning>

<Warning>
  **Vanity Metrics**: Focus on intervention rate and actual time saved, not "AI
  suggestions generated"
</Warning>

## Getting Started Today

<Steps>
  <Step title="Install Gobi CLI">
    `bash npm i -g @gourmanddev/cli `
  </Step>

  <Step title="Pick One Workflow">Choose a daily friction point to automate</Step>

  <Step title="Set Permissions">Configure safe boundaries for AI actions</Step>

  <Step title="Measure Impact">Track intervention rates and time saved</Step>

  <Step title="Iterate and Expand">Gradually add more automated workflows</Step>
</Steps>

## The Competitive Advantage

Teams implementing Continuous AI are coding faster and building institutional intelligence that scales with their organization. While others manually perform routine tasks, your AI handles the repetitive work so your team can focus on innovation and complex problem-solving.

## What's Next?

As AI capabilities gobi to improve and tooling matures, we're moving toward a world where intelligent assistance is as fundamental to development as version control or IDEs. The teams that start building these capabilities now will have refined systems, cultural readiness, and institutional knowledge when Continuous AI becomes the industry standard.

Ready to amplify your development workflow with Continuous AI? Start with one simple automation and build from there.

<Card title="Want to dive deeper?" icon="rocket">
  Check out our guides on [Gobi CLI](/guides/cli) and [Understanding
  Configs](/guides/understanding-configs).
</Card>


# Assessing Your Team's Readiness for Continuous AI
Source: https://docs.gourmand.dev/guides/continuous-ai-readiness-assessment

Complete framework to evaluate team readiness for Continuous AI adoption with maturity levels, assessment criteria, and implementation roadmap.

<Info>
  **TL;DR:** Use this assessment framework to determine if your team is ready to
  move from individual AI tool usage to automated Continuous AI workflows.
  Covers technical infrastructure, processes, culture, and organizational
  support.
</Info>

## Assessing Continuous AI Readiness

Continuous AI can dramatically improve development velocity and code quality, but successful implementation requires careful evaluation across four key dimensions.

<Warning>
  Rushing into Continuous AI without proper foundations leads to frustration and
  failed initiatives. Use this framework to identify gaps before scaling.
</Warning>

### 1. Identify Your Current Maturity Level

Determine where your team falls on the Continuous AI maturity spectrum:

<CardGroup cols={1}>
  <Card title="Level 1: Manual AI Assistance" icon="user">
    Developers use AI tools inconsistently with highly variable results.

    **Characteristics:**

    * High rejection rates of AI-generated code (>50%)
    * No shared standards or prompting rules
    * AI tools lack context about your codebase
    * Ad-hoc usage without team coordination
  </Card>

  <Card title="Level 2: Workflow Automation" icon="gear">
    AI is systematically integrated into team workflows and CI/CD pipelines.

    **Characteristics:**

    * Consistent adoption across 80%+ of team members
    * AI integrated into code reviews and deployment processes
    * Documented standards for prompts and tool usage
    * Basic metrics tracking AI impact
  </Card>

  <Card title="Level 3: Zero-Intervention Workflows" icon="robot">
    Certain development processes run autonomously with minimal human oversight.

    **Characteristics:**

    * Human intervention rates below 15%
    * Robust monitoring and automated rollback systems
    * Measurable ROI from automation initiatives
    * Advanced context awareness and learning loops
  </Card>
</CardGroup>

### 2. Evaluate Readiness Across Four Key Dimensions

Assess your team's strengths and potential risks across these critical areas:

<AccordionGroup>
  <Accordion title="Technical Infrastructure Assessment">
    **Key Questions:**

    * Do our development tools integrate reliably?
    * Can we measure AI effectiveness and impact?
    * Are security policies compatible with AI workflows?

    **🟢 Green Flags:**

    * Stable tool integrations with >99.5% uptime
    * Comprehensive monitoring and observability
    * Security policies that support AI tool usage
    * Automated testing and deployment pipelines

    **🔴 Red Flags:**

    * Frequent integration breakdowns
    * No performance tracking or metrics
    * Restrictive security policies blocking AI tools
    * Manual deployment processes
  </Accordion>

  <Accordion title="Process Maturity Assessment">
    **Key Questions:**

    * Are our development workflows consistent and documented?
    * Do we have quality gates and review processes?
    * Can we reproduce builds and deployments reliably?

    **🟢 Green Flags:**

    * Clear coding standards and style guides
    * Automated CI/CD with quality gates
    * Documented, repeatable processes
    * Consistent code review practices

    **🔴 Red Flags:**

    * Inconsistent code reviews
    * Ad-hoc deployment processes
    * "Works on my machine" culture
    * Undocumented tribal knowledge
  </Accordion>

  <Accordion title="Team Culture & Skills Assessment">
    **Key Questions:**

    * Are developers open to adopting new AI-powered workflows?
    * How does the team handle experimentation and failure?
    * Do team members collaborate effectively on new initiatives?

    **🟢 Green Flags:**

    * High curiosity and willingness to experiment
    * Collaborative problem-solving culture
    * Constructive feedback and learning mindset
    * Active knowledge sharing practices

    **🔴 Red Flags:**

    * Strong resistance to workflow changes
    * Blame culture around mistakes
    * Perfectionism blocking experimentation
    * Siloed work with minimal collaboration
  </Accordion>

  <Accordion title="Organizational Support Assessment">
    **Key Questions:**

    * Does leadership provide budget and resources for AI initiatives?
    * Is there tolerance for experimentation and learning?
    * Are expectations realistic for ROI timelines?

    **🟢 Green Flags:**

    * Executive buy-in and strategic alignment
    * Dedicated budget for training and tools
    * 3-6 month ROI expectations
    * Support for calculated risk-taking

    **🔴 Red Flags:**

    * Pressure for immediate ROI (weeks)
    * No allocated budget for AI initiatives
    * High risk aversion culture
    * Lack of leadership engagement
  </Accordion>
</AccordionGroup>

### 3. Critical Warning Signs

<Warning>
  **Stop and address these issues before scaling Continuous AI:**
</Warning>

<CardGroup cols={2}>
  <Card title="Technical Red Flags" icon="triangle-exclamation">
    * Builds breaking regularly (>5% failure rate)
    * Unstable deployments or rollback frequency >10%
    * No monitoring or observability systems
    * Critical security policy conflicts
  </Card>

  <Card title="Team & Culture Red Flags" icon="users-slash">
    * More than 30% of team opposed to AI tools
    * No established feedback or learning culture
    * History of failed automation initiatives
    * Resistance to changing existing workflows
  </Card>

  <Card title="Process Red Flags" icon="exclamation-triangle">
    * Inconsistent development workflows
    * No quality gates or review processes
    * Manual deployment and testing processes
    * Lack of documentation and standards
  </Card>

  <Card title="Organizational Red Flags" icon="building">
    * Leadership expecting ROI in weeks vs months
    * No allocated budget for AI initiatives
    * High pressure, low experimentation tolerance
    * Lack of strategic alignment on AI adoption
  </Card>
</CardGroup>

### 4. Implementation Roadmap

Based on your assessment results, follow this step-by-step approach:

<Steps>
  <Step title="Establish Baseline Metrics">
    Document current performance across key areas:

    * Development velocity (story
      points, cycle time)
    * Code quality metrics (bug rates, technical debt)
    * Review times and approval rates
    * Developer satisfaction and productivity
      scores
  </Step>

  <Step title="Select Initial Automation Target">
    Choose one high-impact, low-risk workflow to automate first:

    * **Code Review:** Automated analysis and suggestions
    * **Documentation:** Auto-generated API docs and README updates
    * **Testing:** Automated test generation and maintenance
    * **Refactoring:** Systematic code improvement suggestions
  </Step>

  <Step title="Standardize Team AI Usage">
    Create and document consistent practices:

    * AI tool selection and configuration guidelines

    * Prompting standards and best practices

    * Quality gates and review processes

    * Security and compliance requirements
  </Step>

  <Step title="Pilot and Measure Impact">
    Run controlled experiments with success criteria:

    * Start with 2-3 team members for 2-4 weeks
    * Track metrics against baseline performance
    * Gather qualitative feedback on developer experience
    * Document lessons learned and optimization opportunities
  </Step>

  <Step title="Scale Deliberately">
    Expand successful pilots across the organization:

    * Roll out to additional team members gradually
    * Implement monitoring and alerting systems
    * Establish feedback loops for continuous improvement
    * Plan next automation targets based on results
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="Building Async Agents with Gobi CLI" icon="blog" href="https://blog.gourmand.dev/building-async-agents-with-gobi-cli/">
    Comprehensive explanation of maturity levels and organizational readiness
    factors
  </Card>

  <Card title="Developer's Guide" icon="book" href="https://docs.gourmand.dev/guides/continuous-ai">
    Technical implementation details and best practices for Continuous AI
    workflows
  </Card>
</CardGroup>

## Quick Assessment Checklist

<Tip>
  **Ready to get started?** Use this quick checklist to gauge your immediate
  readiness:
</Tip>

**Technical Foundation (Score: \_\_\_/4)**

* Stable CI/CD pipelines with \<5% failure rate
* Monitoring and observability systems in place
* Security policies support AI tool integration
* Development environment standardization

**Process Maturity (Score: \_\_\_/4)**

* Documented coding standards and review processes
* Consistent deployment and rollback procedures
* Quality gates and automated testing
* Regular retrospectives and process improvement

**Team Culture (Score: \_\_\_/4)**

* \<30% resistance to AI tool adoption
* Active experimentation and learning culture
* Collaborative problem-solving approach
* Constructive feedback and knowledge sharing

**Organizational Support (Score: \_\_\_/4)**

* Leadership buy-in and strategic alignment
* Dedicated budget for AI initiatives and training
* 3-6 month ROI expectations (not weeks)
* Support for calculated risk-taking

***

**Overall Readiness Score: \_\_\_/16**

* **12-16:** Ready to begin Continuous AI implementation
* **8-11:** Address gaps in 1-2 areas before scaling
* **\<8:** Focus on foundational improvements first


# How to Build Custom Code RAG
Source: https://docs.gourmand.dev/guides/custom-code-rag

Build a custom retrieval-augmented generation (RAG) system for faster and more cost-efficient code search across large codebases. This guide is for advanced users who need to index code a single time across all users or include custom logic.

## Step 1: How to Choose an Embeddings Model

If possible, we recommend using [`voyage-code-3`](https://docs.voyageai.com/docs/embeddings), which will give the most accurate answers of any existing embeddings model for code. You can obtain an API key [here](https://dash.voyageai.com/api-keys). Because their API is [OpenAI-compatible](https://docs.voyageai.com/reference/embeddings-api), you can use any OpenAI client by swapping out the URL.

## Step 2: How to Choose a Vector Database

There are a number of available vector databases, but because most vector databases will be able to performantly handle large codebases, we would recommend choosing one for ease of setup and experimentation.

[LanceDB](https://lancedb.github.io/lancedb/basic/) is a good choice for this because it can run in-memory with libraries for both Python and Node.js. This means that in the beginning you can focus on writing code rather than setting up infrastructure. If you have already chosen a vector database, then using this instead of LanceDB is also a fine choice.

## Step 3: How to Choose a "Chunking" Strategy

Most embeddings models can only handle a limited amount of text at once. To get around this, we "chunk" our code into smaller pieces.

If you use `voyage-code-3`, it has a maximum context length of 16,000 tokens, which is enough to fit most files. This means that in the beginning you can get away with a more naive strategy of truncating files that exceed the limit. In order of easiest to most comprehensive, 3 chunking strategies you can use are:

1. Truncate the file when it goes over the context length: in this case you will always have 1 chunk per file.
2. Split the file into chunks of a fixed length: starting at the top of the file, add lines in your current chunk until it reaches the limit, then start a new chunk.
3. Use a recursive, abstract syntax tree (AST)-based strategy: this is the most exact, but most complex. In most cases you can achieve high quality results by using (1) or (2), but if you'd like to try this you can find a reference example in [our code chunker](https://github.com/gourmand/gobi/blob/main/core/indexing/chunk/code.ts) or in [LlamaIndex](https://docs.llamaindex.ai/en/stable/api_reference/node_parsers/code/).

As usual in this guide, we recommend starting with the strategy that gives 80% of the benefit with 20% of the effort.

## Step 4: How to Put Together an Indexing Script

Indexing, in which we will insert your code into the vector database in a retrievable format, happens in three steps:

1. Chunking
2. Generating embeddings
3. Inserting into the vector database

With LanceDB, we can do steps 2 and 3 simultaneously, as demonstrated [in their docs](https://lancedb.github.io/lancedb/basic/#using-the-embedding-api). If you are using Voyage AI for example, it would be configured like this:

```
from lancedb.pydantic import LanceModel, Vectorfrom lancedb.embeddings import get_registrydb = lancedb.connect("/tmp/db")func = get_registry().get("openai").create(    name="voyage-code-3",    base_url="https://api.voyageai.com/v1/",    api_key=os.environ["VOYAGE_API_KEY"],)class CodeChunks(LanceModel):    filename: str    text: str = func.SourceField()    # 1024 is the default dimension for `voyage-code-3`: https://docs.voyageai.com/docs/embeddings#model-choices    vector: Vector(1024) = func.VectorField()table = db.create_table("code_chunks", schema=CodeChunks, mode="overwrite")table.add([    {"text": "print('hello world!')", filename: "hello.py"},    {"text": "print('goodbye world!')", filename: "goodbye.py"}])query = "greetings"actual = table.search(query).limit(1).to_pydantic(CodeChunks)[0]print(actual.text)
```

<Check>
  If you are indexing more than one repository, it is best to store these in
  separate "tables" (terminology used by LanceDB) or "collections" (terminology
  used by some other vector DBs). The alternative of adding a "repository" field
  and then filtering by this is less performant.
</Check>

Regardless of which database or model you have chosen, your script should iterate over all of the files that you wish to index, chunk them, generate embeddings for each chunk, and then insert all of the chunks into your vector database.

## Step 5: How to Run Your Indexing Script

<Check>
  In a perfect production version, you would want to build "automatic, incremental indexing", so that you whenever a file changes, that file and nothing else is automatically re-indexed. This has the benefits of perfectly up-to-date embeddings and lower cost.

  That said, we highly recommend first building and testing the pipeline before attempting this. Unless your codebase is being entirely rewritten frequently, an incremental refresh of the index is likely to be sufficient and reasonably cheap.
</Check>

At this point, you've written your indexing script and tested that you can make queries from your vector database. Now, you'll want a plan for when to run the indexing script.

In the beginning, you should probably run it by hand. Once you are confident that your custom RAG is providing value and is ready for the long-term, then you can set up a cron job to run it periodically. Because codebases are largely unchanged in short time frames, you won't want to re-index more than once a day. Once per week or month is probably even sufficient.

## Step 6: How to set up an MCP server

To integrate your custom RAG system with Gobi, you'll create an MCP (Model Context Protocol) server. MCP provides a standardized way for AI tools to access external resources.

### Create your MCP server

Here's a reference implementation using Python that queries your vector database:

```python  theme={null}
"""Custom RAG MCP server for code retrieval"""
import asyncio
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
import lancedb

# Initialize your vector database connection
db = lancedb.connect("/path/to/your/db")
table = db.open_table("code_chunks")

app = Server("custom-rag-server")

@app.tool()
async def search_codebase(query: str, limit: int = 10) -> list[TextContent]:
    """
    Search the codebase using vector similarity.
    
    Args:
        query: The search query
        limit: Maximum number of results to return
    """
    # Query your vector database
    results = table.search(query).limit(limit).to_list()
    
    # Format results for Gobi
    formatted_results = []
    for result in results:
        formatted_results.append(TextContent(
            type="text",
            text=f"File: {result['filename']}\n\n{result['text']}"
        ))
    
    return formatted_results

@app.tool()
async def get_file_context(filename: str) -> list[TextContent]:
    """
    Get all chunks from a specific file.
    
    Args:
        filename: The name of the file to retrieve
    """
    results = table.where(f"filename = '{filename}'").to_list()
    
    return [TextContent(
        type="text",
        text="\n".join([r['text'] for r in results])
    )]

if __name__ == "__main__":
    stdio_server(app).run()
```

### Configure Gobi to use your MCP server

Add your MCP server to Gobi's configuration:

**config.yaml:**

```yaml  theme={null}
mcpServers:
  - name: custom-rag
    command: python
    args:
      - /path/to/your/mcp_server.py
    env:
      VOYAGE_API_KEY: ${VOYAGE_API_KEY}
```

**config.json:**

```json  theme={null}
{
  "mcpServers": [
    {
      "name": "custom-rag",
      "command": "python",
      "args": ["/path/to/your/mcp_server.py"],
      "env": {
        "VOYAGE_API_KEY": "${VOYAGE_API_KEY}"
      }
    }
  ]
}
```

## Step 7 (Bonus): How to Set Up Reranking

If you'd like to improve the quality of your results, a great first step is to add reranking. This involves retrieving a larger initial pool of results from the vector database, and then using a reranking model to order them from most to least relevant. This works because the reranking model can perform a slightly more expensive calculation on the small set of top results, and so can give a more accurate ordering than similarity search, which has to search over all entries in the database.

If you wish to return 10 total results for each query for example, then you would:

1. Retrieve \~50 results from the vector database using similarity search
2. Send all of these 50 results to the reranker API along with the query in order to get relevancy scores for each
3. Sort the results by relevancy score and return the top 10

We recommend using the `rerank-2` model from Voyage AI, which has examples of usage [here](https://docs.voyageai.com/docs/reranker).


# Building Data Pipelines with dlt MCP and Gobi
Source: https://docs.gourmand.dev/guides/dlt-mcp-gobi-cookbook

Set up an AI-powered data engineering workflow that helps you develop, debug, and inspect dlt data pipelines using natural language commands.

<Card title="What You'll Build" icon="database">
  An AI-powered data pipeline development system that uses Gobi's AI agent with dlt
  MCP to inspect pipeline execution, retrieve schemas, analyze datasets, and debug load errors - all through simple natural language prompts
</Card>

## Prerequisites

Before starting, ensure you have:

* Gobi account with **Hub access**
  * Read: [Understanding Configs — How to get started with Hub configs](/guides/understanding-configs#how-to-get-started-with-hub-configs)
* Python 3.8+ installed locally
* A dlt pipeline project (or create one during this guide)
* Basic understanding of data pipelines

For all options, first:

<Steps>
  <Step title="Install Gobi CLI">
    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```
  </Step>

  <Step title="Install dlt">
    ```bash  theme={null}
    pip install dlt
    ```
  </Step>
</Steps>

<Warning>
  To use agents in headless mode, you need a [Gobi API key](https://hub.gourmand.dev/settings/api-keys).
</Warning>

## dlt MCP Workflow Options

<Card title="🚀 Fastest Path to Success" icon="zap">
  Skip the manual setup and use our pre-built [dlt Assistant agent](https://hub.gourmand.dev/dlthub/dlt-assistant) that includes
  the dlt MCP and optimized data pipeline workflows for more consistent results. You can [remix this agent](/guides/understanding-configs#how-to-get-started-with-hub-configs) to customize it for your specific needs.
</Card>

After ensuring you meet the **Prerequisites** above, you have two paths to get started:

<Tabs>
  <Tab title="⚡ Quick Start (Recommended)">
    <Steps>
      <Step title="Load the Pre-Built Agent">
        Navigate to your pipeline project directory and run:

        ```bash  theme={null}
        cn --config dlthub/dlt-assistant
        ```

        This agent includes:

        * **dlt MCP** pre-configured and ready to use
        * **Pipeline-focused rules** for data engineering best practices
      </Step>

      <Step title="Run Your First Pipeline Inspection">
        Start with a comprehensive pipeline check:

        ```bash  theme={null}
        # TUI mode
        Inspect the execution of my dlt pipeline and summarize the load info, including timing and file sizes.
        ```

        That's it! The agent handles everything automatically.
      </Step>
    </Steps>

    <Info>
      **Why Use the Agent?** The pre-built [dlt Assistant agent](https://hub.gourmand.dev/dlthub/dlt-assistant) provides consistent pipeline development workflows and handles MCP configuration automatically, making it easier to get started with AI-powered data engineering. You can [remix and customize this agent](/guides/understanding-configs#how-to-get-started-with-hub-configs) later to fit your team's specific workflow.
    </Info>
  </Tab>

  <Tab title="🛠️ Manual Setup">
    <Steps>
      <Step title="Create a New Agent via the Gobi Hub">
        Go to the [Gobi Hub](https://hub.gourmand.dev) and [create a new agent](https://hub.gourmand.dev/new?type=agent).
      </Step>

      <Step title="Connect dlt MCP via Gobi Hub">
        Visit the [dlt MCP on Gobi Hub](https://hub.gourmand.dev/dlthub/dlt-mcp) and click **Install** to add it to the agent you created in the step above.

        This will add dlt MCP to your agent's available tools. The Hub listing automatically configures the MCP command.

        <Tip>
          **Alternative installation methods:**

          1. **Quick CLI install**: `cn --mcp dlthub/dlt-mcp`
          2. **Manual configuration**: Add the MCP to your `~/.gobi/config.json` under the `mcpServers` section

          Once installed, dlt MCP tools become available to your Gobi agent for all prompts.
        </Tip>

        <Info>
          The MCP will work with your existing dlt pipelines in your current directory.
        </Info>
      </Step>

      <Step title="Run Your First Pipeline Inspection">
        Start with a comprehensive pipeline check:

        ```bash  theme={null}
        # TUI mode
        cn
        # Then type: Inspect the execution of my dlt pipeline and summarize the load info, including timing and file sizes.
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Accordion title="Agent Requirements">
  To use the pre-built [dlt Assistant agent](https://hub.gourmand.dev/dlthub/dlt-assistant), you need either:

  * **Gobi CLI Pro Plan** with the models add-on, OR
  * **Your own API keys** added to Gobi Hub secrets (same as manual setup)

  The agent will automatically detect and use your configuration along with the pre-configured dlt MCP for pipeline operations.
</Accordion>

***

## dlt MCP vs dlt+ MCP

<Card title="Understanding the Difference" icon="info-circle">
  **dlt MCP** is focused on local pipeline development and inspection. It provides tools to:

  * Inspect pipeline execution and load information
  * Retrieve schema metadata from your local pipelines
  * Query dataset records from destination databases
  * Analyze load errors, timings, and file sizes

  **[dlt+ MCP](https://hub.gourmand.dev/dlthub/dlt-plus-mcp)** extends these capabilities with cloud-based features for production deployments:

  * Connect to dlt+ Projects and manage deployments
  * Monitor pipeline runs across multiple environments
  * Access centralized logging and observability
  * Collaborate with team members on pipeline development

  For local development and getting started, **[dlt MCP](https://hub.gourmand.dev/dlthub/dlt-mcp)** is the right choice. Consider **[dlt+ MCP](https://hub.gourmand.dev/dlthub/dlt-plus-mcp)** when you need production deployment features and team collaboration.
</Card>

***

## Pipeline Development Recipes

Now you can use natural language prompts to develop and debug your dlt pipelines. The Gobi agent automatically calls the appropriate dlt MCP tools.

<Info>
  You can add prompts to your agent's configuration for easy access in future sessions. Go to your agent in the [Gobi Hub](https://hub.gourmand.dev), click **Edit**, and add prompts under the **Prompts** section.
</Info>

<Info>
  **Where to run these workflows:**

  * **IDE Extensions**: Use Gobi in VS Code, JetBrains, or other supported IDEs
  * **Terminal (TUI mode)**: Run `cn` to enter interactive mode, then type your prompts
  * **CLI (headless mode)**: Use `cn -p "your prompt"` for headless commands

  **Test in Plan Mode First**: Before running pipeline operations that might make
  changes, test your prompts in plan mode (see the [Plan Mode
  Guide](/guides/plan-mode-guide); press **Shift+Tab** to switch modes in TUI/IDE). This
  shows you what the agent will do without executing it.
</Info>

<Info>
  **About the --auto flag**: The `--auto` flag enables tools to run continuously without manual confirmation. This is essential for headless mode where the agent needs to execute multiple tools automatically to complete tasks like pipeline inspection, schema retrieval, and error analysis.
</Info>

### Pipeline Inspection

<Card title="Inspect Pipeline Execution" icon="magnifying-glass">
  Review pipeline execution details including load timing and file sizes.

  **TUI Mode Prompt:**

  ```
  Inspect my dlt pipeline execution and provide a summary of the load info.
  Show me the timing breakdown and file sizes for each table.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Inspect my dlt pipeline execution and provide a summary of the load info. Show me the timing breakdown and file sizes for each table." --auto
  ```
</Card>

### Schema Management

<Card title="Retrieve Schema Metadata" icon="diagram-project">
  Get detailed schema information for your pipeline's tables.

  **TUI Mode Prompt:**

  ```
  Show me the schema for my users table including all columns,
  data types, and any constraints.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Show me the schema for my users table including all columns, data types, and any constraints." --auto
  ```
</Card>

### Data Exploration

<Card title="Query Dataset Records" icon="table">
  Retrieve and analyze records from your destination database.

  **TUI Mode Prompt:**

  ```
  Get the last 10 records from my orders table and show me
  the distribution of order statuses.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Get the last 10 records from my orders table and show me the distribution of order statuses." --auto
  ```
</Card>

### Error Debugging

<Card title="Analyze Load Errors" icon="triangle-exclamation">
  Investigate and understand pipeline load errors.

  **TUI Mode Prompt:**

  ```
  Check for any load errors in my last pipeline run. If there are errors,
  explain what went wrong and suggest fixes.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Check for any load errors in my last pipeline run. If there are errors, explain what went wrong and suggest fixes." --auto
  ```
</Card>

### Pipeline Creation

<Card title="Build New Pipeline" icon="plus">
  Create a new dlt pipeline from an API or data source.

  **TUI Mode Prompt:**

  ```
  Help me create a new dlt pipeline that loads data from the
  JSONPlaceholder API users endpoint into DuckDB.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Help me create a new dlt pipeline that loads data from the JSONPlaceholder API users endpoint into DuckDB." --auto
  ```
</Card>

### Schema Evolution

<Card title="Handle Schema Changes" icon="code-branch">
  Review and manage schema evolution in your pipelines.

  **TUI Mode Prompt:**

  ```
  Check if my pipeline schema has evolved since the last run.
  Show me what columns were added or modified.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Check if my pipeline schema has evolved since the last run. Show me what columns were added or modified." --auto
  ```
</Card>

## Continuous Data Pipelines with GitHub Actions

This example demonstrates a **Continuous AI workflow** where data pipeline validation runs automatically in your CI/CD pipeline in headless mode using the [dlt Assistant agent](https://hub.gourmand.dev/dlthub/dlt-assistant). Consider [remixing this agent](/guides/understanding-configs#how-to-get-started-with-hub-configs) to add your organization's specific validation rules.

### Add GitHub Secrets

Navigate to **Repository Settings → Secrets and variables → Actions** and add:

* `GOBI_API_KEY`: Your Gobi API key from [hub.gourmand.dev/settings/api-keys](https://hub.gourmand.dev/settings/api-keys)
* Any required database credentials for your destination

<Info>
  The workflow uses the pre-built [dlt Assistant agent](https://hub.gourmand.dev/dlthub/dlt-assistant) with `--agent dlthub/dlt-assistant`. This agent comes pre-configured with the dlt MCP and optimized rules for pipeline operations. You can [remix this agent](/guides/understanding-configs#how-to-get-started-with-hub-configs) to customize the validation rules and prompts for your specific pipeline requirements.
</Info>

### Create Workflow File

This workflow automatically validates your dlt data pipelines on pull requests using the Gobi CLI in [headless mode](/cli/overview#headless-mode%3A-production-automation). It inspects pipeline schemas, checks for errors, and posts a summary report as a PR comment. The workflow can also be triggered manually via `workflow_dispatch`.

Create `.github/workflows/dlt-pipeline-validation.yml` in your repository:

```yaml  theme={null}
name: Data Pipeline Validation with dlt MCP

on:
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  validate-pipeline:
    runs-on: ubuntu-latest
    env:
      GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"

      - name: Install dlt
        run: |
          pip install dlt
          echo "✅ dlt installed"

      - name: Install Gobi CLI
        run: |
          npm install -g @gourmanddev/cli
          echo "✅ Gobi CLI installed"

      - name: Validate Pipeline Schema
        run: |
          echo "🔍 Validating pipeline schema..."
          cn --config dlthub/dlt-assistant \
             -p "Inspect the pipeline schema and verify all required tables
                 and columns are present. Flag any missing or unexpected changes." \
             --auto

      - name: Check Pipeline Health
        run: |
          echo "📊 Checking pipeline health..."
          cn --config dlthub/dlt-assistant \
             -p "Analyze the last pipeline run for errors or warnings.
                 Report any issues that need attention." \
             --auto

      - name: Comment Pipeline Report on PR
        if: always() && github.event_name == 'pull_request'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          REPORT=$(cn --config dlthub/dlt-assistant \
             -p "Generate a concise summary (200 words or less) of:
                 - Pipeline schemas and row counts
                 - Any load errors or warnings
                 - Performance metrics (timing, file sizes)
                 - Recommended improvements" \
             --auto)

          gh pr comment ${{ github.event.pull_request.number }} --body "$REPORT"
```

<Info>
  The dlt MCP works with your local pipeline state. Make sure your CI environment
  has access to the necessary pipeline configuration and credentials.
</Info>

## Pipeline Development Best Practices

Implement automated pipeline quality checks using Gobi's rule system. See the [Rules deep dive](/customize/deep-dives/rules) for authoring tips.

<Card title="Schema Validation" icon="check-circle">
  ```bash  theme={null}
  "Before committing pipeline changes, verify the schema
  matches expectations and flag any unexpected modifications."
  ```
</Card>

<Card title="Error Handling" icon="shield-exclamation">
  ```bash  theme={null}
  "When load errors occur, analyze the error details and
  suggest specific code fixes to handle the data issues."
  ```
</Card>

<Card title="Performance Monitoring" icon="gauge-high">
  ```bash  theme={null}
  "Track pipeline execution times and file sizes. Alert if
  performance degrades significantly from baseline."
  ```
</Card>

<Card title="Data Quality" icon="check-double">
  ```bash  theme={null}
  "After each pipeline run, validate row counts and check for
  null values in critical columns."
  ```
</Card>

## Troubleshooting

### Pipeline Not Found

```bash  theme={null}
"Check if there's a dlt pipeline in the current directory.
If not, help me initialize a new pipeline."
```

### Destination Connection Issues

```bash  theme={null}
"Verify the destination connection and credentials for my pipeline.
Test the connection and report any issues."
```

### Schema Inference Problems

<Check>
  **Verification Steps:**

  * dlt MCP is installed via [Gobi Hub](https://hub.gourmand.dev/dlthub/dlt-mcp)
  * Pipeline directory is accessible
  * Destination database credentials are configured
  * Pipeline has been run at least once
</Check>

## What You've Built

After completing this guide, you have a complete **AI-powered data pipeline development system** that:

✅ Uses natural language — Simple prompts instead of complex pipeline commands
✅ Debugs automatically — AI analyzes errors and suggests fixes
✅ Runs continuously — Automated validation in CI/CD pipelines
✅ Ensures quality — Pipeline checks prevent bad data from shipping

<Card title="Continuous AI" icon="rocket">
  Your data pipeline workflow now operates at **[Level 2 Continuous
  AI](https://blog.gourmand.dev/what-is-continuous-ai-a-developers-guide/)** -
  AI handles routine pipeline inspection and debugging with human oversight
  through review and approval of changes.
</Card>

## Next Steps

1. **Inspect your first pipeline** - Try the pipeline inspection prompt on your current project
2. **Debug load errors** - Use the error analysis prompt to fix any issues
3. **Set up CI pipeline** - Add the GitHub Actions workflow to your repo
4. **Create new pipelines** - Use AI to scaffold new data sources
5. **Monitor performance** - Track pipeline execution metrics over time

## Additional Resources

<CardGroup cols={2}>
  <Card title="dlt Documentation" icon="book" href="https://dlthub.com/docs">
    Complete dlt platform documentation
  </Card>

  <Card title="Gobi Hub" icon="plug" href="https://hub.gourmand.dev">
    Explore more MCP integrations and agents
  </Card>

  <Card title="dlt Blog: MCP Deep Dive" icon="newspaper" href="https://dlthub.com/blog/deep-dive-assistants-mcp-gobi">
    Learn about AI assistants, MCP, and Gobi integration
  </Card>

  <Card title="MCP Concepts" icon="puzzle-piece" href="https://dlthub.com/blog/deep-dive-assistants-mcp-gobi">
    Deep dive into dlt MCP integration
  </Card>
</CardGroup>


# Automating Documentation Updates with Gobi CLI
Source: https://docs.gourmand.dev/guides/doc-writing-agent-cli

Learn how to create automated documentation generation workflows using Gobi CLI. Set up AI agents to analyze code changes and generate or update documentation automatically in GitHub workflows or local development.

# Automating Documentation Updates with Gobi CLI

This guide demonstrates how to create automated documentation generation based on code updates in a git branch using the Gobi CLI, either as part of your local workflow or as part of a GitHub workflow.

This process utilizes the **Gobi CLI** (`cn`) in **headless mode** to analyze changes and generate the necessary documentation, and commit and push the changes. The goal is to keep the workflow as simple as possible by using straightforward shell commands, Gobi CLI prompts, and basic git operations.

## Why Use Gobi CLI for Documentation?

<CardGroup cols={2}>
  <Card title="Intelligent Analysis" icon="brain">
    AI agents understand your codebase and documentation patterns, analyzing git diffs to identify what needs documenting.
  </Card>

  <Card title="Automated Workflows" icon="robot">
    Integrate seamlessly into CI/CD pipelines or local development workflows with minimal setup.
  </Card>

  <Card title="Contextual Understanding" icon="files">
    Agents can read files, explore projects, and access Git history to generate accurate, relevant documentation.
  </Card>

  <Card title="Controlled Permissions" icon="shield">
    Restrict agent actions to specific files and operations, ensuring safe automated documentation updates.
  </Card>
</CardGroup>

## Prerequisites

<CardGroup cols={1}>
  <Card title="Node.js 18+" icon="node-js">
    Gobi CLI requires Node.js 18 or higher. Install globally with:

    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```
  </Card>

  <Card title="Gobi API Key" icon="key">
    Get your API key from [Gobi Hub](https://hub.gourmand.dev/settings/api-keys) and set:

    ```bash  theme={null}
    export GOBI_API_KEY=your_key_here
    ```

    <Info>
      You can use the Gobi CLI in headless mode without interactive login by setting the `GOBI_API_KEY` environment variable.
    </Info>
  </Card>

  <Card title="Git Repository" icon="code">
    A project with code and documentation, or use an open-source project to experiment with the workflow.
  </Card>
</CardGroup>

# Documentation Generation Workflow

## Workflow Overview

The documentation generation process follows these sequential steps:

<Steps>
  <Step title="Environment Setup">
    Validate environment, install Gobi CLI, and set up authentication with API keys.
  </Step>

  <Step title="Change Analysis">
    Generate git diff context and analyze code changes between branches to identify new functionality.
  </Step>

  <Step title="Branch Creation">
    Create a dedicated documentation branch following the pattern `{original-branch}-docs-update-{timestamp}`.
  </Step>

  <Step title="AI Documentation Generation">
    Use Gobi CLI with custom rules to analyze changes and generate or update documentation files.

    <Tip>
      Use an agent configuration with rules specific for documentation writing in your project and fine-tune it to work for your team's standards.
    </Tip>
  </Step>

  <Step title="Review & Commit">
    Review generated documentation, commit changes to the docs directory, and push to origin.
  </Step>

  <Step title="Cleanup">
    Remove temporary files and output completion summary with branch information.
  </Step>
</Steps>

## Implementation

<Tabs>
  <Tab title="GitHub Workflow">
    ### GitHub Actions Implementation

    <Info>
      This example uses a manual workflow dispatch that requires two inputs: the repository name and the branch containing your code changes. This is helpful when you want to generate documentation for a feature branch before creating a pull request.
    </Info>

    **Required Inputs:**

    * **repository:** The repository you are operating on (format: `owner/repo`)
    * **branch\_name:** The name of the branch you have code changes on and want to generate documentation for
    * **gobi\_config:** The Gobi agent configuration to use
      * Consider setting a default value if you have a default config your'd like to use
    * **gobi\_org:** The Gobi org to use
      * Consider setting a default value if you have a default org your'd like to use

    ```yaml title=".github/workflows/generate-docs.yml" theme={null}
    name: Generate Docs for Branch

    on:
      workflow_dispatch:
        inputs:
          repository:
            description: 'Repository (owner/repo)'
            required: true
            default: 'owner/repo'
          branch_name:
            description: 'Branch name to generate docs for'
            required: true
          gobi_config:
            description: 'Gobi agent configuration to use'
            required: true
            # Set a default value if you have a default config your'd like to use
            # default: 'agent-config-name'
          gobi_org:
            description: 'Gobi org to use'
            required: true
            # Set a default value if you have a default org your'd like to use
            # default: 'your-org-name'

    jobs:
      write-docs:
        runs-on: ubuntu-latest
        name: Write Documentation for Branch
        env:
          GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}
          GOBI_ORG: ${{ github.event.inputs.gobi_org }}
          GOBI_CONFIG: ${{ github.event.inputs.gobi_config }}

        steps:

        - name: Checkout fork repository
          uses: actions/checkout@v4
          with:
            repository: ${{ github.event.inputs.repository || 'owner/repo' }}
            token: ${{ secrets.GH_PAT }}
            fetch-depth: 0  # Full history needed for sync

        - name: Setup git configuration
          run: |
            git config user.name "github-actions[doc-writer-bot]"
            git config user.email "yourname@email.com"

        - name: Checkout target branch
          run: |
            git fetch origin ${{ github.event.inputs.branch_name }}
            git checkout ${{ github.event.inputs.branch_name }}

        - name: Setup Node.js
          uses: actions/setup-node@v4
          with:
            node-version: '18'

        - name: Install Gobi CLI
          run: |
            echo "Installing Gobi CLI..."
            npm i -g @gourmanddev/cli

        - name: Verify Gobi CLI installation
          run: |
            echo "Checking Gobi CLI version..."
            cn --version || exit 1

        - name: Set branch name
          id: branch
          run: |
            BRANCH_NAME="${{ github.event.inputs.branch_name }}-docs-update-$(date +%Y-%m-%d-%H-%M-%S)"
            echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
            echo "Branch name: $BRANCH_NAME"

        - name: Generate git diff context
          run: |
            echo "Git changes:" > context.txt
            git diff origin/main..HEAD --stat >> context.txt
            echo -e "\n\nFile list:" >> context.txt
            git diff origin/main..HEAD >> context.txt
            echo "Generated context file:"
            cat context.txt

        - name: Create documentation branch
          run: |
            echo "Creating branch: ${{ steps.branch.outputs.branch_name }}"
            git checkout -b "${{ steps.branch.outputs.branch_name }}"

        - name: Generate documentation with Gobi CLI
          run: |
            echo "Running Gobi agent to generate documentation..."
            cn --config <gobi-user>/<agent-config> \
               --auto \
               --allow Write \
               -p \
               --prompt ./context.txt \
               "Analyze the provided git diff and identify any new functionality introduced. Summarise the new features in a few sentences. Then search the existing documentation in the site docs/ directory to determine whether these features are already documented in a way that enables users to use them. If documentation is missing or incomplete, create or modify Markdown files under the site diretory (without changing any code) to add clear explanations, usage instructions and examples for the new features in the same style and format as the existing documentation. Finally, print a brief summary of the documentation changes you made."

        - name: Clean up temporary files
          run: rm -f context.txt

        - name: Commit and push documentation changes
          run: |
            echo "Review git status..."
            git status

            echo "Adding files edited in site directory to git..."
            git add site/

            echo "Committing changes..."
            git commit -s -m "docs: update for new functionality from branch ${{ github.event.inputs.branch_name }}"

            echo "Pushing changes to origin..."
            git push --set-upstream origin "${{ steps.branch.outputs.branch_name }}"

    ```
  </Tab>

  <Tab title="Local Development">
    ### Local Development Implementation

    <Warning>
      Make sure to set your `GOBI_API_KEY` environment variable before running local scripts to enable headless mode.
    </Warning>

    When using the Gobi CLI on your local machine, you can build workflows in various ways, one of which is by simply creating shell scripts that you can run, which call the CLI.

    The below shell script snippet shows the final part of a docs updating shell script that can be used to generate documentation for the code changes in a branch of a git repository.

    For the example snippet below to work you will need to set the following variables:

    * `GOBI_ORG`
    * `GOBI_CONFIG`
    * `BASE_BRANCH`
    * `COMPARE_BRANCH`
    * `DOCS_BRANCH_NAME`

    For example you can either set these as environment variables or as command line arguments to be used by the script.

    **Example shell script snippet for generating documentation**

    ```bash title="generate-docs.sh" theme={null}
    #!/bin/bash
    # The script below shows the final part of a docs updating shell script that can be used to generate documentation for the code changes in a branch of a git repository.

    # Generate git diff context
    echo "Generating git diff context..."
    echo "Git changes:" > context.txt
    git diff "$BASE_BRANCH..$COMPARE_BRANCH" --stat >> context.txt
    echo -e "\n\nFile list:" >> context.txt
    git diff "$BASE_BRANCH..$COMPARE_BRANCH" >> context.txt
    echo "Generated context file:"
    cat context.txt

    # Create documentation branch
    echo "Creating branch: $DOCS_BRANCH_NAME"
    git checkout -b "$DOCS_BRANCH_NAME"

    # Generate documentation with Gobi CLI
    echo "Running Gobi agent to generate documentation..."
    cn -config "$GOBI_ORG/$GOBI_CONFIG" \
       --auto \
       --allow Write \
       -p \
       --prompt ./context.txt \
       "Analyze the provided git diff and identify any new functionality introduced. Summarise the new features in a few sentences. Then search the existing documentation in the site docs/ directory to determine whether these features are already documented in a way that enables users to use them. If documentation is missing or incomplete, create or modify Markdown files under the site diretory (without changing any code) to add clear explanations, usage instructions and examples for the new features in the same style and format as the existing documentation. Finally, print a brief summary of the documentation changes you made."

    # Clean up temporary files
    echo "Cleaning up temporary files..."
    rm -f context.txt

    # Commit and push documentation changes
    echo "Reviewing git status..."
    git status

    # Only adding files that have been added and modified in the site directory
    echo "Adding files edited in site directory to git..."
    git add site/

    if git diff --cached --quiet; then
        echo "No documentation changes to commit"
    else
        echo "Committing changes..."
        git commit -s -m "docs: update for new functionality from branch $BRANCH_NAME"

        echo "Pushing changes to origin..."
        git push --set-upstream origin "$DOCS_BRANCH_NAME"

        echo "Documentation branch created and pushed: $DOCS_BRANCH_NAME"
    fi
    ```
  </Tab>
</Tabs>

## Enhancement Ideas

The workflow above is a basic example and can be enhanced in various ways to fit your needs. Here are some ideas:

<CardGroup cols={2}>
  <Card title="Change Analysis Agent" icon="magnifying-glass">
    Define a specialized agent for analyzing changes and generating targeted prompts for documentation writers, improving output quality.
  </Card>

  <Card title="Auto-Documentation on Merge" icon="code-compare">
    Create GitHub workflows that automatically generate documentation PRs when new features are merged to main.
  </Card>

  <Card title="Documentation Gap Analysis" icon="clipboard">
    Build an agent that reviews older merged PRs to identify undocumented features and generates missing documentation.
  </Card>

  <Card title="Copy Editor Agent" icon="pencil">
    Add a post-processing agent to enhance writing quality with rules like "use short sentences and simple words."
  </Card>
</CardGroup>

## Next Steps

Ready to implement automated documentation with Gobi CLI? Here are some helpful resources to get you started:

<CardGroup cols={2}>
  <Card title="Gobi CLI Guide" icon="terminal" href="/guides/cli">
    Learn the fundamentals of using Gobi CLI for automated coding tasks and headless workflows.
  </Card>

  <Card title="Understanding Configs" icon="robot" href="/guides/understanding-configs">
    Discover how to configure and customize AI configs for your specific documentation needs.
  </Card>

  <Card title="Video: Leverage AI to help with your docs" icon="video" href="https://www.youtube.com/watch?v=rJ2taa8OLvY">
    Checkout this video from Tetrate about using Gobi Agents to help with writing your docs.
  </Card>

  <Card title="Gobi Hub" icon="users" href="https://hub.gourmand.dev">
    Browse pre-built agents and configurations from the Gobi community.
  </Card>
</CardGroup>


# GitHub Issues and PRs with GitHub MCP and Gobi
Source: https://docs.gourmand.dev/guides/github-mcp-gobi-cookbook

Use Gobi and the GitHub MCP to list, summarize, and act on open issues and recently merged pull requests with natural language prompts.

<Card title="What You'll Build" icon="github">
  A GitHub workflow assistant that uses Gobi with the GitHub MCP to:

  * List, filter, and summarize open issues
  * Review and summarize recently merged PRs
  * Post comments with AI-generated summaries or checklists
  * Automate routine GitHub maintenance with headless CLI runs
</Card>

## Prerequisites

Before starting, ensure you have:

* Gobi account with **Hub access**
  * Read: [Understanding Configs — How to get started with Hub configs](/guides/understanding-configs#how-to-get-started-with-hub-configs)
* Node.js 22+ installed locally
* A GitHub account and a repository to work with
* A GitHub token with the appropriate scopes:
  * For read-only: `repo:read`
  * To comment on issues/PRs: `public_repo` for public repos or `repo` for private repos

For all options, first:

<Steps>
  <Step title="Install Gobi CLI">
    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```
  </Step>

  <Step title="Configure GitHub Token">
    Add your `GITHUB_TOKEN` to your [Gobi Hub agent's environment variables](https://hub.gourmand.dev/settings).
  </Step>
</Steps>

<Warning>
  To use agents in headless mode, you need a [Gobi API key](https://hub.gourmand.dev/settings/api-keys).
  For write actions (e.g., posting comments), your token must include the relevant GitHub scopes.
</Warning>

## GitHub MCP Workflow Options

<Card title="🚀 Fastest Path to Success" icon="rocket">
  Use the GitHub MCP from Gobi Hub for one-click setup, or add it via CLI.
</Card>

After ensuring you meet the **Prerequisites** above, you have two paths to get started:

<Tabs>
  <Tab title="⚡ Quick Start (Recommended)">
    <Steps>
      <Step title="Install GitHub MCP via Gobi Hub">
        Visit the [Anthropic GitHub MCP](https://hub.gourmand.dev/anthropic/github-mcp) on Gobi Hub and click **Install** to add it to your agent.

        The listing provides a pre-configured MCP block; add your `GITHUB_TOKEN` in Hub.
      </Step>

      <Step title="Launch the Agent">
        From your repo root:

        ```bash  theme={null}
        cn --config gourmand/github-manager-ai
        ```

        Now try: "List my open issues labeled bug and summarize priorities."
      </Step>
    </Steps>

    <Info>
      You can also attach an MCP to a one-off session: `cn --mcp anthropic/github-mcp`.
    </Info>
  </Tab>

  <Tab title="🛠️ Manual Setup">
    <Steps>
      <Step title="Create a New Agent on Gobi Hub">
        Go to the [Gobi Hub](https://hub.gourmand.dev) and [create a new agent](https://hub.gourmand.dev/new?type=agent).
      </Step>

      <Step title="Add GitHub MCP">
        Install from Hub (recommended) or add YAML manually. Minimal YAML example:

        ```yaml title="config.yaml" theme={null}
        mcpServers:
          - name: GitHub MCP
            command: npx
            args:
              - "-y"
              - "@modelcontextprotocol/server-github"
            env:
              GITHUB_TOKEN: ${env:GITHUB_TOKEN}
            connectionTimeout: 30
        ```

        Notes:

        * The exact `command`/`args` may differ based on the MCP you choose on Hub. Hub templates prefill these for you.
        * Provide `GITHUB_TOKEN` via environment or Hub secrets.
      </Step>

      <Step title="Test the Connection">
        Launch Gobi and ask:

        ```
        List the 5 most recently updated open issues in this repository.
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Accordion title="Agent Requirements">
  To use GitHub MCP with Gobi CLI, you need either:

  * **Gobi CLI Pro Plan** with the models add-on, OR
  * **Your own API keys** added to Gobi Hub secrets

  The agent will automatically detect and use your configuration along with the GitHub MCP for issue and PR operations.
</Accordion>

***

## Issue Workflows

Use natural language to explore, triage, and act on open issues. The agent calls GitHub MCP tools under the hood.

<Info>
  **Where to run these workflows:**

  * **IDE Extensions**: Use Gobi in VS Code, JetBrains, or other supported IDEs
  * **Terminal (TUI mode)**: Run `cn` to enter interactive mode, then type your prompts
  * **CLI (headless mode)**: Use `cn -p "your prompt" --auto` for automation
</Info>

### Triage and Summaries

<Card title="Summarize Open Issues" icon="clipboard-list">
  Get a prioritized overview of current open issues.

  **TUI Mode Prompt:**

  ```
  List the 20 most recently updated open issues in this repo.
  Cluster by label and severity. Summarize top priorities.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "List the 20 most recently updated open issues in this repo. Cluster by label and severity. Summarize top priorities." --auto
  ```
</Card>

<Card title="Owner/Label Filters" icon="filter">
  Narrow by label or assignee.

  **TUI Mode Prompt:**

  ```
  Show open issues labeled bug or security, assigned to @me.
  Summarize blockers and suggest next steps.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Show open issues labeled bug or security, assigned to @me. Summarize blockers and suggest next steps." --auto
  ```
</Card>

### Taking Action

<Card title="Comment on an Issue" icon="comment">
  Post an AI-generated status update or checklist.

  **TUI Mode Prompt:**

  ```
  Find the issue with the most engagement (comments, reactions) in the last 30 days.
  Come up with a triage plan and draft a comment with:
  - current hypothesis
  - next 2 steps
  - owner and ETA
  Then post the comment.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Find the issue with the most engagement in the last 30 days. Come up with a triage plan and draft a comment (hypothesis, next 2 steps, owner, ETA) and post it." --auto
  ```

  <Note>
    Requires a token with permission to comment (`public_repo` or `repo`). The agent will confirm before posting unless `--auto` is used.
  </Note>
</Card>

<Card title="Find Stale Issues" icon="clock">
  Identify issues that need attention.

  **TUI Mode Prompt:**

  ```
  Find open issues with no activity in the last 30 days.
  Suggest action (close, needs-repro, or prioritize) and draft comments.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Find open issues with no activity in the last 30 days. Suggest action and draft comments for each." --auto
  ```
</Card>

***

## Merged PR Workflows

Analyze recently merged PRs for change awareness, release notes, and quality signals.

### Recently Merged Overview

<Card title="Merged PR Digest" icon="code-merge">
  Summarize merged PRs over a time window.

  **TUI Mode Prompt:**

  ```
  List PRs merged in the last 7 days.
  Group by area (label or path). Summarize impact and notable changes.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "List PRs merged in the last 7 days. Group by area (label or path). Summarize impact and notable changes." --auto
  ```
</Card>

### Release Notes

<Card title="Generate Release Notes" icon="file-lines">
  Turn merged PRs into crisp release notes.

  **TUI Mode Prompt:**

  ```
  Generate release notes for PRs merged since tag v1.2.0.
  Use keep-a-changelog sections and include PR numbers/authors.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Generate release notes for PRs merged since tag v1.2.0. Use keep-a-changelog sections and include PR numbers/authors." --auto
  ```
</Card>

### Deep Dives

<Card title="Summarize a PR" icon="magnifying-glass">
  Get a human-readable summary of a recently merged PR with active discussion.

  **TUI Mode Prompt:**

  ```
  Find the last merged PR with a significant amount of comments.
  Summarize the conversation, including goal, key changes,
  risk areas, and any follow-ups.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Find the last merged PR with a significant amount of comments. Summarize the conversation including goal, key changes, risk areas, and follow-ups." --auto
  ```
</Card>

***

## Automate with GitHub Actions

Run headless commands on a schedule or in PRs to keep teams informed.

### Add GitHub Secrets

Repository Settings → Secrets and variables → Actions:

* `GOBI_API_KEY`: From [hub.gourmand.dev/settings/api-keys](https://hub.gourmand.dev/settings/api-keys)
* `GITHUB_TOKEN`: A token with permissions to read issues/PRs and post comments

### Example Workflow

Create `.github/workflows/github-mcp-reports.yml`:

```yaml  theme={null}
name: GitHub MCP Reports

on:
  schedule:
    - cron: "0 13 * * 1"  # Mondays 13:00 UTC
  workflow_dispatch:
  pull_request:
    types: [opened, synchronize]

jobs:
  report:
    runs-on: ubuntu-latest
    env:
      GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "18"
      - name: Install Gobi CLI
        run: npm i -g @gourmanddev/cli

      - name: Weekly Issue Triage Summary
        if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
        run: |
          cn --config gourmand/github-manager-ai \
             -p "List open issues updated in the last 14 days. Group by label and priority. Propose top 5 actions and include issue links." \
             --auto > issue_summary.txt

      - name: Post PR Context Comment
        if: github.event_name == 'pull_request'
        env:
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          REPORT=$(cn --config gourmand/github-manager-ai \
            -p "Summarize the context for PR #${PR_NUMBER}: related open issues, risk areas, and test suggestions. Keep under 200 words." \
            --auto)
          gh pr comment ${PR_NUMBER} --body "$REPORT"
```

<Info>
  Use `gourmand/github-manager-ai` consistently throughout your automation as the recommended agent configuration.
</Info>

***

## Troubleshooting

* **Missing or invalid token:** Ensure `GITHUB_TOKEN` is set and has the required scopes. Try a minimal test: “List 3 open issues in this repo”.
* **Permissions errors on comment:** Your token must include `public_repo` (public) or `repo` (private) to write comments.
* **Rate limiting:** Reduce frequency or filter queries; consider using a PAT distinct from the default Actions token when running in CI.
* **MCP connection timeout:** If using custom YAML, increase `connectionTimeout` or verify the `command`/`args` from the Hub listing.

## What You've Built

After completing this guide, you have a complete **AI-powered GitHub workflow system** that:

* ✅ Uses natural language — Simple prompts for complex GitHub operations
* ✅ Automates issue triage — AI analyzes and summarizes open issues
* ✅ Generates release notes — Automatic PR digests and changelogs
* ✅ Runs continuously — Automated reports via GitHub Actions

<Card title="Continuous AI" icon="rocket">
  Your GitHub workflow now operates at **[Level 2 Continuous
  AI](https://blog.gourmand.dev/what-is-continuous-ai-a-developers-guide/)** -
  AI handles routine issue triage and PR summaries with human oversight
  through review and approval.
</Card>

## Next Steps

1. **Explore your issues** - Try the issue triage prompts on your repository
2. **Generate release notes** - Use the merged PR prompts to create changelogs
3. **Set up automation** - Add the GitHub Actions workflow to your repo
4. **Customize prompts** - Tailor the prompts to your team's workflow
5. **Monitor progress** - Track issue resolution metrics over time

## Additional Resources

<CardGroup cols={2}>
  <Card title="GitHub MCP (Anthropic)" icon="link" href="https://hub.gourmand.dev/anthropic/github-mcp">
    Anthropic GitHub MCP on Gobi Hub
  </Card>

  <Card title="MCP in Gobi" icon="book" href="/customize/deep-dives/mcp">
    How MCP works with Gobi agents
  </Card>

  <Card title="GitHub Manager AI Agent" icon="robot" href="https://hub.gourmand.dev/gobi/github-manager-ai">
    Pre-configured agent on Gobi Hub
  </Card>

  <Card title="GitHub MCP Server" icon="link" href="https://github.com/github/github-mcp-server/blob/main/README.md">
    Official GitHub MCP server README
  </Card>
</CardGroup>


# Contributing to Gobi with Model Context Protocol (MCP)
Source: https://docs.gourmand.dev/guides/gobi-docs-mcp-cookbook

Use the Gobi Docs MCP to write cookbooks, guides, and documentation with AI-powered workflows.

<Card title="What You'll Build" icon="book-open-cover">
  Master using the Gobi Docs MCP to contribute documentation, create cookbooks, and maintain consistency across Gobi's docs - all through natural language prompts.
</Card>

## Prerequisites

Before starting, ensure you have:

* Gobi account with **Hub access**
* Read: [Contributing to Gobi Documentation](/CONTRIBUTING) for setup instructions
* Forked the [gourmand/gobi](https://github.com/gourmand/gobi) repository
* Node.js 20+ and Gobi CLI installed

<Warning>
  This cookbook assumes you've read the setup in the [CONTRIBUTING guide](/CONTRIBUTING). If you haven't, start there first.
</Warning>

## Gobi Docs MCP Setup

<Card title="Fastest Path to Success" icon="rocket">
  Use the pre-built [Docs Assistant - Mintlify agent](https://hub.gourmand.dev/gobi/docs-mintlify) that includes the Gobi Docs MCP and is ready to use immediately.
</Card>

<Tabs>
  <Tab title="⚡ Quick Start (Recommended)">
    ```bash  theme={null}
    # From your Gobi docs directory
    cn --config gourmand/docs-mintlify
    ```

    This agent includes:

    * **Gobi Docs MCP** for searching Gobi documentation
    * **Mintlify formatting rules** for proper component usage
    * **Documentation-focused prompts** for common tasks
  </Tab>

  <Tab title="🛠️ Custom Agent">
    If you want to customize, create your own agent and add:

    1. [Gobi Docs MCP](https://hub.gourmand.dev/gourmand/gobi-docs-mcp)
    2. [Mintlify Technical Writing Rule](https://hub.gourmand.dev/mintlify/technical-writing-rule)

    See the [CONTRIBUTING guide](/CONTRIBUTING#option-2-create-your-own-custom-agent) for details.
  </Tab>
</Tabs>

***

## What is the Gobi Docs MCP?

<Card title="Gobi Docs MCP" icon="circle-info">
  A Model Context Protocol server built with [Mintlify's MCP generation](https://www.mintlify.com/blog/generate-mcp-servers-for-your-docs) that enables semantic search across Gobi documentation. [Learn more →](/reference/gobi-mcp)
</Card>

The MCP helps you:

* **Find examples** from existing documentation
* **Maintain consistency** with established patterns
* **Source accurate information** about Gobi features
* **Write better documentation** faster

***

## Documentation Workflows with Prompts

### 🆕 Creating a New Cookbook

Cookbooks show how to use Gobi CLI with specific tools or services. Here's how to create one using the Gobi Docs MCP:

<Steps>
  <Step title="Research Existing Cookbooks">
    ```bash  theme={null}
    cn --config gourmand/docs-mintlify
    ```

    **Prompt:**

    ```
    "Show me the structure of existing MCP cookbooks in the Gobi docs.
    I want to create a cookbook for GitHub MCP."
    ```

    The agent will find examples like the dlt, Snyk, and Sanity cookbooks.
  </Step>

  <Step title="Source Official Documentation">
    **Prompt:**

    ```
    "Using the Gobi Docs MCP, find information about how GitHub MCP works.
    Then search the web for the official GitHub MCP documentation and combine
    both sources to create a cookbook following the same structure as the
    dlt cookbook."
    ```

    The agent will:

    * Search Gobi docs for MCP patterns
    * Fetch GitHub MCP official documentation
    * Combine both sources
    * Generate a cookbook with consistent formatting
  </Step>

  <Step title="Add to Navigation">
    **Prompt:**

    ```
    "Add my new github-mcp-gobi-cookbook.mdx to the docs.json navigation
    under the Cookbooks section."
    ```
  </Step>

  <Step title="Preview and Iterate">
    ```bash  theme={null}
    npm run dev
    # Visit http://localhost:3000
    ```

    **Refine with prompts:**

    ```
    "Add more examples to the troubleshooting section"
    "Include a CI/CD workflow example using GitHub Actions"
    "Add authentication setup using environment variables"
    ```
  </Step>
</Steps>

<Info>
  **Pro Tip:** The agent uses the Gobi Docs MCP to maintain consistency with existing cookbooks automatically.
</Info>

***

### ✏️ Updating Existing Documentation

<Steps>
  <Step title="Find the Documentation">
    **Prompt:**

    ```
    "Where is the MCP tools documentation located? Show me the file path."
    ```
  </Step>

  <Step title="Make Targeted Updates">
    **Prompt:**

    ```
    "Update the MCP tools documentation at docs/customization/mcp-tools.mdx
    to include information about the new Slack MCP server. Use the Gobi
    Docs MCP to find examples of how other MCP servers are documented, then
    add a similar section for Slack."
    ```
  </Step>
</Steps>

***

### 📝 Adding New Guides

<Steps>
  <Step title="Research Similar Content">
    **Prompt:**

    ```
    "I want to create a guide for setting up Gobi with Amazon Bedrock.
    Search the Gobi docs for similar model provider setup guides and
    show me the common structure they follow."
    ```
  </Step>

  <Step title="Create the Guide">
    **Prompt:**

    ```
    "Create a new guide at docs/guides/amazon-bedrock-setup.mdx following
    the structure you found. Include:
    - Prerequisites
    - Step-by-step setup with code examples
    - Configuration options
    - Troubleshooting common issues

    Use the Gobi Docs MCP to find accurate information about Gobi's
    model provider configuration."
    ```
  </Step>

  <Step title="Add Navigation Entry">
    **Prompt:**

    ```
    "Add this guide to docs.json under the Model Providers section"
    ```
  </Step>
</Steps>

***

## Real-World Cookbook Examples

### Example 1: PostgreSQL MCP Cookbook

**Prompt:**

```
"Create a cookbook for using Gobi with PostgreSQL MCP. Follow the same
structure as the dlt cookbook, but customize it for database operations.

Include these sections:
1. Quick start with pre-built agent
2. Manual setup with MCP configuration
3. Common database tasks (schema exploration, query writing, migrations)
4. Troubleshooting database connection issues

Use the Gobi Docs MCP to find MCP configuration patterns and search the
web for PostgreSQL MCP documentation."
```

### Example 2: Sentry Error Tracking Cookbook

**Prompt:**

```
"Create a cookbook showing how to use Gobi to analyze Sentry errors.

The cookbook should demonstrate:
1. Setting up Sentry MCP integration
2. Querying recent errors
3. Analyzing error patterns with AI
4. Generating fixes for common errors
5. CI/CD integration for automated error analysis

Research the Snyk cookbook structure since it's also about error detection,
and adapt it for Sentry."
```

### Example 3: OpenAPI Documentation Cookbook

**Prompt:**

```
"I want to create a cookbook for using Gobi to work with OpenAPI specs.

Show how to:
1. Load OpenAPI specs into Gobi's context
2. Generate API client code from specs
3. Create tests based on API endpoints
4. Update documentation when APIs change

Use the Gobi Docs MCP to find how context providers work, then combine
that with OpenAPI MCP information."
```

***

## Advanced Prompt Patterns

<CardGroup cols={2}>
  <Card title="Multi-Source Research" icon="magnifying-glass">
    ```bash  theme={null}
    "Use the Gobi Docs MCP to understand how agents
    work in Gobi, then search the web for Anthropic's
    Computer Use MCP. Create a cookbook showing how to
    combine Gobi agents with Computer Use for
    automated testing."
    ```
  </Card>

  <Card title="Cross-Reference Documentation" icon="link">
    ```bash  theme={null}
    "Find all mentions of MCP servers across Gobi
    documentation. Then create a comprehensive reference
    page that links to all MCP-related guides and
    configurations."
    ```
  </Card>

  <Card title="Consistency Checking" icon="check-double">
    ```bash  theme={null}
    "Review all cookbook files in docs/guides/ and check
    if they follow the same structure. List any
    inconsistencies and suggest updates to make them
    uniform."
    ```
  </Card>

  <Card title="Example Extraction" icon="code">
    ```bash  theme={null}
    "Extract all code examples showing MCP server
    configuration from the Gobi docs. Format them
    as a single reference page with explanations for
    each pattern."
    ```
  </Card>
</CardGroup>

***

## Testing Your Documentation

### Local Preview

```bash  theme={null}
cd docs
npm run dev
# Visit http://localhost:3000
```

### Validation Prompts

```bash  theme={null}
# Check formatting
"Review this documentation for Mintlify formatting issues and fix any problems"

# Verify links
"Check all links in this file and ensure they point to existing documentation"

# Test code examples
"Verify that all code examples in this cookbook are syntactically correct"
```

***

## Submitting Your Contribution

**Prompt:**

```bash  theme={null}
"Create a pull request with my documentation changes and use the repo's
PR template to write the description"
```

The agent will:

* Create a feature branch
* Stage and commit your changes
* Push to your fork
* Generate a PR description following the template
* Open the PR for review

<Info>
  See the full [Contributing Guide](/CONTRIBUTING#submitting-your-contribution) for manual PR submission details.
</Info>

***

## Automated Documentation Checks with GitHub Actions

Add automated documentation checks to your PR workflow using the Gobi Docs MCP agent:

```yaml title=".github/workflows/docs-check.yml" theme={null}
name: Documentation Check

on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - 'core/**'
      - 'extensions/**'
      - 'packages/**'
      - 'gui/**'

jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Gobi CLI
        run: npm i -g @gourmanddev/cli

      - name: Analyze Changes for Documentation Needs
        id: analyze
        env:
          GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}
        run: |
          echo "🔍 Analyzing code changes for documentation needs..."

          # Get changed files
          git diff origin/${{ github.base_ref }}..HEAD --name-only > changed_files.txt

          # Create detailed diff
          git diff origin/${{ github.base_ref }}..HEAD > changes.diff

          # Use Gobi agent to check if docs need updates
          PROMPT="Review these code changes and determine if documentation updates are needed.

          Changed files: $(cat changed_files.txt | tr '\n' ' ')

          Consider:
          - New features or APIs
          - Breaking changes
          - New configuration options
          - Modified CLI commands
          - New MCP integrations

          If docs updates are needed, specify which files in docs/ should be updated.
          If no updates needed, respond with 'NO_DOCS_NEEDED'.
          Be specific and concise."

          cn --config gourmand/docs-mintlify -p "$PROMPT" --auto > analysis.md || {
            echo "⚠️ Analysis failed"
            echo "needs_docs=false" >> $GITHUB_OUTPUT
            exit 0
          }

          if grep -q "NO_DOCS_NEEDED" analysis.md; then
            echo "needs_docs=false" >> $GITHUB_OUTPUT
          else
            echo "needs_docs=true" >> $GITHUB_OUTPUT
          fi

      - name: Post Documentation Recommendation
        if: steps.analyze.outputs.needs_docs == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          echo "📝 Creating PR comment with documentation recommendations..."

          cat > pr-comment.md <<'EOF'
## 📚 Documentation Update Recommended

Based on the code changes in this PR, documentation updates may be needed:

EOF

          cat analysis.md >> pr-comment.md

          cat >> pr-comment.md <<'EOF'

---

### Next Steps

1. Review the suggested documentation areas above
2. Update relevant files in the `/docs` folder
3. Consider updating:
   - API references for interface changes
   - Guides for workflow changes
   - Configuration docs for new settings
   - MCP cookbooks for new integrations

### Resources
- [Contributing to Docs](/CONTRIBUTING)
- [Gobi Docs MCP Cookbook](/guides/gobi-docs-mcp-cookbook)

*This analysis was generated using the Gobi Docs MCP agent.*
EOF

          gh pr comment ${{ github.event.pull_request.number }} --body-file pr-comment.md

      - name: Add Label
        if: steps.analyze.outputs.needs_docs == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh pr edit ${{ github.event.pull_request.number }} --add-label "docs-needed"
```

<Info>
  This workflow uses the Gobi Docs MCP agent to analyze code changes and automatically comment on PRs when documentation updates are recommended.
</Info>

***

## Documentation MCP for Other Projects

Want to create documentation MCPs for your own projects? Mintlify makes it easy:

<Steps>
  <Step title="Set Up Mintlify Docs">
    ```bash  theme={null}
    npm i -g mintlify
    mintlify init
    ```
  </Step>

  <Step title="MCP Auto-Generated">
    Mintlify automatically generates an MCP server for your documentation, enabling semantic search.

    [Learn more about Mintlify MCP generation →](https://www.mintlify.com/blog/generate-mcp-servers-for-your-docs)
  </Step>

  <Step title="Publish to Gobi Hub">
    Share your docs MCP on [Gobi Hub](https://hub.gourmand.dev/new?type=mcp) so others can use it with Gobi agents.
  </Step>
</Steps>

<Info>
  The [Gobi Docs MCP](/reference/gobi-mcp) itself was built this way!
</Info>

***

## Key Prompts Cheat Sheet

| Task                  | Prompt                                                                                         |
| :-------------------- | :--------------------------------------------------------------------------------------------- |
| **Find structure**    | "Show me the structure of existing cookbooks in Gobi docs"                                     |
| **Create cookbook**   | "Create a cookbook for \[tool] MCP following the dlt cookbook structure"                       |
| **Update docs**       | "Update \[file] to include information about \[feature], using Gobi Docs MCP to find examples" |
| **Add navigation**    | "Add \[file] to docs.json under the \[section] section"                                        |
| **Check consistency** | "Review this file for consistency with other Gobi documentation"                               |
| **Fix formatting**    | "Review for Mintlify formatting issues and fix any problems"                                   |
| **Extract examples**  | "Find all examples of \[topic] in Gobi docs"                                                   |
| **Research feature**  | "Use Gobi Docs MCP to explain how \[feature] works in Gobi"                                    |

***

## Resources

### Gobi Documentation

* [Contributing Guide](/CONTRIBUTING) - Setup and submission process
* [Gobi Docs MCP Reference](/reference/gobi-mcp) - MCP server details
  * [Understanding Configs](/guides/understanding-configs) - How configs work

### Mintlify

* [MCP Generation Guide](https://www.mintlify.com/blog/generate-mcp-servers-for-your-docs)
* [Mintlify Documentation](https://mintlify.com/docs)

### Community

* [Gobi Discord](https://discord.gg/gobi) - #documentation channel
* [GitHub Discussions](https://github.com/gourmand/gobi/discussions)

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Start Contributing" icon="code" href="/CONTRIBUTING">
    Set up your environment
  </Card>

  <Card title="Use Docs Agent" icon="robot" href="https://hub.gourmand.dev/gobi/docs-mintlify">
    Install pre-built agent
  </Card>

  <Card title="Browse Cookbooks" icon="book-open" href="/guides/overview">
    See cookbook examples
  </Card>

  <Card title="Join Discord" icon="discord" href="https://discord.gg/gobi">
    Get help from community
  </Card>
</CardGroup>


# How to Self-Host a Model
Source: https://docs.gourmand.dev/guides/how-to-self-host-a-model

Learn how to deploy and self-host open-source language models using HuggingFace TGI, vLLM, SkyPilot, Anyscale Private Endpoints, or Lambda for use with Gobi

* [HuggingFace TGI](https://github.com/gourmand/gobi/deploy-os-code-llm#tgi)
* [vLLM](https://github.com/gourmand/gobi/deploy-os-code-llm#vllm)
* [SkyPilot](https://github.com/gourmand/gobi/deploy-os-code-llm#skypilot)
* [Anyscale Private Endpoints](https://github.com/gourmand/gobi/deploy-os-code-llm#anyscale-private-endpoints) (OpenAI compatible API)
* [Lambda](https://github.com/gourmand/gobi/deploy-os-code-llm#lambda)

## How to Self-Host an Open-Source Model

For many cases, either Gobi will have a built-in provider or the API you use will be OpenAI-compatible, in which case you can use the "openai" provider and change the "baseUrl" to point to the server.

However, if neither of these are the case, you will need to wire up a new LLM object.

## How to Set Up Authentication

Basic authentication can be done with any provider using the `apiKey` field:

* YAML
* JSON

config.yaml

```
models:
  - name: Ollama
    provider: ollama
    model: llama2-7b
    apiKey: <YOUR_CUSTOM_OLLAMA_SERVER_API_KEY>
```

config.json

```json  theme={null}
{
  "models": [
    {
      "title": "Ollama",
      "provider": "ollama",
      "model": "llama2-7b",
      "apiKey": "<YOUR_CUSTOM_OLLAMA_SERVER_API_KEY>"
    }
  ]
}
```

This translates to the header `"Authorization": "Bearer xxx"`.

If you need to send custom headers for authentication, you may use the `requestOptions.headers` property like in this example with Ollama:

* YAML
* JSON

config.yaml

```
models:
  - name: Ollama
    provider: ollama
    model: llama2-7b
    requestOptions:
      headers:
        X-Auth-Token: xxx
```

config.json

```json  theme={null}
{
  "models": [
    {
      "title": "Ollama",
      "provider": "ollama",
      "model": "llama2-7b",
      "requestOptions": { "headers": { "X-Auth-Token": "xxx" } }
    }
  ]
}
```

Similarly if your model requires a Certificate for authentication, you may use the `requestOptions.clientCertificate` property like in the example below:

* YAML
* JSON

config.yaml

```
models:
  - name: Ollama
    provider: ollama
    model: llama2-7b
    requestOptions:
      clientCertificate:
        cert: C:\tempollama.pem
        key: C:\tempollama.key
        passphrase: c0nt!nu3
```

config.json

```json  theme={null}
{
  "models": [
    {
      "title": "Ollama",
      "provider": "ollama",
      "model": "llama2-7b",
      "requestOptions": {
        "clientCertificate": {
          "cert": "C:\\tempollama.pem",
          "key": "C:\\tempollama.key",
          "passphrase": "c0nt!nu3"
        }
      }
    }
  ]
}
```


# Using Instinct with Ollama in Gobi
Source: https://docs.gourmand.dev/guides/instinct

Learn how to run Instinct, Gobi's leading open Next Edit model, on your own hardware with Ollama

<Warning>
  Instinct is a 7 billion parameter model. You should expect slow responses if
  running on a laptop. To learn how to inference Instinct on a GPU, see our
  [HuggingFace model card](https://huggingface.co/gourmand/instinct).
</Warning>

We recently released Instinct, a state-of-the-art open Next Edit model. Robustly fine-tuned from Qwen2.5-Coder-7B, Instinct intelligently predicts your next move to keep you in flow. To learn more about the model, check out [our blog post](https://blog.gourmand.dev/instinct/).

<Frame>
  <img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/instinct.gif?s=b0852b447246045be993e6f112e9bda3" data-og-width="1288" width="1288" data-og-height="1080" height="1080" data-path="images/instinct.gif" data-optimize="true" data-opv="3" />
</Frame>

### 1. Install Ollama

If you haven't already installed Ollama, see our guide [here](./ollama-guide).

### 2. Download Instinct

```bash  theme={null}
ollama run nate/instinct
```

### 3. Update your `config.yaml`

Open your `config.yaml` and add Instinct to the models section:

```yaml  theme={null}
# ... rest of config.yaml ...

models:
  - uses: gourmand/instinct
```

Alternatively, you can just click to add the block at [https://hub.gourmand.dev/gobi/instinct](https://hub.gourmand.dev/gobi/instinct).


# Netlify Performance Optimization Cookbook
Source: https://docs.gourmand.dev/guides/netlify-mcp-continuous-deployment

Optimize web performance with A/B testing, automated monitoring, and data-driven improvements using Netlify MCP and Gobi.

<Card title="Ship Faster Code, Not Slower Sites" icon="gauge-high">
  Use AI to automatically monitor performance metrics, run A/B tests between
  branches, and get actionable optimization suggestions based on real user data
  from Netlify Analytics
</Card>

<Info>
  **Did You Know?** Netlify is more than just static hosting! It offers:

  * [Split Testing](https://docs.netlify.com/site-deploys/split-testing/) for A/B testing branches
  * [Analytics](https://docs.netlify.com/analytics/get-started/) with Core Web Vitals tracking
  * [Edge Functions](https://docs.netlify.com/edge-functions/overview/) for personalization at the edge
  * [Build Plugins](https://docs.netlify.com/integrations/build-plugins/) ecosystem with 100+ integrations
  * [Forms](https://docs.netlify.com/forms/setup/) with built-in spam protection
  * [Identity](https://docs.netlify.com/visitor-access/identity/) for user authentication
  * [Large Media](https://docs.netlify.com/large-media/overview/) for Git LFS support

  This guide shows you how to leverage these features through natural language with Gobi CLI!
</Info>

## What You'll Learn

This cookbook teaches you to:

* Run [A/B tests](https://docs.netlify.com/site-deploys/split-testing/) between branches to measure performance impact
* Monitor [Core Web Vitals](https://docs.netlify.com/analytics/get-started/#core-web-vitals) and build performance metrics
* Automatically block deploys that degrade performance using [Deploy Contexts](https://docs.netlify.com/site-deploys/overview/#deploy-contexts)
* Optimize build times with [Build Plugins](https://docs.netlify.com/integrations/build-plugins/) and bundle sizes with AI assistance

## Prerequisites

* GitHub repository with a web project
* [Netlify account](https://netlify.com) (free tier works)
* Node.js 22+ installed (required for Netlify)
* [Gobi CLI](https://docs.gourmand.dev/guides/cli) (`npm i -g @gourmanddev/cli`)
* [Netlify MCP](https://hub.gourmand.dev/netlify/netlify-mcp) configured
* [Netlify Development Rules](https://hub.gourmand.dev/netlify/netlify-development) (recommended)

## Quick Setup

<Info>
  The Netlify Development Rules bundle includes guardrails for:

  * Proper `.gitignore` configuration
  * Function structure and placement
  * Edge function constraints
  * Local development best practices
</Info>

For all options, first:

<Steps>
  <Step title="Install Gobi CLI">
    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```
  </Step>

  <Step title="Install Netlify CLI">
    1. Install Netlify CLI: `npm i -g netlify-cli`
    2. Authenticate with Netlify:
       `netlify login`
  </Step>
</Steps>

## Netlify Continuous AI Workflow Options

<Card title="🚀 Fastest Path to Success" icon="zap">
  Skip the manual setup and use our pre-built Netlify Continuous AI agent that includes
  optimized prompts, rules, and the Netlify MCP for more consistent results.
</Card>

After completing **Quick Setup** above, you have two paths to get started:

<Tabs>
  <Tab title="⚡ Quick Start (Recommended)">
    <Steps>
      <Step title="Add the Pre-Built Agent">
        Visit the [Netlify Continuous AI Agent](https://hub.gourmand.dev/gobi/netlify-continuous-ai) on Gobi Hub and click **"Install Agent"**

        This agent includes:

        * **Optimized prompts** for Netlify deployment and performance analysis
        * **Built-in rules** for consistent formatting and error handling
        * **Netlify MCP** for more reliable API interactions
      </Step>

      <Step title="Verify Your Setup">
        The agent uses the Netlify MCP automatically and includes best practice rules for deployment and performance optimization.
      </Step>

      <Step title="Run Performance Analysis">
        From your project directory, run:

        ```bash  theme={null}
        cn "Analyze my Netlify site's performance and optimize it for better Core Web Vitals."
        ```

        That's it! The agent handles everything automatically.
      </Step>
    </Steps>

    <Info>
      **Why Use the Agent?** Results are more consistent and debugging is easier thanks to the Netlify MCP integration and pre-tested prompts. You can remix the agent later to customize it to your needs.
    </Info>
  </Tab>

  <Tab title="🛠️ Manual Setup">
    <Steps>
      <Step title="Configure Netlify MCP">
        1. Authenticate with Netlify:
           `netlify login`
        2. Visit [Netlify MCP on Gobi
           Hub](https://hub.gourmand.dev/netlify/netlify-mcp)
        3. Follow the configuration instructions for your editor
      </Step>

      <Step title="Add Development Rules">
        Install the [Netlify Development Rules](https://hub.gourmand.dev/netlify/netlify-development) bundle for best practices:

        1. Visit the bundle page on Gobi Hub
        2. Click **"Install Rules"**
        3. Rules automatically apply to your agent
      </Step>

      <Step title="Verify Setup">
        Test the connection with cn CLI:

        ```bash  theme={null}
        cn
        # Then in TUI mode:
        "Check my Netlify auth and list sites"
        ```
      </Step>
    </Steps>

    <Info>
      You're all set! Now you can use cn CLI to interact with Netlify using natural language prompts. Check out the examples below to get started.
    </Info>
  </Tab>
</Tabs>

<Accordion title="Agent Requirements">
  To use the pre-built agent, you need either:

  * **Gobi CLI Pro Plan** with
    the models add-on, OR
  * **Your own API keys** added to Gobi Hub secrets
    The agent will automatically detect and use your
    configuration along with the Netlify MCP for deployment operations.
</Accordion>

***

## Performance Optimization Steps

### Step 1: Baseline Performance Metrics

Establish your current performance baseline using cn CLI:

```bash  theme={null}
# Start cn in TUI mode
cn

# Then ask:
"Show my site's Core Web Vitals and build times"
```

<Tip>
  **Test in Plan Mode First**: Before making performance optimizations that
  might affect your site, test your prompts in plan mode (see the [Plan Mode
  Guide](/guides/plan-mode-guide); press **Shift+Tab** to switch modes). This
  shows you what the agent will do without executing it. For example: `"Set up
    A/B testing between main and feature branch with performance monitoring"`
</Tip>

<Info>
  Netlify automatically tracks:

  * **Build Performance**: Compile times, cache
    hits
  * **Runtime Performance**: Core Web Vitals, Time to Interactive
  * **Resource Usage**: Bandwidth, function execution times
</Info>

### Step 2: A/B Test Branch Performance

Compare performance between branches:

```bash  theme={null}
# In cn TUI mode:
"Set up A/B test between main and feature branch on Netlify:
- Split traffic 50/50 between branches
- Track Core Web Vitals for each variant
- Monitor conversion metrics and bounce rate
- Enable analytics to measure performance impact
- Configure cookie-based visitor persistence
- Set test duration for 1000 unique visitors
- Auto-conclude test when statistical significance reached
Report winner based on performance + conversion metrics"
```

<Info>
  **Enhanced Analytics**: Combine Netlify's A/B testing with PostHog session
  recordings to understand not just which variant performs better, but why users
  behave differently. See our [PostHog session analysis
  guide](/guides/posthog-github-continuous-ai) to set up session tracking and
  create a complete continuous AI analytics workflow.
</Info>

### Step 3: Advanced Build Optimization with Netlify

Leverage Netlify's powerful build features to dramatically reduce build times:

```bash  theme={null}
# In cn TUI mode:
"Optimize my Netlify build performance using these features:

1. Enable Netlify Cache Plugin for dependency caching
   - Configure @netlify/plugin-cache for node_modules
   - Set up custom cache directories for .next/cache or .nuxt
   - Enable Gatsby's incremental builds if applicable

2. Set up Build Plugins from Netlify's ecosystem:
   - Install @netlify/plugin-lighthouse for performance monitoring
   - Add netlify-plugin-checklinks to prevent broken links
   - Configure netlify-plugin-submit-sitemap for SEO

3. Implement Conditional Builds:
   - Skip builds when only docs change (ignore: /docs/**)
   - Use build.ignore script for custom logic
   - Set up monorepo-specific build triggers

4. Configure concurrent builds for monorepos
   - Set base directory per package
   - Use pnpm workspaces or yarn workspaces

Show me the netlify.toml configuration and explain each optimization"
```

<Info>
  **Netlify Build Features You're Getting**:

  * [Build Caching](https://docs.netlify.com/configure-builds/build-caching/) - Persist dependencies between builds
  * [Build Plugins](https://docs.netlify.com/integrations/build-plugins/) - Extend build process with 100+ plugins
  * [Conditional Builds](https://docs.netlify.com/configure-builds/ignore-builds/) - Skip unnecessary builds
  * [Monorepo Support](https://docs.netlify.com/configure-builds/monorepos/) - Optimize multi-package repos

  These features can reduce build times by 50-70% for most projects!
</Info>

<Tip>
  **Discover more optimization prompts!** The Netlify community has documented dozens of build optimization strategies in their [Support Guide: How can I optimize my Netlify build time](https://answers.netlify.com/t/support-guide-how-can-i-optimize-my-netlify-build-time/3907).

  Use this guide as inspiration for cn CLI prompts not covered in this cookbook, such as:

  * `"Configure my builds to skip Dependabot PRs automatically"`
  * `"Set up custom ignore patterns for documentation-only changes"`
  * `"Optimize my Contentful webhooks to prevent duplicate builds"`
  * `"Show me how to use build hooks instead of automatic git triggers"`
  * `"Help me choose between Astro and Hugo based on build performance"`

  The community guide contains real-world scenarios that you can turn into AI-assisted solutions - just describe what you want to achieve and let cn CLI handle the implementation!
</Tip>

### Step 4: Bundle Analysis with Netlify's Built-in Tools

Use Netlify's bundle analyzer and optimization features:

```bash  theme={null}
# In cn TUI mode:
"Analyze and optimize my bundle using Netlify's tools:

1. Enable Netlify Bundle Analyzer:
   - Add @netlify/plugin-bundle-analyzer to plugins
   - Configure size thresholds in netlify.toml
   - Generate visual bundle reports

2. Set up Asset Optimization:
   - Enable automatic JS minification
   - Configure CSS optimization
   - Turn on HTML minification
   - Set up image processing pipeline

3. Implement Smart Code Splitting:
   - Analyze current chunks with the bundle analyzer
   - Identify components over 50KB for splitting
   - Configure webpack/vite for optimal chunking
   - Set up route-based code splitting

4. Configure Netlify's CDN for optimal delivery:
   - Set cache headers for static assets
   - Enable Brotli compression
   - Configure edge caching rules

Generate a full report with before/after bundle sizes"
```

<Card title="Netlify's Performance Arsenal" icon="rocket">
  **Features Available Through Netlify MCP**:

  * [Bundle
    Analyzer](https://docs.netlify.com/configure-builds/build-plugins/bundle-analyzer/): Visualize your JavaScript bundles
  * [Asset
    Optimization](https://docs.netlify.com/configure-builds/post-processing/):
    Automatic minification and compression
  * [Edge
    Network](https://docs.netlify.com/platform/edge-network/): Global CDN with
    smart caching
  * [Deploy
    Previews](https://docs.netlify.com/site-deploys/deploy-previews/): Test
    optimizations before production
</Card>

### Step 5: Image Optimization

Optimize images for better performance:

```bash  theme={null}
# In cn TUI mode:
"Set up Cloudinary image optimization for my Netlify site:
- Install @cloudinary/netlify-plugin via MCP
- Auto-convert images to WebP with fallbacks
- Generate responsive sizes (320w, 640w, 1024w, 1920w)
- Add lazy loading for all images
- Configure blur-up placeholders
- Update netlify.toml with Cloudinary settings
Target: Reduce image payload by 60-80% and improve LCP"
```

## Continuous Performance Monitoring

### Step 6: Performance Budget Enforcement with Lighthouse CI

Set and enforce performance budgets with automated testing:

```bash  theme={null}
# In cn TUI mode:
"Set up Lighthouse CI with performance budgets for my Netlify site:

Requirements:
- LCP must be < 2.5 seconds
- JavaScript bundle must be < 200KB
- Total size < 500KB
- Performance score >= 90

Setup needed:
1. Install @lhci/cli and @netlify/plugin-lighthouse
2. Create lighthouserc.js with these budget assertions
3. Configure netlify.toml to run checks on all deploys
4. Add GitHub status checks to block PRs that exceed budgets
5. Create performance dashboard at /lighthouse-reports

Please configure the complete Lighthouse CI setup with these budgets."
```

<Tip>
  This comprehensive setup will automatically test every deploy preview and
  production deployment, blocking any changes that violate your performance
  budgets.
</Tip>

### Step 7: Real User Monitoring with Netlify Analytics

Leverage Netlify's built-in analytics and integrate advanced RUM solutions:

```bash  theme={null}
# In cn TUI mode:
"Set up comprehensive Real User Monitoring for my Netlify site:

1. Configure Netlify Analytics Pro (requires Pro account):
   - Set up server-side analytics (no JS required)
   - Track Core Web Vitals (LCP, FID, CLS, INP)
   - Monitor top pages by performance score
   - Create custom performance alerts
   - Configure weekly performance reports

2. Integrate Web Vitals tracking:
   - Install web-vitals library for detailed metrics
   - Send metrics to Netlify Functions endpoint
   - Store performance data in Netlify Blobs
   - Create performance dashboard at /metrics

3. Set up Performance Alerts:
   - Alert when P75 LCP > 3 seconds
   - Notify if CLS increases by 20%
   - Monitor JavaScript error rates
   - Track 404s and broken resources
   - Send alerts to Slack via Netlify Functions

4. Configure Geographic Performance Monitoring:
   - Use Netlify Edge Functions to track region-specific metrics
   - Identify slow regions with Edge geo data
   - Compare performance across CDN nodes
   - Optimize edge caching for slow regions

5. Create Custom Performance Dashboard:
   - Build dashboard page using Netlify Functions
   - Display real-time Core Web Vitals
   - Show performance trends over time
   - Include browser and device breakdowns

Show me the complete implementation with all code and configurations"
```

<Warning>
  **Note**: Netlify Analytics Pro requires a paid Netlify Pro account (\$19/month
  per site). The prompt above assumes you have this plan. For free tier users,
  focus on steps 2-5 which use Netlify Functions and Edge Functions to build
  custom analytics.
</Warning>

<Info>
  **Netlify Analytics Advantages**:

  * [Server-side Analytics](https://docs.netlify.com/analytics/get-started/) - No client-side JavaScript needed
  * [Core Web Vitals](https://docs.netlify.com/analytics/core-web-vitals/) - Automatic tracking of Google's metrics
  * [Custom Metrics](https://docs.netlify.com/functions/logs/) - Track any metric via Functions
  * [Edge Insights](https://docs.netlify.com/edge-functions/overview/#geolocation) - Geographic performance data
  * [No Cookie Banner Required](https://docs.netlify.com/analytics/get-started/#privacy) - GDPR compliant by default

  Unlike Google Analytics, Netlify Analytics:

  * Doesn't slow down your site (server-side)
  * Captures 100% of traffic (no ad blockers)
  * Respects user privacy (no cookies)
  * Shows bot traffic separately
</Info>

<Tip>
  **Pro Tip**
  Combine Netlify Analytics with Edge Functions to create a
  powerful RUM solution that:

  * Tracks performance by user segment
  * A/B tests
    performance optimizations
  * Personalizes content based on connection speed
  * Automatically serves lighter assets to slow connections
</Tip>

## Automated Performance Checks

### Add GitHub Secrets

Navigate to **Repository Settings → Secrets and variables → Actions** and add:

* `GOBI_API_KEY`: Your Gobi API key from [hub.gourmand.dev/settings/api-keys](https://hub.gourmand.dev/settings/api-keys)
* `NETLIFY_AUTH_TOKEN`: Your Netlify personal access token
* `NETLIFY_SITE_ID`: Your Netlify site ID

### GitHub Actions Performance Guard

Block PRs that degrade performance:

```yaml  theme={null}
name: Performance Check

on:
  pull_request:

jobs:
  performance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install Gobi CLI
        run: |
          npm install -g @gourmanddev/cli
          echo "✅ Gobi CLI installed"

      - name: Authenticate Gobi CLI
        env:
          GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}
        run: |
          cn auth login --api-key "$GOBI_API_KEY"
          echo "✅ Gobi CLI authenticated"

      - name: Deploy and Test Performance
        id: perf
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
        run: |
          echo "🚀 Deploying PR preview and analyzing performance..."
          cn -p "Deploy PR preview and run Lighthouse.
                 Compare scores with main branch.
                 Output JSON with score deltas." > performance.json

      - name: Comment Performance Results
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const perf = JSON.parse(fs.readFileSync('performance.json'));

            const emoji = perf.score_delta < -10 ? '🔴' :
                         perf.score_delta < 0 ? '🟡' : '🟢';

            const comment = `## ${emoji} Performance Impact

            | Metric | Main | PR | Delta |
            |--------|------|----|---------|
            | Performance Score | ${perf.main_score} | ${perf.pr_score} | ${perf.score_delta > 0 ? '+' : ''}${perf.score_delta} |
            | LCP | ${perf.main_lcp}s | ${perf.pr_lcp}s | ${perf.lcp_delta > 0 ? '+' : ''}${perf.lcp_delta}s |
            | Bundle Size | ${perf.main_bundle}KB | ${perf.pr_bundle}KB | ${perf.bundle_delta > 0 ? '+' : ''}${perf.bundle_delta}KB |

            ${perf.score_delta < -10 ? '⚠️ **This PR significantly degrades performance. Please optimize before merging.**' : ''}

            [View Full Report](${perf.report_url})`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });

            // Fail check if performance degrades significantly
            if (perf.score_delta < -10) {
              core.setFailed('Performance degraded by more than 10 points');
            }
```

<Warning>
  This workflow will:

  * **Block merge** if performance score drops >10 points
  * **Warn** on any performance regression
  * **Celebrate** improvements with green indicators
</Warning>

## Performance Testing Locally

### Step 8: Local Performance Testing

Test performance before deploying:

```bash  theme={null}
# In cn TUI mode:
"Run production build and measure bundle sizes"
```

### Step 9: Pre-commit Performance Checks

Prevent performance regressions before they happen:

```bash  theme={null}
# In cn TUI mode:
"Add pre-commit hooks for bundle size limits"
```

## Performance Troubleshooting

### Debug Performance Issues

Identify and fix performance bottlenecks:

```bash  theme={null}
# In cn TUI mode:
"Why did my performance score drop?"
```

### Performance Issue Quick Fixes

| Issue         | Quick Fix Command (in cn TUI)     |
| ------------- | --------------------------------- |
| Slow LCP      | `"Preload critical resources"`    |
| High CLS      | `"Add size attributes to images"` |
| Large bundles | `"Implement code splitting"`      |
| Slow builds   | `"Enable build caching"`          |
| Poor caching  | `"Configure cache headers"`       |

## What You've Accomplished

<Card title="Performance-First Development" icon="gauge-high">
  You've built an AI-powered performance optimization system that:

  * Automatically monitors Core Web Vitals
  * Runs A/B tests between branches
  * Blocks deployments that degrade performance
  * Provides actionable optimization
    suggestions
</Card>

## Discover Netlify's Hidden Performance Gems

Features many developers don't know Netlify offers:

<CardGroup cols={2}>
  <Card title="Edge Functions" icon="bolt">
    **[Netlify Edge Functions](https://docs.netlify.com/edge-functions/overview/)**

    * Run code at the edge, closer to users
    * Transform responses on-the-fly
    * A/B test at the edge level
    * Personalize content without client-side JS
  </Card>

  <Card title="Netlify Graph" icon="diagram-project">
    **[Netlify Graph](https://docs.netlify.com/graph/overview/)**

    * Unified GraphQL gateway for all your APIs
    * Automatic TypeScript generation
    * Built-in authentication handling
    * Zero client-side API keys needed
  </Card>

  <Card title="On-Demand Builders" icon="hammer">
    **[On-Demand
    Builders](https://docs.netlify.com/configure-builds/on-demand-builders/)**

    * Generate pages only when requested
    * Cache dynamically generated content
    * Perfect for large sites (10k+ pages)
    * Reduce build times dramatically
  </Card>

  <Card title="Netlify Functions" icon="function">
    **[Background Functions](https://docs.netlify.com/functions/background-functions/)**

    * Run tasks up to 15 minutes
    * Process webhooks asynchronously
    * Handle heavy computations
    * No timeout worries
  </Card>
</CardGroup>

```bash  theme={null}
# Try these advanced features in cn TUI mode:
"Show me how to use Netlify Edge Functions for geo-based personalization"
"Set up On-Demand Builders for my blog with 5000 posts"
"Configure Background Functions for image processing"
```

## Performance Best Practices

The Netlify Performance Rules enforce:

<CardGroup cols={3}>
  <Card title="Build Optimization" icon="hammer">
    * Dependency caching enabled
    * Parallel builds when possible
    * Incremental compilation
    * Smart cache invalidation
  </Card>

  <Card title="Runtime Performance" icon="bolt">
    * Automatic image optimization
    * Efficient resource hints (preload, prefetch)
    * Optimal cache headers
    * CDN configuration
  </Card>

  <Card title="Monitoring Standards" icon="chart-line">
    * Performance budgets enforced
    * Core Web Vitals tracking
    * Real user monitoring
    * Automated alerts
  </Card>
</CardGroup>

## Advanced Performance Strategies

### Progressive Enhancement

```bash  theme={null}
# In cn TUI mode:
"Implement progressive enhancement with basic HTML first"
```

### Multi-variant Testing

```bash  theme={null}
# In cn TUI mode:
"Test 3 bundle strategies and auto-select winner"
```

### Predictive Prefetching

```bash  theme={null}
# In cn TUI mode:
"Analyze navigation patterns and prefetch next pages"
```

## Next Steps

* Install [Netlify MCP](https://hub.gourmand.dev/netlify/netlify-mcp) from Gobi Hub
* Set up [Performance Monitoring](https://docs.netlify.com/analytics/get-started/)
* Configure [A/B Testing](https://docs.netlify.com/split-testing/overview/)
* Join the [Gobi Discord](https://discord.gg/gobi) for support

## Resources

* [Netlify MCP on Gobi Hub](https://hub.gourmand.dev/netlify/netlify-mcp)
* [Core Web Vitals Guide](https://web.dev/vitals/)
* [Netlify Analytics Documentation](https://docs.netlify.com/analytics/)
* [Gobi Performance Guides](https://docs.gourmand.dev/guides)


# Developer & Team Workflows with Notion + Gobi CLI
Source: https://docs.gourmand.dev/guides/notion-gobi-guide

Use Gobi CLI with Notion to generate docs, manage tasks, and automate project workflows – all through natural-language prompts.

<Card title="What You'll Build" icon="notion">
  A workflow that lets you query, update, and create Notion pages or database
  entries from natural-language prompts. Generate PRDs, sprint tasks, meeting
  notes, or status reports automatically – perfect for individual developers
  and cross-functional teams.
</Card>

## What You'll Learn

This guide teaches you to:

* Use natural language to connect to the Notion API directly with Gobi CLI for powerful automation
* Configure Notion API access with proper permissions and security
* Run prompts in both TUI (interactive) and headless modes
* Create automated workflows that generate docs, manage tasks, and sync data

## Prerequisites

Before starting, ensure you have:

* [Gobi CLI](https://docs.gourmand.dev/cli/overview) installed (`npm i -g @gourmanddev/cli`)
* A [Notion workspace](https://notion.so) with Editor (or higher) access
* Node.js 18+ installed locally
* [Gobi account](https://hub.gourmand.dev) with **Hub access**

<Warning>
  **Agent usage requires credits** – create a Gobi API key at
  [hub.gourmand.dev/settings/api-keys](https://hub.gourmand.dev/settings/api-keys)
  and store it as a secret.
</Warning>

<Steps>
  <Step title="Install Gobi CLI">
    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```

    Verify installation:

    ```bash  theme={null}
    cn --version
    ```
  </Step>

  <Step title="Create Notion Integration & Get API Key">
    1. Go to **[Notion Integrations](https://www.notion.so/my-integrations)**
    2. Click **+ New integration** → give it a name (e.g. "Gobi Integration")
    3. Select your workspace
    4. Under **Content Capabilities**, enable:
       * ✅ Read content
       * ✅ Update content
       * ✅ Insert content
    5. Under **Comment Capabilities**, enable:
       * ✅ Read comments
       * ✅ Insert comments
    6. Under **User Capabilities**, select:
       * ✅ Read user information including email addresses
    7. Click **Submit** and copy the **Internal Integration Secret** (starts with `secret_`)

    <Info>
      This token is your `NOTION_API_KEY`.
      Keep it safe – you won't be able to view it again.
    </Info>

    8. In Notion, open each database or top-level page you want accessible → **Share** → **Invite** your new integration → **Full access**.
  </Step>

  <Step title="Configure API Access">
    Set your Notion API key as an environment variable in your terminal:

    ```bash  theme={null}
    export NOTION_API_KEY="secret_xxx"
    ```

    <Tip>
      Running this command sets your API key for the current terminal session only.\
      When you close the terminal, the variable won't persist. To test your API key, run the curl command below in the same session.

      ```bash  theme={null}
      curl -H "Authorization: Bearer $NOTION_API_KEY" \
          -H "Notion-Version: 2022-06-28" \
          https://api.notion.com/v1/databases
      ```
    </Tip>
  </Step>

  <Step title="Add Workspace Keys to Terminal Session">
    Depending on what you want `cn` to accomplish, you'll need to add your Notion workspace keys to the terminal session. The workspace key is your Notion database ID. Run the following command:

    ```bash  theme={null}
    export NOTION_DATABASE_ID="your_database_id"
    ```

    <Tip>
      You can find your database ID by:

      1. Opening your Notion changelog database
      2. Looking at the URL - it will be something like:
         [https://www.notion.so/your-workspace/DATABASE\_ID?v=](https://www.notion.so/your-workspace/DATABASE_ID?v=)...
      3. The DATABASE\_ID is the long string of characters between the last / and the ?
    </Tip>
  </Step>
</Steps>

## Running Gobi CLI with Notion API

<Card title="🚀 Choose Your Interface" icon="zap">
  Gobi CLI offers two powerful modes for Notion automation:
  **TUI mode** for interactive workflows and **Headless mode** for automated scripts.
</Card>

<Tabs>
  <Tab title="🖥️ TUI Mode (Interactive)">
    <Steps>
      <Step title="Launch Interactive Mode">
        Navigate to your project directory and run:

        ```bash  theme={null}
        cn 
        ```
      </Step>

      <Step title="Run Your First Prompt">
        In the TUI interface, enter:

        ```
        1. Fetch my Notion databases using the Notion API key
        and Database ID stored in this terminal session.
        2. Look at the last week of Merged GitHub PRs, and create
        a changelog entry in Notion summarizing the features and breaking changes.
        ```

        <Tip>
          TUI mode lets you review and approve each action before execution,
          perfect for learning and debugging.
        </Tip>
      </Step>
    </Steps>
  </Tab>

  <Tab title="🤖 Headless Mode (Automated)">
    <Steps>
      <Step title="Run Automated Commands">
        Execute prompts directly from the command line:

        ```bash  theme={null}
        cn -p --auto "
        1. Fetch my Notion databases using the Notion API key
        and Database ID stored in this terminal session.
        2. Analyze all merged GitHub PRs from the past week.
        3. Extract feature descriptions and breaking changes.
        4. Create a technical changelog in Notion with PR links."
        ```

        **Flags explained:**

        * `-p`: Run without TUI interface
        * `--auto`: Execute without manual approval

        <Warning>
          Always test prompts in TUI mode first before running
          them with `--auto` in production.
        </Warning>
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Accordion title="API Connection Notes">
  * Environment variable `NOTION_API_KEY` must be set before running Gobi CLI
  * Gobi automatically uses the API key to authenticate with Notion
  * No need for manual curl commands - just reference "the API key stored in this session"
  * For complex workflows, Gobi maintains the API connection throughout
  * Consider creating aliases or scripts for frequently used prompts
</Accordion>

***

## Quick Start Example

Working example that demonstrates the power of Gobi with Notion API:

<Card title="📊 Weekly Sprint Summary" icon="chart-line">
  **This exact command has been tested and works:**

  ```bash  theme={null}
  # Weekly Sprint Summary
  cn -p --auto "
  1. Fetch Notion Sprint database
  2. Analyze completed tasks vs planned
  3. Generate sprint retrospective page
  4. Add velocity metrics and burndown chart"
  ```

  **What this does:**

  1. Connects to your Notion workspace using the API key
  2. Analyzes your sprint data
  3. Calculates completion metrics
  4. Creates a comprehensive retrospective with visualizations
</Card>

## Example Prompts & Workflows

With the Notion API configured, you can use natural language prompts to automate your workspace. Here are examples for both TUI and headless modes:

<CardGroup cols={1}>
  <Card title="API Documentation" icon="code">
    **TUI Mode:**

    ```bash  theme={null}
    cn "
    1. Fetch my Notion databases using the API key and secrets stored in this session
    2. Generate API documentation for all endpoints 
    in src/api/routes with request/response schemas
    3. Create a page in Technical Docs database
    "
    ```

    **Headless Mode:**

    ```bash  theme={null}
    cn -p --auto "Fetch my Notion databases using the API key and secrets stored in this session. Generate API docs 
    for src/api/routes and save to Notion in Technical Docs database"
    ```
  </Card>

  <Card title="Sprint Planning from Code" icon="list-checks">
    **Headless Mode (Automated):**

    ```bash  theme={null}
    cn -p --auto "
    1. Fetch my Notion databases using the API key stored in this session
    2. Scan codebase for TODO and FIXME comments
    3. Create tasks in my Notion Engineering Backlog database
    4. Include file paths and complexity estimates"
    ```
  </Card>

  <Card title="Changelog from PRs" icon="rocket">
    ```bash  theme={null}
        cn -p --auto "
        1. Fetch my Notion databases using the API key stored in this session
        2. Analyze all merged GitHub PRs from past month
        3. In my Notion Launch Database, review the Launch Template.
        4. Create an October Launch doc in Notion with a week of launches and materials based on the Launch documents based on the PR analysis and launch documents."
    ```
  </Card>

  <Card title="Daily Standup Automation" icon="comments">
    ```bash  theme={null}
    cn -p --auto "
    1. Fetch my Tasks database from Notion using the API key
    2. Find tasks completed yesterday
    3. Find tasks in progress
    4. Create standup note with: completed, 
       in-progress, and blockers sections"
    ```
  </Card>
</CardGroup>

## Advanced Workflows

<CardGroup cols={1}>
  <Card title="Notion + GitHub" icon="github">
    ```bash  theme={null}
    cn -p --auto "
    1. Connect to Notion using the API key in this session
    2. Get merged PRs from last 7 days using GitHub
    3. Extract feature descriptions and changes
    4. Create formatted changelog in Notion
    5. Add links back to GitHub PRs"
    ```

    <Info>
      Requires GitHub repository access. To add GitHub access, update your [integration settings](https://hub.gourmand.dev/settings/integrations).
    </Info>
  </Card>

  <Card title="Test Coverage Report" icon="chart-bar">
    ```bash  theme={null}
    cn -p --auto "
    1. Connect to Notion using the API key in this session
    2. Run test coverage report (npm test -- --coverage)
    3. Parse coverage metrics
    4. Update Test Metrics database in Notion
    5. Flag files with coverage below 80%"
    ```
  </Card>

  <Card title="Blog Post Review" icon="magnifying-glass">
    ```bash  theme={null}
    cn "
    1. Connect to Notion using the API key in this session
    2. In my Blog Posts Database, find drafts tagged 'Review'
    3. Review all blog posts for grammar and clarity and suggest improvements through comments.
    ```
  </Card>

  <Card title="Weekly Report Generation" icon="list">
    ```bash  theme={null}
    cn -p --auto "
    1. Connect to Notion databases using API key
    2. Aggregate completed tasks from the week
    3. Calculate velocity and burndown metrics
    4. Generate weekly report with charts
    5. Share link in Slack #team-updates"
    ```
  </Card>
</CardGroup>

## Security Best Practices

<Warning>
  **Protect Your API Keys:**

  * Never commit `NOTION_API_KEY` to version control
  * Use environment variables or secure secret managers
  * Rotate API keys every 90 days
  * Grant integration access only to required databases/pages
  * Monitor API usage through Notion's integration dashboard
  * Use `.env` files with `.gitignore` for local development
</Warning>

## Next Steps

* Create a **GitHub Actions** workflow to automate changelog generation on releases
* Build a **daily standup bot** that runs every morning and posts to Slack
* Set up **database templates** in Notion for consistent formatting
* Explore **batch operations** to update multiple pages efficiently
* Implement **error handling** for API rate limits and network issues

***

## Troubleshooting

<Accordion title="Common Issues and Solutions">
  **API Key Not Found:**

  * Ensure `NOTION_API_KEY` is exported in your current shell session
  * Check for typos in the environment variable name
  * Verify the key starts with `secret_`

  **Database Access Denied:**

  * Share the specific database with your integration in Notion
  * Ensure the integration has the correct permissions (Read, Write, Insert)

  **Connection Issues:**

  * Verify Gobi CLI has internet access
  * Check network connectivity to api.notion.com
  * Ensure your Notion workspace allows API access

  **Rate Limiting:**

  * Notion API has rate limits (3 requests per second)
  * Implement exponential backoff for automated scripts
  * Consider batching operations when possible
</Accordion>


# Using Ollama with Gobi: A Developer's Guide
Source: https://docs.gourmand.dev/guides/ollama-guide

Complete guide to setting up Ollama with Gobi for local AI development. Learn installation, configuration, model selection, performance optimization, and troubleshooting for privacy-focused offline coding assistance

## What Are the Prerequisites for Using Ollama

Before getting started, ensure your system meets these requirements:

* Operating System: macOS, Linux, or Windows
* RAM: Minimum 8GB (16GB+ recommended)
* Storage: At least 10GB free space
* Gobi extension installed

## How to Install Ollama - Step-by-Step

### Step 1: Install Ollama

Choose the installation method for your operating system:

```
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Windows
# Download from ollama.ai
```

### Step 2: Start Ollama Service

After installation, start the Ollama service:

```bash  theme={null}
# Check Ollama version - verify it's installed
ollama --version

# Start Ollama (runs in background)
ollama serve

# Verify it's running
curl http://localhost:11434
# Should return "Ollama is running"
```

### Step 3: Download Models

<Warning>
  **Important**: Always use `ollama pull` instead of `ollama run` to download
  models. The `run` command starts an interactive session which isn't needed for
  Gobi.
</Warning>

Download models using the exact tag specified:

```bash  theme={null}
# Pull models with specific tags
ollama pull deepseek-r1:32b       # 32B parameter version
ollama pull deepseek-r1:latest     # Latest/default version
ollama pull mistral:latest
ollama pull qwen2.5-coder:1.5b

# List all downloaded models
ollama list
```

**Common Model Tags:**

* `:latest` - Default version (used if no tag specified)
* `:32b`, `:7b`, `:1.5b` - Parameter count versions
* `:instruct`, `:base` - Model variants

<Note>
  If a model page shows `deepseek-r1:32b` on Ollama's website, you must pull it
  with that exact tag. Using just `deepseek-r1` will pull `:latest` which may be
  a different size.
</Note>

## How to Configure Ollama with Gobi

There are multiple ways to configure Ollama models in Gobi:

### Method 1: Using Hub Model Blocks in Local config.yaml

The easiest way is to use [pre-configured model blocks](/reference#local-blocks) from the Gobi Hub in your local configuration:

```yaml title="~/.gobi/configs/config.yaml" theme={null}
name: My Local Config
version: 0.0.1
schema: v1
models:
  - uses: ollama/deepseek-r1-32b
  - uses: ollama/qwen2.5-coder-7b
  - uses: ollama/gpt-oss-20b
```

<Warning>
  **Important**: Hub blocks only provide configuration - you still need to pull
  the model locally. The hub block `ollama/deepseek-r1-32b` configures Gobi
  to use `model: deepseek-r1:32b`, but the actual model must be installed:

  ```bash  theme={null}
  # Check what the hub block expects (view on hub.gourmand.dev)
  # Then pull that exact model tag locally
  ollama pull deepseek-r1:32b  # Required for ollama/deepseek-r1-32b hub block
  ```

  If the model isn't installed, Ollama will return:
  `404 model "deepseek-r1:32b" not found, try pulling it first`
</Warning>

### Method 2: Using Autodetect

Gobi can automatically detect available Ollama models. You can configure this in your YAML:

```yaml title="~/.gobi/config.yaml" theme={null}
models:
  - name: Autodetect
    provider: ollama
    model: AUTODETECT
    roles:
      - chat
      - edit
      - apply
      - rerank
      - autocomplete
```

Or use it through the GUI:

1. Click on the model selector dropdown
2. Select "Autodetect" option
3. Gobi will scan for available Ollama models
4. Select your desired model from the detected list

<Note>
  The Autodetect feature scans your local Ollama installation and lists all
  available models. When set to `AUTODETECT`, Gobi will dynamically populate
  the model list based on what's installed locally via `ollama list`. This is
  useful for quickly switching between models without manual configuration. For
  any roles not covered by the detected models, you may need to manually
  configure them.
</Note>

You can update `apiBase` with the IP address of a remote machine serving Ollama.

### Method 3: Manual Configuration

For custom configurations or models not on the hub:

```yaml  theme={null}
models:
  - name: DeepSeek R1 32B
    provider: ollama
    model: deepseek-r1:32b # Must match exactly what `ollama list` shows
    apiBase: http://localhost:11434
    roles:
      - chat
      - edit
    capabilities: # Add if not auto-detected
      - tool_use
  - name: Qwen2.5-Coder 1.5B
    provider: ollama
    model: qwen2.5-coder:1.5b
    roles:
      - autocomplete
```

### Model Capabilities and Tool Support

Some Ollama models support tools (function calling) which is required for Agent mode. However, not all models that claim tool support work correctly:

#### Checking Tool Support

```yaml  theme={null}
models:
  - name: DeepSeek R1
    provider: ollama
    model: deepseek-r1:latest
    capabilities:
      - tool_use # Add this to enable tools
```

<Warning>
  **Known Issue**: Some models like DeepSeek R1 may show "Agent mode is not
  supported" or "does not support tools" even with capabilities configured. This
  is a known limitation where the model's actual tool support differs from its
  advertised capabilities.
</Warning>

#### If Agent Mode Shows "Not Supported"

<img src="https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/guides/images/agent-not-supported.png?fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=70fefc04b1c1ba63109e18fadcea0387" alt="agent not supported" data-og-width="918" width="918" data-og-height="1096" height="1096" data-path="images/guides/images/agent-not-supported.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/guides/images/agent-not-supported.png?w=280&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=95f1f74163acc6e841ed6e43a645a337 280w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/guides/images/agent-not-supported.png?w=560&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=9bdc96100fcf54ef0b9bcee5c1a0d257 560w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/guides/images/agent-not-supported.png?w=840&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=e574c5534008021678278524bc783d7d 840w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/guides/images/agent-not-supported.png?w=1100&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=ab720bb5b8e1df14b49f3f6db7447208 1100w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/guides/images/agent-not-supported.png?w=1650&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=0f303f00d2e15b9d075951be25a6d807 1650w, https://mintcdn.com/gourmand/rp15OrN3WARO_f_5/images/guides/images/agent-not-supported.png?w=2500&fit=max&auto=format&n=rp15OrN3WARO_f_5&q=85&s=69d0c55867402d2bc18a1af855e73fc4 2500w" />

1. First, add `capabilities: [tool_use]` to your model config
2. If you still get errors, the model may not actually support tools despite documentation
3. Use a different model known to work with tools (e.g., Llama 3.1, Mistral)
4. Alternatively, you can turn on [System Message tools](/ide-extensions/agent/model-setup#how-system-message-tools-work)

See the [Model Capabilities guide](/customize/deep-dives/model-capabilities) for more details.

### How to Configure Advanced Settings

For optimal performance, consider these advanced configuration options:

```yaml  theme={null}
models:
  - name: Optimized DeepSeek
    provider: ollama
    model: deepseek-r1:32b
    contextLength: 8192 # Adjust context window (default varies by model)
    completionOptions:
      temperature: 0.7 # Controls randomness (0.0-1.0)
      top_p: 0.9 # Nucleus sampling threshold
      top_k: 40 # Top-k sampling
      num_predict: 2048 # Max tokens to generate
    # Ollama-specific options (set via environment or modelfile)
    # num_gpu: 35        # Number of GPU layers to offload
    # num_thread: 8      # CPU threads to use
```

For GPU acceleration and memory tuning, create an Ollama Modelfile:

```
# Create custom model with optimizations
FROM deepseek-r1:32b
PARAMETER num_gpu 35
PARAMETER num_thread 8
PARAMETER num_ctx 4096
```

## What Are the Best Practices for Ollama

### How to Choose the Right Model

Choose models based on your specific needs (see [recommended models](/customization/models#recommended-models) for more options):

1. **Code Generation**:

   * `qwen2.5-coder:7b` - Excellent for code completion
   * `codellama:13b` - Strong general coding support
   * `deepseek-coder:6.7b` - Fast and efficient

2. **Chat & Reasoning**:

   * `llama3.1:8b` - Latest Llama with tool support
   * `mistral:7b` - Fast and versatile
   * `deepseek-r1:32b` - Advanced reasoning capabilities

3. **Autocomplete**:

   * `qwen2.5-coder:1.5b` - Lightweight and fast
   * `starcoder2:3b` - Optimized for code completion

4. **Memory Requirements**:
   * 1.5B-3B models: \~4GB RAM
   * 7B models: \~8GB RAM
   * 13B models: \~16GB RAM
   * 32B models: \~32GB RAM

### How to Optimize Performance

To get the best performance from Ollama:

* Monitor system resources with `ollama ps` to see memory usage
* Adjust context window size based on available RAM
* Use appropriate model sizes for your hardware
* Enable GPU acceleration when available (NVIDIA CUDA or AMD ROCm)
* Use `ollama logs` to debug performance issues

## How to Troubleshoot Ollama Issues

### Common Configuration Problems

#### "404 model not found, try pulling it first"

This error occurs when the model isn't installed locally:

**Problem**: Using a hub block or config that references a model not yet pulled
**Solution**:

```bash  theme={null}
# Check what models you have
ollama list

# Pull the exact model version needed
ollama pull model-name:tag  # e.g., deepseek-r1:32b
```

#### Model Tag Mismatches

**Problem**: `ollama pull deepseek-r1` installs `:latest` but hub block expects `:32b`
**Solution**: Always pull with the exact tag:

```bash  theme={null}
# Wrong - pulls :latest
ollama pull deepseek-r1

# Right - pulls specific version
ollama pull deepseek-r1:32b
```

#### "Agent mode is not supported"

**Problem**: Model doesn't support tools/function calling
**Solutions**:

1. Add `capabilities: [tool_use]` to your model config
2. If still not working, the model may not actually support tools
3. Switch to a model with confirmed tool support (Llama 3.1, Mistral)

#### Using Hub Blocks in Local Config

**Problem**: Unclear how to use hub models locally
**Solution**: Create a local agent file:

```yaml  theme={null}
# ~/.gobi/configs/config.yaml
name: Local Config
version: 0.0.1
schema: v1
models:
  - uses: ollama/model-name
```

### How to Fix Connection Problems

* Verify Ollama is running: `curl http://localhost:11434`
* Check service status: `systemctl status ollama` (Linux)
* Ensure port 11434 is not blocked by firewall
* For remote connections, set `OLLAMA_HOST=0.0.0.0:11434`

### How to Resolve Performance Issues

* Insufficient RAM: Use smaller models (7B instead of 32B)
* Model too large: Check available memory with `ollama ps`
* GPU issues: Verify CUDA/ROCm installation for GPU acceleration
* Slow generation: Adjust `num_gpu` layers in model configuration
* Check system diagnostics: `ollama ps` for active models and memory usage

## What Are Example Workflows with Ollama

### How to Use Ollama for Code Generation

```python  theme={null}
# Example: Generate a FastAPI endpoint
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    email: str
    age: int

@app.post("/users/")
async def create_user(user: User):
    # Gobi will help complete this implementation
    # Use Cmd+I (Mac) or Ctrl+I (Windows/Linux) to generate code
    pass
```

### How to Use Ollama for Code Review

Use Gobi with Ollama to:

* Analyze code quality
* Suggest improvements
* Identify potential bugs
* Generate documentation

## Conclusion

Ollama with Gobi provides a powerful local development environment for AI-assisted coding. You now have complete control over your AI models, ensuring privacy and enabling offline development workflows.

***

*This guide is based on Ollama v0.11.x and Gobi v1.1.x. Please check for updates regularly.*


# How to Use Gobi Guides
Source: https://docs.gourmand.dev/guides/overview

Comprehensive collection of practical guides for Gobi including model setup, local development with Ollama, offline usage, self-hosting, custom context providers, and advanced customization tutorials

## What Model & Setup Guides Are Available

* [Using Ollama with Gobi](/guides/ollama-guide) - Local AI development with Ollama
* [How to Self-Host a Model](/guides/how-to-self-host-a-model) - Self-hosting AI models
* [Running Gobi Without Internet](/guides/running-gobi-without-internet) - Offline development setup

## Continuous AI

* [Continuous AI: A Developer's Guide](/guides/continuous-ai) - Integrating AI into development workflows
* [How to Use Gobi CLI (cn)](/guides/cli) - Command-line interface for Gobi
* [Continuous AI Readiness Assessment](/guides/continuous-ai-readiness-assessment) - Evaluate team readiness for Continuous AI adoption
* [Notion + Gobi Guide](/guides/notion-gobi-guide) - Automate docs, tasks, and release workflows

## MCP Integration Cookbooks

Step-by-step guides for integrating Model Context Protocol (MCP) servers with Gobi:

* [Gobi Docs MCP Cookbook](/guides/gobi-docs-mcp-cookbook) - Use the Gobi Docs MCP to write cookbooks, guides, and documentation with AI-powered workflows
* [GitHub MCP Cookbook](/guides/github-mcp-gobi-cookbook) - Use GitHub MCP to list, filter, and summarize open issues and merged PRs, and post AI-generated comments
* [PostHog Session Analysis Cookbook](/guides/posthog-github-continuous-ai) - Analyze user behavior data to optimize your codebase with automatic issue creation
* [Netlify Performance Optimization Cookbook](/guides/netlify-mcp-continuous-deployment) - Optimize web performance with A/B testing and automated monitoring using Netlify MCP
* [Chrome DevTools Performance Cookbook](/guides/chrome-devtools-mcp-performance) - Measure and optimize web performance with automated traces, Core Web Vitals monitoring, and performance budgets
* [Sanity CMS Integration Cookbook](/guides/sanity-mcp-gobi-cookbook) - Manage headless CMS content with AI-powered workflows using Sanity MCP
* [Sentry Error Monitoring Cookbook](/guides/sentry-mcp-error-monitoring) - Automated error analysis with Sentry MCP to identify patterns and create actionable GitHub issues
* [Snyk + Gobi Hub Agent Cookbook (MCP)](/guides/snyk-mcp-gobi-cookbook) - Integrate Snyk MCP via Gobi Hub to scan code, deps, IaC, and containers
* [dlt Data Pipelines Cookbook](/guides/dlt-mcp-gobi-cookbook) - Build AI-powered data pipelines with dlt MCP for pipeline inspection, schema management, and debugging

## What Advanced Tutorials Are Available

* [Codebase and Documentation Awareness](/guides/codebase-documentation-awareness) - Make agent mode aware of codebases and documentation
* [Custom Code RAG](/guides/custom-code-rag) - Advanced: Build custom retrieval-augmented generation for large codebases

## How to Contribute to Guides

Have a guide idea or found an issue? We welcome contributions! Check our [GitHub repository](https://github.com/gourmand/gobi) to get involved.


# Using Plan Mode with Gobi
Source: https://docs.gourmand.dev/guides/plan-mode-guide

Plan Mode gives you a safe, read-only environment to explore your codebase, map out solutions, and collaborate with AI before making any changes. Think of it as your sandbox for understanding and strategy.

Plan Mode prevents unintentional file modifications, letting you think through solutions and build confidence before committing to action. The core principle is understand before you change, giving you a research-first approach that prevents costly mistakes and creates better architectural decisions.

<Accordion title="Learn how to choose the right mode" icon="lightbulb">
  <Columns cols={3}>
    <Card title="Chat Mode" icon="comments">
      *Learn and discuss without changing code.*

      **Mental Model:** Talking to a knowledgeable colleague
      **Best For:** Explaining concepts, comparing approaches, code review discussions.
    </Card>

    <Card title="Plan Mode" icon="binoculars">
      *Safely explore and plan with read-only tools.*

      **Mental Model:** Architect surveying before renovation
      **Best For:** Understanding a codebase, bug investigation, planning implementations.
    </Card>

    <Card title="Agent Mode" icon="hammer">
      *Make actual changes with full tool access.*

      **Mental Model:** Contractor executing approved blueprints
      **Best For:** Implementing features, fixing bugs, running tests and commands.
    </Card>
  </Columns>
</Accordion>

## What Are the Use Cases for Plan Mode

Plan Mode excels in four key scenarios where understanding before acting prevents expensive mistakes:

<Columns cols={2}>
  <Card title="Codebase Exploration" icon="map">
    Navigate unfamiliar systems and trace data flows without modification risk.

    [See exploration prompts →](#prompt-library)
  </Card>

  <Card title="Implementation Planning" icon="clipboard-list">
    Map dependencies and sequence complex changes before execution. <br />

    [See planning prompts →](#prompt-library)
  </Card>

  <Card title="Issue Investigation" icon="magnifying-glass">
    Debug systematically by tracing execution paths and analyzing root causes.{" "}

    [See debugging prompts →](#prompt-library)
  </Card>

  <Card title="Architecture Analysis" icon="building">
    Assess system health, identify bottlenecks, and plan improvements.

    [See analysis prompts →](#prompt-library)
  </Card>
</Columns>

## What Are the Best Practices for Plan Mode?

### How to Plan Faster

1. **Scope your requests**: `Focus analysis on the user authentication module only, ignore the admin features`
2. **Use targeted context**: `Analyze @Files and its direct imports for security issues`

### How to Create Higher Quality Plans

1. **Provide business context**: `This feature needs to handle Black Friday traffic (10x normal load). Plan accordingly.`
2. **Share technical constraints**: `We're on AWS with strict security requirements. Plan a file upload system that meets SOC2 compliance.`
3. **Ask for risk analysis**: `What could go wrong with this database migration? Plan rollback procedures.`
4. **Request multiple perspectives**: `Show me 3 different approaches to implementing caching in this API, with pros and cons for each.`

## How to Enable Plan Mode

You can switch to `Plan` in the mode selector below the chat input box.

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=ce952a30fb67850ea861248ceb0f253b" alt="How to select plan mode" data-og-width="1404" width="1404" data-og-height="390" height="390" data-path="images/plan-mode-selector.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=5722692b9d5c7dfdcfa633ccdc4f2025 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=35a7a3a004ef1551280e781738eea595 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=63f902eedc134e233aa96baaae383721 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=c0b559f8944bafe613dc72d2a84f88a6 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=eb336e8e9ffdaace2c683b8566c554a5 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=2782a35a74e6b471965247c1a0ac7201 2500w" />

## What Tools Are Available in Plan Mode?

| Tool                              | Available | Description                                          |
| :-------------------------------- | :-------- | :--------------------------------------------------- |
| **File/directory reading**        | ✅         | Browse and read any file or folder in your workspace |
| **Grep/glob search**              | ✅         | Search for patterns across files and directories     |
| **Repository structure analysis** | ✅         | Understand codebase organization and dependencies    |
| **Git history/diffs**             | ✅         | Review commits, branches, and changes                |
| **Web content fetching**          | ✅         | Access external documentation and resources          |
| **External API access**           | ✅         | Read-only calls to external services                 |
| **MCP tools**                     | ✅         | Model Context Protocol integrations                  |
| **Database schema examination**   | ✅         | Analyze database structure (read-only)               |
| **File creation/editing**         | ❌         | Creating or modifying files                          |
| **Terminal command execution**    | ❌         | Running shell commands                               |
| **System modifications**          | ❌         | Changing system settings or configurations           |
| **Package installation**          | ❌         | Installing dependencies or packages                  |
| **Git commits/pushes**            | ❌         | Making changes to version control                    |
| **Database modifications**        | ❌         | Altering database data or structure                  |

## How Context Integration Works in Plan Mode

Context is the foundation of effective planning. Without proper context, AI models fall back on generic patterns, leading to plans that don't fit your specific system. Gobi's [context system](/ide-extensions/chat/context-selection) transforms broad suggestions into actionable strategies:

| Context Type         | Usage                                                  | Best For                    |
| :------------------- | :----------------------------------------------------- | :-------------------------- |
| **Highlighted Code** | `cmd/ctrl + L` (VS Code) or `cmd/ctrl + J` (JetBrains) | Component-specific analysis |
| **Active File**      | `opt/alt + enter` when sending request                 | Current file context        |
| **@Files**           | `@Files package.json tsconfig.json`                    | Specific file analysis      |
| **@Terminal**        | `@Terminal`                                            | Debugging with output       |
| **@Git Diff**        | `@Git Diff`                                            | Change impact analysis      |

<Accordion title="Advanced Context Examples">
  <AccordionGroup>
    <Accordion title="Component Analysis">
      **After highlighting a React component**:
      `Analyze this component for performance bottlenecks and plan optimization strategies.`
    </Accordion>

    <Accordion title="Configuration Review">
      `@Files docker-compose.yml Dockerfile - Review our containerization setup and
        suggest improvements for production deployment.`
    </Accordion>

    <Accordion title="API Design Review">
      `@Folder src/api - Evaluate our REST API design patterns and identify
        opportunities for better consistency.`
    </Accordion>

    <Accordion title="Cross-Platform Migration">
      `@Codebase - Plan a strategy to migrate this web app to also support mobile using React Native.`
    </Accordion>
  </AccordionGroup>
</Accordion>

## Prompt Library

### Codebase Exploration

<AccordionGroup>
  <Accordion title="Understanding Systems">
    **Data Flow Analysis**:
    `Help me understand how state management works in this Redux app. Map out the data flow from actions to components.`

    **Microservices Communication**:
    `Analyze how our microservices communicate and identify potential bottlenecks in service-to-service calls.`

    **Database Schema Review**:
    `Examine the database schema and relationships to understand how user data is structured and accessed.`
  </Accordion>

  <Accordion title="Legacy Code Investigation">
    **System Mapping**:
    `Map out this legacy codebase architecture. What are the main components and how do they communicate?`

    **Technical Debt Assessment**:
    `Analyze this codebase for technical debt hotspots and maintenance pain points.`

    **Modernization Planning**:
    `Assess this legacy system and recommend modernization opportunities that provide the highest impact with lowest risk.`
  </Accordion>
</AccordionGroup>

### Implementation Planning

<AccordionGroup>
  <Accordion title="Migrations & Upgrades">
    **Cloud Migration**:
    `Plan a migration from on-premise servers to AWS, considering our current Node.js application architecture.`

    **Package Manager Migration**:
    `Create a plan to migrate from npm to pnpm, analyzing dependencies and potential breaking changes.`

    **Monorepo Conversion**:
    `Plan how to convert our multiple repositories into a single monorepo using Nx or Lerna.`
  </Accordion>

  <Accordion title="Refactoring & Integration">
    **Service Extraction**:
    `Plan a refactor to extract shared authentication logic into a reusable service across these microservices.`

    **Payment Integration**:
    `We need to add Stripe payments to this e-commerce app. Plan the integration considering our current architecture.`

    **API Migration**:
    `@Codebase - Plan a migration from REST to GraphQL across our entire API.`
  </Accordion>
</AccordionGroup>

### Issue Investigation

<AccordionGroup>
  <Accordion title="Performance Problems">
    **Dashboard Performance**:
    `Users report slow page loads on the dashboard. Investigate performance bottlenecks in the @Files and related components.`

    **API Optimization**:
    `Plan a performance optimization strategy for this Node.js API, focusing on database queries and caching.`

    **Bundle Analysis**:
    `Analyze this React app for performance bottlenecks. What are the most expensive operations?`
  </Accordion>

  <Accordion title="Bug Investigation">
    **Race Condition Analysis**:
    `Users occasionally see stale data in the UI. Investigate potential race conditions in our async data fetching.`

    **Production Incidents**:
    `@Git Diff We're seeing 500 errors in production. Analyze recent changes and identify what might be causing the issue.`

    **Deployment Issues**:
    `Our staging environment works fine, but production deployments fail. Analyze environment differences.`
  </Accordion>
</AccordionGroup>

### Architecture Analysis

<AccordionGroup>
  <Accordion title="Scalability & Performance">
    **Traffic Planning**:
    `Analyze this @codebase architecture and identify potential bottlenecks for handling 10x more traffic.`

    **CDN Implementation**:
    `Plan a CDN strategy for our global user base, considering asset optimization and edge caching.`

    **Caching Strategy**:
    `Show me 3 different approaches to implementing caching in this API, with pros and cons for each.`
  </Accordion>

  <Accordion title="Security & Compliance">
    **Security Audit**:
    `Audit this API for security vulnerabilities, focusing on authentication, authorization, and data validation.`

    **Threat Modeling**:
    `Model potential security threats for this user registration flow and plan mitigation strategies.`

    **Compliance Planning**:
    `Plan GDPR compliance implementation for this user data handling system.`
  </Accordion>
</AccordionGroup>

## How to Transition From Plan to Execution

### When to Transition to Agent Mode

Move to Agent Mode when you have:

✅ **Clear understanding** of the current system\
✅ **Detailed implementation plan** with specific steps\
✅ **Risk assessment** and mitigation strategies\
✅ **Team approval** (if required)\
✅ **Success criteria** defined

### Key Takeaways

The three-mode system—Chat mode for learning, Plan mode for strategy, and Agent mode for execution—provides a complete development workflow that scales from simple bug fixes to complex system architecture.

**Remember:**

* Choose the right mode for each task
* Start broad, then focus your planning sessions for better results
* Transition to Agent mode with clear execution steps

The best code is planned code.


# Building a Continuous AI Workflow with PostHog and GitHub
Source: https://docs.gourmand.dev/guides/posthog-github-continuous-ai

Build an automated system that continuously monitors PostHog analytics, analyzes user behavior with AI, and creates GitHub issues automatically using PostHog MCP.

<Card title="What You'll Build" icon="robot">
  A fully automated workflow that uses Gobi CLI with the PostHog MCP to fetch analytics data, analyze user experience issues with AI, and automatically create GitHub
  issues with the GitHub CLI.
</Card>

## What You'll Learn

This cookbook teaches you to:

* Use [PostHog MCP](https://posthog.com/docs/model-context-protocol) to query [analytics](https://posthog.com/docs/web-analytics), [errors](https://posthog.com/docs/error-tracking), and [feature flags](https://posthog.com/docs/feature-flags)
* Analyze user behavior patterns with AI
* Automatically create GitHub issues using GitHub CLI
* Set up continuous monitoring with GitHub Actions

## Prerequisites

Before starting, ensure you have:

* GitHub repository where you want to create issues
* [PostHog account](https://posthog.com) with [session recordings enabled](https://posthog.com/docs/session-replay/installation) and data collecting
* Node.js 18+ installed locally
* [Gobi CLI](https://docs.gourmand.dev/guides/cli) with **active credits** (required for API usage)
* [GitHub CLI](https://cli.github.com/) installed (`gh` command)

<Steps>
  <Step title="Install Gobi CLI">
    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```
  </Step>

  <Step title="Set up Gobi CLI Account & API Key">
    1. Visit [Gobi Organizations](https://hub.gourmand.dev/settings/organizations)
    2. Sign up or log in to your Gobi account
    3. Navigate to your organization settings
    4. Click **"API Keys"** and then **"+ New API Key"**
    5. Copy the API key immediately (you won't see it again!)
    6. Login to the CLI: `cn login`
  </Step>

  <Step title="Add Required Secrets to Gobi CLI">
    Gobi CLI will securely store your API keys as secrets that can be referenced in prompts.
  </Step>
</Steps>

<Tip>
  Gobi CLI handles the complex API interactions - you just need to provide
  the right prompts!
</Tip>

## Step 1: Set Up Your Credentials

First, you'll need to gather your PostHog and GitHub API credentials and add them as secrets in Gobi CLI.

<Tabs>
  <Tab title="PostHog API Credentials">
    You'll need a **Personal API Key** (not a Project API key) to access session recordings:

    1. Go to [Personal API Keys](https://app.posthog.com/settings/user-api-keys) in PostHog
    2. Click **+ Create a personal API Key**
    3. Name it "Gobi CLI Session Analysis"
    4. Select these scopes:
       * `session_recording:read` - **Required** for accessing session data
       * `feature_flag:read` - **Required** for feature flag auditing
       * `insight:read`
       * `query:read`
       * `session_recording_playlist:read`
    5. Copy the key immediately (you won't see it again!)
    6. Note your **Project ID** from your PostHog project settings
    7. Note your PostHog host URL (e.g., `https://us.posthog.com` or your custom domain)
    8. You'll also need your POSTHOG\_AUTH\_HEADER value, which is simply `Bearer YOUR_API_KEY`

    <Info>
      **Gobi Secrets**: The `POSTHOG_AUTH_HEADER` secret should be stored in
      Gobi's secure secrets storage. This keeps your API key safe and the MCP
      automatically connects to your default PostHog project.
    </Info>
  </Tab>

  <Tab title="Set Up GitHub CLI Authentication">
    GitHub CLI handles authentication automatically - no manual PAT needed:

    1. Install GitHub CLI if not already installed
    2. Run `gh auth login` and follow the prompts
    3. Choose authentication method (browser or token)
    4. Grant necessary permissions when prompted (`issues:write` is **required** for creating issues)
  </Tab>

  <Tab title="Configure API Access in Gobi CLI">
    <Tip>
      See [https://docs.gourmand.dev/hub/secrets/secret-types#secret-types](https://docs.gourmand.dev/hub/secrets/secret-types#secret-types) for adding secrets
    </Tip>

    You only need to configure the PostHog MCP credential - it automatically handles project selection. To add environment variables to your Gobi Hub account:

    1. Go to the [Gobi Hub](https://hub.gourmand.dev)
    2. Sign in to your account
    3. Navigate to your user settings
    4. Look for the "Secrets" section
    5. Add your Personal API Key from PostHog (phx\_...) as POSTHOG\_AUTH\_HEADER secret with format: Bearer YOUR\_API\_KEY
  </Tab>
</Tabs>

## PostHog GitHub Continuous AI Workflow Options

<Card title="🚀 Fastest Path to Success" icon="zap">
  Skip the manual setup and use our pre-built PostHog GitHub agent that includes
  optimized prompts, rules, and the PostHog MCP for more consistent results.
</Card>

<Info>
  **How PostHog MCP Works**:

  * Your API key is tied to your PostHog account and
    organization
  * It automatically uses your default project (no project ID
    needed)
  * If you have multiple projects, use `mcp__posthog__switch-project` to
    change
  * The MCP connects via `https://mcp.posthog.com/sse` using your account context.
</Info>

<Tabs>
  <Tab title="⚡ Quick Start (Recommended)">
    **Perfect for:** Immediate results with optimized prompts and built-in debugging

    <Steps>
      <Step title="Add the Pre-Built Agent">
        Visit the [PostHog GitHub Continuous AI Agent](https://hub.gourmand.dev/gobi/awesome-models-posthog-gh) on Gobi Hub and click **"Install Agent"** or run:

        ```bash  theme={null}
        cn --config gourmand/awesome-models-posthog-gh
        ```

        This agent includes:

        * **Optimized prompts** for [PostHog analysis](https://hub.gourmand.dev/gobi/posthog-analysis) and [GitHub issue creation](https://hub.gourmand.dev/gobi/posthog-github-issues)
        * **[Built-in rules](https://hub.gourmand.dev/bekah-hawrot-weigel/posthog-github-continuous-ai-rules)** for consistent formatting and error handling
        * **[PostHog MCP](https://hub.gourmand.dev/posthog/posthog-mcp)** for more reliable API interactions
      </Step>

      <Step title="Run the Analysis">
        From your project directory, run:

        ```bash  theme={null}
        cn "Give me my PostHog Session data and create GitHub issues based on the problems."
        ```

        That's it! The agent handles everything automatically.
      </Step>
    </Steps>

    <Info>
      **Why Use the Agent?** Results are more consistent and debugging is easier thanks to the PostHog MCP integration and pre-tested prompts.
    </Info>
  </Tab>

  <Tab title="🛠️ Manual Setup">
    <Steps>
      <Step title="Add PostHog MCP to Gobi CLI">
        First, install the [PostHog MCP](https://hub.gourmand.dev/posthog/posthog-mcp) or run:

        ```bash  theme={null}
        npx -y mcp-remote@latest https://mcp.posthog.com/sse --header Authorization:${{ secrets.gourmand/awesome-models-posthog-gh/posthog/posthog-mcp/POSTHOG_AUTH_HEADER }}
        ```
      </Step>

      <Step title="Add PostHog + GitHub Analysis Rules">
        In the Gobi Hub, add the [PostHog GitHub Continuous AI Rules](https://hub.gourmand.dev/bekah-hawrot-weigel/posthog-github-continuous-ai-rules) to your account for better formatting and error handling.
      </Step>

      <Step title="Create Your Custom Prompts">
        Use this prompt with Gobi CLI to analyze PostHog data and create GitHub issues:

        ```bash  theme={null}

         # In cn TUI mode:
        "Create GitHub issues from the PostHog analysis using gh CLI:
        - For each issue, run: gh issue create --title '🔍 UX Issue: [title]' --body '[details]'
        - Add labels: --label 'bug,user-experience,automated'
        - Set priority labels (high/medium/low)
        - Include session data and technical details in the body
        Execute the commands and confirm each issue was created with URL."
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Info>
  **Why GitHub CLI over GitHub MCP**: While GitHub MCP is available, it can be
  token-expensive to run. The `gh` CLI is more efficient, requires no API tokens
  (authenticated via `gh auth login`), and provides a cleaner command-line
  experience. GitHub MCP remains an option if you prefer full MCP integration.
</Info>

<Accordion title="Agent Requirements">
  To use the pre-built agent, you need either:

  * **Gobi CLI Pro Plan** with
    the models add-on, OR
  * **Your own API keys** added to Gobi Hub secrets
    (same as Step 1 below) The agent will automatically detect and use your
    configuration.
</Accordion>

***

<Warning>
  **Repository Labels Required**: Make sure your GitHub repository has these labels:

  * `bug`, `enhancement`, `technical-debt`
  * `high-priority`, `medium-priority`, `low-priority`
  * `user-experience`, `automated`, `feature-flag`, `cleanup`

  Create missing labels in your repo at: **Settings → Labels → New label**
</Warning>

<Info>
  **What Gobi CLI Does:**

  * Parses your analysis results automatically
  * Makes authenticated GitHub API calls using your stored token
  * Creates properly formatted issues with appropriate labels
  * Checks for duplicate issues to avoid spam
  * Provides confirmation with issue URLs
</Info>

## What You've Built

After completing this guide, you have a complete **Continuous AI system** that:

* **Monitors user experience** - Automatically fetches and analyzes PostHog session data

* **Identifies problems intelligently** - Uses AI to spot patterns and technical issues

* **Creates actionable tasks** - Generates GitHub issues with specific recommendations

* **Runs autonomously** - Operates daily without manual intervention using GitHub Actions

* **Scales with your team** - Handles growing amounts of session data automatically

<Card title="Continuous AI" icon="rocket">
  Your system now operates at **[Level 2 Continuous
  AI](https://blog.gourmand.dev/what-is-continuous-ai-a-developers-guide/)** -
  AI handles routine analysis tasks with human oversight through GitHub issue
  review and prioritization.
</Card>

## Security Best Practices

<Warning>
  **Protect Your API Keys:**

  * Store all credentials as GitHub Secrets, never in
    code
  * Use Gobi CLI's secure secret storage
  * Limit token scopes to minimum required permissions
  * Rotate API keys regularly (every 90 days recommended)
  * Monitor token usage for unusual activity
</Warning>

## Example Use Cases

Here are practical examples of what you can build with PostHog MCP and Gobi CLI:

### Session Recording Analysis (Current Implementation)

The main workflow above focuses on analyzing session recordings to identify UX issues and create GitHub issues automatically.

### Feature Flag Audit and Cleanup

<Card title="🏁 Feature Flag Management" icon="flag">
  Automatically audit your feature flags to identify unused, outdated, or problematic flags that need attention.
</Card>

**What this workflow does:**

* Fetches all feature flags from your PostHog project
* Analyzes flag usage, rollout status, and configuration
* Identifies flags that may be candidates for removal or updates
* Creates GitHub issues for flag cleanup tasks

**Example Gobi CLI prompts:**

```bash  theme={null}
# Get all feature flags and analyze them
cn "Use PostHog MCP to fetch all feature flags with mcp__posthog__feature-flag-get-all. Then analyze each flag to identify: 1) Flags that are 100% rolled out and could be removed, 2) Flags that haven't been updated in 90+ days, 3) Flags with complex targeting that might need simplification, 4) Experimental flags that should be cleaned up."

# Create cleanup issues for identified flags
cn "For each problematic feature flag identified, create a GitHub issue using gh CLI:
- Title: '🏁 Feature Flag Cleanup: [flag_name]'
- Include flag details: rollout percentage, last modified date, targeting rules
- Add labels: 'technical-debt', 'feature-flag', 'cleanup'
- Set priority based on risk level (high for 100% rollouts, medium for stale flags)
- Include specific recommendations for each flag"

# Audit flag performance impact
cn "Cross-reference feature flags with PostHog performance metrics to identify flags that may be impacting user experience or site performance. Create performance-focused GitHub issues for flags showing negative impact."
```

**Required PostHog MCP Tools:**

* `feature-flag-get-all` - Retrieve all feature flags
* `feature-flag-get-definition` - Get detailed flag configuration
* `query-run` - Run analytics queries to check flag usage
* `insights-get-all` - Get insights related to flag performance

**Sample Output:**
This workflow creates GitHub issues like:

* "🏁 Feature Flag Cleanup: dark-mode-toggle" (100% rollout, safe to remove)
* "🏁 Feature Flag Review: experimental-checkout" (unused for 120 days)
* "🏁 Feature Flag Simplify: complex-user-targeting" (overly complex rules)

### Advanced Prompts

Consider enhancing your workflow with these advanced Gobi CLI prompts:

<CardGroup cols={2}>
  <Card title="Performance Analysis" icon="chart-line">
    "Analyze [PostHog performance
    metrics](https://posthog.com/docs/web-analytics) alongside session
    recordings to identify slow page loads affecting user experience"
  </Card>

  <Card title="Error Correlation" icon="bug">
    "Cross-reference JavaScript console errors with user actions to identify the
    root cause of UX issues"
  </Card>

  <Card title="Feature Flag Performance Impact" icon="flag">
    "Use PostHog MCP to correlate feature flag rollouts with performance metrics and user behavior changes to identify flags causing issues"
  </Card>

  <Card title="Custom Slack Alerts" icon="slack">
    "Create Slack alerts when critical UX issues are detected in PostHog
    sessions or when feature flags need attention"
  </Card>
</CardGroup>

## Next Steps

* Consider [GitHub MCP](https://hub.gourmand.dev/github/github-mcp) as an alternative (note: can be token-expensive)
* Configure [Slack MCP](https://hub.gourmand.dev/slack/slack-mcp) for alerts
* Set up [PostHog performance monitoring](https://posthog.com/docs/web-analytics)
* Join the [Gobi Discord](https://discord.gg/gobi) for support

## Resources

* [PostHog API Documentation](https://posthog.com/docs/api)
* [PostHog MCP Documentation](https://posthog.com/docs/model-context-protocol)
* [PostHog Session Replay](https://posthog.com/docs/session-replay)
* [PostHog Feature Flags](https://posthog.com/docs/feature-flags)
* [PostHog Error Tracking](https://posthog.com/docs/error-tracking)
* [GitHub CLI Documentation](https://cli.github.com/)
* [GitHub MCP on Gobi Hub](https://hub.gourmand.dev/github/github-mcp) (alternative option)
* [Gobi CLI Guide](https://docs.gourmand.dev/guides/cli)
* [Continuous AI Best Practices](https://blog.gourmand.dev/what-is-continuous-ai-a-developers-guide/)


# How to Run Gobi Without Internet
Source: https://docs.gourmand.dev/guides/running-gobi-without-internet

Learn how to set up Gobi for air-gapped or offline environments using local models, including steps to disable telemetry and configure local model providers

1. Download the latest .vsix file from the [GitHub Releases page](https://github.com/gourmand/gobi/releases) and [install it to VS Code](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix).
2. Turn off "Allow Anonymous Telemetry" in the user settings. This will stop Gobi from attempting requests to PostHog for [anonymous telemetry](https://docs.gourmand.dev/reference/telemetry).
3. In your `config.yaml` file (or through the Gobi UI), set the default model to a local model. You can find available local model options [here](https://docs.gourmand.dev/reference/model-providers/ollama).
4. Restart VS Code to ensure that the changes to `config.yaml` take effect.


# Content Management with Sanity MCP and Gobi
Source: https://docs.gourmand.dev/guides/sanity-mcp-gobi-cookbook

Set up an AI-powered content management workflow that helps you manage schemas, run GROQ queries, handle documentation, and perform migrations using natural language commands.

<Card title="What You'll Build" icon="database">
  An AI-powered content management system workflow that uses Gobi's AI agent with Sanity
  MCP to manage schemas, execute GROQ queries, handle migrations, and maintain documentation - all through simple natural language prompts
</Card>

## Prerequisites

Before starting, ensure you have:

* Gobi account with **Hub access**
  * Read: [Understanding Configs — How to get started with Hub configs](/hub/configs/intro)
* Node.js 20+ installed locally
* A [Sanity account](https://www.sanity.io/) and project (free tier works)
* Basic understanding of content management systems

For all options, first:

<Steps>
  <Step title="Install Gobi CLI">
    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```
  </Step>

  <Step title="Install Sanity CLI">
    ```bash  theme={null}
    npm install -g @sanity/cli
    ```
  </Step>
</Steps>

<Warning>
  To use agents in headless mode, you need a [Gobi API key](https://hub.gourmand.dev/settings/api-keys) and proper environment variable configuration.
</Warning>

## Getting Started with Sanity

<Accordion title="New to Sanity? Start Here">
  New to Sanity? Follow the [Sanity Getting Started Guide](https://www.sanity.io/docs/getting-started) to set up your first project.

  **Quick setup:**

  ```bash  theme={null}
  npm create sanity@latest
  cd your-project-name
  npm run dev
  ```

  **Key resources:**

  * [Sanity Studio](https://www.sanity.io/docs/sanity-studio) - Content editing interface
  * [Schema Types](https://www.sanity.io/docs/schema-types) - Define content structure
  * [GROQ](https://www.sanity.io/docs/groq) - Query language for fetching content
  * [Content Lake](https://www.sanity.io/docs/datastore) - Real-time data store
</Accordion>

## Sanity MCP Workflow Options

<Card title="Fastest Path to Success" icon="rocket">
  Skip the manual setup and use our pre-built Sanity Assistant agent that includes
  the Sanity MCP and optimized content management workflows for more consistent results. You can [remix this agent](/guides/understanding-configs#how-to-get-started-with-hub-configs) to customize it for your specific needs.
</Card>

After ensuring you meet the **Prerequisites** above, you have two paths to get started:

<Tabs>
  <Tab title="⚡ Quick Start (Recommended)">
    <Steps>
      <Step title="Load the Pre-Built Agent">
        Visit the [Sanity Agent Config](https://hub.gourmand.dev/gobi/sanity-agent-config) on Gobi Hub and click **"Install Agent"** or run:

        ```bash  theme={null}
        cn --config gourmand/sanity-agent-config
        ```

        This agent includes:

        * **[Sanity MCP](https://hub.gourmand.dev/sanity/sanity-mcp)** pre-configured and ready to use
        * **Content management rules** for best practices
        * **Schema optimization** guidelines
      </Step>

      <Step title="Your First MCP Conversation">
        Start with these beginner-friendly prompts to explore your content:

        ```bash  theme={null}
        # Content exploration
        "Show me all blog posts published in the last month"

        # Schema understanding  
        "Show me all the document types in my Sanity schema and explain their relationships"

        # Content management
        "Create a new product page for our upcoming feature"
        ```

        That's it! The agent handles everything automatically. For more starter prompts and examples, see the [official Sanity MCP blog post](https://www.sanity.io/blog/model-context-protocol).
      </Step>
    </Steps>

    <Info>
      **Why Use the Agent?** The pre-built Sanity Assistant agent provides consistent content management workflows and handles MCP configuration automatically, making it easier to get started with AI-powered CMS operations. Results are more consistent and debugging is easier thanks to the [Sanity MCP](https://hub.gourmand.dev/sanity/sanity-mcp) integration and pre-tested prompts.
    </Info>
  </Tab>

  <Tab title="🛠️ Manual Setup">
    <Steps>
      <Step title="Create a New Agent via the Gobi Hub">
        Go to the [Gobi Hub](https://hub.gourmand.dev) and [create a new agent](https://hub.gourmand.dev/new?type=agent).
      </Step>

      <Step title="Connect Sanity MCP via Gobi Hub">
        Visit the [Sanity MCP on Gobi Hub](https://hub.gourmand.dev/sanity/sanity-mcp) and click **"Install"** to add it to the agent you created in the step above.

        This will add Sanity MCP to your agent's available tools. The Hub listing automatically configures the MCP connection.

        <Tip>
          **Alternative installation methods:**

          1. **Quick CLI install**: `cn --mcp sanity/sanity-mcp`
          2. **With config**: Use [Sanity MCP Config](https://hub.gourmand.dev/sanity/sanity-mcp-config) for environment variable setup
          3. **Manual configuration**: Add the MCP to your agent configuration

          Once installed, Sanity MCP tools become available to your Gobi agent for all prompts.
        </Tip>

        <Info>
          **Authentication Options:**

          * **Interactive mode**: OAuth authentication via browser (expires after 7 days)
          * **Headless/CI mode**: Uses environment variables (SANITY\_API\_TOKEN, SANITY\_PROJECT\_ID, etc.)

          See [Sanity MCP Config](https://hub.gourmand.dev/sanity/sanity-mcp-config) for environment variable setup.
        </Info>
      </Step>

      <Step title="Your First MCP Conversation">
        Start with these beginner-friendly prompts:

        ```bash  theme={null}
        cn
        # Try these starter prompts:
        # "Show me all blog posts published in the last month"
        # "Show me all the document types in my Sanity schema and explain their relationships"
        # "Create a new product page for our upcoming feature"
        ```

        For more examples, see the [Sanity MCP blog post](https://www.sanity.io/blog/model-context-protocol).
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Accordion title="Agent Requirements">
  To use the pre-built Sanity Assistant agent, you need either:

  * **Gobi CLI Pro Plan** with the models add-on, OR
  * **Your own API keys** added to Gobi Hub secrets

  The agent will automatically detect and use your configuration along with the pre-configured Sanity MCP for content operations. Note that OAuth authentication will be required on first use.
</Accordion>

***

## Sanity MCP Capabilities

<Card title="Understanding the Capabilities" icon="info-circle">
  **Sanity MCP** provides comprehensive tools for content management:

  * Execute [GROQ queries](https://www.sanity.io/docs/groq) to fetch and analyze content
  * Explore and modify [document schemas](https://www.sanity.io/docs/schema-types)
  * Manage [content releases](https://www.sanity.io/docs/release-schedules) and versions
  * Handle content [migrations](https://www.sanity.io/docs/migrating-data) between environments
  * Automate documentation generation
  * Perform bulk content operations
  * Manage [localization](https://www.sanity.io/docs/localization) and translations

  The MCP integrates seamlessly with your existing Sanity workspace, providing AI-powered assistance for both development and content operations.
</Card>

***

## Your First MCP Conversation

With everything set up, you're ready for your first AI-powered content conversation! Try these beginner-friendly starter prompts:

<CardGroup cols={2}>
  <Card title="Content Discovery" icon="search">
    ```
    "Show me all blog posts published in the last month"
    ```
  </Card>

  <Card title="Content Creation" icon="plus">
    ```
    "Create a new product page for our upcoming feature"
    ```
  </Card>

  <Card title="Content Updates" icon="edit">
    ```
    "Update our pricing information across all service pages"
    ```
  </Card>

  <Card title="Content Scheduling" icon="calendar">
    ```
    "Schedule the Easter marketing campaign content release for next Tuesday"
    ```
  </Card>
</CardGroup>

<Info>
  **New to MCP?** These prompts demonstrate the power of natural language content management. For more examples and detailed explanations, check out the [official Sanity MCP blog post](https://www.sanity.io/blog/model-context-protocol).
</Info>

## Content Management Recipes

Now you can use natural language prompts to manage your Sanity content and schemas. The Gobi agent automatically calls the appropriate Sanity MCP tools.

<Info>
  You can add prompts to your agent's configuration for easy access in future sessions. Go to your agent in the [Gobi Hub](https://hub.gourmand.dev), click **Edit**, and add prompts under the **Prompts** section.
</Info>

<Info>
  **Where to run these workflows:**

  * **IDE Extensions**: Use Gobi in VS Code, JetBrains, or other supported IDEs
  * **Terminal (TUI mode)**: Run `cn` to enter interactive mode, then type your prompts
  * **CLI (headless mode)**: Use `cn -p "your prompt"` for headless commands

  **Test in Plan Mode First**: Before running operations that might make
  changes, test your prompts in plan mode (see the [Plan Mode
  Guide](/guides/plan-mode-guide); press **Shift+Tab** to switch modes in TUI/IDE). This
  shows you what the agent will do without executing it.
</Info>

<Info>
  **About the --auto flag**: The `--auto` flag enables tools to run continuously without manual confirmation. This is essential for headless mode where the agent needs to execute multiple tools automatically to complete tasks like schema exploration, GROQ execution, and content migration.
</Info>

### Schema Management

<Card title="Explore Document Types" icon="diagram-project">
  Review and understand your content schema structure.

  **TUI Mode Prompt:**

  ```
  Show me all document types in my Sanity schema with their fields,
  validation rules, and relationships to other types.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Show me all document types in my Sanity schema with their fields, validation rules, and relationships to other types." --auto
  ```
</Card>

### GROQ Queries

<Card title="Execute GROQ Queries" icon="magnifying-glass">
  Run GROQ queries to fetch and analyze content.

  **TUI Mode Prompt:**

  ```
  Run a GROQ query to fetch all articles published in the last 30 days,
  including their titles, authors, categories, and view counts.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Run a GROQ query to fetch all articles published in the last 30 days, including their titles, authors, categories, and view counts." --auto
  ```
</Card>

### Content Operations

<Card title="Bulk Content Updates" icon="arrows-rotate">
  Perform bulk operations on your content.

  **TUI Mode Prompt:**

  ```
  Find all blog posts with the category "News" and update their
  status to "archived" if they are older than 6 months.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Find all blog posts with the category 'News' and update their status to 'archived' if they are older than 6 months." --auto
  ```
</Card>

### Localization

<Card title="Add Localization Support" icon="language">
  Set up and manage content translations.

  **TUI Mode Prompt:**

  ```
  Add localization support to my article document type for
  Spanish and French languages with appropriate field configurations.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Add localization support to my article document type for Spanish and French languages with appropriate field configurations." --auto
  ```
</Card>

### Content Migration

<Card title="Migrate Content Structure" icon="right-left">
  Migrate content between different schemas or environments.

  **TUI Mode Prompt:**

  ```
  Help me migrate my blog posts from the old schema structure
  to the new one, mapping the deprecated fields to the new format.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Help me migrate my blog posts from the old schema structure to the new one, mapping the deprecated fields to the new format." --auto
  ```
</Card>

### Documentation Generation

<Card title="Generate Schema Documentation" icon="book">
  Automatically generate documentation for your content model.

  **TUI Mode Prompt:**

  ```
  Generate comprehensive documentation for my Sanity schema including
  all document types, their purposes, field descriptions, and usage examples.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Generate comprehensive documentation for my Sanity schema including all document types, their purposes, field descriptions, and usage examples." --auto
  ```
</Card>

### Content Releases

<Card title="Manage Content Releases" icon="rocket">
  Work with Sanity's content release feature.

  **TUI Mode Prompt:**

  ```
  List all active releases in my dataset and show me the content
  changes scheduled for each release.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "List all active releases in my dataset and show me the content changes scheduled for each release." --auto
  ```
</Card>

### Performance Analysis

<Card title="Analyze Query Performance" icon="gauge-high">
  Optimize GROQ queries for better performance.

  **TUI Mode Prompt:**

  ```
  Analyze the performance of my most frequent GROQ queries and
  suggest optimizations to improve response times.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Analyze the performance of my most frequent GROQ queries and suggest optimizations to improve response times." --auto
  ```
</Card>

## Continuous Content Management with GitHub Actions

This example demonstrates a **Continuous AI workflow** where content validation and schema checks run automatically in your CI/CD pipeline in headless mode using the Sanity agent config. Consider [remixing this agent](/guides/understanding-configs#how-to-get-started-with-hub-configs) to add your organization's specific content governance rules.

### Add GitHub Secrets

Navigate to **Repository Settings → Secrets and variables → Actions** and add:

* `GOBI_API_KEY`: Your Gobi API key from [hub.gourmand.dev/settings/api-keys](https://hub.gourmand.dev/settings/api-keys)
* `SANITY_PROJECT_ID`: Your Sanity project ID
* `SANITY_DATASET`: Your Sanity dataset name (usually "production")
* `SANITY_API_TOKEN`: Your Sanity API token with appropriate permissions
* `MCP_USER_ROLE`: Your MCP user role (typically "admin" or "editor")

<Info>
  The workflow uses the [Sanity Agent Config](https://hub.gourmand.dev/gobi/sanity-agent-config) with environment variable authentication via [Sanity MCP Config](https://hub.gourmand.dev/sanity/sanity-mcp-config). This enables headless mode operation without OAuth browser authentication.
</Info>

### Create Workflow File

This workflow automatically validates your Sanity schemas and content on pull requests using the Gobi CLI in [headless mode](/cli/overview#headless-mode%3A-production-automation). It checks schema integrity, validates content relationships, and posts a summary report as a PR comment.

Create `.github/workflows/sanity-content-validation.yml` in your repository:

```yaml  theme={null}
name: Sanity Content Validation with MCP

on:
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  validate-content:
    runs-on: ubuntu-latest
    env:
      GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}
      SANITY_PROJECT_ID: ${{ secrets.SANITY_PROJECT_ID }}
      SANITY_DATASET: ${{ secrets.SANITY_DATASET }}
      SANITY_API_TOKEN: ${{ secrets.SANITY_API_TOKEN }}
      MCP_USER_ROLE: ${{ secrets.MCP_USER_ROLE }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"

      - name: Install Sanity CLI
        run: |
          npm install -g @sanity/cli
          echo "✅ Sanity CLI installed"

      - name: Install Gobi CLI
        run: |
          npm install -g @gourmanddev/cli
          echo "✅ Gobi CLI installed"

      - name: Validate Schema Structure
        run: |
          echo "🔍 Validating schema structure..."
          cn --config gourmand/sanity-agent-config \
             -p "Analyze the Sanity schema for any structural issues,
                 missing required fields, or broken references between document types." \
             --auto

      - name: Check Content Integrity
        run: |
          echo "📊 Checking content integrity..."
          cn --config gourmand/sanity-agent-config \
             -p "Run GROQ queries to identify any orphaned documents,
                 broken references, or missing required fields in the content." \
             --auto

      - name: Generate Schema Documentation
        run: |
          echo "📝 Generating schema documentation..."
          cn --config gourmand/sanity-agent-config \
             -p "Generate a markdown summary of all schema changes
                 in this PR and their potential impact on existing content." \
             --auto > schema-changes.md

      - name: Comment Report on PR
        if: always() && github.event_name == 'pull_request'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          REPORT=$(cn --config gourmand/sanity-agent-config \
             -p "Generate a concise summary (200 words or less) of:
                 - Schema validation results
                 - Content integrity checks
                 - Any breaking changes detected
                 - Recommended actions before merging" \
             --auto)

          gh pr comment ${{ github.event.pull_request.number }} --body "$REPORT"
```

<Info>
  Environment variables enable the MCP to authenticate without OAuth browser prompts. The [Sanity MCP Config](https://hub.gourmand.dev/sanity/sanity-mcp-config) documentation provides detailed setup instructions for all required variables.
</Info>

## Content Management Best Practices

Implement automated content quality checks using Gobi's rule system. See the [Rules deep dive](/customize/deep-dives/rules) for authoring tips.

<Card title="Schema Validation" icon="check-circle">
  ```bash  theme={null}
  "Before deploying schema changes, validate that all required fields
  are present and that no breaking changes affect existing content."
  ```
</Card>

<Card title="Content Consistency" icon="shield-exclamation">
  ```bash  theme={null}
  "When creating new content types, ensure they follow the existing
  naming conventions and field patterns established in the schema."
  ```
</Card>

<Card title="Query Optimization" icon="gauge-high">
  ```bash  theme={null}
  "Review GROQ queries for performance issues and suggest indexes
  or query restructuring to improve response times."
  ```
</Card>

<Card title="Localization Standards" icon="check-double">
  ```bash  theme={null}
  "Ensure all user-facing content fields have proper localization
  support configured for the required languages."
  ```
</Card>

## Troubleshooting

### Authentication Issues

```bash  theme={null}
"Check if I'm properly authenticated with Sanity.
If not, help me set up OAuth or API token authentication."
```

### Schema Not Found

```bash  theme={null}
"Verify that the Sanity project is properly configured
and that the schema files are accessible in the current directory."
```

### GROQ Query Errors

```bash  theme={null}
"Debug this GROQ query and explain why it's failing,
then provide a corrected version that achieves the intended result."
```

### Migration Conflicts

<Check>
  **Verification Steps:**

  * Sanity MCP is installed via [Gobi Hub](https://hub.gourmand.dev/sanity/sanity-mcp)
  * Project is authenticated with Sanity
  * Schema files are present and valid
  * Dataset permissions are correctly configured
</Check>

## What You've Built

After completing this guide, you have a complete **AI-powered content management system** that:

* ✅ Uses natural language — Simple prompts instead of complex CMS commands
* ✅ Manages schemas automatically — AI handles schema evolution and migrations
* ✅ Runs continuously — Automated validation in CI/CD pipelines
* ✅ Ensures quality — Content checks prevent broken references and invalid data

<Card title="Continuous AI" icon="rocket">
  Your content management workflow now operates at **[Level 2 Continuous
  AI](https://blog.gourmand.dev/what-is-continuous-ai-a-developers-guide/)** -
  AI handles routine content operations and schema management with human oversight
  through review and approval of changes.
</Card>

## Next Steps

1. **Explore your schema** - Try the schema exploration prompt on your current project
2. **Run GROQ queries** - Use natural language to query your content
3. **Set up CI validation** - Add the GitHub Actions workflow to your repo
4. **Create documentation** - Generate comprehensive docs for your content model
5. **Optimize performance** - Analyze and improve query performance

## Additional Resources

<CardGroup cols={2}>
  <Card title="Sanity Documentation" icon="book" href="https://www.sanity.io/docs">
    Complete Sanity platform documentation
  </Card>

  <Card title="Gobi Hub" icon="plug" href="https://hub.gourmand.dev">
    Explore more MCP integrations and agents
  </Card>

  <Card title="GROQ Documentation" icon="code" href="https://www.sanity.io/docs/groq">
    Learn GROQ query language
  </Card>

  <Card title="Sanity MCP Blog Post" icon="newspaper" href="https://www.sanity.io/blog/model-context-protocol">
    Official Sanity MCP introduction with examples
  </Card>

  <Card title="Sanity MCP Setup" icon="puzzle-piece" href="https://www.sanity.io/docs/compute-and-ai/mcp-server">
    Official Sanity MCP documentation
  </Card>
</CardGroup>


# Automated Error Analysis with Sentry MCP
Source: https://docs.gourmand.dev/guides/sentry-mcp-error-monitoring

Build an AI-powered error monitoring workflow that analyzes Sentry issues, identifies patterns, and creates actionable GitHub issues automatically.

<Card title="What You'll Build" icon="bug">
  An automated error monitoring system that uses Gobi CLI with Sentry MCP to analyze production errors, identify root causes with AI, and create detailed GitHub issues with suggested fixes.
</Card>

## What You'll Learn

This cookbook teaches you to:

* Use [Sentry MCP](https://docs.sentry.io/product/sentry-mcp/) to access [issues](https://docs.sentry.io/product/issues/)

* Analyze error patterns and stack traces with AI

* Automatically create GitHub issues with root cause analysis

* Set up continuous error monitoring with GitHub Actions

## Prerequisites

Before starting, ensure you have:

* GitHub repository where you want to create issues
* [Sentry account](https://sentry.io) with an active project collecting errors
* Node.js 18+ installed locally
* [Gobi CLI](https://docs.gourmand.dev/guides/cli) with **active credits** (required for API usage)
* [GitHub CLI](https://cli.github.com/) installed (`gh` command)

<Steps>
  <Step title="Install Gobi CLI">
    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```
  </Step>

  <Step title="Set up Gobi CLI Account & API Key">
    1. Visit [Gobi Organizations](https://hub.gourmand.dev/settings/organizations)
    2. Sign up or log in to your Gobi account
    3. Navigate to your organization settings
    4. Click **"API Keys"** and then **"+ New API Key"**
    5. Copy the API key immediately (you won't see it again!)
    6. Login to the CLI: `cn login`
  </Step>
</Steps>

<Tip>
  Gobi CLI handles complex error analysis and API interactions - you just need to provide the right prompts!
</Tip>

## Step 1: Set Up Your Credentials

First, you'll need to gather your Sentry and GitHub API credentials.

<Tabs>
  <Tab title="Configure Sentry MCP">
    <Tip>
      See [Sentry MCP Documentation](https://docs.sentry.io/product/sentry-mcp/) for detailed configuration options
    </Tip>

    The Sentry MCP supports multiple configuration methods. For Gobi CLI, OAuth is recommended:

    **Option 1: OAuth Configuration (Recommended)**

    The Sentry MCP will prompt for OAuth authentication when first used. Simply follow the authorization flow.

    **Option 2: STDIO Mode with Auth Token**

    For local development or self-hosted Sentry installations, you can use STDIO mode:

    ```bash  theme={null}
    npx @sentry/mcp-server@latest --access-token=YOUR_SENTRY_TOKEN --host=sentry.io
    ```

    Or use environment variables:

    ```bash  theme={null}
    SENTRY_ACCESS_TOKEN=your-token SENTRY_HOST=sentry.io
    ```

    <Info>
      The `--host` parameter is required and should point to your Sentry instance (e.g., `sentry.io` or `sentry.example.com` for self-hosted).
    </Info>
  </Tab>

  <Tab title="Sentry API Credentials">
    You'll need a **Sentry User Auth Token** to access issues and error data:

    1. Go to [User Auth Tokens](https://sentry.io/settings/account/api/auth-tokens/) in Sentry
       * For self-hosted Sentry, use: `https://YOUR-SENTRY-DOMAIN/settings/account/api/auth-tokens/`
    2. Click **Create New Token**
    3. Name it "Gobi CLI Error Analysis"
    4. **Select these permission scopes** (required for full functionality):
       * `org:read` - **Required** - Access organization information
       * `project:read` - **Required** - Read project configurations
       * `project:releases` - **Required** - Access release information for deployment tracking
       * `event:read` - **Required** - Read detailed error event data and stack traces
       * `event:write` - Optional - Update error events (for marking as resolved)
       * `member:read` - Recommended - Read team member information for auto-assignment
       * `team:read` - Recommended - Access team data for routing issues
    5. Copy the token immediately (you won't see it again!)
    6. Note your organization slug (found in your Sentry URL: `https://sentry.io/organizations/YOUR-ORG-SLUG`)
    7. Note your Sentry host URL (typically `https://sentry.io` or your self-hosted domain)

    <Info>
      **Sentry MCP Connection**: The MCP server connects via OAuth to `https://mcp.sentry.dev/mcp` and handles authentication securely. For local development, you can use STDIO mode with your auth token.
    </Info>
  </Tab>

  <Tab title="Set Up GitHub CLI Authentication">
    GitHub CLI handles authentication automatically - no manual PAT needed:

    1. Install GitHub CLI if not already installed
    2. Run `gh auth login` and follow the prompts
    3. Choose authentication method (browser or token)
    4. Grant necessary permissions when prompted (`issues:write` is **required** for creating issues)
  </Tab>
</Tabs>

## Sentry Error Monitoring Workflow Options

<Card title="Fastest Path to Success" icon="rocket">
  Skip the manual setup and use our pre-built Sentry Continuous AI agent that includes
  optimized prompts, rules, and the Sentry MCP for more consistent results.
</Card>

<Info>
  **How Sentry MCP Works**:

  * Connects to your Sentry organization via OAuth
  * Provides tools for accessing issues, projects, teams, and DSNs
  * Supports both hosted (`https://mcp.sentry.dev`) and self-hosted Sentry instances
  * Automatically handles authentication and API interactions
</Info>

<Tabs>
  <Tab title="⚡ Quick Start (Recommended)">
    **Perfect for:** Immediate error analysis with AI-powered root cause detection and built-in debugging

    <Steps>
      <Step title="Add the Pre-Built Agent">
        Visit the [Sentry Continuous AI Agent](https://hub.gourmand.dev/gobi/sentry-continuous-ai) on Gobi Hub and click **"Install Agent"** or run:

        ```bash  theme={null}
        cn --config gourmand/sentry-continuous-ai
        ```

        This agent includes:

        * **Optimized prompts** for Sentry error analysis and GitHub issue creation
        * **Built-in rules** for consistent formatting and error handling
        * **[Sentry MCP](https://docs.sentry.io/product/sentry-mcp/)** for more reliable API interactions
        * **Automatic authentication** via OAuth flow
      </Step>

      <Step title="Run Error Analysis">
        Navigate to your project directory and enter this prompt in the Gobi CLI TUI:

        ```
        Analyze recent Sentry errors and create GitHub issues for critical bugs with suggested fixes
        ```

        That's it! The agent handles everything automatically.
      </Step>
    </Steps>

    <Info>
      **Why Use the Agent?** Results are more consistent and debugging is easier thanks to the Sentry MCP integration and pre-tested prompts.
    </Info>
  </Tab>

  <Tab title="🛠️ Manual Setup">
    <Steps>
      <Step title="Add Sentry MCP to Gobi CLI">
        Configure the [Sentry MCP](https://docs.sentry.io/product/sentry-mcp/) using OAuth:

        The MCP server will automatically prompt for OAuth authentication when you first use it.
      </Step>

      <Step title="Verify Sentry Connection">
        Test your Sentry MCP connection with this prompt:

        ```
        List my Sentry organizations and projects
        ```
      </Step>

      <Step title="Create Custom Error Analysis Prompts">
        Use this prompt template with Gobi CLI to analyze Sentry errors:

        ```
        Analyze Sentry errors from the past 24 hours:
        - Group errors by root cause
        - Identify the top 5 most critical issues by frequency and impact
        - For each critical issue, provide:
          * Stack trace analysis
          * Affected user count
          * First seen and last seen timestamps
          * Suggested fix based on error context
        - Create GitHub issues using gh CLI with:
          * Title format: '🐛 [Sentry] [Error Type]: Brief description'
          * Labels: 'bug', 'sentry', 'production'
          * Priority labels based on severity
          * Full error context and suggested fix in the body
        Execute the commands and confirm each issue was created.
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Info>
  **Why GitHub CLI over GitHub MCP**: While GitHub MCP is available, it can be
  token-expensive to run. The `gh` CLI is more efficient, requires no API tokens
  (authenticated via `gh auth login`), and provides a cleaner command-line
  experience. GitHub MCP remains an option if you prefer full MCP integration.
</Info>

<Accordion title="Agent Requirements">
  To use the pre-built agent, you need either:

  * **Gobi CLI Pro Plan** with the models add-on, OR
  * **Your own API keys** added to Gobi Hub secrets (same as Step 1)

  The agent will automatically detect and use your configuration. For Sentry MCP:

  * **Sentry account** with at least one project
  * **User Auth Token** with appropriate scopes (or OAuth flow)
  * The MCP works with both Sentry's hosted service (`sentry.io`) and self-hosted instances
</Accordion>

***

<Warning>
  **Repository Labels Required**: Make sure your GitHub repository has these labels:

  * `bug`, `sentry`, `production`
  * `critical`, `high-priority`, `medium-priority`, `low-priority`
  * `needs-investigation`, `has-fix`

  Create missing labels in your repo at: **Settings → Labels → New label**
</Warning>

## Step 2: Analyze Sentry Errors with AI

Use Gobi CLI to perform intelligent error analysis. Enter these prompts in the Gobi CLI TUI:

<Tabs>
  <Tab title="Recent Errors Analysis">
    **Prompt:**

    ```
    Show me Sentry errors from the past 7 days, grouped by error type, with frequency counts
    ```
  </Tab>

  <Tab title="Critical Error Investigation">
    **Prompt:**

    ```
    Find the most critical Sentry error affecting the most users in production and provide:
    - Full stack trace analysis
    - Affected user count and browser/OS breakdown
    - Timeline of when the error started occurring
    - Similar historical issues from Sentry
    - Root cause hypothesis based on code context
    - Suggested fix with code examples
    ```
  </Tab>

  <Tab title="Performance Issue Detection">
    **Prompt:**

    ```
    Analyze Sentry performance data to identify:
    - Slowest transactions in the past 24 hours
    - Database queries with high latency
    - API endpoints with degraded performance
    - Suggested optimizations for each issue
    ```
  </Tab>
</Tabs>

<Info>
  **Available Sentry MCP Tools**:

  * **Organizations**: Access org-level data and settings
  * **Projects**: Query projects and their configurations
  * **Issues**: Search and analyze error issues
  * **Teams**: Manage team assignments
  * **DSNs**: Retrieve project DSN configurations
</Info>

## Step 3: Automate GitHub Issue Creation

Create actionable GitHub issues from Sentry errors. Enter this prompt in the Gobi CLI TUI:

**Prompt:**

```
For each unresolved Sentry error with 'critical' or 'high' severity:
1. Analyze the error using Sentry MCP
2. Create a GitHub issue with gh CLI:
   - Title: '🐛 [Sentry] [Error Type]: Brief description'
   - Body with:
     * Error summary and impact (affected users, frequency)
     * Full stack trace
     * Environment details (browser, OS, release version)
     * Link to Sentry issue
     * Root cause analysis from AI
     * Suggested fix with code snippets
     * Related Sentry issues
   - Labels: 'bug', 'sentry', 'production', and severity label
   - Assignees: Team member based on code ownership
3. Update Sentry issue with GitHub issue link
4. Confirm creation with GitHub issue URL
```

<Tip>
  **Best Practice**: Link GitHub issues back to Sentry for full traceability. This creates a bidirectional connection between your error monitoring and issue tracking.
</Tip>

## Step 4: Set Up Continuous Monitoring with GitHub Actions

Automate error monitoring with the [Sentry Release GitHub Action](https://docs.sentry.io/product/releases/setup/release-automation/github-actions/) and Gobi CLI to create comprehensive, AI-powered issue descriptions:

<Tip>
  **Why Combine Sentry Releases with Gobi CLI?**

  * **Release Tracking**: Associate errors with specific deployments
  * **AI-Powered Analysis**: Gobi CLI generates detailed issue descriptions with root cause analysis
  * **Better Context**: Link errors to commits and pull requests
  * **Automated Workflows**: Create issues with full stack traces and suggested fixes
</Tip>

```yaml  theme={null}
name: Sentry Error Monitoring

on:
  push:
    branches:
      - main
  schedule:
    # Run every 6 hours
    - cron: "0 */6 * * *"
  workflow_dispatch: # Allow manual triggers

jobs:
  monitor-errors:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: "22"

      # Create Sentry release for better error tracking
      - name: Create Sentry release
        uses: getsentry/action-release@v1
        env:
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
          SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
        with:
          environment: production

      - name: Install Gobi CLI
        run: |
          npm install -g @gourmanddev/cli
          echo "✅ Gobi CLI installed"

      - name: Authenticate GitHub CLI
        run: |
          echo "${{ secrets.GITHUB_TOKEN }}" | gh auth login --with-token
          echo "✅ GitHub CLI authenticated"

      - name: Analyze Sentry Errors and Create Issues
        env:
          GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}
          SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
          SENTRY_ORG: ${{ secrets.SENTRY_ORG }}
          SENTRY_PROJECT: ${{ secrets.SENTRY_PROJECT }}
        run: |
          echo "🔍 Analyzing Sentry errors..."
          
          # Use Gobi CLI to analyze errors and generate comprehensive issue descriptions
          cn -p "Using Sentry MCP, analyze errors from the past 6 hours for project $SENTRY_PROJECT:
                 1. Filter for unresolved errors with high or critical severity
                 2. Group similar errors to avoid duplicates
                 3. For each unique critical error:
                    - Generate a comprehensive issue description including:
                      * Error summary with frequency and user impact metrics
                      * Full stack trace with highlighted problem areas
                      * Environment details (browser, OS, release version)
                      * Link to Sentry issue dashboard
                      * Root cause analysis using AI
                      * Step-by-step reproduction if available
                      * Suggested fix with code examples
                      * Related errors or patterns
                    - Check if a GitHub issue already exists for this error
                    - If not, create a new issue with the generated description
                    - Use gh CLI: gh issue create --title '[Sentry] [Error Type]: Brief description' --body 'AI-generated comprehensive analysis' --label 'bug,sentry,critical,needs-investigation'
                    - Link the GitHub issue back to Sentry
                 4. Generate a summary report with:
                    - Total errors analyzed
                    - New issues created with URLs
                    - Errors skipped (already tracked)
                    - Release correlation if available

                 Sentry Organization: $SENTRY_ORG
                 Project: $SENTRY_PROJECT
                 Only process errors not already tracked in GitHub."

      - name: Post workflow summary
        if: always()
        run: |
          echo "## 📊 Sentry Error Monitoring Summary" >> $GITHUB_STEP_SUMMARY
          echo "✅ Workflow completed at $(date)" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "Check the 'Analyze Sentry Errors' step above for:" >> $GITHUB_STEP_SUMMARY
          echo "- Number of errors analyzed" >> $GITHUB_STEP_SUMMARY
          echo "- GitHub issues created" >> $GITHUB_STEP_SUMMARY
          echo "- Errors already tracked" >> $GITHUB_STEP_SUMMARY
```

<Warning>
  **Required GitHub Secrets**:

  * `GOBI_API_KEY`: Your Gobi API key from [hub.gourmand.dev/settings/api-keys](https://hub.gourmand.dev/settings/api-keys)
  * `SENTRY_AUTH_TOKEN`: Your Sentry User Auth Token (needs scopes: `org:read`, `project:read`, `project:releases`, `event:read`)
  * `SENTRY_ORG`: Your Sentry organization slug
  * `SENTRY_PROJECT`: Your Sentry project slug
  * `GITHUB_TOKEN`: Automatically provided by GitHub Actions

  Add these at: **Repository Settings → Secrets and variables → Actions**
</Warning>

<Info>
  **Workflow Best Practices**:

  * Run every 6 hours to catch critical errors quickly
  * Create Sentry releases on push to track error-to-deployment correlation
  * Use Gobi CLI to generate comprehensive, AI-powered issue descriptions
  * Use duplicate detection to avoid creating multiple issues for the same error
  * Filter by severity to focus on high-impact issues
  * Include full error context and suggested fixes in issues
  * Tag issues with appropriate labels for team routing
  * Link GitHub issues back to Sentry for bidirectional tracking
</Info>

## What You've Built

After completing this guide, you have a complete **Sentry-powered error monitoring system** that:

* **Monitors production errors** - Automatically fetches and analyzes Sentry issues every 6 hours

* **Identifies critical bugs** - Uses AI to spot high-impact errors

* **Creates actionable tasks** - Generates GitHub issues with root cause analysis and suggested fixes

* **Runs autonomously** - Operates continuously without manual intervention using GitHub Actions

* **Scales with your app** - Handles growing error volumes and complexity automatically

<Card title="Continuous AI Error Monitoring" icon="shield-check">
  Your system now operates at **[Level 2 Continuous AI](https://blog.gourmand.dev/what-is-continuous-ai-a-developers-guide/)** - AI handles routine error analysis with human oversight through GitHub issue review and resolution.
</Card>

## Advanced Error Analysis Prompts

Enhance your workflow with these advanced Gobi CLI prompts:

<CardGroup cols={2}>
  <Card title="Release Impact Analysis" icon="rocket">
    Compare error rates before and after the latest [Sentry release](https://docs.sentry.io/product/releases/) to identify regressions introduced in the deployment
  </Card>

  <Card title="Error Trend Detection" icon="chart-line">
    Analyze Sentry error trends over the past 30 days and identify emerging issues before they become critical
  </Card>

  <Card title="User Impact Assessment" icon="users">
    Identify which errors are affecting the most unique users and prioritize fixes based on user impact
  </Card>

  <Card title="Performance Correlation" icon="gauge">
    Cross-reference Sentry [performance issues](https://docs.sentry.io/product/performance/) with error spikes to identify root causes
  </Card>
</CardGroup>

## Security Best Practices

<Warning>
  **Protect Your API Keys**:

  * Store all credentials as GitHub Secrets, never in code
  * Use Gobi CLI's secure secret storage
  * Limit Sentry token scopes to minimum required permissions
  * Rotate API keys regularly (every 90 days recommended)
  * Monitor token usage for unusual activity
  * Use OAuth when possible for better security
</Warning>

## Troubleshooting

### Sentry MCP Connection Issues

If you encounter connection issues:

1. Verify OAuth authentication is complete
2. Check your Sentry organization access
3. Ensure the MCP server URL is correct (`https://mcp.sentry.dev/mcp`)
4. For self-hosted Sentry, verify your host URL is configured correctly

See the [Sentry MCP GitHub Issues](https://github.com/getsentry/sentry-mcp/issues) for known issues and solutions.

### Common Error Analysis Issues

| Issue                      | Solution                                                 |
| :------------------------- | :------------------------------------------------------- |
| No errors returned         | Verify your Sentry project has collected errors recently |
| OAuth prompt not appearing | Check that Gobi CLI has proper MCP configuration         |
| Duplicate GitHub issues    | Implement duplicate detection in your prompts            |
| Missing error context      | Ensure your Sentry token has `event:read` scope          |

## Next Steps

* Set up [Sentry performance monitoring](https://docs.sentry.io/product/performance/)
* Configure [Sentry release tracking](https://docs.sentry.io/product/releases/) for deployment correlation
* Integrate [Slack MCP](https://hub.gourmand.dev/slack/slack-mcp) for error alerts
* Join the [Gobi Discord](https://discord.gg/gobi) for support

## Resources

* [Sentry MCP Documentation](https://docs.sentry.io/product/sentry-mcp/)

* [Sentry API Documentation](https://docs.sentry.io/api/)

* [Sentry Issues Guide](https://docs.sentry.io/product/issues/)

* [Sentry Performance Monitoring](https://docs.sentry.io/product/performance/)

* [Sentry Release Tracking](https://docs.sentry.io/product/releases/)

* [Sentry MCP GitHub Repository](https://github.com/getsentry/sentry-mcp)

* [GitHub CLI Documentation](https://cli.github.com/)

* [Gobi CLI Guide](https://docs.gourmand.dev/guides/cli)

* [Continuous AI Best Practices](https://blog.gourmand.dev/what-is-continuous-ai-a-developers-guide/)


# Automated Security Scanning with Snyk MCP and Gobi
Source: https://docs.gourmand.dev/guides/snyk-mcp-gobi-cookbook

Set up an AI-powered security workflow that automatically scans your code, dependencies, infrastructure, and containers using natural language commands.

<Card title="What You'll Build" icon="shield-halved">
  An automated security scanning system that uses Gobi's AI agent with Snyk
  MCP to identify vulnerabilities in code, dependencies, infrastructure, and
  containers - all through simple natural language prompts
</Card>

## Prerequisites

Before starting, ensure you have:

* Gobi account with **Hub access**
* Read: [Understanding Configs — How to get started with Hub configs](/guides/understanding-configs#how-to-get-started-with-hub-configs)
* Node.js 18+ installed locally
* [Snyk account](https://snyk.io/) (free tier works)
* A local project to scan for vulnerabilities

For all options, first:

<Steps>
  <Step title="Install Gobi CLI">
    ```bash  theme={null}
    npm i -g @gourmanddev/cli
    ```
  </Step>

  <Step title="Add Your Project to Snyk">
    1. Sign up for a Snyk account at [snyk.io](https://snyk.io/)
    2. Create a new project in Snyk by importing your code repository (Git
       provider or manual upload)
    3. Install and authenticate the Snyk CLI locally:
       ```bash  theme={null}
       npm install -g snyk
       snyk auth
       ```
       This will open your browser to authenticate with your Snyk account.
  </Step>
</Steps>

<Note>
  **Important**: The Snyk MCP requires the Snyk CLI to be authenticated locally. Run `snyk auth` to authenticate before using the Gobi agent with Snyk MCP.
</Note>

<Warning>
  To use agents in headless mode, you need a [Gobi API key](https://hub.gourmand.dev/settings/api-keys).
</Warning>

## Snyk Continuous AI Workflow Options

<Card title="🚀 Fastest Path to Success" icon="zap">
  Skip the manual setup and use our pre-built Snyk Continuous AI agent that includes
  the Snyk MCP and optimized security scanning workflows for more consistent results.
</Card>

After ensuring you meet the **Prerequisites** above, you have two paths to get started:

<Tabs>
  <Tab title="⚡ Quick Start (Recommended)">
    <Steps>
      <Step title="Load the Pre-Built Agent">
        Navigate to your project directory and run:

        ```bash  theme={null}
        cn --config gourmand/snyk-continuous-ai
        ```

        This agent includes:

        * **Snyk MCP** pre-configured and ready to use
        * **Security-focused rules** for best practices
      </Step>

      <Step title="Run Your First Security Scan">
        From your project directory, start with a comprehensive security scan:

        ```bash  theme={null}
         # Headless mode
        cn -p "Run a complete security scan on this project including code vulnerabilities, dependencies, and any IaC files. Summarize findings by severity." --auto
        ```

        That's it! The agent handles everything automatically.
      </Step>
    </Steps>

    <Info>
      **Why Use the Agent?** The pre-built agent provides consistent security scanning workflows and handles MCP configuration automatically, making it easier to get started with AI-powered security scanning.
    </Info>
  </Tab>

  <Tab title="🛠️ Manual Setup">
    <Steps>
      <Step title="Create a New Agent via the Gobi Hub">
        Go to the [Gobi Hub](https://hub.gourmand.dev) and [create a new agent](https://hub.gourmand.dev/new?type=agent).
      </Step>

      <Step title="Connect Snyk MCP via Gobi Hub">
        Visit the [Snyk MCP on Gobi Hub](https://hub.gourmand.dev/snyk/snyk-mcp) and click **Install** to add it to the agent you created in the step above.

        This will add Snyk MCP to your agent's available tools. The Hub listing automatically configures the MCP command:

        ```bash  theme={null}
        npx -y snyk@latest mcp -t stdio
        ```

        <Tip>
          **Alternative installation methods:**

          1. **Quick CLI install**: `cn --mcp snyk/snyk-mcp`
          2. **Manual configuration**: Add the MCP to your `~/.gobi/config.json` under the `mcpServers` section

          Once installed, Snyk MCP tools become available to your Gobi agent for all prompts.
        </Tip>

        <Info>
          The MCP will request authentication and folder trust permissions when first used.
          This is handled automatically by the Gobi agent.
        </Info>
      </Step>

      <Step title="Add Secure-at-Inception Rules">
        Install the [Snyk Secure-at-Inception rules](https://hub.gourmand.dev/snyk/secure-at-inception) from the Hub to enable automatic security scanning.

        **How to add rules to your agent:**

        1. Visit the rules link above and click **Install**
        2. The rules will be added to your agent configuration automatically
        3. Rules apply globally to all your Gobi sessions

        These rules configure your agent to:

        * **Run [SAST](https://snyk.io/learn/application-security/sast/) scans** on newly generated or modified code
        * **Check dependencies** when adding or updating packages
        * **Auto-fix issues** using Snyk's recommendations, then rescan
      </Step>

      <Step title="Run Your First Security Scan">
        Start with a comprehensive security scan:

        ```bash  theme={null}
        # TUI mode
        cn "Run a complete security scan on this project including code vulnerabilities, dependencies, and any IaC files. Summarize findings by severity."
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Accordion title="Agent Requirements">
  To use the pre-built agent, you need either:

  * **Gobi CLI Pro Plan** with the models add-on, OR
  * **Your own API keys** added to Gobi Hub secrets (same as manual setup)

  The agent will automatically detect and use your configuration along with the pre-configured Snyk MCP for security scanning operations.
</Accordion>

***

## Security Scanning Recipes

Now you can use natural language prompts to run comprehensive security scans. The Gobi agent automatically calls the appropriate Snyk MCP tools.

<Info>
  You can add prompts to your agent's configuration for easy access in future sessions. Go to your agent in the [Gobi Hub](https://hub.gourmand.dev), click **Edit**, and add prompts under the **Prompts** section.
</Info>

<Info>
  **Where to run these workflows:**

  * **IDE Extensions**: Use Gobi in VS Code, JetBrains, or other supported IDEs
  * **Terminal (TUI mode)**: Run `cn` to enter interactive mode, then type your prompts
  * **CLI (headless mode)**: Use `cn -p "your prompt" --auto` for headless commands

  **Test in Plan Mode First**: Before running security scans that might make
  changes, test your prompts in plan mode (see the [Plan Mode
  Guide](/guides/plan-mode-guide); press **Shift+Tab** to switch modes in TUI/IDE). This
  shows you what the agent will do without executing it. For example: `"Run a
    Snyk Code scan and fix the top 3 issues"`
</Info>

### Code Vulnerability Scanning ([SAST](https://snyk.io/learn/application-security/sast/))

<Card title="Static Application Security Testing" icon="code">
  Scan your source code for security vulnerabilities and code quality issues.

  **TUI Mode Prompt:**

  ```
  Run a Snyk Code scan on this repo with severity threshold medium.
  Summarize issues with file:line. Propose minimal diffs for the top 3
  and rerun to verify.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Run a Snyk Code scan on this repo with severity threshold medium. Summarize issues with file:line. Propose minimal diffs for the top 3 and rerun to verify." --auto
  ```
</Card>

### Dependency Scanning ([SCA](https://snyk.io/learn/software-composition-analysis-sca/))

<Card title="Software Composition Analysis" icon="cube">
  Check open source dependencies for known vulnerabilities.

  **TUI Mode Prompt:**

  ```
  Run Snyk Open Source on this repo (include dev deps).
  Summarize vulnerable paths and propose a minimal-risk upgrade plan.
  Re-test after the plan (dry run).
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Run Snyk Open Source on this repo (include dev deps). Summarize vulnerable paths and propose a minimal-risk upgrade plan. Re-test after the plan (dry run)." --auto
  ```
</Card>

### Infrastructure as Code ([IaC](https://snyk.io/learn/infrastructure-as-code-iac/))

<Card title="IaC Security" icon="cloud">
  Scan Terraform, CloudFormation, and Kubernetes configs for misconfigurations.

  **TUI Mode Prompt:**

  ```
  Scan ./infra with Snyk IaC. Report high/critical misconfigs
  with exact files/lines. Provide code changes and re-scan to confirm.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Scan ./infra with Snyk IaC. Report high/critical misconfigs with exact files/lines. Provide code changes and re-scan to confirm." --auto
  ```
</Card>

### Container Scanning

<Card title="Container Security" icon="docker">
  Analyze Docker images for vulnerabilities in base images and packages.

  **TUI Mode Prompt:**

  ```
  Scan image my-api:latest. Exclude base image vulns.
  Print dependency tree. Recommend a safer base image or upgrades.
  Re-test after the change (dry run).
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Scan image my-api:latest. Exclude base image vulns. Print dependency tree. Recommend a safer base image or upgrades. Re-test after the change (dry run)." --auto
  ```
</Card>

### Pull Request Scanning

<Card title="Changed Files Only" icon="code-branch">
  Focus scanning on modified files to catch issues before merging.

  **TUI Mode Prompt:**

  ```
  Scan only files changed since origin/main with Snyk Code.
  Block if new high issues would be introduced. Show deltas.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Scan only files changed since origin/main with Snyk Code. Block if new high issues would be introduced. Show deltas." --auto
  ```
</Card>

### Security Learning

<Card title="Snyk Learn Integration" icon="graduation-cap">
  Access security education resources based on identified vulnerabilities ([CWE](https://cwe.mitre.org/)).

  **TUI Mode Prompt:**

  ```
  Open Snyk Learn lessons related to the top CWE(s) from this scan.
  ```

  **Headless Mode Prompt:**

  ```bash  theme={null}
  cn -p "Open Snyk Learn lessons related to the top CWE(s) from this scan." --auto
  ```
</Card>

## Continuous Security with GitHub Actions

This example demonstrates a **Continuous AI workflow** where security scanning runs automatically on pull requests, generates AI-powered mitigation suggestions, and posts them as PR comments.

<Info>
  **About the --auto flag**: The `--auto` flag enables tools to run continuously without manual confirmation. This is essential for headless mode where the agent needs to execute multiple tools automatically to complete tasks like security scanning, vulnerability analysis, and fix validation.
</Info>

### Add GitHub Secrets

Navigate to **Repository Settings → Secrets and variables → Actions** and add:

* `GOBI_API_KEY`: Your Gobi API key from [hub.gourmand.dev/settings/api-keys](https://hub.gourmand.dev/settings/api-keys)
* `SNYK_TOKEN`: Your Snyk authentication token from [app.snyk.io/account](https://app.snyk.io/account)

### Create Workflow File

Create `.github/workflows/snyk-security.yml` in your repository:

```yaml  theme={null}
name: Snyk Security Scanning

on:
  pull_request:
    branches: [main]

jobs:
  security-scan:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for git diff

      - name: Get Changed Files
        id: changed-files
        run: |
          echo "📝 Getting changed files since main branch..."
          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | tr '\n' ' ')
          echo "changed_files=$CHANGED_FILES" >> $GITHUB_OUTPUT
          echo "Changed files: $CHANGED_FILES"

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install Snyk CLI
        run: |
          npm install -g snyk
          echo "✅ Snyk CLI installed"

      - name: Install Gobi CLI
        run: |
          npm install -g @gourmanddev/cli
          echo "✅ Gobi CLI installed"

      - name: Validate Secrets
        run: |
          if [ -z "${{ secrets.SNYK_TOKEN }}" ]; then
            echo "❌ Error: SNYK_TOKEN secret is not set"
            exit 1
          fi
          if [ -z "${{ secrets.GOBI_API_KEY }}" ]; then
            echo "⚠️ Warning: GOBI_API_KEY not set - AI mitigation suggestions will be skipped"
          fi
          echo "✅ Required secrets validated"

      - name: Authenticate Snyk
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
        run: |
          snyk auth "$SNYK_TOKEN"
          echo "✅ Snyk authenticated"

      - name: Run Security Scans
        id: security-scan
        continue-on-error: true
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
          CHANGED_FILES: ${{ steps.changed-files.outputs.changed_files }}
        run: |
          SCAN_FAILED=0

          if [ -n "$CHANGED_FILES" ]; then
            echo "🔍 Running targeted scan on changed files..."
            echo "Changed files: $CHANGED_FILES"
            FILE_ARGS=""
            for file in $CHANGED_FILES; do
              if [[ "$file" =~ \.(js|jsx|ts|tsx|py|java|go|rb)$ ]]; then
                FILE_ARGS="$FILE_ARGS --file=$file"
              fi
            done

            if [ -n "$FILE_ARGS" ]; then
              echo "🔍 Running Snyk Code scan on changed files..."
              snyk code test $FILE_ARGS --severity-threshold=high --json > snyk-code-results.json || {
                echo "❌ Snyk Code found high severity issues in changed files"
                SCAN_FAILED=1
              }
            else
              echo "⚠️ No scannable code files changed, skipping Snyk Code scan"
              echo '{"runs": [{"results": []}]}' > snyk-code-results.json
            fi
          else
            echo "⚠️ No changed files detected, creating empty results"
            echo '{"runs": [{"results": []}]}' > snyk-code-results.json
          fi

          echo "📦 Checking dependencies..."
          snyk test --severity-threshold=high --json > snyk-oss-results.json || {
            echo "❌ Snyk Open Source found high severity issues"
            SCAN_FAILED=1
          }

          if [ $SCAN_FAILED -eq 1 ]; then
            echo "scan_status=failed" >> $GITHUB_OUTPUT
            echo "⚠️ Scans completed with issues - continuing to generate mitigation suggestions"
          else
            echo "scan_status=passed" >> $GITHUB_OUTPUT
            echo "✅ All security scans passed"
          fi

      - name: Generate AI Mitigation Suggestions
        if: always() && steps.security-scan.outputs.scan_status == 'failed'
        continue-on-error: true
        env:
          GOBI_API_KEY: ${{ secrets.GOBI_API_KEY }}
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
        run: |
          echo "🤖 Generating AI-powered mitigation suggestions..."

          # Create a summary of findings for Gobi CLI
          FINDINGS_SUMMARY=$(cat snyk-code-results.json snyk-oss-results.json | jq -r '
            if .runs then
              .runs[0].results[] | "Code Issue: \(.message.text) in \(.locations[0].physicalLocation.artifactLocation.uri) (Severity: \(.level))"
            elif .vulnerabilities then
              .vulnerabilities[] | "Dependency Issue: \(.title) in \(.packageName)@\(.version) (Severity: \(.severity))"
            else
              empty
            end
          ' | head -20)

          if [ -n "$FINDINGS_SUMMARY" ]; then
            echo "📋 Security findings to analyze:"
            echo "$FINDINGS_SUMMARY"
            echo ""

            # Use Gobi CLI to generate mitigation suggestions
            PROMPT="Analyze these Snyk security findings and provide specific, actionable mitigation steps for each issue. Focus on: 1) Root cause, 2) Immediate fix, 3) Long-term prevention. Findings: $FINDINGS_SUMMARY. Provide clear, prioritized recommendations."

            cn --config gourmand/snyk-continuous-ai -p "$PROMPT" --auto > mitigation-suggestions.md || {
              echo "⚠️ Warning: Could not generate AI suggestions"
              exit 0
            }

            if [ -f mitigation-suggestions.md ]; then
              echo "✅ AI mitigation suggestions generated"
              echo ""
              echo "--- Mitigation Suggestions ---"
              cat mitigation-suggestions.md
            fi
          else
            echo "⚠️ No findings to analyze"
          fi

      - name: Post Mitigation Summary to PR
        if: steps.security-scan.outputs.scan_status == 'failed' && hashFiles('mitigation-suggestions.md') != ''
        continue-on-error: true
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          if [ -f mitigation-suggestions.md ]; then
            echo "💬 Posting mitigation summary to PR..."

            # Create PR comment with mitigation suggestions
            cat > pr-comment.md <<'EOF'
          ## 🛡️ Snyk Mitigation Summary

          Snyk has identified security issues in this PR. Here are AI-generated mitigation recommendations:

          EOF

            cat mitigation-suggestions.md >> pr-comment.md

            cat >> pr-comment.md <<EOF

          ---
          **Scan Details:**
          - 📊 Full report available in workflow artifacts
          - 🔍 Review the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for complete details
          - 🤖 Generated with Gobi CLI + Snyk

          _This is an automated security analysis. Please review and address the findings before merging._
          EOF

            gh pr comment ${{ github.event.pull_request.number }} --body-file pr-comment.md

            echo "✅ Mitigation summary posted to PR"
          else
            echo "⚠️ No mitigation suggestions file found"
          fi

      - name: Generate Security Report
        if: always()
        continue-on-error: true
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
        run: |
          echo "📊 Generating security report..."
          {
            echo "# Security Scan Report"
            echo ""
            echo "**Date:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")"
            echo "**Branch:** ${{ github.ref_name }}"
            echo "**Commit:** ${{ github.sha }}"
            echo "**Status:** ${{ steps.security-scan.outputs.scan_status }}"
            echo ""

            echo "## Snyk Code Scan Results"
            if [ -f snyk-code-results.json ]; then
              jq -r '.runs[0].results[] | "- **\(.level | ascii_upcase)**: \(.message.text) in \(.locations[0].physicalLocation.artifactLocation.uri)"' snyk-code-results.json || echo "No code issues found"
            else
              echo "No scan results available"
            fi
            echo ""

            echo "## Snyk Open Source Scan Results"
            if [ -f snyk-oss-results.json ]; then
              jq -r '.vulnerabilities[] | "- **\(.severity | ascii_upcase)**: \(.title) (\(.packageName)@\(.version))"' snyk-oss-results.json || echo "No dependency issues found"
            else
              echo "No scan results available"
            fi
            echo ""

            if [ -f mitigation-suggestions.md ]; then
              echo "## AI-Powered Mitigation Suggestions"
              echo ""
              cat mitigation-suggestions.md
            fi
          } > scan-results.md

          if [ -f scan-results.md ]; then
            echo "✅ Security report generated successfully"
            cat scan-results.md
          else
            echo "⚠️ Warning: scan-results.md was not created"
          fi

      - name: Upload Security Report
        if: always()
        continue-on-error: true
        uses: actions/upload-artifact@v4
        with:
          name: security-scan-results
          path: |
            scan-results.md
            snyk-code-results.json
            snyk-oss-results.json
            mitigation-suggestions.md
          if-no-files-found: warn

      - name: Fail if Security Issues Found
        if: steps.security-scan.outputs.scan_status == 'failed'
        run: |
          echo "❌ Security scan failed - high severity issues found"
          echo "📋 Review the security report artifact for details and mitigation suggestions"
          exit 1
```

<Info>
  **About SNYK\_TOKEN**: The workflow uses the SNYK\_TOKEN in two ways:

  1. **Direct Snyk CLI authentication** - Authenticates the Snyk CLI for running scans
  2. **Gobi CLI access** - Available as an environment variable when Gobi generates AI mitigation suggestions

  The `cn` agent automatically uses the SNYK\_TOKEN when needed for Snyk MCP operations.
</Info>

<Info>
  This workflow demonstrates several advanced features:

  * **Changed Files Detection**: Only scans files modified in the PR
  * **AI Mitigation**: Uses Gobi CLI to generate actionable mitigation steps
  * **PR Comments**: Automatically posts mitigation suggestions as PR comments
  * **Comprehensive Reporting**: Generates detailed security reports with artifacts
</Info>

## Security Guardrails

Implement automated security policies using Gobi's rule system. See the [Rules deep dive](/customize/deep-dives/rules) for authoring tips.

<Note>
  **Coming Soon**: These security guardrail prompts will be available as pre-configured rules on the Gobi Hub for easy installation.
</Note>

<Card title="Pre-commit Scanning" icon="lock">
  ```bash  theme={null}
  "Always run Snyk Code before committing newly
  generated code; refuse to proceed if high
  issues remain."
  ```
</Card>

<Card title="Dependency Safety" icon="shield-check">
  ```bash  theme={null}
  "When adding/updating a dependency, run Snyk Open Source, choose the
  lowest-risk upgrade, and re-test."
  ```
</Card>

<Card title="Container Hardening" icon="box">
  ```bash  theme={null}
  "Before building containers, scan base images and recommend
  security-hardened alternatives."
  ```
</Card>

<Card title="IaC Compliance" icon="clipboard-list">
  ```bash  theme={null}
  "Scan all Terraform changes for compliance
  violations before applying infrastructure."
  ```
</Card>

<Tip>
  Enable the **Secure-at-Inception** rules from the Hub to automatically apply
  these guardrails to all code generation and modifications.
</Tip>

## Troubleshooting

### Authentication Issues

```bash  theme={null}
"Check Snyk auth status and current org. If not authenticated,
help me authenticate. Then run a quick Code scan on ./
with severity medium and print one example issue."
```

### Fix Validation

```bash  theme={null}
"Propose minimal diffs only in affected files,
then rerun the same Snyk scan to confirm resolution."
```

### Connection Problems

<Check>
  **Verification Steps:** - Snyk MCP is installed via [Gobi
  Hub](https://hub.gourmand.dev/snyk/snyk-mcp) - Secure-at-Inception rules are
  [enabled](https://hub.gourmand.dev/snyk/secure-at-inception) - Authentication
  completed successfully - Project folder has been trusted
</Check>

## What You've Built

After completing this guide, you have a complete **AI-powered security system** that:

* ✅ Uses natural language — Simple prompts instead of complex CLI commands
* ✅ Fixes automatically — AI suggests and validates security fixes
* ✅ Runs continuously — Automated scanning in CI/CD pipelines
* ✅ Enforces guardrails — Security rules prevent vulnerable code from shipping

<Card title="Continuous AI" icon="rocket">
  Your security workflow now operates at **[Level 2 Continuous
  AI](https://blog.gourmand.dev/what-is-continuous-ai-a-developers-guide/)** -
  AI handles routine security scanning and remediation with human oversight
  through review and approval of fixes.
</Card>

## Next Steps

1. **Run your first scan** - Try the [SAST](https://snyk.io/learn/application-security/sast/) prompt on your current project
2. **Review findings** - Analyze the security report and implement fixes
3. **Set up CI pipeline** - Add the GitHub Actions workflow to your repo
4. **Customize rules** - Add project-specific security policies
5. **Monitor trends** - Track [vulnerability](https://snyk.io/learn/security-vulnerability/) reduction over time

## Additional Resources

<CardGroup cols={2}>
  <Card title="Snyk Documentation" icon="book" href="https://docs.snyk.io">
    Complete Snyk platform documentation
  </Card>

  <Card title="Gobi Hub" icon="plug" href="https://hub.gourmand.dev">
    Explore more MCP integrations and agents
  </Card>

  <Card title="Security Best Practices" icon="shield" href="https://snyk.io/learn">
    Learn about secure coding practices
  </Card>

  <Card title="MCP Concepts" icon="puzzle-piece" href="https://docs.snyk.io/integrations/developer-guardrails-for-agentic-workflows">
    Understanding MCP architecture
  </Card>
</CardGroup>


# How to Understand Hub vs Local Configuration
Source: https://docs.gourmand.dev/guides/understanding-configs

Learn how to choose between cloud-managed Hub and local configuration for AI development assistance in Gobi, including setup, management, and best practices for each approach

Every developer has unique needs when it comes to AI assistance. Some prefer the convenience of cloud-managed configurations, while others need the control and privacy of local setups. Gobi offers both paths, and this guide will help you choose the right one for your workflow.

## What Are the Two Paths to AI Assistance?

Gobi provides two distinct ways to configure:

Think of Gobi's configuration options like choosing between a managed service and self-hosting. Both get you to the same destination—powerful AI assistance in your IDE—but the journey and control level differ significantly.

### How to Access Your Configuration

Before we dive into the specifics, let's understand how to access your configuration:

1. Open the Gobi Chat sidebar by pressing <kbd>cmd/ctrl</kbd> + <kbd>L</kbd> (VS Code) or <kbd>cmd/ctrl</kbd> + <kbd>J</kbd> (JetBrains)
2. Click the Config selector above the main chat input
3. Hover over a config and click:
   * `new window` icon for Hub configs
   * `gear` icon for Local configs

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=a320ac89603934bd55aea06a9e33bbe2" alt="configure" data-og-width="750" width="750" data-og-height="514" height="514" data-path="images/configure-gobi.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=af5f992b067017bfa49d479469858e6f 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=c4a36deb917e59ac95b12bd17a14cb42 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=333a094e82359f1a9296bcb0353b60e2 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=0a7866b929a3babe2ac537d8019f87d5 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=43279bb07b641d19084f2bc34f6ae86b 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/configure-gobi.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=72f6f94585b2ed9528dcb0f83e3ba1c0 2500w" />

## What Are Hub Configurations: The Managed Experience

Hub Configurations represent the "it just works" philosophy. When you [sign in to Gobi Hub](https://auth.gourmand.dev/), you gain access to a curated ecosystem of established configurations that sync seamlessly across all your development environments.

### Why Should You Choose Hub Configs?

**The Power of Simplicity**

* **Instant Setup**: Browse the [configuration marketplace](https://hub.gourmand.dev) and add any config to your account with a single click
* **Web-Based Management**: Configure models, add secrets, and customize settings through an intuitive web interface—no JSON editing required
* **Automatic Synchronization**: Make a change on the hub, and it reflects immediately across all your IDE instances
* **Team Collaboration**: Share custom configurations with your team, ensuring everyone uses the same optimized configurations

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/nextjs-assistant.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=27ff2b31c3cae25227d93cb2b1f7a247" alt="nextjs config" data-og-width="1575" width="1575" data-og-height="1140" height="1140" data-path="images/nextjs-assistant.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/nextjs-assistant.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=eb6cefd3222637f731dc1e0adcd5669f 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/nextjs-assistant.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=535ceac900b6bbb80dd24f543bd426ec 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/nextjs-assistant.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=6a3454fa325f49abb03e0f03344b2edc 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/nextjs-assistant.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=69d886180a8fef56922fd2c77c00956d 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/nextjs-assistant.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=0c13eda33703efe848f3413150968bbd 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/nextjs-assistant.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=dc763dac90776600038d06d0696b31ed 2500w" />

### How to Get Started with Hub Configs

The journey from zero to AI-powered coding takes just four steps:

1. **Select Your Config**: Click the config selector in your IDE's Gobi panel
2. **Explore or Create**: Browse community configurations or craft your own specialized setup
3. **Secure Your Keys**: Add API keys as [User Secrets](https://hub.gourmand.dev/settings/secrets) in the hub—they're encrypted and never exposed
4. **Sync and Code**: Click "Reload config" to pull your latest settings

Pro tip: Hub configurations are perfect for teams. Create a custom config with your team's coding standards, preferred models, and context sources, then share it with a simple link.

### How to Manage Hub Configs

All Hub config management happens through [the Hub](https://hub.gourmand.dev). For detailed customization, see our guide on [Editing a Config](/hub/configs/edit-a-config).

## What Are Local Configs: The Power User's Choice

Local configuration puts you in the driver's seat. Using a `config.yaml` file, you have complete control over every aspect of your Gobi experience with all configuration stored directly on your machine.

### Why Should You Choose Local Configs?

**Complete Control and Privacy**

* **Your Data, Your Rules**: All configuration stays on your machine—perfect for air-gapped environments or strict data policies
* **Version Control Integration**: Check your `config.yaml` into git alongside your code, ensuring reproducible environments
* **Offline Capability**: Once configured, no internet connection needed (assuming you're using local models)
* **Unlimited Customization**: Access every configuration option, experimental feature, and advanced setting

### How to Set Up Local Configs

Local configuration lives in a single YAML file in your home directory:

**File Locations:**

* macOS/Linux: `~/.gobi/config.yaml`
* Windows: `%USERPROFILE%\.gobi\config.yaml`

**Quick Access Method:**

1. Open the configs dropdown in your IDE
2. Click the gear icon next to "Local Config"
3. The `config.yaml` file opens in your editor

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=944f96f540277b89efb50f653abc9ad1" alt="local-config-open-steps" data-og-width="778" width="778" data-og-height="484" height="484" data-path="images/local-config-open-steps.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=65695a6de18c4888688ae8ef688ad972 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=dc6fed29115963949125e5bcc018e736 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=16df4500230f0b2ced52df66bbab0e97 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=4cd793b4dfaa656eb691b878a236776f 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=1b0ecbfb543f06e76e08ec72fcdf588b 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/local-config-open-steps.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=3aa1a4ca8c5aa49fcdf06ab199a9c2e0 2500w" />

### The Local Config Experience

When you edit your `config.yaml`, Gobi provides intelligent autocomplete for all available options. Save the file, and Gobi automatically reloads your configuration—no restart required.

The first time you use Gobi, it generates a `config.yaml` with sensible defaults. From there, you can customize everything from model selection to context providers, slash commands, and more.

For the complete configuration reference, see our [config.yaml documentation](/reference).

## How to Make the Right Choice

The decision between Hub and Local configs often comes down to your specific needs and constraints. Here's a framework to help you decide:

### Choose Hub Configs When You:

**Value Convenience Over Control**

* Want to start coding with AI assistance in under 60 seconds
* Prefer visual interfaces over editing configuration files
* Need to switch between multiple machines frequently
* Work in a team that needs standardized AI assistance

**Need Advanced Collaboration**

* Want to share custom configs with teammates
* Need centralized API key management
* Require quick updates across your entire organization

**Are Getting Started**

* New to AI-powered development
* Want to experiment with different models and configurations
* Prefer guided setup experiences

### Choose Local Configs When You:

**Require Maximum Control**

* Need to version control your exact configuration
* Want to customize every aspect of the AI behavior
* Require reproducible development environments

**Have Privacy Requirements**

* Work with sensitive code that requires air-gapped environments
* Need to ensure all configuration data stays local
* Have strict compliance requirements about data storage

**Are a Power User**

* Comfortable editing YAML/JSON files
* Want access to experimental features
* Need to integrate with local tools and scripts

## How to Use the Hybrid Approach

Here's a secret: you don't have to choose just one. Many developers use both approaches:

* **Hub Configs** for general development and experimentation
* **Local Configs** for production work or client projects with specific requirements

You can switch between them seamlessly using the configs selector in your IDE.

## Common Patterns and Best Practices

### For Hub Config Users

1. **Start with Community Configs**: Before creating your own, explore what others have built
2. **Use Secrets Properly**: Never hardcode API keys—always use the User Secrets feature
3. **Create Specialized Configs**: Make different configs for different contexts (frontend, backend, DevOps)
4. **Share Liberally**: If you create something useful, share it with the community

### For Local Config Users

1. **Version Control Your Config**: Treat your `config.yaml` like code—commit it, review changes, and maintain history
2. **Use Environment Variables**: For sensitive data, reference environment variables instead of hardcoding values
3. **Document Your Setup**: Add comments to your config explaining non-obvious choices
4. **Keep a Backup**: Before major changes, save a working copy of your configuration

## Troubleshooting and Tips

### Hub Config Issues

**Changes Not Reflecting?**

* Click "Reload config" in your IDE
* Check your internet connection
* Ensure you're signed in to the correct account

**Config Not Available?**

* Verify it's added to your account on the hub
* Check if it requires specific API keys

### Local Config Issues

**Config Not Loading?**

* Verify file location matches your OS
* Check YAML syntax (Gobi will show errors)
* Ensure file permissions allow reading

**Autocomplete Not Working?**

* Update to the latest Gobi version
* Check that you're editing the correct file

## Next Steps

Now that you understand both configuration approaches, you're ready to dive deeper:

* **For Hub Users**: [Create A Config](/hub/configs/create-a-config)
* **For Local Users**: [Explore the Config Reference](/reference)
* **For Everyone**: [Discover Available Models](/customize/model-providers/overview)

Remember, the best configuration is the one that helps you code more effectively. Start simple, experiment freely, and gradually refine your setup as you discover what works best for your workflow.

Happy coding with Gobi! 🚀


# How to Create a Config
Source: https://docs.gourmand.dev/hub/configs/create-a-config

Learn how to create custom AI coding configs in Gobi Hub by remixing existing configs or building new ones from scratch with reusable blocks and YAML configuration.

## How to Create a Config from Scratch

To create an config from scratch, select “New config” in the top bar.

Choose a name, slug, description, and icon for your config.

The easiest way to create an config is to click "Create config" with the default configuration and then add / remove blocks using the sidebar.

Alternatively, you can edit the config YAML directly before clicking "Create config". Refer to examples of configs on [hub.gourmand.dev](https://hub.gourmand.dev) and visit the [YAML Reference](/reference#complete-yaml-config-example) docs for more details.

## How to Remix an config

You can also create an config by remixing an existing one. This is useful if you want to start with a pre-configured config and make modifications.

By clicking the “remix” button, you’ll be taken to the “Create a remix” page.

Once here, you’ll be able to

1. add or remove blocks in YAML configuration
2. change the name, description, icon, etc.

Clicking “Create config” will make this config available for use.


# How to Edit a Config
Source: https://docs.gourmand.dev/hub/configs/edit-a-config

New versions of a config can be created and published using the sidebar.

First, select a config from the dropdown at the top.

While editing a config, you can explore the hub and click "Add Block" from a block page to add it to your config.

For blocks that require secret values like API keys, you will see a small notification on the block's tile in the sidebar that will indicate if action is needed.

To delete a block, click the trash icon.

If a block you want to use does not exist yet, you can [create a new block](/hub/configs/create-a-block).

When you are done editing, click "Publish" to publish a new version of the config.

Click "Open VS Code" or "Open JetBrains" to open your IDE for using the config.


# Introduction
Source: https://docs.gourmand.dev/hub/configs/intro

Custom configuration options include Models, MCP Servers, Rules, Prompts, etc.

Following the [`config.yaml`](/reference) format, you can create a custom configuration for the Gobi CLI and IDE extensions.


# How to Use a Custom Config
Source: https://docs.gourmand.dev/hub/configs/use-a-config

Learn how to add and use a custom configuration in Gobi, including setting required inputs and selecting it in your IDE extension.

## Steps to use a custom configuration in Gobi

Once you've found the configuration you want to use on Gobi Hub:

1. Click “Add Config” on its page
2. Add any required inputs (e.g. secrets like API keys)

After saving, open the Gobi CLI or IDE extension and

* Select the configuration from the **config dropdown** in the Gobi extension
* Type `/config` and select the configuration in the Gobi CLI
* Begin using it for chat mode, agent mode, or other configured capabilities.


# Creating an Organization
Source: https://docs.gourmand.dev/hub/governance/creating-an-org

To Create an Organization, click the organization selector in the top right and select

<img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-selector-4ea627afc7c0765633780920a0fbe16e.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=210b6a254f81ce0dfd881a6a13799639" alt="create an org selector" data-og-width="876" width="876" data-og-height="354" height="354" data-path="images/hub/governance/images/org-selector-4ea627afc7c0765633780920a0fbe16e.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-selector-4ea627afc7c0765633780920a0fbe16e.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=815d4c337f2975cc4edd67109933c2e7 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-selector-4ea627afc7c0765633780920a0fbe16e.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=3135b1cf976f9ee4ccc6e033828cb1a3 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-selector-4ea627afc7c0765633780920a0fbe16e.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=f443281de69b650ad7d5f9fb6b0d2627 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-selector-4ea627afc7c0765633780920a0fbe16e.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=d9c3818273fa207dd7f56e102c0afa5a 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-selector-4ea627afc7c0765633780920a0fbe16e.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=5263101fa22228023f6d0c947a9d4dbc 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-selector-4ea627afc7c0765633780920a0fbe16e.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=d788ada2ce7ec84baceeb772c6d07609 2500w" />

1. Choose a name, which will be used as the display name for your organization throughout the hub
2. Add a slug, which will be used for your org URL and as the prefix to all organization configuration slugs
3. Select an icon for your organization using the image uploader
4. Finally, add a Biography, which will be displayed on your org Home Page

<img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/create-org-form-1c7655050d8f423b0ecdfbd1cc85e0af.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=ee4aeab29afd5dfb69ced8129feb8041" alt="Creating an org" data-og-width="1754" width="1754" data-og-height="1360" height="1360" data-path="images/hub/governance/images/create-org-form-1c7655050d8f423b0ecdfbd1cc85e0af.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/create-org-form-1c7655050d8f423b0ecdfbd1cc85e0af.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=8e3e262070c4d314f6131692e9d852a1 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/create-org-form-1c7655050d8f423b0ecdfbd1cc85e0af.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=6e1086dab8ac027f356b8b630d25b5fd 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/create-org-form-1c7655050d8f423b0ecdfbd1cc85e0af.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=458d8fb845125ef476c0d46d72c322c2 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/create-org-form-1c7655050d8f423b0ecdfbd1cc85e0af.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=24ec071e09fba4b41db6360406875065 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/create-org-form-1c7655050d8f423b0ecdfbd1cc85e0af.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=3c606a919265d42f33f033b23cb38dbb 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/create-org-form-1c7655050d8f423b0ecdfbd1cc85e0af.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=3a15173d3059e30548649a823e381ea3 2500w" />

You will then be signed in to your org and taken to the org home page

<img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-home-page-4509e2ff8c4e1d6325c8f0afae3b16dd.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=fc335059e63b756fae34b32ac795ed63" alt="Org home page" data-og-width="1612" width="1612" data-og-height="828" height="828" data-path="images/hub/governance/images/org-home-page-4509e2ff8c4e1d6325c8f0afae3b16dd.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-home-page-4509e2ff8c4e1d6325c8f0afae3b16dd.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=f10d1c3827e3c1ca416bd475b360b7ce 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-home-page-4509e2ff8c4e1d6325c8f0afae3b16dd.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=02de52de4bd057e0718c2c1fa03b966e 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-home-page-4509e2ff8c4e1d6325c8f0afae3b16dd.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=8649f760559d36e2f2dfd97d127655e0 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-home-page-4509e2ff8c4e1d6325c8f0afae3b16dd.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=20daf14c8245103c55c5f99bfe399539 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-home-page-4509e2ff8c4e1d6325c8f0afae3b16dd.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=1bbe88866797d2a2545f22e568292f29 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/governance/images/org-home-page-4509e2ff8c4e1d6325c8f0afae3b16dd.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=4a0debdc5652bca4a6c842fb1d96c654 2500w" />


# Organization Permissions
Source: https://docs.gourmand.dev/hub/governance/org-permissions

Users can have the following roles within an organization:

1. Admins are users who can manage members, secrets, blocks, assistants, etc.
2. Members are users who can use assistants, blocks, secrets, etc.

**User permissions for each role depend on the pricing plan:**

* [Solo](/hub/governance/pricing#solo)
* [Teams](/hub/governance/pricing#teams)
* [Enterprise](/hub/governance/pricing#enterprise)


# Pricing
Source: https://docs.gourmand.dev/hub/governance/pricing

Gobi Hub pricing plans for individuals, teams, and enterprises, including the Models Add-On that provides access to frontier AI models for a flat monthly fee

## Solo

**Solo** is best suited for individuals and small teams with "single-player" problems.

You can read more about what **Solo** includes [here](https://hub.gourmand.dev/pricing).

## Teams

**Teams** is best suited for growing teams with "multiplayer" problems.

You can read more about what **Teams** includes [here](https://hub.gourmand.dev/pricing).

## Enterprise

**Enterprise** is best suited for large teams with enterprise-grade requirements.

You can read more about what **Enterprise** includes [here](https://hub.gourmand.dev/pricing).

## Models Add-On

The **Models Add-On** allows you to use a variety of frontier models for a flat monthly fee. It’s designed to cover the usage of most developers.

You can read more about usage limits and what models are included [here](https://hub.gourmand.dev/pricing).

### Free Trial

To try out Gobi, we offer a free trial of the **Models Add-On** that allows you to use 50 Chat requests and 2,000 autocomplete requests.


# Introduction
Source: https://docs.gourmand.dev/hub/introduction

Gobi Hub provides a central registry for creating, managing, and sharing agents, prompts, rules, MCP servers, models, etc. with organization-level governance and configuration

[Gobi Hub](https://hub.gourmand.dev) is the place to discover, configure, and govern your custom prompts, models, rules, MCP tools, and agents.

Gobi Hub provides a centralized platform for managing the essential building blocks of your AI coding workflow:

* **[Models](/hub/configs/block-types#models)**: Discover and configure models from various providers
* **[MCP Tools](/hub/configs/block-types#mcp-servers)**: Access and integrate Model Context Protocol tools to retrieve real-time data and take action
* **[Rules](/hub/configs/block-types#rules)**: Define custom guidelines, constraints, policies, etc. for the solution
* **[Prompts](/hub/configs/block-types#prompts)**: Create and share reusable instructions that kickoff an agent
  * **[Configs](/hub/configs/intro)**: a prompt and model that can be configured with rules and MCP tools to complete a task

Gobi Hub also makes it easy for engineering leaders to centrally [set up](/hub/secrets/secret-types) and [govern](/hub/governance/org-permissions) these resources for their organization.


# Secret Resolution
Source: https://docs.gourmand.dev/hub/secrets/secret-resolution

User or Org secrets should be used depending on how users want them to be shared within their organization and assistants.

For individual users and [Solo](/hub/governance/pricing#solo) organizations, secret resolution is performed in the following order:

1. User [models add-on](/hub/governance/pricing#models-add-on) (if subscribed)
2. [User secrets](/hub/secrets/secret-types#user-secrets) (if set)
3. [Free trial](/hub/governance/pricing#free-trial) (if below limit)

For [Teams](/hub/governance/pricing#teams) and [Enterprise](/hub/governance/pricing#enterprise) organizations, secret resolution is performed in the following order:

1. Org [models add-on](/hub/governance/pricing#models-add-on) (if subscribed)
2. [Org secrets](/hub/secrets/secret-types#org-secrets) (if set)
3. [User secrets](/hub/secrets/secret-types#user-secrets) (if set)


# Secret Types
Source: https://docs.gourmand.dev/hub/secrets/secret-types

The Gobi Hub comes with secrets management built-in. Secrets are values such as API keys or endpoints that can be shared across configurations and within organizations.

## User secrets

User secrets are defined by the user for themselves. This means that user secrets are available only to the user that created them. User secrets are assumed to be safe for the user to know, so they will be sent to the IDE extensions alongside `config.yaml`.

This allows API requests to be made directly from the IDE extensions. You can use user secrets with [Solo](/hub/governance/pricing#solo), [Teams](/hub/governance/pricing#teams), and [Enterprise](/hub/governance/pricing#enterprise). User secrets can be managed [here](https://hub.gourmand.dev/settings/secrets) in the hub.

## Org secrets

Org secrets are defined by admins for their organization. Org secrets are available to anyone in the organization to use with configurations in that organization. Org secrets are assumed to not be shareable with the user (e.g. you are a team lead who wants to give team members access to models without passing out API keys).

This is why LLM requests are proxied through api.gourmand.dev / on-premise proxy and secrets are never sent to the IDE extensions. You can only use org secrets on [Teams](/hub/governance/pricing#teams) and [Enterprise](/hub/governance/pricing#enterprise). If you are an admin, you can manage secrets for your organization from the org settings page.


# Sharing
Source: https://docs.gourmand.dev/hub/sharing

Connect with the Gobi community to discover, share, and collaborate on AI development tools.

## Community

Join thousands of developers using Gobi. Share experiences, get help, and contribute to the ecosystem.

[Join our Discord Community →](https://discord.gg/gobi)

## Publishing

Share your custom assistants, blocks, and configurations with the Gobi community.

[Visit the Hub →](https://hub.gourmand.dev)

## Browse Configurations

Explore assistants created by the community for specific use cases and workflows.

[Browse Configurations →](https://hub.gourmand.dev)

## Using Configurations

Learn how to discover, install, and use community-created assistants in your projects.

[Learn About Configurations →](/hub/configs/intro)

***

The Gobi Hub makes it easy to leverage community knowledge and share your innovations with fellow developers.


# Source Control
Source: https://docs.gourmand.dev/hub/source-control

When managing your custom configurations within an organization, you might want to take advantage of your usual source control workflows. Gobi makes this easy with a GitHub Action that automatically syncs your YAML files with hub.gourmand.dev. We are also planning on adding automations for GitLab, BitBucket, Gitee, and others. If you are interested, please reach out to us on .

## Quickstart

This quickstart uses a template repository, but you can also follow these steps 2-4 from an existing repository.

### 1. Create a new repository from the template

As shown in the image below, start by creating a new repository from [the template](https://github.com/gourmand/gobi-hub-template). Click "Use Template" and then "Create a new repository".

<img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/images/template-repo-65ccd7537b6fba3bbb202ee3e83e1953.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=ff2cbd8bb3271bff96b5c7bf64c4c714" alt="Use the template repository" data-og-width="2420" width="2420" data-og-height="1506" height="1506" data-path="images/hub/images/template-repo-65ccd7537b6fba3bbb202ee3e83e1953.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/images/template-repo-65ccd7537b6fba3bbb202ee3e83e1953.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=9860f6702eb065e4d08686839afb5d56 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/images/template-repo-65ccd7537b6fba3bbb202ee3e83e1953.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=25d611b63bb753ed7ab64b0fbb07c4dc 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/images/template-repo-65ccd7537b6fba3bbb202ee3e83e1953.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=4e0e50220fc6f288fbc66ad1e4b66562 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/images/template-repo-65ccd7537b6fba3bbb202ee3e83e1953.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=229d54e2b53bdf78a4dc376cb42c2067 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/images/template-repo-65ccd7537b6fba3bbb202ee3e83e1953.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=1959cf233031b1263c7315b6272ed86f 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/images/template-repo-65ccd7537b6fba3bbb202ee3e83e1953.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=9a6796aa2a872ee6b16adcd5c64e307e 2500w" />

### 2. Obtain a deploy key

Deploy keys allow the GitHub Action to authenticate with hub.gourmand.dev. [Obtain your deploy key here](https://hub.gourmand.dev/settings/api-keys) and then [create a secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) named `GOBI_API_KEY` in your GitHub repository.

### 3. Configure the GitHub Action

<Check>
  This step assumes you have already created an organization on
  hub.gourmand.dev. If not, learn more [here](/hub/governance/creating-an-org).
</Check>

In the repository you created, navigate to `.github/workflows/main.yaml` and update the lines below to match your organization:

```
env:  OWNER_SLUG: my-org-slug # <-- TODO
```

This is the only configuration necessary, but you can view the full list of options [here](https://github.com/gourmand/gobi-publish-action/blob/main/README.md).

### 4. Commit and push

Add the [YAML for your configurations](/reference) to the appropriate directories. The name of the file will be the slug of the configuration options.

* `assistants/public` for public configurations
* `assistants/private` for private (visible only within your organization) configurations
* `blocks/public` for public configuration options
* `blocks/private` for private configuration options

Then, commit and push your changes. Once the GitHub Action has completed running, you should be able to view the configurations within your organization on hub.gourmand.dev. For subsequent changes, make sure to increment the `version` property of your updated YAML file(s).


# Introduction
Source: https://docs.gourmand.dev/hub/workflows/intro

Run and manage background agents in Mission Control

<Info>
  Mission Control is in beta. Please share any feedback with us in [GitHub discussions](https://github.com/gourmand/gobi/discussions/8051).
</Info>

Mission Control is a way to run and manage background agents in Gobi. You can use it to kick off:

* Addressing small nitpicks and bugs
* Building boilerplate-heavy features
* Investigating an issue to kickstart your work
* [Automated security scanning](../../guides/snyk-mcp-gobi-cookbook)
* Running repeatable tasks with your own rules, prompts, and MCP servers
* Much more!

## Quickstart

To kick off your first agent

1. Go to [hub.gourmand.dev/agents](https://hub.gourmand.dev/agents)

<img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/workflows/images/workflows-setup.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=126a89951fccc28acefada4002380f86" alt="Mission Control Setup" data-og-width="2524" width="2524" data-og-height="1290" height="1290" data-path="images/hub/workflows/images/workflows-setup.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/workflows/images/workflows-setup.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=1f322ef7dd8135041e4ef6a7218f581b 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/workflows/images/workflows-setup.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=11bd8b1de5a071d618ee5f45e9440629 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/workflows/images/workflows-setup.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=8dabb934340b227ae6c3ecfdcb33b645 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/workflows/images/workflows-setup.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=de543280bb234900bc6f13c3d92de629 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/workflows/images/workflows-setup.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=64405134e817685e06ef20fc39e5c191 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/hub/workflows/images/workflows-setup.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=0835dc4caa80264d8a8120357dc6b59a 2500w" />

2. Connect with your GitHub account
3. Enter the prompt for your agent

## Example Workflow Tasks

Here are some example tasks you can try with your agents:

<AccordionGroup>
  <Accordion title="Bug Fixes & Code Quality">
    * "Fix the TypeError in api/users.ts where the user object might be undefined"
    * "Add null checks to all database query results in the services/ directory"
    * "Fix all ESLint warnings in the components folder"
    * "Update deprecated React lifecycle methods to hooks in legacy components"
  </Accordion>

  <Accordion title="Feature Development">
    * "Create a new REST endpoint for user profile updates with validation and error handling"
    * "Add pagination to the products list page with previous/next buttons"
    * "Implement dark mode toggle using Tailwind CSS classes across all pages"
    * "Add unit tests for the authentication service using Jest"
  </Accordion>

  <Accordion title="Security & Compliance">
    * "Scan the codebase for hardcoded API keys and move them to environment variables"
    * "Add input sanitization to all user-facing form fields"
    * "Update all npm packages with known security vulnerabilities"
    * "Implement rate limiting on the /api/login endpoint"
  </Accordion>

  <Accordion title="Documentation & Boilerplate">
    * "Add JSDoc comments to all exported functions in the utils/ directory"
    * "Create a README.md for the new payment-processing module with setup instructions"
    * "Generate TypeScript interfaces for all API response schemas"
    * "Add error handling boilerplate to all async functions missing try-catch blocks"
  </Accordion>

  <Accordion title="Investigation & Analysis">
    * "Investigate why the login API is returning 500 errors intermittently and suggest fixes"
    * "Analyze the performance bottleneck in the data processing pipeline"
    * "Review the database schema for the orders table and suggest optimizations"
    * "Find all TODO comments related to authentication and create a summary"
  </Accordion>

  <Accordion title="Refactoring">
    * "Extract the repeated validation logic in controllers into a shared utility function"
    * "Convert all class components in src/legacy to functional components with hooks"
    * "Rename all instances of 'userId' to 'accountId' across the codebase"
    * "Split the 500-line UserService.ts into smaller, single-responsibility services"
  </Accordion>
</AccordionGroup>

## How to use background agents

The practice of using background agents, which we call Continuous AI, requires practice and forethought to set up the right guiderails and habits to fit your development workflow, much like learning to work with a larger engineering team. We are constantly sharing our learnings on the [Continuous AI Blog](https://blog.gourmand.dev), but these few high-level tips are a great way to quickly become successful with agents:

* Practice first with the [Gobi CLI](../../guides/cli) in "TUI mode". The Gobi CLI is used to run agents, so you can easily test your prompts locally.
* Identify and begin with tasks that you are confident can be accomplished by Gobi. For example, ask Gobi to fix a small bug where you already know the solution is simple.
* Once you have merged a PR created by Gobi, be increasingly ambitious with your tasks. By being willing to start tasks that might not succeed on the first try, you will learn about prompting best practices and limitations of current language models.
* Use thorough prompts. Workflows can run for a long time to complete their task, so it is worthwhile to invest in sharing all of the important details.
* Discuss the use of agents with your team. Truly embracing Continuous AI likely means acknowledging that a higher volume of PRs will be created and adjusting your code review habits.


# Context Selection
Source: https://docs.gourmand.dev/ide-extensions/agent/context-selection

Learn how Gobi's agent mode selects relevant code context using file content, language server definitions, imports, and recent file history.

You can use the same methods to manually add context as [Chat](/ide-extensions/chat/context-selection).

Tool call responses are automatically included as context items. This enables Agent mode to see the result of the previous action and decide what to do next.


# How Agent Mode Works
Source: https://docs.gourmand.dev/ide-extensions/agent/how-it-works

Agent mode offers the same functionality as Chat mode, while also including tools in the request to the model and an interface for handling tool calls and responses.

## How the Tool Handshake Works

Tools provide a flexible, powerful way for models to interface with the external world. They are provided to the model as a JSON object with a name and an arguments schema. For example, a `read_file` tool with a `filepath` argument will give the model the ability to request the contents of a specific file.

The following handshake describes how Agent mode uses tools:

1. In Agent mode, available tools are sent along with `user` chat requests
2. The model can choose to include a tool call in its response
3. The user gives permission. This step is skipped if the policy for that tool is set to `Automatic`
4. Gobi calls the tool using built-in functionality or the MCP server that offers that particular tool
5. Gobi sends the result back to the model
6. The model responds, potentially with another tool call and step 2 begins again

<Info>
  Tool availability varies by mode: - **Chat mode**: No tools included - **Plan
  mode**: Only read-only tools included - **Agent mode**: All tools included
</Info>

## What Built-in Tools Are Available

Gobi includes several built-in tools which provide the model access to IDE functionality.

### What Tools Are Available in Plan Mode (Read-Only)

In Plan mode, only these read-only tools are available:

* **Read file** (`read_file`)
* **Read currently open file** (`read_currently_open_file`)
* **List directory** (`ls`)
* **Glob search** (`glob_search`)
* **Grep search** (`grep_search`)
* **Fetch URL content** (`fetch_url_content`)
* **Search web** (`search_web`)
* **View diff** (`view_diff`)
* **View repo map** (`view_repo_map`)
* **View subdirectory** (`view_subdirectory`)
* **Codebase tool** (`codebase_tool`)

### What Tools Are Available in Agent Mode (All Tools)

In Agent mode, all tools are available including the read-only tools above plus:

* **Create new file** (`create_new_file`): Create a new file within the project
* **Edit file** (`edit_file`): Make changes to existing files
* **Run terminal command** (`run_terminal_command`): Run commands from the workspace root
* **Create Rule Block** (`create_rule_block`): Create a new rule block in `.gobi/rules`
* All other write/execute tools for modifying the codebase


# How to Customize Agent Mode
Source: https://docs.gourmand.dev/ide-extensions/agent/how-to-customize

Learn how to customize Agent Mode in Gobi to better fit your workflow and coding style.

## How to Add Rules Blocks

Adding Rules can be done in your configuration locally or in the Hub. You can explore Rules on the Gobi Hub and refer to the [Rules deep dive](/customize/deep-dives/rules) for more details.

## How to Customize System Messages

You can customize the system messages for Chat, Agent, and Plan modes using model-level configuration:

```yaml  theme={null}
models:
  - name: GPT-4o
    provider: openai
    model: gpt-4o
    chatOptions:
      baseSystemMessage: "You are a helpful coding agent."
      baseAgentSystemMessage: "You are a systematic coding agent. Break down problems methodically."
      basePlanSystemMessage: "You are a planning agent. Create clear, actionable steps."
```

## How to Add MCP Tools

You can add MCP servers to your configuration to give Agent mode access to more tools. Explore [MCP Servers on the Hub](https://hub.gourmand.dev) and consult the [MCP guide](/customize/deep-dives/mcp) for more details.

## How to Configure Tool Policies

You can adjust the Agent mode's tool usage behavior to three options:

* **Ask First (default)**: Request user permission with "Cancel" and "Gobi" buttons
* **Automatic**: Automatically call the tool without requesting permission
* **Excluded**: Do not send the tool to the model

:::warning
Be careful setting tools to "automatic" if their behavior is not read-only.
:::

To manage tool policies:

1. Click the tools icon in the input toolbar
2. View and change policies by clicking on the policy text
3. You can also toggle groups of tools on/off

Tool policies are stored locally per user.


# Model Setup for Agent Mode
Source: https://docs.gourmand.dev/ide-extensions/agent/model-setup

Learn how to set up models for Agent Mode in Gobi, including recommended models and configuration options for optimal performance

export const ModelRecommendations = ({role = "all"}) => {
  const parseMarkdownLinks = text => {
    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const parts = [];
    let lastIndex = 0;
    let match;
    let key = 0;
    while ((match = regex.exec(text)) !== null) {
      if (match.index > lastIndex) {
        const beforeText = text.slice(lastIndex, match.index);
        if (beforeText) {
          parts.push(<span key={key++}>{beforeText}</span>);
        }
      }
      const [, linkText, url] = match;
      parts.push(<a key={key++} href={url} target="_blank" rel="noopener noreferrer" style={{
        color: "#0066cc",
        textDecoration: "underline"
      }}>
          {linkText}
        </a>);
      lastIndex = regex.lastIndex;
    }
    if (lastIndex < text.length) {
      const remainingText = text.slice(lastIndex);
      if (remainingText) {
        parts.push(<span key={key++}>{remainingText}</span>);
      }
    }
    return parts.length > 0 ? parts : text;
  };
  const modelRecs = {
    agent_plan: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[Devstral (27B)](https://hub.gourmand.dev/ollama/devstral)", "[Kimi K2 (1T)](https://hub.gourmand.dev/openrouter/kimi-k2)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)", "[GLM 4.5 (355B)](https://hub.gourmand.dev/openrouter/glm-4-5)", "[GLM 4.5 Air (106B)](https://hub.gourmand.dev/openrouter/glm-4-5-air)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed models are slightly better than open models"
    },
    chat_edit: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed and open models have pretty similar performance"
    },
    autocomplete: {
      open: ["[QwenCoder2.5 (1.5B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)", "[QwenCoder2.5 (7B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)"],
      closed: ["[Codestral](https://hub.gourmand.dev/mistral/codestral)", "[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are slightly better than open models"
    },
    apply: {
      open: ["N/A"],
      closed: ["[Relace Instant Apply](https://hub.gourmand.dev/relace/instant-apply)", "[Morph Fast Apply](https://hub.gourmand.dev/morphllm/morph-v2)"],
      notes: "Open models are not good enough for this model role"
    },
    embed: {
      open: ["[Nomic Embed Text](https://hub.gourmand.dev/ollama/nomic-embed-text-latest)", "Qwen3 Embedding"],
      closed: ["[Voyage Code 3](https://hub.gourmand.dev/voyageai/voyage-code-3)", "[Morph Embeddings](https://hub.gourmand.dev/morphllm/morph-embedding-v2)", "Codestral Embed"],
      notes: "Closed models are slightly better than open models"
    },
    rerank: {
      open: ["zerank-1", "zerank-1-small", "Qwen3 Reranker"],
      closed: ["[Voyage Rerank 2.5](https://hub.gourmand.dev/voyageai/rerank-2-5)", "Relace Code Rerank", "[Morph Rerank](https://hub.gourmand.dev/morphllm/morph-rerank-v2)"],
      notes: "Open models are beginning to emerge for this model role"
    },
    next_edit: {
      open: ["[Instinct](https://hub.gourmand.dev/gobi/instinct)"],
      closed: ["[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are better than open models"
    }
  };
  let rolesToShow = [];
  if (!role || role === "all") {
    rolesToShow = Object.keys(modelRecs);
  } else {
    const key = role.toLowerCase().replace(/\s|\//g, "_").replace(/-/g, "_");
    if (modelRecs[key]) {
      rolesToShow = [key];
    }
  }
  if (rolesToShow.length === 0) {
    return <div>No recommendations found for role: {role}</div>;
  }
  return <table style={{
    width: "100%",
    borderCollapse: "collapse",
    marginTop: "1rem"
  }}>
      <thead>
        <tr>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Model role
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best open models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best closed models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Notes
          </th>
        </tr>
      </thead>
      <tbody>
        {rolesToShow.map(roleKey => {
    const rec = modelRecs[roleKey];
    if (!rec) return null;
    return <tr key={roleKey}>
              <td style={{
      fontWeight: 600,
      verticalAlign: "top",
      padding: "8px"
    }}>
                {roleKey.replace(/_/g, " ").replace(/\b\w/g, l => l.toUpperCase())}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.open.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.closed.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.notes}
              </td>
            </tr>;
  })}
      </tbody>
    </table>;
};

The models you set up for Chat mode will be used with Agent mode if the model supports tool calling. The recommended models and how to set them up can be found [here](/ide-extensions/chat/model-setup).

## How System Message Tools Work

Gobi implements an innovative approach called **system message tools** that ensures consistent tool functionality across all models, regardless of their native capabilities. This allows Agent mode to work seamlessly with a wider range of models and providers.

### How System Message Tools Function

Instead of relying solely on native tool calling APIs (which vary between providers), Gobi converts tools into XML format and includes them in the system message. The model generates tool calls as structured XML within its response, which Gobi then parses and executes. This approach provides:

* **Universal compatibility** - Any model capable of following instructions can use tools, not just those with native tool support
* **Consistent behavior** - Tool calls work identically across OpenAI, Anthropic, local models, and others
* **Better reliability** - Models that struggle with native tools often perform better with system message tools
* **Seamless switching** - Change between providers without modifying your workflow

## Recommended Agent Models

<ModelRecommendations role="all" />

### How to Configure Agent Mode

Agent mode automatically determines whether to use native or system message tools based on the model's capabilities. No additional configuration is required - simply select your model and Gobi handles the rest.

## How to Check Model Compatibility

To see which models support specific features like tool use (for Agent mode) and image input, check out our [Model Capabilities guide](/customize/deep-dives/model-capabilities).


# Plan Mode in Gobi – Safe, Read-Only Code Exploration
Source: https://docs.gourmand.dev/ide-extensions/agent/plan-mode

Learn how to use Plan Mode in Gobi to explore and understand codebases safely with read-only tools, search, and analysis before making changes

## What is Plan mode?

Plan mode is a restricted environment that provides read-only access to your codebase. It's designed for safe exploration, understanding code, and planning changes without making any modifications.

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode.gif?s=d6e5ad7e6d35831bf4bf3c94305300c5" alt="Plan mode in action" data-og-width="1108" width="1108" data-og-height="720" height="720" data-path="images/plan-mode.gif" data-optimize="true" data-opv="3" />

### What Are the Key Features of Plan Mode?

* **Read-only tools**: Access files, search, and analyze without risk
* **Safe exploration**: Perfect for understanding unfamiliar codebases
* **Planning focus**: Develop implementation strategies before execution
* **MCP support**: Works with all MCP tools alongside built-in read-only tools

### How Plan Mode Works

Plan mode filters the available tools to only include read-only operations. This means you can:

* Read any file in your project
* Search through code with grep and glob patterns
* View repository structure and diffs
* Fetch web content for additional context
* Use all MCP tools

But you cannot:

* Create, edit, or delete files
* Run terminal commands
* Make any system changes

### How to Get Started with Plan Mode

Select "Plan" from the mode selector below the chat input, or use `Cmd/Ctrl + .` to cycle through modes.

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=ce952a30fb67850ea861248ceb0f253b" alt="Plan mode selector" data-og-width="1404" width="1404" data-og-height="390" height="390" data-path="images/plan-mode-selector.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=5722692b9d5c7dfdcfa633ccdc4f2025 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=35a7a3a004ef1551280e781738eea595 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=63f902eedc134e233aa96baaae383721 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=c0b559f8944bafe613dc72d2a84f88a6 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=eb336e8e9ffdaace2c683b8566c554a5 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode-selector.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=2782a35a74e6b471965247c1a0ac7201 2500w" />

For detailed information about tools and usage, see the [Agent documentation](/ide-extensions/agent/how-it-works), which covers both Agent and Plan modes.

### What Is the Common Workflow for Plan Mode?

1. **Start in Plan mode** to explore and understand
2. **Develop your approach** with the model's help
3. **Switch to Agent mode** when ready to implement

<Tip>
  Plan mode shares the same interface and context features as Chat and Agent
  modes. You can use `@` context providers and highlight code just like in other
  modes.
</Tip>


# Quick Start
Source: https://docs.gourmand.dev/ide-extensions/agent/quick-start

Get started with Gobi's Agent mode to automatically implement code changes, fix bugs, and run commands using AI-powered tools that can modify your codebase based on natural language instructions

Agent mode equips the Chat model with the tools needed to handle a wide range of coding tasks, allowing the model to make decisions and save you the work of manually finding context and performing actions.

<Accordion title="Learn how to choose the right mode" icon="lightbulb">
  <Columns cols={3}>
    <Card title="Chat Mode" icon="comments">
      *Learn and discuss without changing code.*

      **Mental Model:** Talking to a knowledgeable colleague

      **Best For:** Explaining concepts, comparing approaches, code review discussions.
    </Card>

    <Card title="Plan Mode" icon="binoculars">
      *Safely explore and plan with read-only tools.*

      **Mental Model:** Architect surveying before renovation

      **Best For:** Understanding a codebase, bug investigation, planning implementations.
    </Card>

    <Card title="Agent Mode" icon="hammer">
      *Make actual changes with full tool access.*

      **Mental Model:** Contractor executing approved blueprints

      **Best For:** Implementing features, fixing bugs, running tests and commands.
    </Card>
  </Columns>
</Accordion>

### How to Use Agent Mode

You can switch to `Agent` in the mode selector below the chat input box. The mode selector offers three options:

* **Chat mode**: No tools available, pure conversation
* **Plan mode**: Read-only tools for safe exploration and planning
* **Agent mode**: All tools available for making changes

<img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mode-select-agent.png?fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=e8f0e1ce68925b0284337d0cad9ff1df" alt="How to select agent mode" data-og-width="186" width="186" data-og-height="124" height="124" data-path="images/mode-select-agent.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mode-select-agent.png?w=280&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=ed29a5caf65f5275e5310eedfc05231c 280w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mode-select-agent.png?w=560&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=4972dc3eba2838d60f3ad99079b48ffa 560w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mode-select-agent.png?w=840&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=d9f9b6d1b52122a1ed25dfc22f4c0c43 840w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mode-select-agent.png?w=1100&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=494f240fea24f9c083f5f597c59d1911 1100w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mode-select-agent.png?w=1650&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=5c19e862ef6ad49b370efd5d8bd98941 1650w, https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/mode-select-agent.png?w=2500&fit=max&auto=format&n=lfYeqLX2hvXkgz5p&q=85&s=79a03f595b9e050b5205c805687bf618 2500w" />

<Info>
  If Agent mode or Plan mode is disabled with a `Not Supported` message, the selected
  model or provider doesn't support tools, or Gobi doesn't yet support tools
  with it. See [Model Blocks](/customization/models) for more information.
</Info>

<Tip>
  Use the keyboard shortcut `Cmd/Ctrl + .` to quickly cycle between modes.
</Tip>

### How to Chat with Agent mode

Agent mode lives within the same interface as [Chat](/ide-extensions/chat/how-it-works) mode, so the same [input](/ide-extensions/chat/quick-start#how-to-start-a-conversation) is used to send messages and you can still use the same manual methods of providing context, such as [`@` context providers](/ide-extensions/chat/quick-start#how-to-use--for-additional-context) or adding [highlighted code from the editor](/ide-extensions/chat/quick-start#how-to-include-code-context).

#### How to Use Natural Language with Agent mode

With Agent mode, you can provide natural language instruction and let the model do the work. As an example, you might say

> Set the @typescript-eslint/naming-convention rule to "off" for all eslint configurations in this project

Agent mode will then decide which tools to use to get the job done.

## How to Give Agent Mode Permission

By default, Agent mode will ask permission when it wants to use a tool. Click `Gobi` to allow Agent mode to proceed with the tool call or `Cancel` to reject it.

<img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-permission-c150919a5c43eb4f55d9d4a46ef8b2d6.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=660583fbf0838c462cf249ec102763e7" alt="agent requesting permission" data-og-width="1432" width="1432" data-og-height="702" height="702" data-path="images/ide-extensions/agent/images/agent-permission-c150919a5c43eb4f55d9d4a46ef8b2d6.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-permission-c150919a5c43eb4f55d9d4a46ef8b2d6.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=942569b0a6da0f2fa65e9806007350ed 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-permission-c150919a5c43eb4f55d9d4a46ef8b2d6.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=579bf6e46022dcfa09f94186086f28f4 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-permission-c150919a5c43eb4f55d9d4a46ef8b2d6.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=325ab83e66804989eee6b8edb68d5310 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-permission-c150919a5c43eb4f55d9d4a46ef8b2d6.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=92e31f87d10c1bffdf5160574c5aad90 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-permission-c150919a5c43eb4f55d9d4a46ef8b2d6.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=060620c8ee2ecf5a634bb53b2c1042f1 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-permission-c150919a5c43eb4f55d9d4a46ef8b2d6.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=cee636193232b54bea286bcf0a14d871 2500w" />

You can use tool policies to exclude or make usage automatic for specific tools. See [MCP Tools](/customization/mcp-tools) for more background.

## How to View Tool Responses

Any data returned from a tool call is automatically fed back into the model as a context item. Most errors are also caught and returned, so that Agent mode can decide how to proceed.

<img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-response-c7287c82aac93fb4376f9d85b352b2d7.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=156913435132dd544d24955d426fdada" alt="agent response" data-og-width="1454" width="1454" data-og-height="1038" height="1038" data-path="images/ide-extensions/agent/images/agent-response-c7287c82aac93fb4376f9d85b352b2d7.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-response-c7287c82aac93fb4376f9d85b352b2d7.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=29a5a71d88ffd7710cd2272181a7b938 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-response-c7287c82aac93fb4376f9d85b352b2d7.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=0b9a4b80e3bf1a30f7d221845f786c35 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-response-c7287c82aac93fb4376f9d85b352b2d7.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=7effe9c85bbc43cbfcb7e1cde49dbbbe 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-response-c7287c82aac93fb4376f9d85b352b2d7.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=691a767b3e654f62d4c538c89cf1e7f1 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-response-c7287c82aac93fb4376f9d85b352b2d7.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=0d0287086367dfdfae0291bb8b1d9c2c 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/agent/images/agent-response-c7287c82aac93fb4376f9d85b352b2d7.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=95e232246f98891f6bb122ffc65050df 2500w" />


# Context Selection
Source: https://docs.gourmand.dev/ide-extensions/autocomplete/context-selection

Learn how Gobi's autocomplete selects relevant code context using file content, language server definitions, imports, and recent file history.

Autocomplete will automatically determine context based on the current cursor position. We use the following techniques to determine what to include in the prompt:

## File Prefix and Suffix Context

We will always include the code from your file prior to and after the cursor position.

## Language Server Protocol (LSP) Definitions

Similar to how you can use cmd/ctrl + click in your editor, we use the same tool (the LSP) to power "go to definition". For example, if you are typing out a function call, we will include the function definition. Or, if you are writing code inside of a method, we will include the type definitions for any parameters or the return type.

## Imported File Context

Because there are often many imports, we can't include all of them. Instead, we look for symbols around your cursor that have matching imports and use that as context.

## Recent File Context

We automatically consider recently opened or edited files and include snippets that are relevant to the current completion.


# How Autocomplete Works in Gobi
Source: https://docs.gourmand.dev/ide-extensions/autocomplete/how-it-works

Understand how Gobi's autocomplete works, including timing optimization, context retrieval from your codebase, and filtering to improve AI code suggestions.

## Timing Optimization for Autocomplete

In order to display suggestions quickly, without sending too many requests, we do the following:

* Debouncing: If you are typing quickly, we won't make a request on each keystroke. Instead, we wait until you have finished.
* Caching: If your cursor is in a position that we've already generated a completion for, this completion is reused. For example, if you backspace, we'll be able to immediately show the suggestion you saw before.

## Context Retrieval from Your Codebase

Gobi uses a number of retrieval methods to find relevant snippets from your codebase to include in the prompt.

## Filtering and Post-Processing AI Suggestions

Language models aren't perfect, but can be made much closer by adjusting their output. We do extensive post-processing on responses before displaying a suggestion, including:

* Removing special tokens
* Stopping early when regenerating code to avoid long, irrelevant output
* Fixing indentation for proper formatting
* Occasionally discarding low-quality responses, such as those with excessive repetition

You can learn more about how it works in the [Autocomplete deep dive](/customization/models#autocomplete).

<Info>
  **Looking for AI that predicts your next changes or additions?** Check out
  [Next Edit](/ide-extensions/autocomplete/next-edit), an experimental feature that
  proactively suggests code changes before you even start typing, going beyond
  traditional autocomplete to anticipate entire code modifications.
</Info>


# “Customize Autocomplete Settings in Gobi”
Source: https://docs.gourmand.dev/ide-extensions/autocomplete/how-to-customize

“Learn how to customize autocomplete behavior in Gobi, including user settings, configuration options, and adjustments to improve AI code suggestions in your IDE.”

Gobi offers a handful of settings to customize autocomplete behavior. Visit the User Settings Page (Gear Icon) to manage these settings.

For a comprehensive guide on all configuration options and their impacts, see the [Autocomplete deep dive](/customize/deep-dives/autocomplete).


# Recommended Models for Autocomplete in Gobi
Source: https://docs.gourmand.dev/ide-extensions/autocomplete/model-setup

Choose the best autocomplete model for Gobi, including hosted high-performance options, fast speed/quality tradeoffs, and local privacy-first models.

export const ModelRecommendations = ({role = "all"}) => {
  const parseMarkdownLinks = text => {
    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const parts = [];
    let lastIndex = 0;
    let match;
    let key = 0;
    while ((match = regex.exec(text)) !== null) {
      if (match.index > lastIndex) {
        const beforeText = text.slice(lastIndex, match.index);
        if (beforeText) {
          parts.push(<span key={key++}>{beforeText}</span>);
        }
      }
      const [, linkText, url] = match;
      parts.push(<a key={key++} href={url} target="_blank" rel="noopener noreferrer" style={{
        color: "#0066cc",
        textDecoration: "underline"
      }}>
          {linkText}
        </a>);
      lastIndex = regex.lastIndex;
    }
    if (lastIndex < text.length) {
      const remainingText = text.slice(lastIndex);
      if (remainingText) {
        parts.push(<span key={key++}>{remainingText}</span>);
      }
    }
    return parts.length > 0 ? parts : text;
  };
  const modelRecs = {
    agent_plan: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[Devstral (27B)](https://hub.gourmand.dev/ollama/devstral)", "[Kimi K2 (1T)](https://hub.gourmand.dev/openrouter/kimi-k2)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)", "[GLM 4.5 (355B)](https://hub.gourmand.dev/openrouter/glm-4-5)", "[GLM 4.5 Air (106B)](https://hub.gourmand.dev/openrouter/glm-4-5-air)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed models are slightly better than open models"
    },
    chat_edit: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed and open models have pretty similar performance"
    },
    autocomplete: {
      open: ["[QwenCoder2.5 (1.5B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)", "[QwenCoder2.5 (7B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)"],
      closed: ["[Codestral](https://hub.gourmand.dev/mistral/codestral)", "[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are slightly better than open models"
    },
    apply: {
      open: ["N/A"],
      closed: ["[Relace Instant Apply](https://hub.gourmand.dev/relace/instant-apply)", "[Morph Fast Apply](https://hub.gourmand.dev/morphllm/morph-v2)"],
      notes: "Open models are not good enough for this model role"
    },
    embed: {
      open: ["[Nomic Embed Text](https://hub.gourmand.dev/ollama/nomic-embed-text-latest)", "Qwen3 Embedding"],
      closed: ["[Voyage Code 3](https://hub.gourmand.dev/voyageai/voyage-code-3)", "[Morph Embeddings](https://hub.gourmand.dev/morphllm/morph-embedding-v2)", "Codestral Embed"],
      notes: "Closed models are slightly better than open models"
    },
    rerank: {
      open: ["zerank-1", "zerank-1-small", "Qwen3 Reranker"],
      closed: ["[Voyage Rerank 2.5](https://hub.gourmand.dev/voyageai/rerank-2-5)", "Relace Code Rerank", "[Morph Rerank](https://hub.gourmand.dev/morphllm/morph-rerank-v2)"],
      notes: "Open models are beginning to emerge for this model role"
    },
    next_edit: {
      open: ["[Instinct](https://hub.gourmand.dev/gobi/instinct)"],
      closed: ["[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are better than open models"
    }
  };
  let rolesToShow = [];
  if (!role || role === "all") {
    rolesToShow = Object.keys(modelRecs);
  } else {
    const key = role.toLowerCase().replace(/\s|\//g, "_").replace(/-/g, "_");
    if (modelRecs[key]) {
      rolesToShow = [key];
    }
  }
  if (rolesToShow.length === 0) {
    return <div>No recommendations found for role: {role}</div>;
  }
  return <table style={{
    width: "100%",
    borderCollapse: "collapse",
    marginTop: "1rem"
  }}>
      <thead>
        <tr>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Model role
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best open models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best closed models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Notes
          </th>
        </tr>
      </thead>
      <tbody>
        {rolesToShow.map(roleKey => {
    const rec = modelRecs[roleKey];
    if (!rec) return null;
    return <tr key={roleKey}>
              <td style={{
      fontWeight: 600,
      verticalAlign: "top",
      padding: "8px"
    }}>
                {roleKey.replace(/_/g, " ").replace(/\b\w/g, l => l.toUpperCase())}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.open.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.closed.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.notes}
              </td>
            </tr>;
  })}
      </tbody>
    </table>;
};

Setting up the right model for autocomplete is important for a smooth coding experience. Here are our top recommendations:

## Model Recommendations

<ModelRecommendations role="autocomplete" />

<Info>
  For a complete comparison of all models, see our [comprehensive model recommendations](/customization/models#recommended-models).
</Info>

## Next Edit Model

For proactive code prediction that anticipates your next edit, Gobi supports specialized [Next Edit](/ide-extensions/autocomplete/next-edit) models:

**Supported Next Edit model:**

* `mercury-coder-nextedit`: Primary model optimized for next edit prediction

Next Edit automatically activates when you have a compatible model configured for autocomplete and the appropriate access permissions.

## Need Help?

If you're not seeing any completions or need more detailed configuration options, check out our comprehensive [autocomplete deep dive guide](/customize/deep-dives/autocomplete).

## Model Compatibility

To see a complete list of models and their capabilities, visit our [Model Capabilities guide](/customize/deep-dives/model-capabilities).


# Next Edit
Source: https://docs.gourmand.dev/ide-extensions/autocomplete/next-edit

Learn how Gobi's Next Edit feature predicts and suggests your next code changes using AI, going beyond traditional autocomplete to anticipate entire code modifications

<Warning>
  Next Edit is currently an experimental feature. It requires
  [Instinct](https://hub.gourmand.dev/gobi/instinct) or [Mercury Coder
  model](https://hub.gourmand.dev/inception/mercury-coder) configured in
  your Gobi autocomplete settings and is not yet available for JetBrains
  use.
</Warning>

## What is Next Edit?

Next Edit is an advanced AI-powered code prediction feature that anticipates what changes you'll make next in your code. Unlike traditional autocomplete that reacts to your typing, Next Edit proactively analyzes your recent edits and coding patterns to suggest entire code modifications before you even start typing.

Think of it as having an AI pair programmer that understands your coding flow and suggests the logical next step in your development process.

## How Next Edit Works

### The Prediction Process

1. **Context Analysis**: Captures your current cursor position and recent edit history
2. **Pattern Recognition**: Analyzes your coding patterns and the surrounding code context
3. **Next Step Prediction**: Uses specialized AI models to predict what you'll likely change next
4. **Visual Presentation**: Shows predictions as diff overlays rather than simple text completions
5. **Interactive Review**: Lets you accept (Tab) or reject (Esc) the suggested changes
6. **Jump to Next Edit Location**: Lets you jump (Tab) to the next edit location or reject (Esc)

### Intelligent Triggering

Next Edit activates automatically when:

* You finish making a code change
* The AI detects a logical continuation point
* Specialized next-edit models are available
* The current context suggests a predictable next step

## Next Edit vs Traditional Autocomplete

<AccordionGroup>
  <Accordion title="Prediction Scope">
    **Autocomplete**: Completes the current line or statement you're typing

    **Next Edit**: Predicts entire code modifications across multiple lines
  </Accordion>

  <Accordion title="User Interaction">
    **Autocomplete**: Shows ghost text at your cursor position

    **Next Edit**: Displays diff overlays showing before/after changes, while also displaying ghost text if the change is purely additive.
  </Accordion>

  <Accordion title="Timing">
    **Autocomplete**: Reactive - responds to what you're currently typing

    **Next Edit**: Proactive - anticipates what you'll do next
  </Accordion>

  <Accordion title="Context Awareness">
    **Autocomplete**: Focuses on immediate code completion

    **Next Edit**: Analyzes recent edit patterns and broader code context
  </Accordion>
</AccordionGroup>

## How to Use Next Edit

### Prerequisites

Next Edit requires:

* Compatible AI models (Mercury Coder or Instinct)
* VS Code (JetBrains support coming soon)
* **API Keys**: Organizations can add API keys to [org secrets](/hub/secrets/secret-types) for team-wide access. Individual users need to provide their own API keys in their [model configuration](/customize/model-providers/overview)

<Note>
  To use Next Edit, you must have the Instinct or Mercury Coder model configured
  in your Gobi autocomplete model settings. This model is specifically
  designed for next edit predictions. Once it's been loaded, you must reload VS
  Code to activate it.

  <img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/autocomplete/images/instinct-autocomplete.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=0da764997309087640dafc0a95d3f082" alt="Next Edit Model Setup" data-og-width="740" width="740" data-og-height="562" height="562" data-path="images/ide-extensions/autocomplete/images/instinct-autocomplete.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/autocomplete/images/instinct-autocomplete.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=bb84b12f0775263e94a9dc43acad4fd8 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/autocomplete/images/instinct-autocomplete.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=94806c1b3ba4edf6abc0f0a0292acf14 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/autocomplete/images/instinct-autocomplete.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=db6eaf72cc8b1f6d867271c229b5816a 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/autocomplete/images/instinct-autocomplete.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=d3ff07c57e5641776c93e6463bc37f66 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/autocomplete/images/instinct-autocomplete.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=423c4f84564dc17ad81fb1a8da34f508 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/ide-extensions/autocomplete/images/instinct-autocomplete.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=f89e9e8c3f873639cc2101b2030913ae 2500w" />
</Note>

### Using Next Edit Predictions

<Steps>
  <Step title="Make a Code Change">
    Edit your code normally. Next Edit will analyze your change patterns.
  </Step>

  <Step title="Review Predictions">
    When Next Edit activates, you'll see a diff overlay showing predicted changes
    in an editable region.
  </Step>

  <Step title="Accept or Reject">
    * **Tab**: Accept the prediction and apply changes - **Esc**: Reject the
      prediction and gobi coding normally
  </Step>

  <Step title="Gobi Coding">
    If accepted, your cursor moves to the last changed line. If rejected, your
    workflow gobis uninterrupted.
  </Step>
</Steps>

## What are the Model Requirements for Next Edit?

### Specialized Models

Next Edit requires AI models specifically trained for code prediction:

* **Mercury Coder**: Primary model optimized for next edit prediction
* **Instinct**: The leading open Next Edit model, trained by Gobi

### Automatic Detection

Gobi automatically enables Next Edit when:

1. Your configured autocomplete model supports next edit capabilities
2. You have development team access permissions
3. The current code context suggests predictable next steps

## Best Practices

<CardGroup cols={2}>
  <Card title="Trust the Process" icon="robot">
    Let Next Edit observe your coding patterns for a few editing sessions before expecting highly accurate predictions.
  </Card>

  <Card title="Review Carefully" icon="magnifying-glass">
    Always review suggested changes before accepting, especially for complex logic
    modifications.
  </Card>

  <Card title="Provide Feedback" icon="message">
    Have feedback? We want to hear it. **[Add your thoughts to our feedback
    discussions](https://github.com/gourmand/gobi/discussions/categories/feedback)**
    to help us improve.
  </Card>

  <Card title="Combine with Other Features" icon="puzzle-piece">
    Use Next Edit alongside Gobi's Chat and Agent modes for comprehensive AI-assisted development.
  </Card>
</CardGroup>

***

*Next Edit represents Gobi's vision for proactive AI coding assistance that anticipates developer needs rather than just reacting to input. As this feature evolves, it will become a powerful tool for accelerating development workflows and reducing repetitive coding tasks.*


# Quick Start with Gobi Autocomplete
Source: https://docs.gourmand.dev/ide-extensions/autocomplete/quick-start

Learn how to quickly start using Gobi's AI autocomplete in your IDE, including enabling inline code suggestions and keyboard shortcuts for accepting, rejecting, or partially accepting completions.

## How to Enable and Use Gobi Autocomplete

Autocomplete provides inline code suggestions as you type. To enable it, simply click the "Gobi" button in the status bar at the bottom right of your IDE or ensure the "Enable Tab Autocomplete" option is checked in your IDE settings.

## Keyboard Shortcuts for Autocomplete

### Accept a Full Suggestion

Accept a full suggestion by pressing `Tab`

### Reject a Full Suggestion

Reject a full suggestion with `Esc`

### Partially Accept a Suggestion

For more granular control, use `cmd/ctrl` + `→` to accept parts of the suggestion word-by-word.

### Force a Suggestion (VS Code)

If you want to trigger a suggestion immediately without waiting, or if you've dismissed a suggestion and want a new one, you can force it by using the keyboard shortcut **`cmd/ctrl` + `alt` + `space`**.


# Chat Mode Context Selection
Source: https://docs.gourmand.dev/ide-extensions/chat/context-selection

Learn how Gobi selects relevant context for your chat requests, including text input, highlighted code, active files.

## How to Use Text Input

Typing a question or instructions into the input box is the only required context.

## How to Include Highlighted Code

The highlighted code you've selected by pressing cmd/ctrl + L (VS Code) or cmd/ctrl + J (JetBrains) will be included in your prompt.

## How to Include the Active File

You can include the currently open file as context by pressing opt/alt + enter when you send your request.

## How to Include a Specific File

You can include a specific file in your current workspace by typing '@Files' and selecting the file.

## Codebase Search

For better codebase awareness, see our [guide on making agent mode aware of codebases and documentation](/guides/codebase-documentation-awareness).

## How to Include Documentation Sites

For better documentation awareness, see our [guide on making agent mode aware of codebases and documentation](/guides/codebase-documentation-awareness).

## How to Include Terminal Contents

You can include the contents of the terminal in your IDE by typing '@Terminal'.

## How to Include Git Diff

You can include all of the changes you've made to your current branch by typing '@Git Diff'.

## How to Use Other Context Providers

You can see a full list of built-in context providers [here](/customize/deep-dives/custom-providers).


# How Chat Works
Source: https://docs.gourmand.dev/ide-extensions/chat/how-it-works

Gobi's Chat feature provides a conversational interface with AI models directly in your IDE sidebar.

## How Chat Core Functionality Works

When you start a chat conversation, Gobi:

1. **Gathers Context**: Uses any selected code sections and @-mentioned context
2. **Constructs Prompt**: Combines your input with relevant context
3. **Sends to Model**: Prompts the configured AI model for a response
4. **Streams Response**: Returns the AI response in real-time to the sidebar

## How Context Management Works

### What Context Is Automatically Included

* Selected code in your editor
* Current file context when relevant
* Previous conversation history in the session

### How to Add Manual Context

* `@Files` - Reference specific files

## How Response Handling Works

Each code section in the AI response includes action buttons:

* **Apply to current file** - Replace selected code
* **Insert at cursor** - Add code at cursor position
* **Copy** - Copy code to clipboard

## How Session Management Works

* Use `Cmd/Ctrl + L` (VS Code) or `Cmd/Ctrl + J` (JetBrains) to start a new session
* Clears all previous context for a fresh start
* Helpful for switching between different tasks

## What Advanced Features Are Available

### How to Use Prompt Inspection

View the exact prompt sent to the AI model in the [prompt logs](/troubleshooting) for debugging and optimization.

### Context

Learn more about how you can bring in context:

* [Codebase Context](/guides/codebase-documentation-awareness)
* [Documentation Context](/guides/codebase-documentation-awareness)
* [Built-in Context Providers](/customize/deep-dives/custom-providers)

***

*Chat is designed to feel like a natural conversation while maintaining full transparency about what context is being used.*


# How to Customize Chat
Source: https://docs.gourmand.dev/ide-extensions/chat/how-to-customize

Learn how to customize the Chat feature in Gobi to better suit your workflow.

## How to Customize Chat

There are a number of different ways to customize Chat:

* Add [rules](/customization/rules) to give the model persistent instructions through the system prompt
* Create [prompts](/customization/prompts) to kickoff workflows with instructions you repeat often


# Recommended Models for Chat in Gobi
Source: https://docs.gourmand.dev/ide-extensions/chat/model-setup

Choose the best chat model for Gobi, including hosted high-performance options, fast speed/quality tradeoffs, and local privacy-first models.

export const ModelRecommendations = ({role = "all"}) => {
  const parseMarkdownLinks = text => {
    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const parts = [];
    let lastIndex = 0;
    let match;
    let key = 0;
    while ((match = regex.exec(text)) !== null) {
      if (match.index > lastIndex) {
        const beforeText = text.slice(lastIndex, match.index);
        if (beforeText) {
          parts.push(<span key={key++}>{beforeText}</span>);
        }
      }
      const [, linkText, url] = match;
      parts.push(<a key={key++} href={url} target="_blank" rel="noopener noreferrer" style={{
        color: "#0066cc",
        textDecoration: "underline"
      }}>
          {linkText}
        </a>);
      lastIndex = regex.lastIndex;
    }
    if (lastIndex < text.length) {
      const remainingText = text.slice(lastIndex);
      if (remainingText) {
        parts.push(<span key={key++}>{remainingText}</span>);
      }
    }
    return parts.length > 0 ? parts : text;
  };
  const modelRecs = {
    agent_plan: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[Devstral (27B)](https://hub.gourmand.dev/ollama/devstral)", "[Kimi K2 (1T)](https://hub.gourmand.dev/openrouter/kimi-k2)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)", "[GLM 4.5 (355B)](https://hub.gourmand.dev/openrouter/glm-4-5)", "[GLM 4.5 Air (106B)](https://hub.gourmand.dev/openrouter/glm-4-5-air)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed models are slightly better than open models"
    },
    chat_edit: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed and open models have pretty similar performance"
    },
    autocomplete: {
      open: ["[QwenCoder2.5 (1.5B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)", "[QwenCoder2.5 (7B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)"],
      closed: ["[Codestral](https://hub.gourmand.dev/mistral/codestral)", "[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are slightly better than open models"
    },
    apply: {
      open: ["N/A"],
      closed: ["[Relace Instant Apply](https://hub.gourmand.dev/relace/instant-apply)", "[Morph Fast Apply](https://hub.gourmand.dev/morphllm/morph-v2)"],
      notes: "Open models are not good enough for this model role"
    },
    embed: {
      open: ["[Nomic Embed Text](https://hub.gourmand.dev/ollama/nomic-embed-text-latest)", "Qwen3 Embedding"],
      closed: ["[Voyage Code 3](https://hub.gourmand.dev/voyageai/voyage-code-3)", "[Morph Embeddings](https://hub.gourmand.dev/morphllm/morph-embedding-v2)", "Codestral Embed"],
      notes: "Closed models are slightly better than open models"
    },
    rerank: {
      open: ["zerank-1", "zerank-1-small", "Qwen3 Reranker"],
      closed: ["[Voyage Rerank 2.5](https://hub.gourmand.dev/voyageai/rerank-2-5)", "Relace Code Rerank", "[Morph Rerank](https://hub.gourmand.dev/morphllm/morph-rerank-v2)"],
      notes: "Open models are beginning to emerge for this model role"
    },
    next_edit: {
      open: ["[Instinct](https://hub.gourmand.dev/gobi/instinct)"],
      closed: ["[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are better than open models"
    }
  };
  let rolesToShow = [];
  if (!role || role === "all") {
    rolesToShow = Object.keys(modelRecs);
  } else {
    const key = role.toLowerCase().replace(/\s|\//g, "_").replace(/-/g, "_");
    if (modelRecs[key]) {
      rolesToShow = [key];
    }
  }
  if (rolesToShow.length === 0) {
    return <div>No recommendations found for role: {role}</div>;
  }
  return <table style={{
    width: "100%",
    borderCollapse: "collapse",
    marginTop: "1rem"
  }}>
      <thead>
        <tr>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Model role
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best open models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best closed models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Notes
          </th>
        </tr>
      </thead>
      <tbody>
        {rolesToShow.map(roleKey => {
    const rec = modelRecs[roleKey];
    if (!rec) return null;
    return <tr key={roleKey}>
              <td style={{
      fontWeight: 600,
      verticalAlign: "top",
      padding: "8px"
    }}>
                {roleKey.replace(/_/g, " ").replace(/\b\w/g, l => l.toUpperCase())}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.open.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.closed.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.notes}
              </td>
            </tr>;
  })}
      </tbody>
    </table>;
};

The model you use for for Chat mode will be:

* used with Edit mode by default but can be switched
* always used with Agent mode if the model supports tool calling

## Model Recommendations

<ModelRecommendations role="chat_edit" />

<Info>
  For a comprehensive comparison of all available models by role, see our [model recommendations table](/customization/models#recommended-models).
</Info>

For model recommendations, please refer to our [Model Recommendations page](/customization/models).


# Chat Mode Quick Start
Source: https://docs.gourmand.dev/ide-extensions/chat/quick-start

Get started with Gobi's AI chat assistant to solve coding problems directly in your IDE, with features for code context sharing, codebase search, and applying generated solutions to your files

Chat makes it easy to ask for help from an AI without leaving your IDE. Get explanations, generate code, and iterate on solutions conversationally.

## How to Use Chat - Basic Usage

### How to Start a Conversation

Type your question or request in the chat input and press Enter.

**Examples:**

* "Explain this function"
* "How do I handle errors in this code?"
* "Generate a test for this component"

### How to Include Code Context

Select code in your editor, then use the keyboard shortcut to include it in your chat:

* VS Code
* JetBrains

Press `Cmd/Ctrl + L` to send selected code to chat

Press `Cmd/Ctrl + J` to send selected code to chat

### How to Use @ for Additional Context

Type `@` to include specific context:

* `@Files` - Reference specific files
* `@Terminal` - Include terminal output

## How to Work with Responses

When the AI provides code in its response, you'll see action buttons:

* **Apply to current file** - Replace your selected code
* **Insert at cursor** - Add code at your cursor position
* **Copy** - Copy code to clipboard

## What Are the Pro Tips for Chat

### Start Fresh

Press `Cmd/Ctrl + L` (VS Code) or `Cmd/Ctrl + J` (JetBrains) in an empty chat to start a new session.

### Be Specific

Include details about:

* What you're trying to accomplish
* Any constraints or requirements
* Your preferred coding style or patterns

### Iterate

If the first response isn't perfect:

* Ask follow-up questions
* Request modifications
* Provide additional context

## What Are Common Use Cases for Chat

### Code Explanation

Select confusing code and ask "What does this code do?"

### Bug Fixing

Include error messages and ask "How do I fix this error?"

### Code Generation

Describe what you want: "Create a React component that displays a user profile"

### Refactoring

Select code and ask "How can I make this more efficient?"

***

*Chat is designed for quick interactions and iterative problem-solving. Don't hesitate to ask follow-up questions!*


# Context Selection in Edit Mode
Source: https://docs.gourmand.dev/ide-extensions/edit/context-selection

Learn how Gobi's Edit mode selects relevant code context using file content, language server

## How to Use Text Input

Typing a question or instructions into the input box is the only required context.

## What Context is Included in Edit Mode

The **entire contents** of the current file are included in the prompt for context. The model will only attempt to edit the highlighted/specified ranges.


# How Edit Works
Source: https://docs.gourmand.dev/ide-extensions/edit/how-it-works

Using the highlighted code, the contents of the current file containing your highlight, and your input instructions, we prompt the model to edit the code according to your instructions. No other additional context is provided to the model.

## How Edit Functionality Works

When you start an edit session, Gobi:

1. **Gathers Context**: Uses the highlighted code and the current file contents
2. **Prompts the Model**: Sends the gathered context and your input instructions to the model
3. **Applies Changes**: The model response is then streamed directly back to the highlighted range in your code, where we apply a diff formatting to show the proposed changes.

If you accept the diff, we remove the previously highlighted lines, and if you reject the diff, we remove the proposed changes.

<Info>
  **Looking for AI that predicts your next edit?** Check out [Next Edit](/ide-extensions/autocomplete/next-edit), an experimental feature that proactively suggests code changes before you even start typing, going beyond traditional autocomplete to anticipate entire code modifications.
</Info>

If you would like to view the exact prompt that is sent to the model during an edit, you can [find it in the prompt logs](/troubleshooting#check-the-logs).


# How to Customize Edit Functionality
Source: https://docs.gourmand.dev/ide-extensions/edit/how-to-customize

Learn how to customize the Edit functionality in Gobi to better suit your workflow.

## How to Set Active Edit/Apply Model

You can configure particular models to be used for Edit and Apply requests.

1. Click the 3 dots above the main input
2. Click the cube icon to expand the "Models" section
3. Use the dropdowns to select models for Edit and Apply

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/edit-model.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=1599fcae358fdd4393411d007d1eafe4" alt="Edit model selection" data-og-width="1160" width="1160" data-og-height="824" height="824" data-path="images/edit-model.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/edit-model.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=df0fae70ee2d519511176cccdc551b09 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/edit-model.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=546744f54375beb55ef86c7786437c0d 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/edit-model.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=43f53675eec472d22e942fb1cabdf8c9 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/edit-model.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=ac770e812c8069f70deb60b6862ef988 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/edit-model.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=d0d45d1604470e818d75fb93a762b40b 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/edit-model.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=3dbd48ad82a0f57b1ba555076a16ffb6 2500w" />

Learn more about the [Edit role](/customize/model-roles/edit) and [Apply role](/customize/model-roles/apply).


# How to Set Up Edit Models
Source: https://docs.gourmand.dev/ide-extensions/edit/model-setup

Learn how to set up and customize models for Edit functionality in Gobi.

export const ModelRecommendations = ({role = "all"}) => {
  const parseMarkdownLinks = text => {
    const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
    const parts = [];
    let lastIndex = 0;
    let match;
    let key = 0;
    while ((match = regex.exec(text)) !== null) {
      if (match.index > lastIndex) {
        const beforeText = text.slice(lastIndex, match.index);
        if (beforeText) {
          parts.push(<span key={key++}>{beforeText}</span>);
        }
      }
      const [, linkText, url] = match;
      parts.push(<a key={key++} href={url} target="_blank" rel="noopener noreferrer" style={{
        color: "#0066cc",
        textDecoration: "underline"
      }}>
          {linkText}
        </a>);
      lastIndex = regex.lastIndex;
    }
    if (lastIndex < text.length) {
      const remainingText = text.slice(lastIndex);
      if (remainingText) {
        parts.push(<span key={key++}>{remainingText}</span>);
      }
    }
    return parts.length > 0 ? parts : text;
  };
  const modelRecs = {
    agent_plan: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[Devstral (27B)](https://hub.gourmand.dev/ollama/devstral)", "[Kimi K2 (1T)](https://hub.gourmand.dev/openrouter/kimi-k2)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)", "[GLM 4.5 (355B)](https://hub.gourmand.dev/openrouter/glm-4-5)", "[GLM 4.5 Air (106B)](https://hub.gourmand.dev/openrouter/glm-4-5-air)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed models are slightly better than open models"
    },
    chat_edit: {
      open: ["[Qwen3 Coder (480B)](https://hub.gourmand.dev/openrouter/qwen3-coder)", "[Qwen3 Coder (30B)](https://hub.gourmand.dev/ollama/qwen3-coder-30b)", "[gpt-oss (120B)](https://hub.gourmand.dev/openrouter/gpt-oss-120b)", "[gpt-oss (20B)](https://hub.gourmand.dev/ollama/gpt-oss-20b)"],
      closed: ["[Claude Opus 4.1](https://hub.gourmand.dev/anthropic/claude-4-1-opus)", "[Claude Sonnet 4](https://hub.gourmand.dev/anthropic/claude-4-sonnet)", "[GPT-5](https://hub.gourmand.dev/openai/gpt-5)", "[Gemini 2.5 Pro](https://hub.gourmand.dev/google/gemini-2.5-pro)"],
      notes: "Closed and open models have pretty similar performance"
    },
    autocomplete: {
      open: ["[QwenCoder2.5 (1.5B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-1.5b)", "[QwenCoder2.5 (7B)](https://hub.gourmand.dev/ollama/qwen2.5-coder-7b)"],
      closed: ["[Codestral](https://hub.gourmand.dev/mistral/codestral)", "[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are slightly better than open models"
    },
    apply: {
      open: ["N/A"],
      closed: ["[Relace Instant Apply](https://hub.gourmand.dev/relace/instant-apply)", "[Morph Fast Apply](https://hub.gourmand.dev/morphllm/morph-v2)"],
      notes: "Open models are not good enough for this model role"
    },
    embed: {
      open: ["[Nomic Embed Text](https://hub.gourmand.dev/ollama/nomic-embed-text-latest)", "Qwen3 Embedding"],
      closed: ["[Voyage Code 3](https://hub.gourmand.dev/voyageai/voyage-code-3)", "[Morph Embeddings](https://hub.gourmand.dev/morphllm/morph-embedding-v2)", "Codestral Embed"],
      notes: "Closed models are slightly better than open models"
    },
    rerank: {
      open: ["zerank-1", "zerank-1-small", "Qwen3 Reranker"],
      closed: ["[Voyage Rerank 2.5](https://hub.gourmand.dev/voyageai/rerank-2-5)", "Relace Code Rerank", "[Morph Rerank](https://hub.gourmand.dev/morphllm/morph-rerank-v2)"],
      notes: "Open models are beginning to emerge for this model role"
    },
    next_edit: {
      open: ["[Instinct](https://hub.gourmand.dev/gobi/instinct)"],
      closed: ["[Mercury Coder](https://hub.gourmand.dev/inception/mercury-coder)"],
      notes: "Closed models are better than open models"
    }
  };
  let rolesToShow = [];
  if (!role || role === "all") {
    rolesToShow = Object.keys(modelRecs);
  } else {
    const key = role.toLowerCase().replace(/\s|\//g, "_").replace(/-/g, "_");
    if (modelRecs[key]) {
      rolesToShow = [key];
    }
  }
  if (rolesToShow.length === 0) {
    return <div>No recommendations found for role: {role}</div>;
  }
  return <table style={{
    width: "100%",
    borderCollapse: "collapse",
    marginTop: "1rem"
  }}>
      <thead>
        <tr>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Model role
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best open models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Best closed models
          </th>
          <th style={{
    textAlign: "left",
    borderBottom: "1px solid #ddd",
    padding: "8px"
  }}>
            Notes
          </th>
        </tr>
      </thead>
      <tbody>
        {rolesToShow.map(roleKey => {
    const rec = modelRecs[roleKey];
    if (!rec) return null;
    return <tr key={roleKey}>
              <td style={{
      fontWeight: 600,
      verticalAlign: "top",
      padding: "8px"
    }}>
                {roleKey.replace(/_/g, " ").replace(/\b\w/g, l => l.toUpperCase())}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.open.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.closed.map((m, i) => <div key={i} style={{
      marginBottom: "4px"
    }}>
                    {parseMarkdownLinks(m)}
                  </div>)}
              </td>
              <td style={{
      padding: "8px",
      verticalAlign: "top"
    }}>
                {rec.notes}
              </td>
            </tr>;
  })}
      </tbody>
    </table>;
};

The model you set up for Chat mode will be used for Edit mode by default.

## Recommendations

<ModelRecommendations role="chat_edit" />

<Info>
  See our [comprehensive model recommendations](/customization/models#recommended-models) for the best models for each role, including Edit and Apply.
</Info>

## How to Set Up an Apply Model

We also recommend setting up an Apply model for the best Edit experience.

For recommended Apply models, please refer to our [Model Recommendations page](/customization/models).

## How to Determine Model Compatibility

For a complete overview of which models support various features, see our [Model Capabilities guide](/customize/deep-dives/model-capabilities).


# Quick Start with Gobi Edit
Source: https://docs.gourmand.dev/ide-extensions/edit/quick-start

Get started with Gobi's Edit feature for making quick, targeted code changes directly in your file using AI suggestions, with keyboard shortcuts for accepting or rejecting modifications

## How to Gobi Edit

Edit is a convenient way to make quick changes to specific code and files. Select code, describe your code changes, and a diff will be streamed inline to your file which you can accept or reject.

Edit is recommended for small, targeted changes, such as

* Writing comments
* Generating unit tests
* Refactoring functions or methods

## How to Activate Edit

Highlight the block of code you would like to modify and press `Cmd+I` (Mac) or `Ctrl+I` (Windows/Linux) to activate Edit mode. You can also press `Cmd/Ctrl+I` with no code highlighted, which will default to inserting code at the current cursor location.

Once you've activated Edit, you're ready to provide instructions.

### How to Provide Instructions

Describe the changes you would like the model to make to your highlighted code. For edits, a good prompt should be relatively short and concise. For longer, more complex tasks, we recommend using [Chat](/ide-extensions/chat/quick-start).

### How to Accept or Reject Changes

Proposed changes appear as inline diffs within your highlighted text.

You can navigate through each proposed change, accepting or rejecting them using `Cmd+Opt+Y` (Mac) or `Ctrl+Alt+Y` (Windows/Linux) to accept, or `Cmd+Opt+N` (Mac) or `Ctrl+Alt+N` (Windows/Linux) to reject.

You can also accept or reject all changes at once using `Cmd+Shift+Enter` (Mac) or `Ctrl+Shift+Enter` (Windows/Linux) to accept, or `Cmd+Shift+Delete` (Mac) or `Ctrl+Shift+Backspace` (Windows/Linux) to reject.

If you want to request a new suggestion for the same highlighted code section, you can use `Cmd+I` (Mac) or `Ctrl+I` (Windows/Linux) to re-prompt the model.

## How to Use Edit in Jetbrains

In Jetbrains, Edit is implemented as an inline popup. See the header GIF example.


# Install
Source: https://docs.gourmand.dev/ide-extensions/install

Get Gobi installed in your favorite IDE in just a few steps.

<iframe width="100%" height="400" src="https://www.youtube.com/embed/gjekTru4Cg4" title="Install Gobi VS Code Extension" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />

<Tabs>
  <Tab title="VS Code">
    <Steps>
      <Step title="Install from Marketplace">
        Click `Install` on the [Gobi extension page in the Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Gourmand.gobi)
      </Step>

      <Step title="Install in VS Code">
        This will open the Gobi extension page in VS Code, where you will need to
        click `Install` again
      </Step>

      <Step title="Move to Right Sidebar">
        The Gobi logo will appear on the left sidebar. For a better experience, move Gobi to the right sidebar
      </Step>

      <Step title="Sign In">
        [Sign in to the hub](https://auth.gourmand.dev/) to get started
      </Step>
    </Steps>

    <Info>
      If you have any problems, see the [troubleshooting guide](/troubleshooting) or
      ask for help in [our Discord](https://discord.gg/TODO)
    </Info>
  </Tab>

  <Tab title="JetBrains">
    <Steps>
      <Step title="Open Settings">
        Open your JetBrains IDE and open **Settings** using `Ctrl` + `Alt` + `S`
      </Step>

      <Step title="Find Gobi Plugin">
        Select **Plugins** on the sidebar and search for "Gobi" in the marketplace
      </Step>

      <Step title="Install Plugin">
        Click `Install`, which will cause the Gobi logo to show up on the right toolbar

                <img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/jetbrains-getting-started-d62b7edee1cdd58508c5075faf285955.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=95979d95da7fd66b6b89d3b074c8fb26" alt="jetbrains-getting-started.png" data-og-width="3024" width="3024" data-og-height="1888" height="1888" data-path="images/getting-started/images/jetbrains-getting-started-d62b7edee1cdd58508c5075faf285955.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/jetbrains-getting-started-d62b7edee1cdd58508c5075faf285955.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=372d0eceb3d1657b1d018c222a2215d5 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/jetbrains-getting-started-d62b7edee1cdd58508c5075faf285955.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=2c79d1e656dffdcc8e96b2fd45e606e8 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/jetbrains-getting-started-d62b7edee1cdd58508c5075faf285955.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=af2569b1ccbb9411baec336bcc358299 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/jetbrains-getting-started-d62b7edee1cdd58508c5075faf285955.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=9d9ee013a459a9e8592108c908b0280d 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/jetbrains-getting-started-d62b7edee1cdd58508c5075faf285955.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=79fb12b78f25310d8cbc1529fe4b351b 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/jetbrains-getting-started-d62b7edee1cdd58508c5075faf285955.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=0069e528b14b49b25da15637aeb45364 2500w" />
      </Step>

      <Step title="Sign In">
        [Sign in to the hub](https://auth.gourmand.dev/) to get started
      </Step>
    </Steps>

    <Info>
      If you have any problems, see the [troubleshooting guide](/troubleshooting) or
      ask for help in [our Discord](https://discord.com/invite/EfJEfdFnDQ)
    </Info>
  </Tab>
</Tabs>

## Signing in

Click "Get started" to sign in to the hub and get started.

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/hub-onboarding-card-81abd457b6d131c4b0aa89a5a6d647d3.png?fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=5bfe4af54e029cdeb970b6ee875057eb" alt="Hub Onboarding in the Extension" data-og-width="738" width="738" data-og-height="1008" height="1008" data-path="images/getting-started/images/hub-onboarding-card-81abd457b6d131c4b0aa89a5a6d647d3.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/hub-onboarding-card-81abd457b6d131c4b0aa89a5a6d647d3.png?w=280&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=41f10b77bd07b873fa22b0c502130d51 280w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/hub-onboarding-card-81abd457b6d131c4b0aa89a5a6d647d3.png?w=560&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=1057f29129b4f175f395baffec5ed53f 560w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/hub-onboarding-card-81abd457b6d131c4b0aa89a5a6d647d3.png?w=840&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=520b68dc5e1ef5b2d4fb9fb5626014ff 840w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/hub-onboarding-card-81abd457b6d131c4b0aa89a5a6d647d3.png?w=1100&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=ad7615edce9719d9f7497333b867d4a3 1100w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/hub-onboarding-card-81abd457b6d131c4b0aa89a5a6d647d3.png?w=1650&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=b2f52c1c7c08e45c148bd87824c2f94f 1650w, https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/getting-started/images/hub-onboarding-card-81abd457b6d131c4b0aa89a5a6d647d3.png?w=2500&fit=max&auto=format&n=kkqYf7UwBaqLLOdV&q=85&s=9697a434607347ce2572c764735e4881 2500w" />


# Quick Start Tutorial
Source: https://docs.gourmand.dev/ide-extensions/quick-start

Learn Gobi's core features through hands-on exercises. Get started with Autocomplete, Edit, Chat, and Agent mode in minutes.

Welcome to Gobi! This interactive tutorial will guide you through all four core features using practical examples. Follow along step-by-step to learn more about Gobi's capabilities.

<Info>
  **Prerequisites**: Make sure you have [installed
  Gobi](/ide-extensions/install) and [signed
  in](https://auth.gourmand.dev/) to get started.
</Info>

***

## 🔄 Autocomplete

**What it does**: Provides intelligent inline code suggestions as you type, powered by AI.

<Steps>
  <Step title="Create a Test File">
    Create a new file called `tutorial.js` (or use any language you prefer) in your IDE
  </Step>

  <Step title="Try Autocomplete">
    Copy this starter code and place your cursor at the end of the comment:

    ```javascript  theme={null}
    // TODO: Implement a sorting algorithm function
    function sortingAlgorithm(arr) {
      // Place cursor here and press Enter
    }
    ```

    Press **Enter** and watch Gobi suggest code completions. Press **Tab** to accept suggestions.
  </Step>

  <Step title="See the Magic">
    Gobi will intelligently suggest function implementations based on the context and comment.
  </Step>
</Steps>

<Tip>
  Autocomplete works best when you provide clear function names, comments, or
  type annotations that give context about your intent.
</Tip>

***

<img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-quick-start.gif?s=f5c5315e0972785a68fc364cd29fabf2" alt="autocomplete-demo" data-og-width="924" width="924" data-og-height="720" height="720" data-path="images/autocomplete-quick-start.gif" data-optimize="true" data-opv="3" />

## ✏️ Edit

**What it does**: Make quick, targeted changes to specific code sections using natural language instructions.

<Steps>
  <Step title="Add Sample Code">
    Paste this bubble sort implementation in your file:

    ```javascript  theme={null}
    function sortingAlgorithm(x) {
      for (let i = 0; i < x.length; i++) {
        for (let j = 0; j < x.length - 1; j++) {
          if (x[j] > x[j + 1]) {
            let temp = x[j];
            x[j] = x[j + 1];
            x[j + 1] = temp;
          }
        }
      }
      return x;
    }
    ```
  </Step>

  <Step title="Highlight the Function">
    **Highlight** the entire function in your editor
  </Step>

  <Step title="Open Edit Mode">Press **Cmd/Ctrl + I** to open Edit mode</Step>

  <Step title="Give Instructions">
    Type: `"make this more readable and add TypeScript types"`
  </Step>

  <Step title="Watch the Magic">
    Watch Gobi refactor your code automatically!
  </Step>

  <Step title="Review Changes">
    Gobi will show you a diff of the proposed changes. Accept or reject individual changes as needed.
  </Step>
</Steps>

<Note>
  Edit is perfect for refactoring, adding documentation, fixing bugs, or
  converting between languages/frameworks.
</Note>

<img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/edit-quick-start.gif?s=cc0040cbe42dc2b3ce8765a910e2624b" alt="edit-demo" data-og-width="980" width="980" data-og-height="720" height="720" data-path="images/edit-quick-start.gif" data-optimize="true" data-opv="3" />

## 💬 Chat Mode

**What it does**: Interactive AI assistant that can analyze code, answer questions, and provide guidance without leaving your IDE.

<Steps>
  <Step title="Add Another Function">
    Add this second sorting function to your file:

    ```javascript  theme={null}
    function sortingAlgorithm2(x) {
      for (let i = 0; i < x.length; i++) {
        for (let j = 0; j < x.length - 1; j++) {
          if (x[j] > x[j + 1]) {
            let temp = x[j];
            x[j] = x[j + 1];
            x[j + 1] = temp;
          }
        }
      }
      return x;
    }
    ```
  </Step>

  <Step title="Start a Conversation">
    1. **Highlight** the function
    2. Use the keyboard shortcuts below to add it to Chat.
    3. Ask: `"What sorting algorithm is this and how can I optimize it?"`
  </Step>

  <Step title="Explore Further">
    Try these follow-up questions:

    * `"Show me how to implement quicksort instead"`
    * `"What's the time complexity of this algorithm?"`
    * `"Can you write unit tests for this function?"`
  </Step>
</Steps>

### Chat Mode Keyboard Shortcuts

<Tabs>
  <Tab title="VS Code">
    **Cmd/Ctrl + L**\
    New Chat / New Chat With Selected Code / Close Gobi Sidebar If Chat Already In Focus

    **Cmd/Ctrl + Shift + L**\
    Focus Current Chat / Add Selected Code To Current Chat / Close Gobi Sidebar If Chat Already In Focus
  </Tab>

  <Tab title="JetBrains IDEs">
    **Cmd/Ctrl + J**\
    New Chat / New Chat With Selected Code / Close Gobi Sidebar If Chat Already In Focus

    **Cmd/Ctrl + Shift + J**\
    Focus Current Chat / Add Selected Code To Current Chat / Close Gobi Sidebar If Chat Already In Focus
  </Tab>
</Tabs>

<Tip>
  Use Chat for code reviews, debugging help, learning new concepts, or
  brainstorming solutions to complex problems.
</Tip>

<img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/chat-quick-start.gif?s=7c4685b7396fe7fe0844df114a2b0a0b" alt="chat-demo" data-og-width="1140" width="1140" data-og-height="720" height="720" data-path="images/chat-quick-start.gif" data-optimize="true" data-opv="3" />

***

## 🤖 Agent Mode

**What it does**: An autonomous coding assistant that can read files, make changes, run commands, and handle complex multi-step tasks.

<Steps>
  <Step title="Switch to Agent Mode">
    1. Open the Gobi panel
    2. Click the **dropdown** in the bottom left of the input box
    3. Select **"Agent"** mode
  </Step>

  <Step title="Give Agent Mode a Complex Task">
    Try this prompt: `"Write comprehensive unit tests for the sorting functions
      in this file. Create the tests in a new file using Jest, and make sure to test
      edge cases like empty arrays and single elements."`
  </Step>

  <Step title="Watch Agent Mode Work">
    Agent mode will:

    * ✅ Analyze your existing code
    * ✅ Create a new test file
    * ✅ Write comprehensive tests
    * ✅ Handle setup and imports
    * ✅ Explain what it's doing at each step
  </Step>
</Steps>

<Warning>
  Agent mode has powerful capabilities including file creation and modification.
  Always review Agent mode's changes before accepting them.
</Warning>

<img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/agent-quick-start.gif?s=0f54f781f58da9edd9821df2715b11e7" alt="agent-demo" data-og-width="996" width="996" data-og-height="720" height="720" data-path="images/agent-quick-start.gif" data-optimize="true" data-opv="3" />

***

## Explore More Extension Examples

Ready to explore more? Gobi offers five powerful features to enhance your coding workflow:

<Tabs>
  <Tab title="Agent Mode">
    [Agent Mode](/ide-extensions/agent/quick-start) equips the Chat model with the tools needed to handle a wide range of coding tasks

        <img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/agent-9ef792cfc196a3b5faa984fb072c4400.gif?s=50e3215743ec9e90b68dfa942f54f472" alt="agent mode" data-og-width="1552" width="1552" data-og-height="1080" height="1080" data-path="images/agent-9ef792cfc196a3b5faa984fb072c4400.gif" data-optimize="true" data-opv="3" />

    <Info>
      Learn more about [Agent Mode](/ide-extensions/agent/quick-start)
    </Info>
  </Tab>

  <Tab title="Chat Mode">
    [Chat](/ide-extensions/chat/quick-start) makes it easy to ask for help from an LLM without needing to leave the IDE

        <img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/chat-489b68d156be2aafe09ee7cedf233fba.gif?s=3ebf398335129457e849aebf3a437f4a" alt="chat" data-og-width="1552" width="1552" data-og-height="1080" height="1080" data-path="images/chat-489b68d156be2aafe09ee7cedf233fba.gif" data-optimize="true" data-opv="3" />

    <Info>
      Learn more about [Chat Mode](/ide-extensions/chat/quick-start)
    </Info>
  </Tab>

  <Tab title="Plan">
    [Plan](/ide-extensions/agent/plan-mode) provides a safe environment with read-only tools for exploring code and planning changes

        <img src="https://mintcdn.com/gourmand/lfYeqLX2hvXkgz5p/images/plan-mode.gif?s=d6e5ad7e6d35831bf4bf3c94305300c5" alt="plan" data-og-width="1108" width="1108" data-og-height="720" height="720" data-path="images/plan-mode.gif" data-optimize="true" data-opv="3" />

    <Info>
      Learn more about [Plan Mode](/ide-extensions/agent/plan-mode)
    </Info>
  </Tab>

  <Tab title="Edit">
    [Edit](/ide-extensions/edit/quick-start) is a convenient way to modify code without leaving your current file

        <img src="https://mintcdn.com/gourmand/kkqYf7UwBaqLLOdV/images/edit.gif?s=db562c1367d4f05e4743a0bcf1aedd08" alt="edit" data-og-width="1552" width="1552" data-og-height="1080" height="1080" data-path="images/edit.gif" data-optimize="true" data-opv="3" />

    <Info>
      Learn more about [Edit](/ide-extensions/edit/quick-start)
    </Info>
  </Tab>

  <Tab title="Autocomplete">
    [Autocomplete](/ide-extensions/autocomplete/quick-start) provides inline code suggestions as you type

        <img src="https://mintcdn.com/gourmand/cY6wRTl5s2wbpiM-/images/autocomplete-9d4e3f7658d3e65b8e8b20f2de939675.gif?s=acde9a6522d5c136a7f0ce4b5e2017f1" alt="autocomplete" data-og-width="1552" width="1552" data-og-height="1080" height="1080" data-path="images/autocomplete-9d4e3f7658d3e65b8e8b20f2de939675.gif" data-optimize="true" data-opv="3" />

    <Info>
      Learn more about [Autocomplete](/ide-extensions/autocomplete/quick-start)
    </Info>
  </Tab>
</Tabs>

## 🚀 Next Steps

Congratulations! You've experienced all four core Gobi features. Here's what to explore next:

<CardGroup cols={2}>
  <Card title="Customize Your Setup" icon="gear" href="/customize/overview">
    Configure models, add context providers, and personalize your workflow
  </Card>

  <Card title="Advanced Features" icon="rocket" href="/ide-extensions/agent/quick-start">
    Dive deeper into Agent mode capabilities and advanced use cases
  </Card>

  <Card title="Model Providers" icon="brain" href="/customize/model-providers/overview">
    Connect your preferred AI models and providers
  </Card>

  <Card title="Join Community" icon="users" href="https://discord.gg/TODO">
    Get help and share experiences with other Gobi users
  </Card>
</CardGroup>

***

## 📚 Feature Deep Dives

Ready to master specific features? Check out these detailed guides:

<AccordionGroup>
  <Accordion title="Autocomplete Deep Dive">
    Learn about [configuring autocomplete
    models](/customize/model-roles/autocomplete), [fine-tuning
    suggestions](/customize/deep-dives/autocomplete), and [troubleshooting
    common issues](/troubleshooting).
  </Accordion>

  <Accordion title="Chat & Agent Mode Best Practices">
    Discover [effective prompting techniques](/customize/deep-dives/prompts), [hub
    v. local configuration](/guides/understanding-configs), and [custom slash
    commands](/customize/deep-dives/prompts).
  </Accordion>

  <Accordion title="Enterprise & Teams">
    Explore [Hub configurations](/hub/configs/intro), [organization
    management](/hub/governance/creating-an-org), and [sharing
    configurations](/hub/sharing).
  </Accordion>
</AccordionGroup>

<Info>
  **Need help?** Check our [troubleshooting guide](/troubleshooting) or ask a
  question in our [community
  discussions](https://github.com/gourmand/gobi/discussions).
</Info>


# Welcome to Gobi
Source: https://docs.gourmand.dev/index

Practice Continuous AI with an open-source CLI, open-source IDE extensions, and a Hub for custom agents

<Frame>
  <img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/intro-0c302b9c15b890c251b1ad04586c880f.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=359c2a70dfb2a6b70dcd48422cbe8a7d" data-og-width="1792" width="1792" data-og-height="576" height="576" data-path="images/intro-0c302b9c15b890c251b1ad04586c880f.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/intro-0c302b9c15b890c251b1ad04586c880f.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=07c20856af83794db213401994c462d3 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/intro-0c302b9c15b890c251b1ad04586c880f.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=bac869d2a33acf2036fa3517f5f594f7 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/intro-0c302b9c15b890c251b1ad04586c880f.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=d4c84a7ce8f96f93d3339246f008fccb 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/intro-0c302b9c15b890c251b1ad04586c880f.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=f73f9b3a32ece9faf4521b6d881d5006 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/intro-0c302b9c15b890c251b1ad04586c880f.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=39d08724ea629b29e13d8b2b37a5e331 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/intro-0c302b9c15b890c251b1ad04586c880f.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=231904db354c9eac3eecff642399e11b 2500w" />
</Frame>

<Note>
  **Build faster with AI across your IDE, terminal, and CI/CD pipelines with
  Gobi.**
</Note>

## Gobi CLI

<Info>Terminal-native AI coding assistance with TUI and headless modes.</Info>

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @gourmanddev/cli
  ```

  ```bash yarn theme={null}
  yarn global add @gourmanddev/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @gourmanddev/cli
  ```
</CodeGroup>

<CardGroup cols={2}>
  <Card title="TUI Mode" icon="terminal" href="/cli/overview#tui-mode%3A-interactive-development">
    Interactive terminal interface for development workflows

    <br />

    <sub>• Automate builds & refactoring</sub>

    <br />

    <sub>• Pre-commit hooks & scripted fixes</sub>

    <br />

    <sub>• Terminal-first development</sub>
  </Card>

  <Card title="Headless Mode" icon="server" href="/cli/overview#headless-mode%3A-production-automation">
    Automated AI coding for CI/CD and server environments

    <br />

    <sub>• Run in CI/CD pipelines</sub>

    <br />

    <sub>• Batch processing & bulk operations</sub>

    <br />

    <sub>• Server & container deployments</sub>
  </Card>
</CardGroup>

## IDE Extensions

<Info>
  **Complement your CLI workflow** - Rich editor integrations for interactive
  development.
</Info>

<CardGroup cols={2}>
  <Card title="VS Code" icon="code" href="https://marketplace.visualstudio.com/items?itemName=Gobi.gobi">
    Install from VS Code Marketplace

    <br />

    <sub>Real-time coding assistance and refactoring</sub>
  </Card>

  <Card title="JetBrains" icon="jet-fighter" href="https://plugins.jetbrains.com/plugin/22707-gobi-extension">
    Install from JetBrains Plugin Repository

    <br />

    <sub>Autocomplete and multi-file edits</sub>
  </Card>
</CardGroup>

## Core Features

<CardGroup cols={2}>
  <Card title="Agent" icon="robot" href="/ide-extensions/agent/quick-start">
    Multi-step workflows and complex task automation
  </Card>

  <Card title="Chat" icon="messages" href="/ide-extensions/chat/quick-start">
    Ask questions and explore your codebase
  </Card>

  <Card title="Edit" icon="pen-to-square" href="/ide-extensions/edit/quick-start">
    In-place code editing without breaking flow
  </Card>

  <Card title="Autocomplete" icon="sparkles" href="/ide-extensions/autocomplete/quick-start">
    Inline AI suggestions as you type
  </Card>
</CardGroup>

## Configuration

<CardGroup cols={3}>
  <Card title="Models" icon="brain" href="/customization/models">
    Connect your preferred AI models
  </Card>

  <Card title="Rules" icon="shield" href="/customization/rules">
    Configure AI behavior and constraints
  </Card>

  <Card title="MCPs" icon="wrench" href="/customization/mcp-tools">
    Extend functionality with MCP tools
  </Card>
</CardGroup>

## Resources

<CardGroup cols={3}>
  <Card title="Gobi Hub" icon="globe" href="https://hub.gourmand.dev/">
    Community models, rules, and tools
  </Card>

  <Card title="GitHub Discussions" icon="comments" href="https://github.com/gourmand/gobi/discussions">
    Get help from the community
  </Card>

  <Card title="CLI Examples" icon="code-branch" href="/guides/overview#continuous-ai">
    TUI and headless workflow examples
  </Card>
</CardGroup>


# config.yaml Reference
Source: https://docs.gourmand.dev/reference

Comprehensive guide to the config.yaml format used by gourmand.dev for building custom coding agents. Learn how to define models, context providers, rules, prompts, and more using YAML configuration.

## Introduction

Gobi Agents are defined using the `config.yaml` specification.

**Agents** are composed of models, rules, and tools (MCP servers).

<Columns cols={2}>
  <Card title="Configuring Models, Rules, and Tools" icon="cube" href="/guides/configuring-models-rules-tools">
    Learn how to work with Gobi's configuration system, including using hub models, rules, and tools, creating local configurations, and organizing your setup.
  </Card>

  <Card title="Understanding Configs" icon="robot" href="/guides/understanding-configs">
    Learn how to build and configure configs, understand their capabilities, and customize them for your development workflow.
  </Card>
</Columns>

## Properties

Below are details for each property that can be set in `config.yaml`.

**All properties at all levels are optional unless explicitly marked as required.**

The top-level properties in the `config.yaml` configuration file are:

* [`name`](#name) (**required**)
* [`version`](#version) (**required**)
* [`schema`](#schema) (**required**)
* [`models`](#models)
* [`context`](#context)
* [`rules`](#rules)
* [`prompts`](#prompts)
* [`docs`](#docs)
* [`mcpServers`](#mcpservers)
* [`data`](#data)

***

### `name`

The `name` property specifies the name of your project or configuration.

```yaml title="config.yaml" theme={null}
name: MyProject
```

***

### `version`

The `version` property specifies the version of your project or configuration.

### `schema`

The `schema` property specifies the schema version used for the `config.yaml`, e.g. `v1`

***

### `models`

The `models` section defines the language models used in your configuration. Models are used for functionalities such as chat, editing, and summarizing.

**Properties:**

* `name` (**required**): A unique name to identify the model within your configuration.

* `provider` (**required**): The provider of the model (e.g., `openai`, `ollama`).

* `model` (**required**): The specific model name (e.g., `gpt-4`, `starcoder`).

* `apiBase`: Can be used to override the default API base that is specified per model

* `roles`: An array specifying the roles this model can fulfill, such as `chat`, `autocomplete`, `embed`, `rerank`, `edit`, `apply`, `summarize`. The default value is `[chat, edit, apply, summarize]`. Note that the `summarize` role is not currently used.

* `capabilities`: Array of strings denoting model capabilities, which will overwrite Gobi's autodetection based on provider and model. See the [Model Capabilities guide](/customize/deep-dives/model-capabilities) for detailed information. Supported capabilities include:

  * `tool_use`: Enables function/tool calling support (required for Agent mode)
  * `image_input`: Enables image upload and processing support

  Gobi automatically detects these capabilities for most models, but you can override this when using custom deployments or if autodetection isn't working correctly.

* `maxStopWords`: Maximum number of stop words allowed, to avoid API errors with extensive lists.

* `promptTemplates`: Can be used to override the default prompt templates for different model roles. Valid values are [`chat`](), [`edit`](/customize/model-roles/edit#edit-prompt-templating), [`apply`](/customize/model-roles/apply#apply-prompt-templating) and [`autocomplete`](/customize/model-roles/autocomplete#autocomplete-prompt-templating). The `chat` property must be a valid template name, such as `llama3` or `anthropic`.

* `chatOptions`: If the model includes role `chat`, these settings apply for Agent and Chat mode:

  * `baseSystemMessage`: Can be used to override the default system prompt for **Chat** mode.
  * `baseAgentSystemMessage`: Can be used to override the default system prompt for **Agent** mode.
  * `basePlanSystemMessage`: Can be used to override the default system prompt for **Plan** mode.

* `embedOptions`: If the model includes role `embed`, these settings apply for embeddings:

  * `maxChunkSize`: Maximum tokens per document chunk. Minimum is 128 tokens.
  * `maxBatchSize`: Maximum number of chunks per request. Minimum is 1 chunk.

* `defaultCompletionOptions`: Default completion options for model settings.

  * `contextLength`: Maximum context length of the model, typically in tokens.
  * `maxTokens`: Maximum number of tokens to generate in a completion.
  * `temperature`: Controls the randomness of the completion. Values range from `0.0` (deterministic) to `1.0` (random).
  * `topP`: The cumulative probability for nucleus sampling.
  * `topK`: Maximum number of tokens considered at each step.
  * `stop`: An array of stop tokens that will terminate the completion.
  * `reasoning`: Boolean to enable thinking/reasoning for Anthropic Claude 3.7+ and some Ollama models.
  * `reasoningBudgetTokens`: Budget tokens for thinking/reasoning in Anthropic Claude 3.7+ models.

* `requestOptions`: HTTP request options specific to the model.

  * `timeout`: Timeout for each request to the language model.

  * `verifySsl`: Whether to verify SSL certificates for requests.

  * `caBundlePath`: Path to a custom CA bundle for HTTP requests.

  * `proxy`: Proxy URL for HTTP requests.

  * `headers`: Custom headers for HTTP requests.

  * `extraBodyProperties`: Additional properties to merge with the HTTP request body.

  * `noProxy`: List of hostnames that should bypass the specified proxy.

  * `clientCertificate`: Client certificate for HTTP requests.
    * `cert`: Path to the client certificate file.
    * `key`: Path to the client certificate key file.
    * `passphrase`: Optional passphrase for the client certificate key file.

* `autocompleteOptions`: If the model includes role `autocomplete`, these settings apply for tab autocompletion:

  * `disable`: If `true`, disables autocomplete for this model.
  * `maxPromptTokens`: Maximum number of tokens for the autocomplete prompt.
  * `debounceDelay`: Delay before triggering autocomplete in milliseconds.
  * `modelTimeout`: Model timeout for autocomplete requests in milliseconds.
  * `maxSuffixPercentage`: Maximum percentage of prompt allocated for suffix.
  * `prefixPercentage`: Percentage of input allocated for prefix.
  * `transform`: If `false`, disables trimming of multiline completions. Defaults to `true`. Useful for models that generate better multiline completions without transformations.
  * `template`: Custom template for autocomplete using Mustache syntax. You can use the `{{{ prefix }}}`, `{{{ suffix }}}`, `{{{ filename }}}`, `{{{ reponame }}}`, and `{{{ language }}}` variables.
  * `onlyMyCode`: Only includes code within the repository for context.
  * `useCache`: If `true`, enables caching for completions.
  * `useImports`: If `true`, includes imports in context.
  * `useRecentlyEdited`: If `true`, includes recently edited files in context.
  * `useRecentlyOpened`: If `true`, includes recently opened files in context.

**Example:**

```yaml title="config.yaml" theme={null}
models:
  - name: GPT-4o
    provider: openai
    model: gpt-4o
    roles:
      - chat
      - edit
      - apply
    defaultCompletionOptions:
      temperature: 0.7
      maxTokens: 1500
  - name: Codestral
    provider: mistral
    model: codestral-latest
    roles:
      - autocomplete
    autocompleteOptions:
      debounceDelay: 250
      maxPromptTokens: 1024
      onlyMyCode: true
  - name: My Model - OpenAI-Compatible
    provider: openai
    apiBase: http://my-endpoint/v1
    model: my-custom-model
    capabilities:
      - tool_use
      - image_input
    roles:
      - chat
      - edit
```

***

### `context`

The `context` section defines context providers, which supply additional information or context to the language models. Each context provider can be configured with specific parameters.

More information about usage/params for each context provider can be found [here](/customize/deep-dives/custom-providers)

**Properties:**

* `provider` (**required**): The identifier or name of the context provider (e.g., `code`, `docs`, `web`)
* `name`: Optional name for the provider
* `params`: Optional parameters to configure the context provider's behavior.

**Example:**

```yaml title="config.yaml" theme={null}
context:
  - provider: file
  - provider: code
  - provider: diff
  - provider: http
    name: Context Server 1
    params:
      url: "https://api.example.com/server1"
  - provider: terminal
```

***

### `rules`

Rules are concatenated into the system message for all [Agent](/ide-extensions/agent/quick-start), [Chat](/ide-extensions/chat/quick-start), and [Edit](/ide-extensions/edit/quick-start) requests.

Confiugration example:

```yaml title="config.yaml" theme={null}
rules:
  - uses: sanity/sanity-opinionated # rules file stored on Gobi Hub
  - uses: file://user/Desktop/rules.md # rules file stored on local computer
```

Rules file example:

```md title="rules.md" theme={null}
---
name: Pirate rule
---

Talk like a pirate
```

See the [rules deep dive](/customize/deep-dives/rules) for more details.

***

### `prompts`

Prompts can be invoked with a <kbd>/</kbd> command.

Configuration example:

```yaml title="config.yaml" theme={null}
prompts:
  - uses: supabase/create-functions # prompts file stored on Gobi Hub 
  - uses: file://user/Desktop/prompts.md # prompts file stored on local computer
```

Prompts file example:

```md title="prompts.md" theme={null}
---
name: Make pirate comments
invokable: true
---

Rewrite all comments in the active file to talk like a pirate
```

See the [prompts deep dive](/customize/deep-dives/prompts) for more details.

***

### `docs`

List of documentation sites to index.

**Properties:**

* `name` (**required**): Name of the documentation site, displayed in dropdowns, etc.
* `startUrl` (**required**): Start page for crawling - usually root or intro page for docs
* `favicon`: URL for site favicon (default is `/favicon.ico` from `startUrl`).
* `useLocalCrawling`: Skip the default crawler and only crawl using a local crawler.

**Example:**

```yaml title="config.yaml" theme={null}
docs:
  - name: Gobi
    startUrl: https://docs.gourmand.dev/intro
    favicon: https://docs.gourmand.dev/favicon.ico
```

***

### `mcpServers`

The [Model Context Protocol](https://modelcontextprotocol.io/introduction) is a standard proposed by Anthropic to unify prompts, context, and tool use. Gobi supports any MCP server with the MCP context provider.

**Properties:**

* `name` (**required**): The name of the MCP server.
* `command` (**required**): The command used to start the server.
* `args`: An optional array of arguments for the command.
* `env`: An optional map of environment variables for the server process.
* `cwd`: An optional working directory to run the command in. Can be absolute or relative path.
* `requestOptions`: Optional request options for `sse` and `streamable-http` servers. Same format as [model requestOptions](#models).
* `connectionTimeout`: Optional timeout for *initial* connection to MCP server

**Example:**

```yaml title="config.yaml" theme={null}
mcpServers:
  - name: My MCP Server
    command: uvx
    args:
      - mcp-server-sqlite
      - --db-path
      - ./test.db
    cwd: /Users/NAME/project
    env:
      NODE_ENV: production
```

### `data`

Destinations to which [development data](/customize/deep-dives/development-data) will be sent.

**Properties:**

* `name` (**required**): The display name of the data destination
* `destination` (**required**): The destination/endpoint that will receive the data. Can be:
  * an HTTP endpoint that will receive a POST request with a JSON blob
  * a file URL to a directory in which events will be dumpted to `.jsonl` files
* `schema` (**required**): the schema version of the JSON blobs to be sent. Options include `0.1.0` and `0.2.0`
* `events`: an array of event names to include. Defaults to all events if not specified.
* `level`: a pre-defined filter for event fields. Options include `all` and `noCode`; the latter excludes data like file contents, prompts, and completions. Defaults to `all`
* `apiKey`: api key to be sent with request (Bearer header)
* `requestOptions`: Options for event POST requests. Same format as [model requestOptions](#models).

**Example:**

```yaml title="config.yaml" theme={null}
data:
  - name: Local Data Bank
    destination: file:///Users/dallin/Documents/code/gourmand/gobi-extras/external-data
    schema: 0.2.0
    level: all
  - name: My Private Company
    destination: https://mycompany.com/ingest
    schema: 0.2.0
    level: noCode
    events:
      - autocomplete
      - chatInteraction
```

***

## Complete YAML Config Example

Putting it all together, here's a complete example of a `config.yaml` configuration file:

```yaml title="config.yaml" theme={null}
name: MyProject
version: 0.0.1
schema: v1
models:
  - uses: anthropic/claude-3.5-sonnet
    with:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    override:
      defaultCompletionOptions:
        temperature: 0.8
  - name: GPT-4
    provider: openai
    model: gpt-4
    roles:
      - chat
      - edit
    defaultCompletionOptions:
      temperature: 0.5
      maxTokens: 2000
    requestOptions:
      headers:
        Authorization: Bearer YOUR_OPENAI_API_KEY
  - name: Ollama Starcoder
    provider: ollama
    model: starcoder
    roles:
      - autocomplete
    autocompleteOptions:
      debounceDelay: 350
      maxPromptTokens: 1024
      onlyMyCode: true
    defaultCompletionOptions:
      temperature: 0.3
      stop:
        - "\n"
rules:
  - Give concise responses
  - Always assume TypeScript rather than JavaScript
prompts:
  - name: test
    description: Unit test a function
    prompt: |
      Please write a complete suite of unit tests for this function. You should use the Jest testing framework.
      The tests should cover all possible edge cases and should be as thorough as possible.
      You should also include a description of each test case.
  - uses: myprofile/my-favorite-prompt
context:
  - provider: diff
  - provider: file
  - provider: code
mcpServers:
  - name: DevServer
    command: npm
    args:
      - run
      - dev
    env:
      PORT: "3000"
data:
  - name: My Private Company
    destination: https://mycompany.com/ingest
    schema: 0.2.0
    level: noCode
    events:
      - autocomplete
      - chatInteraction
```

## Using YAML anchors to avoid config duplication

You can also use node anchors to avoid duplication of properties. To do so, adding the YAML version header `%YAML 1.1` is needed, here's an example of a `config.yaml` configuration file using anchors:

```yaml title="config.yaml" theme={null}
%YAML 1.1
---
name: MyProject
version: 0.0.1
schema: v1
model_defaults: &model_defaults
  provider: openai
  apiKey: my-api-key
  apiBase: https://api.example.com/llm
models:
  - name: mistral
    <<: *model_defaults
    model: mistral-7b-instruct
    roles:
      - chat
      - edit
  - name: qwen2.5-coder-7b-instruct
    <<: *model_defaults
    model: qwen2.5-coder-7b-instruct
    roles:
      - chat
      - edit
  - name: qwen2.5-coder-7b
    <<: *model_defaults
    model: qwen2.5-coder-7b
    useLegacyCompletionsEndpoint: false
    roles:
      - autocomplete
    autocompleteOptions:
      debounceDelay: 350
      maxPromptTokens: 1024
      onlyMyCode: true
```

***

## `config.json` Deprecation

`config.yaml `replaces `config.json`, which is deprecated. View the **[Migration Guide](/reference/yaml-migration)** for help transitioning from the old format.


# Gobi Documentation MCP Server
Source: https://docs.gourmand.dev/reference/gobi-mcp

Set up an MCP server to search Gobi documentation

The Gobi Documentation MCP Server allows you to search and retrieve information from the Gobi documentation directly within your agent conversations.

## Set up

### Configure Gobi

1. Create a folder called `.gobi/mcpServers` at the top level of your workspace
2. Add a file called `gobi-docs-mcp.yaml` to this folder
3. Write the following contents and save:

```yaml title=".gobi/mcpServers/gobi-docs-mcp.yaml" theme={null}
name: Gobi Documentation MCP
version: 0.0.1
schema: v1
mcpServers:
  - uses: gourmand/gobi-docs-mcp
```

### Enable Agent Mode

MCP servers only work in agent mode. Make sure to switch to agent mode in Gobi before testing.

## Usage Examples

Once configured, you can use the MCP server to search Gobi documentation:

### Model Configuration Help

```
How do I add Claude 4 Sonnet as a model from Bedrock in Gobi?
```

### Context Providers

```
What context providers are available in Gobi?
```

### Customization

```
How do I add custom rules to my configuration in Gobi?
```

## Troubleshooting

### MCP Server Not Loading

1. **Check configuration**: Ensure your YAML configuration uses the correct `uses` field with `gourmand/gobi-docs-mcp`
2. **Check agent mode**: MCP servers only work in agent mode
3. **Restart Gobi**: Try restarting the Gobi extension

### No Search Results

1. **Verify connection**: The MCP server needs internet access to search the documentation
2. **Check query format**: Try rephrasing your search query
3. **Test with known topics**: Search for well-documented features like "model configuration"

## Related Documentation

* [MCP Overview](/customize/deep-dives/mcp)
* [Agent Mode](/ide-extensions/agent/quick-start)
* [Configuration](/customize/overview)


# Migrating Config to YAML
Source: https://docs.gourmand.dev/reference/yaml-migration

Gobi's YAML configuration format provides more readable, maintainable, consistent configuration files, as well as new configuration options and removal of some old configuration options. YAML is the preferred format and will be used to integrate with future Gobi products. Below is a brief guide for migration from config.json to config.yaml.

See also

* [Intro to YAML](https://yaml.org/)
* [YAML Gobi Config Reference](/reference)

## Create YAML file

Create a `config.yaml` file in your Gobi Global Directory (`~/.gobi` on Mac, `%USERPROFILE%\.gobi`) alongside your current config.json file. If a `config.yaml` file is present, it will be loaded instead of config.json.

Give your configuration a `name` and a `version`:

config.yaml

```
name: my-configurationversion: 0.0.1schema: v1
```

### Models

Add all model configurations in `config.json`, including models in `models`, `tabAutocompleteModel`, `embeddingsProvider`, and `reranker`, to the `models` section of your new YAML config file. A new `roles` YAML field specifies which roles a model can be used for, with possible values `chat`, `autocomplete`, `embed`, `rerank`, `edit`, `apply`, `summarize`.

* `models` in config should have `roles: [chat]`

* `tabAutocompleteModel`(s) in config should have `roles: [autocomplete]`

* `embeddingsProvider` in config should have `roles: [embed]`

* `reranker` in config should have `roles: [rerank]`

* `experimental.modelRoles` is replaced by simply adding roles to the model
  * `inlineEdit` -> e.g. `roles: [chat, edit]`
  * `applyCodeBlock` -> e.g. `roles: [chat, apply]`

Model-level `requestOptions` remain, with minor changes. See [YAML Gobi Config Reference](/reference#models)

Model-level `completionOptions` are replaced by `defaultCompletionOptions`, with minor changes. See [YAML Gobi Config Reference](/reference#models)

**Before**

config.json

```json  theme={null}
{
  "models": [
    {
      "title": "GPT-4",
      "provider": "openai",
      "model": "gpt-4",
      "apiKey": "<YOUR_OPENAI_API_KEY>",
      "completionOptions": { "temperature": 0.5, "maxTokens": 2000 }
    },
    { "title": "Ollama", "provider": "ollama", "model": "AUTODETECT" },
    {
      "title": "My Open AI Compatible Model",
      "provider": "openai",
      "apiBase": "http://3.3.3.3/v1",
      "model": "my-openai-compatible-model",
      "requestOptions": { "headers": { "X-Auth-Token": "<API_KEY>" } }
    }
  ],
  "tabAutocompleteModel": {
    "title": "My Starcoder",
    "provider": "ollama",
    "model": "starcoder2:3b"
  },
  "embeddingsProvider": {
    "provider": "openai",
    "model": "text-embedding-ada-002",
    "apiKey": "<YOUR_OPENAI_API_KEY>",
    "maxEmbeddingChunkSize": 256,
    "maxEmbeddingBatchSize": 5
  },
  "reranker": {
    "name": "voyage",
    "params": { "model": "rerank-2", "apiKey": "<YOUR_VOYAGE_API_KEY>" }
  }
}
```

**After**

config.yaml

```yaml  theme={null}
models:
  - name: GPT-4
    provider: openai
    model: gpt-4
    apiKey: <YOUR_OPENAI_API_KEY>
    defaultCompletionOptions:
      temperature: 0.5
      maxTokens: 2000
    roles:
      - chat
      - edit
  - name: My Voyage Reranker
    provider: voyage
    model: rerank-2
    apiKey: <YOUR_VOYAGE_API_KEY>
    roles:
      - rerank
  - name: My Starcoder
    provider: ollama
    model: starcoder2:3b
    roles:
      - autocomplete
  - name: My Ada Embedder
    provider: openai
    model: text-embedding-ada-002
    apiKey: <YOUR_OPENAI_API_KEY>
    roles:
      - embed
    embedOptions:
      maxChunkSize: 256
      maxBatchSize: 5
  - name: Ollama Autodetect
    provider: ollama
    model: AUTODETECT
    roles:
      - chat
  - name: My Open AI Compatible Model
    provider: openai
    model: my-openai-compatible-model
    apiBase: http://3.3.3.3/v1
    requestOptions:
      headers:
        X-Auth-Token: <API_KEY>
    roles:
      - chat
      - apply
```

Note that the `repoMapFileSelection` experimental model role has been deprecated and is only available in `config.json`.

### Context Providers

The JSON `contextProviders` field is replaced by the YAML `context` array.

* JSON `name` maps to `provider`
* JSON `params` map to `params`

**Before**

config.json

```json  theme={null}
{
  "contextProviders": [
    { "name": "docs" },
    { "name": "codebase", "params": { "nRetrieve": 30, "nFinal": 3 } },
    { "name": "diff", "params": {} }
  ]
}
```

**After**

config.yaml

```yaml  theme={null}
context:
  - provider: docs
  - provider: codebase
    params:
      nRetrieve: 30
      nFinal: 3
  - provider: diff
```

### System Message

The `systemMessage` property has been replaced with a `rules` property that takes an array of strings.

**Before**

config.json

```json  theme={null}
{
  "systemMessage": "Always give concise responses"
}
```

**After**

config.yaml

```yaml  theme={null}
rules:
  - Always give concise responses
```

### Prompts

Rather than with `customCommands`, you can now use the `prompts` field to define custom prompts.

**Before**

config.json

```json  theme={null}
{
  "customCommands": [
    {
      "name": "check",
      "description": "Check for mistakes in my code",
      "prompt": "{{{ input }}}\n\nPlease read the highlighted code and check for any mistakes. You should look for the following, and be extremely vigilant:\n- Syntax errors\n- Logic errors\n- Security vulnerabilities\n- Performance issues\n- Anything else that looks wrong\n\nOnce you find an error, please explain it as clearly as possible, but without using extra words. For example, instead of saying 'I think there is a syntax error on line 5', you should say 'Syntax error on line 5'. Give your answer as one bullet point per mistake found."
    }
  ]
}
```

**After**

config.yaml

```yaml  theme={null}
prompts:
  - name: check
    description: Check for mistakes in my code
    prompt: |
      Please read the highlighted code and check for any mistakes. You should look for the following, and be extremely vigilant:
        - Syntax errors
        - Logic errors
        - Security vulnerabilities
        - Performance issues
        - Anything else that looks wrong
      Once you find an error, please explain it as clearly as possible, but without using extra words. For example, instead of saying 'I think there is a syntax error on line 5', you should say 'Syntax error on line 5'. Give your answer as one bullet point per mistake found.
```

### Documentation

Documentation is largely the same, but the `title` property has been replaced with `name`. The `startUrl`, `rootUrl`, and `faviconUrl` properties remain.

**Before**

config.json

```json  theme={null}
{
  "docs": [
    {
      "startUrl": "https://docs.nestjs.com/",
      "title": "nest.js"
    },
    {
      "startUrl": "https://mysite.com/docs/",
      "title": "My site"
    }
  ]
}
```

**After**

config.yaml

```yaml  theme={null}
docs:
  - name: nest.js
    startUrl: https://docs.nestjs.com/
  - name: My site
    startUrl: https://mysite.com/docs/
```

### MCP Servers

**Properties:**

* `name` (**required**): The name of the MCP server.
* `command` (**required**): The command used to start the server.
* `args`: An optional array of arguments for the command.
* `env`: An optional map of environment variables for the server process.
* `cwd`: An optional working directory to run the command in. Can be absolute or relative path.

**Before**

config.json

```json  theme={null}
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": [
            "mcp-server-sqlite",
            "--db-path",
            "/Users/NAME/test.db"
          ],
          "env": {
            "KEY": "<VALUE>"
          }
        }
      }
    ]
  }
}
```

**After**

config.yaml

```yaml  theme={null}
mcpServers:
  - name: My MCP Server
    command: uvx
    args:
      - mcp-server-sqlite
      - --db-path
      - /Users/NAME/test.db
    env:
      KEY: <VALUE>
```

***

## Deprecated configuration options

Some deprecated config.json settings are no longer stored in config and have been moved to be editable through the user settings (Gear Icon). If found in config.json, they will be auto-migrated to User Settings and removed from config.json.

The following top-level fields from config.json have been deprecated and don't have a config.yaml equivalent:

* Slash commands (`slashCommands`)

* top-level `requestOptions`

* top-level `completionOptions`

* `tabAutocompleteOptions`

  * `disable`
  * `maxPromptTokens`
  * `debounceDelay`
  * `maxSuffixPercentage`
  * `prefixPercentage`
  * `template`
  * `onlyMyCode`

* `analytics`

The following top-level fields from config.json have been deprecated. Most UI-related and user-specific options will move into a settings page in the UI

* `customCommands`
* `experimental`
* `userToken`

## New Configuration options

The YAML configuration format offers new configuration options not available in the JSON format. See the [YAML Config Reference](/reference) for more information.


# Troubleshooting
Source: https://docs.gourmand.dev/troubleshooting

Comprehensive guide to resolving common issues with Gobi, including logging, keyboard shortcuts, networking problems, model capabilities, and extension configuration troubleshooting

1. [Check the logs](#check-the-logs)
2. [Try the latest pre-release](#download-the-latest-pre-release)
3. [Download an older version](#download-an-older-version)
4. [Resolve keyboard shortcut issues](#keyboard-shortcuts-not-resolving)
5. [Check FAQs for common issues](/faqs)

## Check the logs

To solve many problems, the first step is reading the logs to find the relevant error message. To do this, follow these steps:

### VS Code

#### Console logs

<Info>
  In order to view debug logs, which contain extra information, click the
  dropdown at the top that says "Default levels" and select "Verbose".
</Info>

1. `cmd` + `shift` + `P` for MacOS or `ctrl`
   * `shift` + `P` for Windows
2. Search for and then select "Developer: Toggle Developer Tools"
3. This will open the [Chrome DevTools window](https://developer.chrome.com/docs/devtools/)
4. Select the `Console` tab
5. Read the console logs

#### Prompt Logs (Gobi Console)

To view prompt logs/analytics, you can enable the Gobi Console.

1. Open VS Code settings (`cmd/ctrl` + `,`)
2. Search for the setting "Gobi: Enable Console" and enable it
3. Reload the window
4. Open the Gobi Console by using the command palette (`cmd/ctrl` + `shift` + `P`) and searching for "Gobi: Focus on Gobi Console View"

<img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/gobi-console-d387a10c2918c117c6c253a3b5f18c22.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=e212abe1415fc00a113f87a52c47b3d3" alt="Gobi Console" data-og-width="1606" width="1606" data-og-height="714" height="714" data-path="images/images/gobi-console-d387a10c2918c117c6c253a3b5f18c22.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/gobi-console-d387a10c2918c117c6c253a3b5f18c22.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=7630234f88d8a59f4b8bbb6eb140c7e6 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/gobi-console-d387a10c2918c117c6c253a3b5f18c22.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=9640416206a6004f33a2ac8200bc44cc 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/gobi-console-d387a10c2918c117c6c253a3b5f18c22.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=b9deaaae626d2e34b79b2944c604f0e9 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/gobi-console-d387a10c2918c117c6c253a3b5f18c22.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=438dc2e63f58cbdbd449473b3230ec34 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/gobi-console-d387a10c2918c117c6c253a3b5f18c22.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=108b307f42a737195511078eb648bcb3 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/gobi-console-d387a10c2918c117c6c253a3b5f18c22.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=afc2fe603cac84c3daa3ebff64651e8e 2500w" />

### JetBrains

Open `~/.gobi/logs/core.log` to view the logs for the Gobi plugin. The most recent logs are found at the bottom of the file.

Some JetBrains-related logs may also be found by clicking "Help" > "Show Log in Explorer/Finder".

## Download the latest pre-release

### VS Code

We are constantly making fixes and improvements to Gobi, but the latest changes remain in a "pre-release" version for roughly a week so that we can test their stability. If you are experiencing issues, you can try the pre-release by going to the Gobi extension page in VS Code and selecting "Switch to Pre-Release" as shown below.

<img src="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/prerelease-9bed93e846914165d30a3b227a680d9b.png?fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=5e89447f71b9307103b4d8d266a0e3e9" alt="Pre-Release" data-og-width="1678" width="1678" data-og-height="460" height="460" data-path="images/images/prerelease-9bed93e846914165d30a3b227a680d9b.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/prerelease-9bed93e846914165d30a3b227a680d9b.png?w=280&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=ea30698fd666a4f5897bcf964462cb4a 280w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/prerelease-9bed93e846914165d30a3b227a680d9b.png?w=560&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=957eea357047edc3594f3eeff6bd55b8 560w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/prerelease-9bed93e846914165d30a3b227a680d9b.png?w=840&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=2371a0dc9463bf3613f017ed2a277b21 840w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/prerelease-9bed93e846914165d30a3b227a680d9b.png?w=1100&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=03bb25defb60e2d220d08c7ebf6a3b87 1100w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/prerelease-9bed93e846914165d30a3b227a680d9b.png?w=1650&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=3515d13ca6b03a38bb7b225de1c2f04b 1650w, https://mintcdn.com/gourmand/HGSXhgUNM88nD3iS/images/images/prerelease-9bed93e846914165d30a3b227a680d9b.png?w=2500&fit=max&auto=format&n=HGSXhgUNM88nD3iS&q=85&s=09d802788d180cc32e4290da71a35a5d 2500w" />

### JetBrains

On JetBrains, the "pre-release" happens through their Early Access Program (EAP) channel. To download the latest EAP version, enable the EAP channel:

1. Open JetBrains settings (`cmd/ctrl` + `,`) and go to "Plugins"
2. Click the gear icon at the top
3. Select "Manage Plugin Repositories..."
4. Add "[https://plugins.jetbrains.com/plugins/eap/list](https://plugins.jetbrains.com/plugins/eap/list)" to the list
5. You'll now always be able to download the latest EAP version from the marketplace

## Download an Older Version

If you've tried everything, reported an error, know that a previous version was working for you, and are waiting to hear back, you can try downloading an older version of the extension.

For VS Code, All versions are hosted on the Open VSX Registry [here](https://open-vsx.org/extension/Gobi/gobi). Once you've downloaded the extension, which will be a .vsix file, you can install it manually by following the instructions [here](https://code.visualstudio.com/docs/editor/extension-gallery#_install-from-a-vsix).

You can find older versions of the JetBrains extension on their [marketplace](https://plugins.jetbrains.com/plugin/22707-gobi), which will walk you through installing from disk.

## Keyboard shortcuts not resolving

If your keyboard shortcuts are not resolving, you may have other commands that are taking precedence over the Gobi shortcuts. You can see if this is the case, and change your shortcut mappings, in the configuration of your IDE.

* [VSCode keyboard shortcuts docs](https://code.visualstudio.com/docs/getstarted/keybindings)
* [IntelliJ keyboard shortcut docs](https://www.jetbrains.com/help/idea/configuring-keyboard-and-mouse-shortcuts.html)

## Still having trouble?

You can also join our Discord community [here](https://discord.gg/TODO) for additional support and discussions. Alternatively, you can create a GitHub issue [here](https://github.com/gourmand/gobi/issues/new?assignees=\&labels=bug\&projects=\&template=bug-report-%F0%9F%90%9B.md\&title=), providing details of your problem, and we'll be able to help you out more quickly.