# Welcome
Welcome to SUPgpt for Mac documentation.
If you are looking for the iPhone/iPad version click [here](https://mobiledocs.supgpt.app)
# License
Licensing is only available for the macOS version.
## How to Obtain a License
To purchase a license, visit [this link](https://supgpt.app/#open-checkout) and follow the provided instructions. Once your purchase is complete, you will receive an email containing your receipt and license key.
## Entering Your License for the First Time
Upon launching the app for the first time, you will see a popup panel. Here, enter your license key and click **Continue**.
## Changing Your License Key
IIf you need to update your license key, navigate to the Main Menu and select **SUPgpt -> License.**
Then click **Change.**
After entering your new license key, click **Submit**.
# API Keys
The app requires at least one API key to function, and it **specifically requires an OpenAI API key for advanced tools** such as web content extraction and knowledge files.
## How to Obtain API Keys
To use the app's features, you must individually sign up for each API provider and create your API keys:
* OpenAI
* Anthropic
* Google
* Groq
## Adding API Keys to the App
#### Open Settings
Access the Settings by pressing **Cmd ⌘** + **,** or by selecting **SUPgpt -> Settings** from the Main Menu.
#### Input Your API Keys
In the left panel, click on **API Keys** and paste your keys into their respective fields. The app automatically saves your entries, allowing you to close the window when you're finished.
## API Key Storage
Your API keys are encrypted and stored locally on your device.
## Syncing API Keys Across Devices
Please note that API keys are not synced between devices. If you use the app on multiple devices, you will need to enter your keys manually for each instance.
# Starting a New Chat
## When No Chat is Selected
When you launch the app for the first time, or if there is no chat selected, the **New Chat** button will be at the center of the window. Click it, and select the type of chat you want to start.
## When You Have Selected a Chat
When there is a selected chat, the **New Chat** button will be located at the top left corner of the chat panel. Click it, and select the type of chat you want to start.
## From the Main Menu
From the Main Menu select **File -> New Temp Chat** or **New Chat.**
Using Keyboard Shortcuts
* **Cmd ⌘ + N** To start new temporary chat
* **Shift ⇧ + Cmd ⌘ + N** To start new persistent chat.
{% hint style="info" %}
To learn the difference between temporary and persistent chats, follow [this link](/chat/chat/persistent-and-temporary-chat).
{% endhint %}
# Accessing App Settings
From the Main Menu select **SUPgpt -> Settings** or use the keyboard shortcut **Cmd ⌘ + ,**
# API Keys
Each API key must be entered into its respective field to activate the models and features associated with these services. Changes are automatically saved when the settings window is closed.
# General
The following settings are available in the General section:
#### Show in Dock
This toggle controls the visibility of the app icon in the dock. Changes to this setting require a restart of the application.
#### Run on Startup
This toggle allows the app to start automatically when macOS starts. When enabling this option for the first time, permission will be prompted to allow the app to run at startup.
#### Appearance
This setting allows the app's theme to match the macOS system theme. Options include **System** (to follow the macOS appearance), **Light**, and **Dark** modes
#### Quick Chat Shortcut
This setting defines the keyboard shortcut for accessing the quick chat feature. To change the shortcut, click inside the field and press the desired new key combination. To revert to the original shortcut, click the **Reset** button.
{% hint style="info" %}
Learn more about Quick Chat click [here](/chat/quick-chat).
{% endhint %}
# Chat
## New Chat Defaults
Configure the default settings for all new chats, which will also apply to [Quick Chat.](/chat/quick-chat)
#### Model
Set the default model to be used in a new chat.
#### Context Window Limit
Define the context window limit for new chats. Deleting the contents of this field will reset the limit to the maximum allowed for the selected model.
#### Output Limit
Specify the output limit for new chats. Deleting the contents of this field will set the output limit to unlimited.
{% hint style="info" %}
Context Window Limit and Output Limit are using tokens.
{% endhint %}
## Available Models
This section provides information about all available models, including the following details:
* **Provider**: The source of the model.
* **Max Context Window**: The maximum context window for each model.
* **Max Output Limit**: The maximum output limit for each model.
* **Tool Usage**: Indicates whether the model can utilize additional tools.
Additionally, unused models can be disabled to prevent them from appearing in the model selection dropdown.
# Tools
## New Chat Tools Defaults
Configure the default tools settings for all new chats.
#### Enabled
Toggle tools active for new chats.
#### Knowledge Limit
Set the token limit for content retrieval when using the search tool within knowledge files. This retrieved knowledge will be utilized to answer questions related to the content of those files.
#### $PATH
The **$PATH** variable represents a list of directories on your system where essential applications and commands are stored. By including a directory in **$PATH**, the system can recognize the commands located within it.
{% hint style="info" %}
To grant SUPgpt access to all applications and commands on your system, open the **Terminal**, type **`echo $PATH`**, and paste the output in this field. This allows SUPgpt to efficiently locate and utilize system-level commands.
{% endhint %}
## Active Tools
View a list of all available tools along with a brief description of each. Specific tools can be deactivated for use in new chats.
{% hint style="info" %}
To learn more about tools click [here](/tools/overview)
{% endhint %}
# Image Generation
## Image Generation New Chat Defaults
Configure the default image generation settings for all new chats.
#### Enabled
Toggle image generation active for new chats.
#### Model
Set the default image model to be used in a new chat.
The remaining settings are model-specific and will change depending on the selected model.
# Manage Chats
All persistent chats are listed in the chat list panel, sorted by the date of the last message.
To delete or toggle chat as favourite hover it and click the to delete or to toggle favourite
# Chat Settings
The chat settings affect only the current chat session and override the default chat settings.
## Chat
#### Model
Select the model to be used for the current chat session.
#### Context Window Limit
This defines the maximum size of the context, in tokens, that the model will use. Since different models calculate tokens differently, this is an approximation. If the field is empty, the context limit is set to the maximum possible value for the model.
**Keep in mind**: Your new, unsent messages and unsent attached files are not included in the context window limit. Adjust the context limit accordingly if attaching large files.
**Note**: The context window limit does not account for system parameters required for the app to function. These typically do not exceed an additional 1000 tokens per request. It is advisable to always set the limit to 1000 tokens more than your actual needs.
{% hint style="info" %}
**Hint**: If your files were not included in the context, simply set the context window limit to a larger value and submit an empty message.
{% endhint %}
**Important**: Be cautious when using an empty context limit with long chats or large files, as this can quickly lead to high costs.
#### Output Limit
This defines the model's maximum response length in tokens.
#### Temperature
This setting varies by model but generally influences the predictability or creativity of the model's output. Switching between models resets this value.
#### Presence Penalty
Available on certain models only. This setting controls the repetition of specific phrases or words in the generated text. Switching between models resets this value.
#### Context Memory
Click **Change** to open the context memory panel. To learn more, refer to the [Memorize tool](/tools/memorize).
#### System Prompt
System prompts provide instructions and information to the model regarding the nature of the chat.
{% hint style="info" %}
This is the place to set a persona for the model, if needed.
{% endhint %}
## Tools
Available only for models that support tools.
#### Enabled
Toggle this setting to enable or disable the model's use of tools.
#### Knowledge Window Limit
This sets the limit for knowledge retrieval in tokens, affecting the [Search in Files](/tools/search-in-files) and [Extract Web Content](/tools/extract-web-content) tools.
**Important**: Since the retrieved knowledge is injected into the model’s context, it is crucial that the model’s Context Window Limit is greater than the Knowledge Window Limit.
#### Active Tools
By default, all tools are active for the model to use. However, you can disable specific tools as needed.
#### Active Directory
You can manually set and delete the Active Directory path. Refer to the [Set Active Directory](/tools/set-active-directory) tool for more informatio
#### $PATH
The $PATH is utilized by the [Run Command](/tools/run-command) tool.
## Image
Available only for models that support tools.
#### Enabled
Toggle this setting to allow or disallow the model's ability to generate images.
#### Model
Select the model to be used for image generation.
#### Image Size
This depends on the model. Choose the desired resolution for the generated images.
#### Quality
This depends on the model:
* Standard: Default setting.
* HD: Allocates more time for image generation, resulting in higher quality images but also increased latency and price.
#### Style
This depends on the model:
* Vivid: Encourages the model to generate hyper-real and dramatic images.
* Natural: Promotes a more realistic, less hyper-real appearance in the generated images.
# Chat
# Persistent and Temporary Chat
When creating a new chat, you have the option to select whether the chat is temporary or persistent.
* **Temporary**: This chat is not saved in the database and will be lost when switching to another chat or closing the app. You can also start a new temporary chat by using **Cmd ⌘ + N**. A temporary chat is indicated by the next to the title.
* **Persistent**: This chat is saved in the database and synced across devices. You can also start a new persistent chat by using **Shift ⇧ + Cmd ⌘ + N**.
## Converting Temporary to Persistent
If you need to save a temporary chat, you can convert it to persistent by clicking the  button in the top right corner.
# Prompt Bar
To create a new line in the prompt bar, press **Shift ⇧ + Enter ⏎**. To submit the prompt, press **Enter ⏎**.
While the model is generating text or running a tool, you can interrupt the process by pressing the  button on the prompt bar.
# Attaching Files
You can attach text-based files to your message in two ways:
* By pressing the  button on the prompt bar.
* By dragging the files into the chat window.
The contents of attached files are injected into the message. As long as the message containing the attached files is within the current context window, their content will remain accessible to the model.
**I****mportant**: For large files, you may need to adjust the context window limit.
{% hint style="info" %}
**Hint**: To have continuous access to the content of larger files, it is recommended to utilize the [Search in Files](/tools/search-in-files) tool.
{% endhint %}
# Attaching Images (Vision)
You can attach images to your message to leverage the model's ability to analyze visual content in two ways:
* By pressing the  button on the prompt bar.
* By dragging the images into the chat window.
Attached images are injected in the message. As long as the message containing the attached images is in the current context window their content will continue to be available to the model.
**Important**: Different models, even from the same provider, handle image analysis differently in terms of cost. If you encounter a context window error with the GPT-4o Mini, it does not necessarily mean you will receive the same error with the GPT-4o, even if both are set to the same context limit. You will be notified if the context window is too small for the attached images.
# Messages
There are two types of messages: user messages (yours) and assistant messages (from the model).
You can reveal additional information and functions by hovering over each message.
## User Message
When you hover over a user message, you will see two options:
* - Copy the text of the message.
* - Delete the message from the conversation.
## Assistant Message
Assistant messages consist of up to three parts:
* Body:
* Tools:
* Fragments - Generated files and images:
When you hover over an assistant message, you will find additional options and information:
* - Scroll to the beginning of the message.
* - Copy the body of the message.
* - Regenerate (if you have switched to a different model, it will use the new model to regenerate the message).
* - Delete the message from the conversation.
*  1,383 - Input tokens used.
* 468 - Output tokens used.
*  claude-3-5-sonnet-20240620 - The model used to generate the message.
## Limited Markdown Support
Assistant messages support limited markdown features, including the display of code blocks and tables.
# Title Bar
The title bar contains the **New Chat** button, the chat title, and buttons for **Generated Fragments** and **Knowledge Files**.
{% hint style="info" %}
For more information about generated fragments, please see the [Create File](/tools/create-file) tool.
For more information about knowledge files, please refer to the [Search in Files](/tools/search-in-files) tool.
{% endhint %}
The title is automatically generated after the first 4 messages. To create the title, the app uses the most cost-effective model available.
When you hover over the title, you will find three options:
* - Toggle to add or remove the chat from favorites.
* - Regenerate the title, using the content of the last messages (up to 1000 tokens).
*  - Set the title manually.
# Context Window Marker
The context window marker serves as a visual cue to indicate what content is within the model's context and what is outside of it. The marker automatically recalibrates its position when the context window limit setting is changed or when new messages are added to the conversation.
**Important**: The marker does not account for the message that you are about to send, which may change its position when sent.
# Quick Chat
The quick chat window is accessible at any time by pressing **Shift ⇧ + Cmd ⌘ + D** (this is the default shortcut, which can be changed in the App Settings).
The quick chat configuration reflects the default values you’ve set in the [**App Settings**](/app-settings/general).
When the quick chat window loses focus, it hides but does not close. You can reopen the same quick chat by pressing **Shift ⇧ + Cmd ⌘ + D** (or the shortcut you have configured).
To start a new quick chat, you must first close the current one, either by pressing the **X** button or by using **Cmd ⌘ + W**.
If you need to move the quick chat session to persistent storage, press the button.
# Overview
Models that support tool calls can extend their capabilities beyond just chatting. Tools will appear as separate messages in the chat window, displaying a preloader while the tool is being executed and an orange checkmark when the execution is complete.
The model is executing the Set active directory tool
The model has finished executing the Set active directory tool
Models that support tools
**OpenAI**:
* GPT-4o mini
* GPT-4o
* GPT-4 Turbo
* GPT-3.5 Turbo
**Anthropic**:
* Claude 3.5 Sonnet
* Claude 3 Sonnet
* Claude 3 Opus
* Claude 3 Haiku
**Google**:
* Gemini 1.5 Pro
* Gemini 1.5 Flash
* Gemini 1.0 Flash
**Groq**:
* Llama 3.1 70b
* Llama 3.1 70b
{% hint style="info" %}
OpenAI API key is required for **Search in Files** and **Extract Web Content** tools.
{% endhint %}
## Using the Tools
There is no need to explicitly specify which tool the model should use. The model will attempt to infer the appropriate tool based on the context of the conversation and the content of your prompt.
## Available Tools
### Set Active Directory
Sets the active directory, where the chat can manipulate files.
### Get Active Directory
Retrieves the active directory if set.
### Run Command
Executes bash command.
### Create File
Creates a text based file. If the active directory is set it will also create the file in it
### Read File
Reads an entire file from the generated fragments, knowledge files or the active directory if set.
### List Files
Lists all files in the generated fragments or knowledge files.
### Search in Files
Searches throught the knowledge files for relevent information and use it as context.
### Generate Image
Generates an image using the selected image model.
### Memorize
Memorizes a piece of information making it always available in the context. You can manage the memorized snipets from the Chat Settings Panel.
### Extract Web Content
Tries to extract relative text content from a web page.
### Search Web
Performs a web search. **(Spawns assistant)**
# Set Active Directory
Sets the active directory, where the chat can create, read and edit files.
When the model runs command, the active directory is used as the location for executing the command. For example, if the active directory is set and a request is made to the model to initialize a React project, it will be created in that directory.
The active directory can also be set or changed from the chat settings panel.
# Get Active Directory
When executing file-related tasks or commands, the model can determine if the active directory is set and get its location..
# Run Command
The Run Command Tool enables AI models to execute shell commands on macOS. This functionality allows tasks to be performed by simply describing the desired action, without the need to recall specific commands. The AI processes the request and executes the appropriate shell commands.
## $PATH
The Run Command tool relies heavily on the $PATH configuration, which enables it to access installed applications and extend its functionalities.
{% hint style="info" %}
To grant SUPgpt access to all commands on your system, follow these steps:
1\. Open the Terminal.
2\. Type echo $PATH and press Enter.
3\. Copy the output.
4\. Paste it into the $PATH field in either the App Settings or the Chat Settings.
{% endhint %}
## Limitations
Run Command cannot execute commands that require user input. For example, commands that prompt for confirmation, such as `Do you want to continue Y/n`, will cause the tool to run indefinitely.
If encountering such a command, the process can be terminated by clicking the stop button in the prompt field, which will instantly kill the running process.
## Some "Run Command" Uses
* Run python code
* Initialize node.js projects
* Use FFmpeg for video processing
* Resize and convert images
* Download files
* Retrieve system information
* Use available installed interpreters
* Make API calls
* Zip files
* Search for files
* Manage packages
* Perform file operations
* Check network status
* Create and manage virtual environments
* Monitor system resources
* Schedule tasks
* Generate SSH keys
* Compile code
* Run Docker containers
* And more
# Create File
The Create File tool allows the model to generate text-based files. Supported file types include, but are not limited to:
* Code and script files
* CSVs
* PDFs
* Text
If the [Active Directory](/tools/set-active-directory) is set, the files will be created in that directory. If the Active Directory is not set, the files will only be accessible within the chat.
To view the contents of a created file, click the  button.
To export the file, click the  button or simply drag the file out of the chat window.
## Generated Fragments
All created files are available in the Generated Fragments window. To open this window, click the button in the top right corner of the chat window.
# Read File
The Read File tool enables the model to access and read text-based files from three distinct sources:
* Filesystem
* Generated files
* Knowledge files
{% hint style="info" %}
If the size of the file contents exceeds the token limit set for the context window limit, the file will not be sent to the model.
{% endhint %}
{% hint style="info" %}
It is recommended to specify the desired source when asking the model to read a file. This ensures accurate retrieval of the intended content.
{% endhint %}
# List Files
The List Files tool allows the model to retrieve a list of all generated or knowledge files associated with the current chat session.
# Search in Files
The Search in Files tool requires an **OpenAI API key**.
The Search in Files tool allows the addition of files to enhance the chat's knowledge base. Models can search for relevant information within these files and utilize it as context for responses. **Only text-based files are supported, such as texts, code, CSVs, and PDFs where the text is selectable.**
To add knowledge files, click the button in the top right corner. You can drag the file into the Chat Knowledge window or click the button to open Finder. Please wait for the files to complete parsing.
{% hint style="info" %}
Large files may take more time to parse. While it is not mandatory, it is advisable to keep individual knowledge files under 50 MB.
{% endhint %}
{% hint style="info" %}
The models may not always choose to search in the knowledge files for content. It is a good practice to remind them to use the knowledge files to answer queries.
{% endhint %}
## Knowledge Window Limit
This setting defines how much content to fetch from the knowledge files.
**Important:** It is essential that the knowledge window limit is less than the context window limit of the model, otherwise, the model will not be able to use the knowledge due to its larger size.
## Time to Process
Processing approximately 3,000,000 symbols from the knowledge files takes about 1 minute when parsing. Please keep in mind that processing time will increase with larger files.
# Generate Image
To enable image generation in the app, activate the feature in either the **App Settings -> Image Generation** or in the **Chat Settings**.
## Model Settings
Each model has different settings to choose from.
## Saving the Image
The generated images can be saved in two ways:
* Drag the image directly from the chat to your desired location.
* Click thebutton to save the image to the drive.
## Generated Fragments
All generated images are available in the Generated Fragments window. To open this window, click the button in the top right corner of the chat window.
# Memorize
The Memorize tool enables the model to "remember" specific pieces of information that remain accessible in the context of the conversation.
{% hint style="info" %}
An example use of the Memorize tool would be to create a Python virtual environment and have the model remember to always use this environment for Python-related tasks.
{% endhint %}
## Modify Memory
To view and modify what the model has in its memory, click on the **Change** button in the **Chat Settings**. Here, you can add, edit, or delete memorized pieces of information.
# Extract Web Content
The Extract Web Content tool enables the model to retrieve relevant information from a single web page and utilize it as context during the conversation.
The size (in tokens) of the retrieved content is determined by the knowledge window limit setting in the [**Chat Settings**](/chat/chat-settings)**.**
# Search Web
The Search Web tool enables the model to perform a real-time web search to gather external information.
