| at least one field or aggregation is required |
Did not detect any selections or aggregations - make sure the query request contains at least one. |
| invalid aggregation function for string type field ide: QUERY\_AGGREGATION\_SUM |
One of the selections used an invalid aggregation function. In this case we tried to use SUM on the "ide" field, but it only supports COUNT and UNSPECIFIED |
| invalid query table: QUERY\_DATA\_SOURCE\_UNSPECIFIED |
There is likely a typo in the data\_source field, double check the spelling. |
| all selection fields should have an aggregation function, or none of them should |
If there are multiple selection fields, either all should contain an aggregation\_function, or none of them should. For example, this selection is invalid because num\_acceptances is summed, but num\_lines\_accepted is not:
```json
"selections": [
{
"field": "num_acceptances",
"name": "total_acceptances",
"aggregation_function": "QUERY_AGGREGATION_SUM"
},
{
"field": "num_lines_accepted",
"name": "total_lines_accepted",
"aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
}
]
```
Note: PCW is always considered aggregated. If no aggregation\_function is explicitly chosen, it is considered unspecified. If you would like information about both of these fields, use two seperate queries.
|
| invalid aggregation function for string type field ide: QUERY\_AGGREGATION\_SUM |
Not every field supports every aggregation function; see the available fields section for the matches. In this case, the query used a QUERY\_AGGREGATION\_SUM aggregation function with the "ide" field, which is invalid. |
| tried to aggregate on a distinct field: distinct\_developer\_days. Consider aggregating on the non-distinct fields instead: \[api\_key date] |
Fields with the pattern "distinct\_\*" can not be in the aggregations section; the error suggests an alternative field(s) to aggregate on instead. So instead of:
```json
"aggregations": [
{
"field": "distinct_developer_days",
"name": "distinct_developer_days"
}
]
```
Try:
```json
"aggregations": [
{
"field": "api_key",
"name": "api_key"
},
{
"field": "date",
"name": "date"
}
]
```
|
| duplicate field alias for selection/aggregation: num\_acceptances |
All selections and aggregations must have a different name. Keep in mind that if the name is not specified, by default it is set to \\_\. |
| invalid group name: GroupName |
The group with the specified name was not found, double check the spelling. |
Our autocomplete makes in-line and multi-line suggestions based on the context of your code.
Suggestions appear in grey text as you type. You can press `esc` to cancel a suggestion.
Suggestions will also disappear if you continue typing or navigating without accepting them.
## Keyboard Shortcuts
### General Shortcuts
Here are the general shortcuts that apply for macOS.
Replace `⌘` with `Ctrl` and `⌥` with `Alt` to get the corresponding shortcuts on Windows/Linux.
* **Accept suggestion**: `⇥`
* **Cancel suggestion**: `esc`
* **Accept suggestion word-by-word**: `⌘+→` (VS Code), `⌥+⇧+\` (JetBrains)
* **Next/previous suggestion**: `⌥+]`/`⌥+[`
* **Trigger suggestion**: `⌥+\`
### JetBrains Shortcuts - 2.2.2 (stable) and 2.3.5 (pre-release) and later
# Tips
Source: https://docs.windsurf.com/autocomplete/tips
## Inline Comments
You can instruct autocomplete with the use of comments in your code.
Windsurf will read these comments and suggest the code to bring the comment to life.
This method can get you good mileage, but if you're finding value in writing natural-language instructions and having the AI execute them,
consider using [Windsurf Command](/command/overview).
## Fill In The Middle (FIM)
Windsurf's Autocomplete can Fill In The Middle (FIM).
Read more about in-line FIM on our blog [here](https://windsurf.com/blog/inline-fim-code-suggestions).
## Snooze
Click the Windsurf widget in the status bar towards the bottom right of your editor to see the option to switch Autocomplete off,
either temporarily or until you reenable it.
# Prompt Engineering
Source: https://docs.windsurf.com/best-practices/prompt-engineering
If you're reading this, you're probably someone that already understands some of the use cases and limitations of LLMs. The better prompt and context that provide to the model, the better the outcome will be.
Similarly with Windsurf, there are best practices for crafting more effective prompts to get the most out of the tool, and get the best quality code possible to help you accelerate your workflows.
Model selection can be found directly under the chat.
## Base Model ⚡
**Access:** All users
Available for unlimited use to all users is a fast, high-quality Windsurf Chat model based on Meta's [Llama 3.1 70B](https://ai.meta.com/blog/meta-llama-3-1/).
This model is optimized for speed, and is the **fastest** model available in Windsurf Chat. This is all while still being extremely accurate.
## Windsurf Premier 🚀
**Access:** Any paying users (Pro, Teams, Enterprise, etc.)
Available in our paid tier is unlimited usage of our premier Windsurf Chat model based on Meta's [Llama 3.1 405B](https://ai.meta.com/blog/meta-llama-3-1/).
This is the **highest-performing model** available for use in Windsurf, due to its size and integration with Windsurf's reasoning engine and native workflows.
## Other Models (GPT-4o, Claude 3.5 Sonnet)
**Access:** Any paying users (Pro, Teams, Enterprise, etc.)
Windsurf provides access to OpenAI's and Anthropic's flagship models.
# Overview
Source: https://docs.windsurf.com/chat/overview
Converse with a codebase-aware AI
You can use `⌘+⇧+A` on Mac or `Ctrl+⇧+A` on Windows/Linux to open the chat panel and toggle focus between it and the editor.
You can also pop the chat window out of the IDE entirely by clicking the page icon at the top of the chat panel.
You can use `⌘+⇧+L` on Mac or `Ctrl+⇧+L` on Windows/Linux to open the chat panel while you are typing in the editor.
You can also open the chat in a popped-out browser window by clicking `Tools > Windsurf > Open Windsurf Chat in Browser` in the top menu bar.
You can also try `@diff`, which lets you chat about your repository's current `git diff` state.
The `@diff` feature is currently in beta.
In this tab, you can see:
* **Custom Chat Instructions**: a short prompt guideline like "Respond in Kotlin and assume I have little familiarity with it" to orient the model towards a certain type of response.
* **Pinned Contexts**: items from your codebase like files, directories, and code snippets that you would like explicitly for the model to take into account.
See also [Context Pinning](/context-awareness/overview#context-pinning).
* **Active Document**: a marker for your currently active file, which receives special focus.
* **Local Indexes**: a list of local repositories that the Windsurf context engine has indexed.
## Slash Commands
You can prefix a message with `/explain` to ask the model to explain something of your choice.
Currently, `/explain` is the only supported slash command.
[Let us know](https://codeium.canny.io/feature-requests/) if there are other common workflows you want wrapped in a slash command.
## Copy and Insert
Sometimes, Chat responses will contain code blocks. You can copy a code block to your clipboard or insert it directly into the editor
at your cursor position by clicking the appropriate button atop the code block.
## Stats for Nerds
Lots of things happen under the hood for every chat message. You can click the stats icon to see these statistics for yourself.
## Chat History
To revisit past conversations, click the history icon at the top of the chat panel.
You can click the `+` to create a new conversation, and
you can click the `⋮` button to export your conversation. This applies only for the Windsurf Plugins.
## Settings
Click on the gear icon to reach the `Settings` tab. Here, you can view settings that are applicable to your account. For example, you can update your theme preferences (light or dark), change autocomplete speed, view current plan, and change font size.
The settings panel also gives you an option to download diagnostics, which are debug logs that can be helpful for the Windsurf team to debug an issue, should you encounter one.
## Telemetry
You can accept, reject, or follow-up a generation by clicking the corresponding code lens above the generated diff,or by using the appropriate shortcuts (`Cmd/Ctrl+Enter`/`Cmd/Ctrl+Delete`)
# Models
Command comes with its own set of models that are optimized for current-file edits.
# Best Practices
Command is great for file-scoped, in-line changes that you can describe as an instruction in natural language.
Here are some pointers to keep in mind:
* The model that powers Command is larger than the one powering autocomplete.
It is slower but more capable, and it is trained to be especially good at instruction-following.
* If you highlight a block of code before invoking Command, it will edit the selection. Otherwise, it will do a pure generation.
* Using Command effectively can be an art. Simple prompts like "Fix this" or "Refactor" will likely work
thanks to Windsurf's context awareness.
A specific prompt like "Write a function that takes two inputs of type `Diffable` and implements the Myers diff algorithm"
that contains a clear objective and references to relevant context may help the model even more.
# Code Lenses
Source: https://docs.windsurf.com/command/windsurf-related-features
Shortcuts for common operations
## Explain, Refactor, and Add Docstring
At the top of the text editor, Windsurf gives exposes *code lenses* on functions and classes.
The `Explain` code lens will invoke Cascade, which will simply explain what the function or class does and how it works.
The `Refactor` and `Docstring` code lenses in particular will invoke Command.
* If you click `Refactor`, Windsurf will prompt you with a dropdown of selectable, pre-populated
instructions that you can choose from. You can also write your own. This is equivalent to highlighting the function and invoking Command.
* If you click `Docstring`, Windsurf will generate a docstring for you above the function header.
(In Python, the docstring will be correctly generated *underneath* the function header.)
## Smart Paste
This feature allows you to copy code and paste it into a file in your IDE written in a different programming language.
Use `⌘+⌥+V` (Mac) or `Ctrl+Alt+V` (Windows/Linux) to invoke Smart Paste.
Behind the scenes, Windsurf will detect the language of the destination file and use Command to translate the code in your clipboard.
Windsurf's context awareness will try to write it to fit in your code, for example by referencing proper variable names.
Some possible use cases:
* **Migrating code**: you're rewriting JavaScript into TypeScript, or Java into Kotlin.
* **Pasting from Stack Overflow**: you found a utility function online written in Go, but you're using Rust.
* **Learning a new language**: you're curious about Haskell and want to see what your would look like if written in it.
# Local Indexing
Source: https://docs.windsurf.com/context-awareness/local-indexing
The **Indexing Engine** is Windsurf's codebase awareness service that powers:
* Codebase-Aware [Chat](/chat/overview)
* Codebase-Aware [Autocomplete](/autocomplete/overview)
Compared to regular context-aware Autocomplete and Chat, the Indexing Engine is able to retrieve context from across the entire codebase, not just files that you have recently interacted with. This significantly improves the quality of autocomplete and chat responses.
You can see if your workspace is indexed by checking the "Context" pane in the "Chat" panel. If there is a green dot next to your workspace, then it is indexed and searchable.
## System Requirements
When first enabled, Windsurf will consume a fraction of CPU while it indexes the workspace. Depending on your workspace size, this should take 5-10 minutes, and only needs to happen once per workspace. CPU usage will return to normal automatically. Windsurf Indexing also requires RAM (\~300MB for a 5000-file workspace).
The "Max Workspace Size (File Count)" setting determines the largest workspace for which Windsurf Indexing will try to index a particular workspace / module. If your workspace does not appear to be indexed, please try adjusting this number higher. For users with \~10GB of RAM, we recommend setting this no higher than 10,000 files.
# Overview
Source: https://docs.windsurf.com/context-awareness/overview
On codebase context and related features
Windsurf's context engine builds a deep understanding of your codebase, past actions, and next intent.
Historically, code-generation approaches focused on fine-tuning large language models (LLMs) on a codebase,
which is difficult to scale to the needs of every individual user.
A more recent and popular approach leverages retrieval-augmented generation (RAG),
which focuses on techniques to construct highly relevant, context-rich prompts
to elicit accurate answers from an LLM.
We've implemented an optimized RAG approach to codebase context,
which produces higher quality suggestions and fewer hallucinations.
You can choose to index a particular branch and to automatically re-index the repository after some number of days.
## Security Guarantees
We clone the repository in order to create the index, but once we finish creating embeddings for the codebase we delete all the code and code snippets **assuming that the Store Snippets setting is unchecked.** We don't persist anything other than the embeddings themselves, from which you cannot derive the original code.
Furthermore, all indexing and embedding is performed on a single-tenant instance—nothing about the indexing process is shared between multiple Windsurf Teams customers.
# Overview
Source: https://docs.windsurf.com/context-awareness/windsurf-overview
On codebase context and related features
Windsurf's context engine builds a deep understanding of your codebase, past actions, and next intent.
Historically, code-generation approaches focused on fine-tuning large language models (LLMs) on a codebase,
which is difficult to scale to the needs of every individual user.
A more recent and popular approach leverages retrieval-augmented generation (RAG),
which focuses on techniques to construct highly relevant, context-rich prompts
to elicit accurate answers from an LLM.
We've implemented an optimized RAG approach to codebase context,
which produces higher quality suggestions and fewer hallucinations.
# Analytics API (Enterprise SaaS)
Source: https://docs.windsurf.com/plugins/accounts/analytics-api
## Overview
Windsurf supports an API for custom analytics. It allows querying for data from autocomplete, chat, and command, and a variety of filters, groupings, and aggregations.
We provide all examples in curl; it can then be translated into HTTP requests in other languages.
## User Data Analytics API specification
Data from the Users table on the teams page can be obtained with the following command:
```sh
curl -X POST --header "Content-Type: application/json" \
--data '{
"service_key": "
Click on **Add app**, and then **Add custom SAML app**.
Fill out **App name** with `Windsurf`, and click **Next**.
The next screen (Google Identity Provider details) on Google’s console page has data you’ll need to copy to Windsurf’s SSO settings on [www.windsurf.com/team/team\_settings](http://www.windsurf.com/team/team_settings).
* Copy **SSO URL** from Google’s console page to Windsurf’s settings under **SSO URL**
* Copy **Entity ID** from Google’s console page to Windsurf’s settings under **Idp Entity ID**
* Copy **Certificate** from Google’s console page to Windsurf’s settings under **X509 Certificate**
* Click **Continue** on Google’s console page
The next screen on Google’s console page requires you to copy data from Codeium’s settings page
* Copy **Callback URL** from Codeium’s settings page to Google’s console page under **ACS URL**
* Copy **SP Entity ID** from Codeium’s settings page to Google’s console page under **SP Entity ID**
* Change **Name ID** format to **EMAIL**
* Click **Continue** on Google’s console page
The next screen on Google’s console page requires some configuration
* Click on **Add Mapping**, select **First name** and set the **App attributes** to **firstName**
* Click on **Add Mapping**, select **Last name** and set the **App attributes** to **lastName**
* Click **Finish**
On Codeium’s settings page, click **Enable Login with SAML**, and then click **Save**. Make sure to click on **Test Login** to make sure login works as expected. All users now will have SSO login enforced.
Click on **Create your own application**.
Name your application **Windsurf**, select *Integrate any other application you don’t find in the gallery*, and then click **Create**.
Configure your enterprise application with SAML
* Click on Set up single sign on in the new Windsurf application, and then Click on SAML
* Click on Edit under Basic SAML Configuration, and open up the Windsurf Teams SSO settings at [https://www.codeium.com/team/team\_settings](https://www.codeium.com/team/team_settings)
* On Entra’s SAML configuration form and Windsurf SSO settings page
* For Identifier (Entity ID), copy the SP Entity ID value in the SSO settings page
* For Reply URL (Assertion Consumer Service URL), copy the Callback URL value in the SSO settings page
* Click Save at the top
* Pick the SSO ID you want to use, which creates a login portal for your team. Note that this is not changeable after this is saved.
* Fill out IdP Entity ID in the settings page with the value in Entra ID under Set up Windsurf -> Microsoft Entra Identifier
* Fill out SSO URL in the settings page with the value in Entra ID under Login URL
* Download the SAML certificate (Base64), get the text content of the file, and paste it to X509 Certificate on the Windsurf settings page
* Click on Enable Login with SAML
* Click Save in the Windsurf settings page
* We also need to set up name claims. This step is important in order for Windsurf to know the display name of the user.
* Under Attributes & Claims under Entra ID, click on Edit
* Create 2 new claims. You can do so by clicking on Add new claim
* The first claim should have ‘firstName’ as the Name, and ‘user.givenname’ as the Source attribute
* The second claim should have ‘lastName’ as the Name, and ‘user.surname’ as the Source attribute
* At this point you should have successfully configured SSO. Under Save in the settings page, click on Test Login to make sure everything works as expected.
Select SAML 2.0 as the sign-in method
Set the app name as Windsurf (or to any other name), and click Next
Configure the SAML settings as
* Single sign-on URL to [https://auth.windsurf.com/\_\_/auth/handler](https://auth.windsurf.com/__/auth/handler)
* Audience URI (SP Entity ID) to [www.codeium.com](http://www.codeium.com)
* NameID format to EmailAddress
* Application username to Email
Configure the attribute statements as following, and then click **Next**.
In the feedback section, select “This is an internal app that we have created”, and click **Finish**.
### Register Okta as a SAML provider
You should be redirected to the Sign on tab under your custom SAML application. Now you’ll want to take the info in this page and fill it out in Windsurf’s SSO settings.
* Open [www.windsurf.com/team/team\_settings](http://www.windsurf.com/team/team_settings), and click on Configure SAML
* Copy the text after ‘Issuer’ in Okta’s application page and paste it under Idp Entity ID
* Copy the text after ‘Sign on URL’ in Okta’s application page and paste it under SSO URL
* Download the Signing Certificate and paste it under X509 certificate
* Check Enable Login with SAML and then click Save
* Test the login with the Test Login button. You should see a success message:
At this point everything should have been configured, and can now add users to the new Windsurf Okta application.
You should share your organization's custom Login Portal URL with your users and ask them to sign in via that link.
Users who login to Windsurf via SSO will be auto-approved into the team.
### Caveats
Note that Windsurf does not currently support IDP-initiated login flows.
We also do not yet support OIDC.
# Troubleshooting
### Login with SAML config failed: Firebase: Error (auth/operation-not-allowed)
This points to your an invalid SSO ID, or your SSO URL being incorrect, make sure it is alphanumeric and has no extra spaces or invalid characters. Please go over the steps in the guide again and make sure you use the correct values.
### Login with SAML config failed: Firebase: SAML Response \
This points to your IdP entity ID being invalid, please make sure you copy it correctly from the Okta portal, without any extra characters or spaces before or after the string.
### Failed to verify the signature in samlresponse
This points to an incorrect value of your X509 certificate, please make sure you copy the correct key, and that it is formatted as:
```
-----BEGIN CERTIFICATE-----
value
------END CERTIFICATE------
```
## Step 2: Setup SCIM provisioning
Click on Get started under Provision User Accounts in the middle (step 3), and then click on Get started again.
Under the Provisioning setup page, select the following options.
Provisioning Mode: Automatic
Admin Credentials > Tenant URL: [https://server.codeium.com/scim/v2](https://server.codeium.com/scim/v2)
Leave the Azure provisioning page open, now go to the Windsurf web portal, and click on the profile icon in the NavBar on the top of the page. Under Team Settings, select Service Key and click on Add Service Key. Enter any key name (such as 'Azure Provisioning Key') and click Create Service Key. Copy the output key, go back to the Azure page, paste it to Secret Token.
(What you should see after creating the key on Windsurf)
On the Provisioning page, click on Test Connection and that should have verified the SCIM connection.
Now above the Provisioning form click on Save.
## Step 3: Configure SCIM Provisioning
After clicking on Save, a new option Mappings should have appeared in the Provisioning page. Expand Mappings, and click on Provision Microsoft Entra ID Users
Under attribute Mappings, delete all fields under displayName, leaving only the fields userName, active, and displayName.
For active, now click on Edit. Under Expression, modify the field to
```
NOT([IsSoftDeleted])
```
Then click Ok.
Your user attributes should look like
In the Attribute Mapping page, click on Save on top, and navigate back to the Provisioning page.
Now click on the same page, under Mappings click on Provision Microsoft Entra ID Groups. Now only click delete for externalId, and click Save on top. Navigate back to the Provisioning page.
On the Provisioning page at the bottom, there should also be a Provisioning Status toggle. Set that to On to enable SCIM syncing. Now every 40 minutes your users and groups for the Entra ID application will be synced to Windsurf.
Click on Save to finish, you have now enabled user and group syncing for SCIM. Only users and groups assigned to the application will be synced to Windsurf. Note that removing users only disables them access to Windsurf (and stops them from taking up a seat) rather than deleting users due to Azure's SCIM design.
2. Navigate to SSO in Team Settings
3. When enabling SAML for the first time, you will be required to set up your SSO ID. **You will not be able to change it later.**
It is advised to set this to your organization or team name with alphanumeric characters only.
4. Copy the `Entity ID` value from the Duo portal and paste it into the `IdP Entity ID` field in the Windsurf portal.
5. Copy the `Single Sign-On URL` value from the Duo portal and paste it into the `SSO URL` field in the Windsurf portal.
6. Copy the certificate value from the Duo portal and paste it in the `X509 Certificate` field in the Windsurf portal
7. Copy the `SP Identity ID` value from the Windsurf portal and paste it into the `Entity ID` field in the Duo portal.
8. Copy the `Callback URL (Assertion Consumer Service URL)` from the Windsurf portal and paste it into the `Assertion Consumer Service (ACS) URL` field in the Duo portal.
9. In the Duo portal, configure the attribute statements as following:
10. Enable the SAML login in the Windsurf portal so you can test it.
**NOTE: DO NOT LOGOUT OR CLOSE THE WINDOW AT THIS POINT.**
If you get an error or it times out, troubleshoot your settings, otherwise you have to disable your SAML Settings in the Windsurf portal.
**If you logout or close the window without confirming a successful test - you may get locked out.**
11. Once your test was successfully completed, you may logout. You can now use SSO sign in when browsing to your team/organization page with the SSO ID you have configured in step 3.
[https://www.codeium.com/yourssoid/login](https://www.codeium.com/yourssoid/login)
2. Navigate to SSO in Team Settings
5. Copy the `Issuer ID` from PingID to the `IdP Entity ID` value in the Windsurf portal.
6. Copy the `Single Signon Service` value from PingID to the `SSO URL` value in the Windsurf portal.
7. Download the Signing Certificate from PingID as X509 PEM (.crt), open the file and copy its contents to the `X509 Certificate` value in the Windsurf portal.
**Note**: make sure you have the fill begin and end lines with 5 dashes (-) and no other characters are copied!
8. In attribute mappings, make sure to map:
* `saml_subject` - Email Address
* `firstName` - Given Name
* `lastName` - Family Name
9. Add/edit any other policies and access as required by your setup/organization
10. Enable the SAML login in the Windsurf portal so you can test it.
**NOTE: DO NOT LOGOUT OR CLOSE THE WINDOW AT THIS POINT.**
If you get an error or it times out, troubleshoot your settings, otherwise you have to disable your SAML Settings in the Windsurf portal.
**If you logout or close the window without confirming a successful test - you may get locked out.**
11. Once your test was successfully completed, you may logout. You can now use SSO sign in when browsing to your team/organization page with the SSO ID you have configured in step 3.
[https://www.codeium.com/yourssoid/login](https://www.codeium.com/yourssoid/login)
## User Groups
View the settings panel by clicking on "Windsurf Settings" on the status bar, followed by selecting the "Plan Info" tab.
You can also view it on your plan page at [codeium.com/plan](https://codeium.com/plan) after you're authenticated.
## Upgrading to a paid plan
To learn more about paid features or to upgrade to a paid plan, [click here](https://codeium.com/plan). Paid plans include Pro for individuals, Teams for organizations, and Enterprise for larger companies.
We accept all major credit cards, Apple Pay, Cash App Pay, Google Pay, Link, WeChat Pay, and Alipay. If you have a payment method not listed, please reach out to us at [support](https://codeium.com/support). You may need to disable your VPN to view the relevant payment methods for your region.
## What happens when you run out of prompt credits?
If you no longer have prompt credits, you have two options:
* You can purchase additional prompt credits to continue using premium models
* You can use Write or Chat mode with the models that cost 0 credits!
## Automatic Credit Refills
We've introduced Automatic Credit Refills so that you no longer need to manually purchase additional credits. Under your plan settings page on the Windsurf website, you can specify a maximum amount of credits and other refill settings. The system will automatically "top-up" your credits as you start running low (below 15 credits).
Automatic Credit Refills are purchased in configurable increments (multiples of $10 for Pro and $40 for Teams) and subject to maximum monthly budget caps ($50 by default for Pro users and $160 for Teams users). This ensures you won't lose access to Cascade during critical work.
## Purchasing additional credits
If you run out of prompt credits, you can purchase additional credits in the [billing website](https://codeium.com/plan). Additional prompt credits can be purchased at a rate of \$10 for 250 credits for Pro users.
For Team and Enterprise plans, additional credits are purchased within and treated as a pool amongst all members of the team at a rate of \$40 for 1000 pooled credits. Please contact your Teams admin to purchase more credits if you're on a team plan.
## Usage examples
To explain how credits work, here's a simple example:
When you send a message to Cascade with a premium model, 1 prompt credit is consumed. It doesn't matter how many actions Cascade takes to fulfill your request - whether it searches your codebase, analyzes files, or makes edits - you only pay for the initial prompt.
This simplified system makes it much easier to predict and manage your usage. No more complicated calculations of flow actions or different credit types.
## Plan Usage
### Using a Free Pro Trial
The Pro Trial lasts for 2 weeks and includes unlimited Windsurf Tab, 100 prompt credits, Previews, and Deploys.
When you're on a Pro Trial, you'll have access to premium features! To get started, ask Cascade a question. In Write and Chat mode, Cascade is optimized to fully understand your codebase and leverages tool calls to assist you. By default, all of your requests will use premium models until you run out of credits.
After your trial period ends, you'll need to upgrade to a paid plan to continue using premium models.
If you don't upgrade during the Free Trial period, you'll be downgraded to our Free plan which includes 25 prompt credits per month.
### Using Pro Plan
The Pro plan costs \$15/month and includes:
* 500 prompt credits/month
* All premium models
* Previews
* App Deploys
Additional prompt credits can be purchased at a rate of \$10 for 250 credits.
While on Pro, you'll have access to a monthly quota of prompt credits. You can view how many credits you have remaining in the Windsurf Settings panel that's accessible in the status bar.
If you're running low on credits, Cascade will notify you so that you can purchase additional credits or enable Automatic Credit Refills. To purchase additional credits, visit the billing website and select "Purchase credits". The credits purchased will rollover to the following usage month if there are any remaining.
If you want to reduce your consumption of prompt credits, there are several available models that cost 0 credits!
In addition to prompt credits, Pro comes with unlimited Fast Autocomplete and unlimited premium model requests with Command.
### Using Teams Plan
The Teams plan costs \$30/user/month (up to 200 users) and includes:
* 500 prompt credits/user/month
* Everything in Pro, plus:
* Centralized billing
* Admin dashboard with analytics
* Priority support
Additional prompt credits can be purchased at a rate of \$40 for 1000 pooled credits.
The Teams plan has a seat cap of 200 users. Coming soon, there will be an option to add Access Control features for +\$10/user/month.
While on the Teams plan, each user will have access to a monthly quota of prompt credits. Unlike the previous system, base prompt credits are not pooled - each user has their own credit limit. However, purchased add-on prompt credits are pooled across the organization. You can view how many credits your team has remaining in the Windsurf Settings panel.
If your team is running low on credits, your administrator can purchase additional credits or enable Automatic Credit Refills. These add-on prompt credits purchased will rollover to the following usage month if there are any remaining.
### Using Enterprise Plan
The Enterprise plan costs \$60/user/month (up to 200 users) and includes everything in Teams plus:
* 1000 prompt credits/user/month
* Role-Based Access Control (RBAC)
* SSO & SCIM (included)
* Longer model context lengths
* Highest priority support
Additional prompt credits can be purchased at a rate of \$40 for 1000 pooled credits.
Coming soon, Enterprise will be self-serviceable with month-to-month pricing. The Enterprise plan includes self-serve SSO integration and enhanced security features.
For enterprise support, account management, and more involved deployments such as Hybrid or FedRAMP under an annual commitment, contact our enterprise team at [trust.windsurf.com](https://trust.windsurf.com) for any standard security collateral.
### Using a Free plan
The Free plan comes with:
* 25 prompt credits/month
* Unlimited Windsurf Tab
Windsurf can still be used for free after your credits are exhausted! There are several models available that cost 0 credits to use.
When editing code, you'll have access to unlimited Tab completions and AI command instructions. To learn more about features in Free and in paid tiers, [click here](https://codeium.com/pricing).
## Canceling your paid plan
To cancel your paid plan, visit the billing website. Upon canceling your paid plan, you'll still have access to all of your credits from your monthly quota and add-on prompt credits until the end of the usage month. After the usage month, all add-on prompt credits will expire and you'll be downgraded to the Free plan where you'll be provided a limited number of prompt credits. If you change your mind and decide not to cancel before the end of the usage month, you can renew your plan by visiting the billing page.
# Overview
Source: https://docs.windsurf.com/plugins/cascade/cascade-overview
Windsurf's Cascade brings the best of agentic coding to the JetBrains suite.
To open Cascade, press `Cmd/Ctrl+L` or click the Cascade icon.
# Model selection
Select your desired model from the selection menu below the Cascade conversation input box. Click below too see the full breakdown of the available models and their availability across different plans, pricing, and their ability to accept image upload.
Cascade supports two [transport types](https://modelcontextprotocol.io/docs/concepts/transports) for MCP servers: `stdio` and `/sse`.
For `/sse` servers, the URL should reflect that of the endpoint and resemble `https://
## Memories
During conversation, Cascade can automatically generate and store memories if it encounters context that it believes is useful to remember.
Additionally, you can ask Cascade to create a memory at any time. Just prompt Cascade to "create a memory of ...".
Cascade's autogenerated memories are associated with the workspace that they were created in and Cascade will retrieve them when it believes that they are relevant. Memories generated in one workspace will not be available in another.
## Reading Pages
Cascade can read individual pages for things like documentation, blog posts, and GitHub files. The page reads happen entirely on your device within your network so if you're using a VPN you shouldn't have any problems.
Pages are picked up either from web search results, inferred based on the conversation, or from URLs pasted directly into your message.
We break pages up into multiple chunks, very similar to how a human would read a page: for a long page we skim to the section we want then read the text that's relevant. This is how Cascade operates as well.
It's worth noting that not all pages can be parsed. We are actively working on improving the quality of our website reading. If you have specific sites you'd like us to handle better, feel free to file a feature request!
# Compatibility
Source: https://docs.windsurf.com/plugins/compatibility
Visit our [download page](https://windsurf.com/download) for a list of supported IDEs and installation instructions.
If you are a Windsurf Enterprise user, visit your enterprise portal URL for download and installation instructions.
Contact your internal Windsurf administrator if you have questions.
# Supported IDEs and Versions
**VS Code**: Version 1.89+
**JetBrains IDEs**: Version 2022.3+
Note: JetBrains IDEs with remote SSH support require versions 2023.3+.
**Visual Studio**: 17.5.5+
**NeoVim**: Version 0.6+
**Vim**: 9.0.0185+
**Emacs**: All versions compiled with lbxml
**Xcode**: All versions
**Sublime Text**: Version 3+
**Eclipse**: Version 4.25+ (2022-09+)
# Getting Started
Source: https://docs.windsurf.com/plugins/getting-started
Welcome to Windsurf
**Windsurf** is an AI toolkit that empowers developers to dream bigger and write more code using tools like Cascade, Autocomplete, Chat, Command, and more.
Our models and features have been optimized to build a deep understanding of your codebase in order to provide the highest quality code suggestions.
## Plugin Set Up
Our plugins for Visual Studio Code and JetBrains are our most popular plugins.
The installation steps for these two are given below.
For other IDEs and editors like Eclipse, Visual Studio, Neovim, Google Colab, and more, visit [our download page](https://windsurf.com/download) to get started.
If you do not have an account or otherwise are not already logged in online, you will be prompted to login.
Once you have logged in online, the webpage will indicate that you can return to your IDE.
If you’re inside a virtual environment, run:
Click **Get Windsurf Authentication Token** and follow the link. Paste the token back into the settings dialog.
## Fill In The Middle (FIM)
Windsurf Tab can Fill In The Middle (FIM), meaning it can make suggestions while your cursor is in the middle of a line of code.
Read more about in-line FIM on our blog [here](https://windsurf.com/blog/inline-fim-code-suggestions).
## Terminal Context Awareness
Windsurf Tab is also context aware of your the content of your terminal.
# General Issues
Source: https://docs.windsurf.com/troubleshooting/plugins-common-issues
### I subscribed to Pro but I'm stuck on the Free tier
First, give it a few minutes to update. If that doesn't work, try logging out of Windsurf on the website, restarting your IDE, and logging back into Windsurf. Additionally, please make sure you have the latest version of Windsurf installed.
### How do I cancel my Pro/Teams subscription?
You can cancel your paid plan by going to your Profile by clicking your icon on the top right of the [Windsurf website](https://windsurf.com/profile).
To cancel your Pro subscription, navigate to the `Billing` page in the navigation panel on the left and click "Cancel Plan".
To cancel your Teams subscription, navigate to the `Manage Team` page in the navigation panel on the left and click "Cancel Plan".
### How do I disable code snippet telemetry?
As mentioned in our [security page](https://windsurf.com/security), you can opt out of code snippet telemetry by going to your settings [account settings](https://windsurf.com/settings). For more information, please visit our [Terms of Service](https://windsurf.com/terms-of-service-individual).
### How do I delete my account?
You can delete your account by going to your settings [account settings](https://windsurf.com/settings), scrolling down and clicking on "Delete Account".
# Known IDE issues and solutions
## Codeium isn't starting
If Codeium isn't starting up, use the logs to debug what the cause could be (See above). If you are not able to resolve the issue, file a help request by submitting a ticket at help.codeium.com. Make sure to include the logs referenced above to help our team debug the issue as quickly as possible.
## Codeium Chat shows an empty screen
If you are using Windows 10, it's possible you need to install **WebView2** to switch the Eclipse web renderer from Internet Explorer to Edge.
You can see if this is the case by right-clicking --> `Properties` and seeing if there is an Internet Explorer icon.
## Certificate issue
This issue may be indicated by the following errors in the logs:
```
Failed to fetch extension version at 
## Tab key is not always accepting completions
You can rebind this to a different keyboard shortcut in your settings:
# Visual Studio Code (VSCode)
Source: https://docs.windsurf.com/troubleshooting/plugins-enterprise/vscode
VS Code 1.89 or greater are supported!
# Gathering extension logs
Starting in VS Code Extension 1.10.0, the Extension Diagnostics are accessible for download via the Settings page. This download will contain a collection of relevant logs and parameters into a text file.
*For full output logs of VSCode:*
1. Go to the Command Palette (`Ctrl/Cmd + Shift + P` or go to View > Command Palette)
2. Type in "Show logs" and select the option that reads `Developer: Show Logs`
3. From the dropdown, select `Extension Host`
4. You should see something similar to the image below:
5. Change the dropdown in the top right that reads "Extension Host" and select "Codeium"
6. Export or copy the logs
# How to reset or change your Enterprise URL
1. Navigate to the Codeium Enterprise extension settings by pressing Ctrl+Shift+X. Choose the Enterprise Updater (purple extension)
2. Click on the gear icon and select `Extension Settings`
3. In the extension settings, click the gear icon and select `Reset Setting` for each box populated with a URL
4. Reload VSCode by going to View -> Command Palette. Once the command palette is open type "Reload window" and press enter.
5. Once reloaded, you should be prompted to Set URL. From here, type in the new URL.
6. Close out of the Setting tab.
7. Reload VSCode by going to View -> Command Palette. Once the command palette is open type 'Reload window' and press enter.
8. After reloading, you should see a pop-up in the bottom right prompting you to sign in to Codeium. If not, go to the bottom left Accounts tab and click Sign in with Auth to use Codeium. Either method will redirect you to your Codeium Enterprise portal.
# Known IDE issues and solutions
## e.split is not defined
You are using an unsupported VS Code version, please update to a supported version and try again. You can find a list of supported versions [here](/plugins/compatibility).
## Using the wrong API Server
If a user changes their API Server/Portal URL in their **workspace** settings, this will override their user settings and may result in an error where the extension is communicating with the wrong API server.
Make sure that your API Server/Portal URL is set correctly and not overridden accidentally by the workspace settings.
## Not seeing Codeium Chat responses
If you are trying to send messages to Codeium chat but not seeing responses, check if you can cancel the response. If you are unable to cancel the response, this means that the response was completed but not displayed. This can happen if the Chat Web Server loses connection to the extension. Reloading VS Code and opening the Codeium Chat panel again should show the responses.
## Unable to read file .../package.json
```
Unable to read file .../.vscode/extensions/codeium.codeium-
5. Change the dropdown in the top right that reads "Extension Host" and select "Windsurf"
6. Export or copy the logs
## JetBrains IDEs
Starting in extension version 1.10.0, the Chat Panel has an Extension Diagnostics button on the Settings page. This button will automatically collect relevant logs and parameters into a text file that can be downloaded.
1. Logs are written to the idea.log file. To locate this file, go to the Help > Show Log in Finder/Explorer menu option
2. Export or copy the logs
## Eclipse
In Eclipse, logs are written to the following paths:
* **Mac/Linux**: \~/.codeium/codeium.log
* **Windows**: C:\Users\
### On MacOS, I see a pop-up: 'Windsurf' is damaged and cannot be opened.
This pop-up is due to a false positive in MacOS security features. You can usually resolve this by going to "System Settings -> Privacy & Security" and clicking "Allow" or "Open anyway" for Windsurf. If this fails or is not possible, try the following steps:
1. Ensure that Windsurf is placed under your `/Applications` folder and that you are running it from there.
2. Check your processor type: if your Mac has an Intel chip, make sure you have the Intel version. If it's Apple Silicon (like M1, M2 or M3), make sure you have the Apple Silicon version. You can select the processor type from the [Mac download page](https://windsurf.com/windsurf/download_mac).
3. Try redownloading the DMG and reinstalling from [the official download page](https://windsurf.com/windsurf/download_mac), as the failing security feature is usually triggered on download.
4. Make sure Windsurf (and the "Windsurf is Damaged" pop-up) is closed, and run `xattr -c "/Applications/Windsurf.app/"`.
### I received an error message about updates on Windows, or updates are not appearing on Windows.
For example:
> Updates are disabled because you are running the user-scope installation of Windsurf as Administrator.
We cannot auto-update Windsurf when it is run as Administrator. Please re-run Windsurf with User scope to update.
### What domains should I whitelist for network filters/firewalls, VPNs, or proxies?
If you're using any network filtering, firewalls, VPN services, or working in environments with restricted network access, you may experience connectivity issues with Windsurf. To ensure smooth operation, please whitelist the following domains in your network configuration:
* \*.codeium.com
* \*.windsurf.com
* \*.codeiumdata.com
### On Linux, Windsurf quietly doesn't launch, or crashes on launch
This is usually due to an Electron permissions issue, which VSCode also has, and is expected when using the tarball on Linux.
The easiest way to fix it is to run the following:
```bash
sudo chown root:root /path/to/windsurf/chrome-sandbox
sudo chown 4755 /path/to/windsurf/chrome-sandbox
```
You should then be able to launch Windsurf. You can also just run `windsurf` with the flag `--no-sandbox`, though we don't encourage this.
If this fails, then try the below.
### I received an error message saying 'Windsurf failed to start'
Please delete the following folder:
Windows: `C:\Users\
## How It Works
Once enabled, Windsurf automatically reviews eligible pull requests in selected repositories and provides feedback as GitHub review comments.
Reviews can be manually triggered when you mark a PR as “ready for review” or you type `/windsurf-review` in a PR comment.
You can also edit a PR title by typing `/windsurf` into the PR title.
Example workflow:
1. Developer opens a pull request in an enabled repository
2. Developer marks the PR as ready for review or types “@windsurf /review” in a PR comment
3. Windsurf reviews the PR and posts feedback as GitHub review comments
4. Developer addresses feedback and updates the PR
## Windsurf Plugins
# How It Works
When you're ready to commit changes:
1. Stage your files in the Git panel
2. Click the sparkle (✨) icon next to the commit message field
3. Review the generated message and edit if needed
4. Complete your commit
The AI analyzes your recent code changes and creates a meaningful commit message that describes what you've done.
# Best Practices
For better results:
* Apply general best practices for commit scope: group together small, meaningful units of changes
* Review the message before committing
# Limitations
* Large or complex commits may result in more generic messages
* Specialized terminology might not always be captured perfectly
* Generated messages are suggestions and may need editing
# Privacy
Your code and commit messages remain private. We don't store your code changes or use them for training our models.
# App Deploys
Source: https://docs.windsurf.com/windsurf/cascade/app-deploys
App Deploys lets you deploy web applications and sites directly within Windsurf through Cascade tool calls. This feature helps you share your work through public URLs, update your deployments, and claim projects for further customization. This feature is in beta and support for additional frameworks, more robust builds, etc. are coming soon.
## Overview
With App Deploys, you can:
* Deploy a website or JS web app to a public domain
* Re-deploy to the same URL after making changes
* Claim the project to your personal account
This likely means that your build failed. Please claim your site (you can find it on your [deploy history](https://windsurf.com/deploy)) and check the build logs for more details. Often times you can paste your build logs into Cascade and ask for help.
### Changing Your Subdomain / URL
#### Updating `netlify.app` domain
You can change your subdomain by claiming your deployment and updating the Netlify site settings. This will update your `.netlify.app` domain.
#### Updating custom `.windsurf.build` subdomain
# Overview
Source: https://docs.windsurf.com/windsurf/cascade/cascade
Windsurf's Cascade unlocks a new level of collaboration between human and AI.
To open Cascade, press `Cmd/Ctrl+L`click the Cascade icon in the top right corner of the Windsurf window. Any selected text in the editor or terminal will automatically be included.
### Quick links to features
# Explain and fix
For any errors that you run into from within the editor, you can simply highlight the error and click `Explain and Fix` to have Cascade fix it for you.
# Ignoring files
If you'd like Cascade to ignore files, you can add your files to `.codeiumignore` at the root of your workspace. This will prevent Cascade from viewing, editing or creating files inside of the paths designated. You can declare the file paths in a format similar to `.gitignore`.
# Linter integration
Cascade can automatically fix linting errors on generated code. This is turned on by default, but it can be disabled by clicking `Auto-fix` on the tool call, and clicking `disable`. This edit will not consume any credits.
When Cascade makes an edit with the primary goal of fixing lints that it created and auto-detected,
it may discount the edit to be free of credit charge. This is in recognition of the fact that
fixing lint errors increases the number of tool calls that Cascade makes.
# Sounds for Cascade
Play a sound when Cascade finishes a trajectory to let you know when it's done. You can enable it via `Windsurf Settings` > `Cascade` > `Enable Sounds for Cascade`.
# Sharing your conversation
## Configuring MCP tools
Each plugin has a certain number of tools it has access to. Cascade has a limit of 100 total tools that it has access to at any given time.
At the plugin level, you can navigate to the Tools tab and toggle the tools that you wish to enable. Or, from the `Windsurf Settings`, you can click on the `Manage plugins` button.
## mcp\_config.json
The `~/.codeium/windsurf/mcp_config.json` file is a JSON file that contains a list of servers that Cascade can connect to.
The JSON should follow the same schema as the config file for Claude Desktop.
Here’s an example configuration, which sets up a single server for GitHub:
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "
To execute a Workflow, users simply invoke it in Cascade using the `/[workflow-name]` command.
### 1. Select setup flow
If you're coming from VS Code or Cursor, you can easily import your configurations. Otherwise, select "Start fresh". You can also optionally install `windsurf` in PATH such that you can run `windsurf` from your command line.
### 3. Sign up / Log in
To use Windsurf, you need to use your Windsurf account or create one if you don't have one. Signing up is completely free!
Once you've authenticated correctly, you should see this page. Hit "Open Windsurf" and you're good to go!
#### Having Trouble?
If you're having trouble with this authentication flow, you can also log in and manually provide Windsurf with an authentication code.
If you are not seeing this button, you can:
1. Click on your Profile icon dropdown > Check for Updates
2. In the Command Palette (`Cmd/Ctrl+Shift+P`) > "Check for Updates"
## Things to Try
Now that you've successfully opened Windsurf, let's try out some of the features! These are all conveniently accessible from the starting page. :)
On the right side of the IDE, you'll notice a new panel called "Cascade". This is your AI-powered code assistant! You can chat, write code, and run code with Cascade! Learn more about how it works [here](/windsurf/cascade).
You can create brand new projects with Cascade! Click the "New Project" button to get started.
You can open a folder or connect to a remote server via SSH or a local dev container. Learn more [here](/windsurf/advanced).
Click on the "Windsurf - Settings" button on the bottom right to pop up the settings panel. To access Advanced Settings, click on the button in this panel or select "Windsurf Settings" in the top right profile dropdown.
You can open the command palette with the `⌘+⇧+P` (on Mac) or `Ctrl+Shift+P` (on Windows/Linux) shortcut. Explore the available commands!
# Send Elements to Cascade
In the Preview, you can select and send elements/components and errors directly to Cascade. Simply click on the "Send element" button on the bottom right and then proceed to select the element you want to send.
The selected element will be inserted into your current Cascade prompt as an `@ mention`. You can add as many elements as you want in the prompt.
# In-IDE Preview
Windsurf can open a up a Preview as a new tab in your editor. This is a simple web view that enables you to view web app alongside your Cascade panel.
Because these Previews are hosted locally, you can open them in your system browser as well, complete with all the listeners and ability to select and send elements and console errors to Cascade.
# Auto-executed Cascade commands
Cascade has the ability to run terminal commands on its own with user permission. However, certain terminal commands can be accepted or rejected automatically through the Allow and Deny lists.
By enabling Auto mode, it will rely on Cascade's judgement on whether the command requires the user's permission to be executed. This feature is only available for messages sent with premium models.
### Turbo Mode
In Turbo mode, Cascade will always execute the command, unless it is in the deny list.
You can toggle this via the Windsurf - Settings panel in the bottom right hand corner of the editor.
### Allow list
An allow list defines a set of terminal commands that will always auto-execute. For example, if you add `git`, then Cascade will always accept `git add -A`.
The setting can be via Command Palette → Open Settings (UI) → Search for `windsurf.cascadeCommandsAllowList`.
### Deny list
A deny list defines a set of terminal commands that will never auto-execute. For example, if you add `rm`, then Cascade will always ask for permission to run `rm index.py`.
The setting can be via Command Palette → Open Settings (UI) → Search for `windsurf.cascadeCommandsDenyList`.
