# Table of Contents - [Welcome to Askimo Documentation | Askimo](#welcome-to-askimo-documentation-askimo) - [Askimo Recipes - Reusable AI Workflows | Askimo](#askimo-recipes-reusable-ai-workflows-askimo) - [Contributing Translations to Askimo | Askimo](#contributing-translations-to-askimo-askimo) - [How to Contribute | Askimo](#how-to-contribute-askimo) - [Updating Askimo App | Askimo](#updating-askimo-app-askimo) - [Update Askimo App on Windows | Askimo](#update-askimo-app-on-windows-askimo) - [xAI (Grok) Setup for Askimo App | Askimo](#xai-grok-setup-for-askimo-app-askimo) - [Install Askimo App on Linux | Askimo](#install-askimo-app-on-linux-askimo) - [Update Askimo App on Linux | Askimo](#update-askimo-app-on-linux-askimo) - [Install Askimo App on Windows | Askimo](#install-askimo-app-on-windows-askimo) - [Docker AI Setup for Askimo App | Askimo](#docker-ai-setup-for-askimo-app-askimo) - [Askimo CLI Installation Guide | Askimo](#askimo-cli-installation-guide-askimo) - [Web Search | Askimo](#web-search-askimo) - [LM Studio Setup for Askimo App | Askimo](#lm-studio-setup-for-askimo-app-askimo) - [Gemini Setup in Askimo Desktop App (API Key, Models, Troubleshooting) | Askimo](#gemini-setup-in-askimo-desktop-app-api-key-models-troubleshooting-askimo) - [Askimo App Features & Workflows | Askimo](#askimo-app-features-workflows-askimo) - [AI Providers Setup Guide | Askimo](#ai-providers-setup-guide-askimo) - [OpenAI-Compatible Provider - Connect Any OpenAI-Compatible API to Askimo | Askimo](#openai-compatible-provider-connect-any-openai-compatible-api-to-askimo-askimo) - [MCP (Model Context Protocol) Integration | Askimo](#mcp-model-context-protocol-integration-askimo) - [Custom Directives - Personalize AI Behavior | Askimo](#custom-directives-personalize-ai-behavior-askimo) - [Getting Started with Askimo CLI | Askimo](#getting-started-with-askimo-cli-askimo) - [AI Model Configuration | Askimo](#ai-model-configuration-askimo) - [Mermaid Diagrams in Askimo | Askimo](#mermaid-diagrams-in-askimo-askimo) - [Ollama Desktop App - Best Free Ollama Client for Mac, Windows & Linux | Askimo](#ollama-desktop-app-best-free-ollama-client-for-mac-windows-linux-askimo) - [Plans - AI-Powered Multi-Step Workflows | Askimo](#plans-ai-powered-multi-step-workflows-askimo) - [HiDPI & UI Scale — Sharp Display on Any Screen | Askimo](#hidpi-ui-scale-sharp-display-on-any-screen-askimo) - [Askimo App Settings Overview | Askimo](#askimo-app-settings-overview-askimo) - [Askimo App Installation Overview | Askimo](#askimo-app-installation-overview-askimo) - [LocalAI Setup for Askimo App | Askimo](#localai-setup-for-askimo-app-askimo) - [Askimo App UI Preferences & Settings | Askimo](#askimo-app-ui-preferences-settings-askimo) - [Claude Desktop App - Free Anthropic Claude Client for Mac, Windows & Linux | Askimo](#claude-desktop-app-free-anthropic-claude-client-for-mac-windows-linux-askimo) - [Proxy Configuration in Askimo | Askimo](#proxy-configuration-in-askimo-askimo) - [Update Askimo App on macOS | Askimo](#update-askimo-app-on-macos-askimo) - [ChatGPT Desktop App - Free OpenAI Desktop Client for Mac, Windows & Linux | Askimo](#chatgpt-desktop-app-free-openai-desktop-client-for-mac-windows-linux-askimo) - [Install Askimo App on macOS | Askimo](#install-askimo-app-on-macos-askimo) - [Askimo CLI Architecture Guide | Askimo](#askimo-cli-architecture-guide-askimo) - [Create Custom Commands in Askimo CLI | Askimo](#create-custom-commands-in-askimo-cli-askimo) - [Askimo App Architecture Guide | Askimo](#askimo-app-architecture-guide-askimo) - [Composite Commands Reference | Askimo](#composite-commands-reference-askimo) - [Askimo Development & Customization Guide | Askimo](#askimo-development-customization-guide-askimo) - [Askimo CLI Commands Reference | Askimo](#askimo-cli-commands-reference-askimo) - [RAG - Retrieval-Augmented Generation | Askimo](#rag-retrieval-augmented-generation-askimo) - [Skills - AI Agents for Your Workspace | Askimo](#skills-ai-agents-for-your-workspace-askimo) - [Integrate New AI Providers in Askimo | Askimo](#integrate-new-ai-providers-in-askimo-askimo) --- # Welcome to Askimo Documentation | Askimo [Skip to content](https://askimo.chat/docs/#_top) Welcome to Askimo Documentation =============================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Askimo.chat is an AI-powered chat and automation platform available as both a CLI and Desktop application. These docs help you move from first install to advanced workflow customization. 📟 CLI ---------- Command-line interface for terminal users and automation workflows. Perfect for scripting, CI/CD pipelines, and DevOps tasks. Use the sidebar to explore installation, commands, and recipes. 🖥️ Desktop --------------- Visual interface for chatting with multiple AI providers. Features include searchable chat history, custom directives, and conversation management. Explore the Desktop section in the sidebar to get started. 🛠️ Develop & Extend ------------------------ Askimo is open-source and extensible. Contribute new CLI commands, integrate additional AI providers, add UI translations, or customize the architecture to fit your workflows. Check the Development section in the sidebar for setup guides, architecture overviews, and contribution guidelines. Core Concepts ------------- [Section titled “Core Concepts”](https://askimo.chat/docs/#core-concepts) | Concept | Summary | | --- | --- | | Commands | Reusable actions you invoke directly or embed in recipes. | | Recipes | Declarative automation chains combining prompts + commands. | | Providers | Pluggable AI model backends (OpenAI, Anthropic, local models). | | Projects | Knowledge-aware workspaces with indexed documents & code. | Learn More ---------- [Section titled “Learn More”](https://askimo.chat/docs/#learn-more) | Resource | What you’ll find | | --- | --- | | [Features Overview](https://askimo.chat/features/) | Visual tour of RAG, MCP Tools, AI Plans, Script Runner, and all capabilities | | [Download Askimo](https://askimo.chat/download/) | macOS, Windows, and Linux installers - free, no account required | | [RAG: Chat with your documents](https://askimo.chat/blog/ollama-rag-chat-with-documents-local-ai/) | Practical guide with real-world examples using Ollama and local models | | [MCP Integration guide](https://askimo.chat/blog/mcp-integration-askimo-desktop/) | Connect AI to GitHub, databases, APIs, and real-world tools | | [Run scripts from chat](https://askimo.chat/blog/askimo-run-scripts-inside-app-python-bash-node/) | Execute Python, Bash, and Node.js scripts inside Askimo | | [Multi-provider comparison](https://askimo.chat/blog/benefits-multi-ai-providers/) | Why using ChatGPT, Claude, Gemini, and Ollama together beats picking one | Community & Support ------------------- [Section titled “Community & Support”](https://askimo.chat/docs/#community--support) If you get stuck: * Open an issue on [GitHub](https://github.com/askimo-ai/askimo) * Star the repo to support development * Share ideas & feature requests in issues --- # Askimo Recipes - Reusable AI Workflows | Askimo [Skip to content](https://askimo.chat/docs/cli/using-recipes/#_top) Askimo Recipes - Reusable AI Workflows ====================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Recipes are a key feature of Askimo, designed to automate repetitive tasks and enable advanced customization. With recipes, you can define reusable workflows, create custom prompts, and parameterize both system and user messages to fit your needs. * * * 1\. Recipe Lifecycle: Quick Reference ------------------------------------- [Section titled “1. Recipe Lifecycle: Quick Reference”](https://askimo.chat/docs/cli/using-recipes/#1-recipe-lifecycle-quick-reference) | Operation | Non-Interactive Mode | | --- | --- | | Create recipe | ✅ `askimo --create-recipe` | | List recipes | ✅ `askimo --recipes` | | Delete recipe | ✅ `askimo --delete-recipe` | | Run recipe | ✅ `askimo -r recipe args` | * * * 2\. Anatomy of a Recipe ----------------------- [Section titled “2. Anatomy of a Recipe”](https://askimo.chat/docs/cli/using-recipes/#2-anatomy-of-a-recipe) A recipe in Askimo is defined in a YAML file with the following sections: * `name`: Unique identifier for the recipe. * `version`: (Optional) Recipe version number. * `description`: Short summary of what the recipe does. * `allowedTools`: (Optional) List of tool names the recipe is allowed to use. If omitted, all tools are allowed. * `vars`: (Optional) Variables computed using tools, often referencing external arguments. * `system`: Instructions or context for the AI (system prompt). * `userTemplate`: The main user prompt, can reference variables and external arguments. * `postActions`: (Optional) Actions to perform after the main recipe execution. ### Section-by-Section Explanation [Section titled “Section-by-Section Explanation”](https://askimo.chat/docs/cli/using-recipes/#section-by-section-explanation) #### `name` [Section titled “name”](https://askimo.chat/docs/cli/using-recipes/#name) A unique string to identify your recipe. Used to run the recipe from CLI or REPL. #### `version` [Section titled “version”](https://askimo.chat/docs/cli/using-recipes/#version) (Optional) Integer or string to track changes to your recipe. #### `description` [Section titled “description”](https://askimo.chat/docs/cli/using-recipes/#description) A short summary of the recipe’s purpose. Shown in listings and help. #### `allowedTools` [Section titled “allowedTools”](https://askimo.chat/docs/cli/using-recipes/#allowedtools) (Optional) List of tool names the recipe can use. If omitted or empty, all tools are allowed. See the next section for details. #### `vars` [Section titled “vars”](https://askimo.chat/docs/cli/using-recipes/#vars) (Optional) Define variables that are computed before running the recipe. Each variable uses a tool and arguments. Arguments can reference external parameters (see below). #### `system` [Section titled “system”](https://askimo.chat/docs/cli/using-recipes/#system) System prompt for the AI, setting context, rules, or persona. #### `userTemplate` [Section titled “userTemplate”](https://askimo.chat/docs/cli/using-recipes/#usertemplate) Main user prompt, can reference variables and external arguments. #### `postActions` [Section titled “postActions”](https://askimo.chat/docs/cli/using-recipes/#postactions) (Optional) List of actions to perform after the main recipe execution (e.g., save output). * * * 3\. Arguments and Parameterization ---------------------------------- [Section titled “3. Arguments and Parameterization”](https://askimo.chat/docs/cli/using-recipes/#3-arguments-and-parameterization) When you run a recipe, you can pass external arguments from the CLI. These are referenced in the recipe as `{{arg1}}`, `{{arg2}}`, etc. The mapping is positional: * `arg1` = first argument after the recipe name * `arg2` = second argument, and so on **Example:** askimo -r summarize README.md * `arg1` will be `README.md` In your recipe YAML, you can use `{{arg1}}` in `vars`, `system`, or `userTemplate`: vars: file_content: tool: readFile args: ["{{arg1}}"] * * * 4\. Tool Access Control (`allowedTools`) ---------------------------------------- [Section titled “4. Tool Access Control (allowedTools)”](https://askimo.chat/docs/cli/using-recipes/#4-tool-access-control-allowedtools) By default, a recipe has access to ALL built‑in tools. You only need to specify `allowedTools:` when you want to restrict what the recipe may call. You can view all available tools at any time by running: * Non-interactive mode: `askimo --tools` Ways to allow all tools: * Omit the `allowedTools` field entirely. * Or set it to an empty list: `allowedTools: []` Restricting tools example: allowedTools: - readFile - writeFile This limits the recipe to just those tools; any attempt to use others will fail with an error. > Note: Tool names are the Kotlin method names (e.g. `writeFile`). If new tools are added you’ll see them in `askimo --tools` or error messages listing available tools. * * * 5\. Handling Recipe Output (AI Response) ---------------------------------------- [Section titled “5. Handling Recipe Output (AI Response)”](https://askimo.chat/docs/cli/using-recipes/#5-handling-recipe-output-ai-response) When a recipe runs, the AI’s response is stored in a special variable called `output`. This variable is available for use in the `postActions` section. You can use `output` to decide what happens to the result—print it to the user, save it to a file, use it in a tool, or even perform multiple actions. **Common output handling patterns:** ### 1\. Display output to the user (stdout) [Section titled “1. Display output to the user (stdout)”](https://askimo.chat/docs/cli/using-recipes/#1-display-output-to-the-user-stdout) postActions: - call: tool: print args: ["{{output}}"] ### 2\. Save output to a file [Section titled “2. Save output to a file”](https://askimo.chat/docs/cli/using-recipes/#2-save-output-to-a-file) postActions: - call: tool: writeFile args: ["/path/to/file.txt", "{{output}}"] ### 3\. Use output in a tool (e.g., git commit) [Section titled “3. Use output in a tool (e.g., git commit)”](https://askimo.chat/docs/cli/using-recipes/#3-use-output-in-a-tool-eg-git-commit) postActions: - call: tool: commit args: message: "{{output}}" ### 4\. Both save and display [Section titled “4. Both save and display”](https://askimo.chat/docs/cli/using-recipes/#4-both-save-and-display) postActions: - call: tool: writeFile args: ["output.txt", "{{output}}"] - call: tool: print args: ["✅ Saved to output.txt\n\n{{output}}"] ### 5\. Conditional output [Section titled “5. Conditional output”](https://askimo.chat/docs/cli/using-recipes/#5-conditional-output) postActions: - when_: "{{verbose|false}} == true" call: tool: print args: ["{{output}}"] ### Output Tools Reference [Section titled “Output Tools Reference”](https://askimo.chat/docs/cli/using-recipes/#output-tools-reference) | Tool | Purpose | | --- | --- | | `print` | Display text to stdout | | `writeFile` | Write text to a file | | `commit` | Git commit (no stdout) | * * * 6\. Example Recipes ------------------- [Section titled “6. Example Recipes”](https://askimo.chat/docs/cli/using-recipes/#6-example-recipes) ### Summarize Recipe (prints output) [Section titled “Summarize Recipe (prints output)”](https://askimo.chat/docs/cli/using-recipes/#summarize-recipe-prints-output) name: summarizeversion: 1description: "Summarize the content of a file concisely"allowedTools: - readFile - printvars: file_content: tool: readFile args: ["{{arg1}}"]system: | You are an expert technical writer. Summarize the following file content in a concise and precise way. Output MUST be plain text only.userTemplate: | File path: {{arg1}} Content: ====BEGIN==== {{file_content}} ====END====postActions: - call: tool: print args: ["{{output}}"]defaults: {} **Usage:** askimo -r summarize README.md * The summary will be printed to the terminal. ### Git Commit Recipe (uses output in a tool) [Section titled “Git Commit Recipe (uses output in a tool)”](https://askimo.chat/docs/cli/using-recipes/#git-commit-recipe-uses-output-in-a-tool) name: gitCommitversion: 1description: "Generate a Conventional Commit message from staged changes"allowedTools: - stagedDiff - status - branch - commitvars: diff: tool: stagedDiff args: ["--no-color", "--unified=0"]system: | You are a senior engineer writing Conventional Commit messages.userTemplate: | Generate the commit message in the exact plaintext format described above.postActions: - call: tool: commit args: message: "{{output}}" * The commit message is written to git, not printed to the terminal. ### File Search Recipe (restricted tools) [Section titled “File Search Recipe (restricted tools)”](https://askimo.chat/docs/cli/using-recipes/#file-search-recipe-restricted-tools) name: searchFilesversion: 2description: "Search for files by pattern in a directory"allowedTools: - searchFilesByGlobvars: results: tool: searchFilesByGlob args: ["{{arg1}}", "{{arg2}}"]system: | You are a helpful assistant. List all files in the directory {{arg1}} matching the pattern {{arg2}}.userTemplate: | Directory: {{arg1}} Pattern: {{arg2}} Results: {{results}}postActions: - call: tool: print args: ["{{output}}"] * * * 7\. Best Practices & Tips ------------------------- [Section titled “7. Best Practices & Tips”](https://askimo.chat/docs/cli/using-recipes/#7-best-practices--tips) * The `output` variable always contains the AI’s response. * Use `postActions` to control what happens to `output`. * For user-facing results, use the `print` tool. * For file output, use the `writeFile` tool. * For side effects (like git), use the appropriate tool (e.g., `commit`). * You can chain multiple actions or use conditions for flexible workflows. * Always add the tools you use in `postActions` to `allowedTools`. * * * 8\. Default Bundled Recipes & Further Resources ----------------------------------------------- [Section titled “8. Default Bundled Recipes & Further Resources”](https://askimo.chat/docs/cli/using-recipes/#8-default-bundled-recipes--further-resources) Askimo comes bundled with several default recipes, including `gitcommit` and `summarize`. These are available out-of-the-box in every Askimo distribution. * You can view the default recipe templates at: [src/main/resources/templates](https://github.com/askimo-ai/askimo/tree/main/cli/src/main/resources/templates) * For more advanced and custom examples, see: [samples/recipes](https://github.com/askimo-ai/askimo/tree/main/samples/recipes) * * * --- # Contributing Translations to Askimo | Askimo [Skip to content](https://askimo.chat/docs/contributing/contributing-localization/#_top) Contributing Translations to Askimo =================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Askimo is available in English, Chinese (Simplified & Traditional), Japanese, Korean, French, Spanish, German, Portuguese, and Vietnamese. If you speak another language, your help means a lot. Even fixing a single awkward phrase makes a difference for someone using the app every day. Translations are managed on **Crowdin**. No coding, no pull requests, no local setup required. How to Start ------------ [Section titled “How to Start”](https://askimo.chat/docs/contributing/contributing-localization/#how-to-start) **[→ crowdin.com/project/askimo](https://crowdin.com/project/askimo) ** 1. Create a free Crowdin account (or sign in with GitHub or Google) 2. Select your language from the project page 3. Pick any file and start translating strings in the online editor 4. Your contributions are reviewed and merged into the app periodically That’s it. Crowdin shows translation progress per language and highlights missing or outdated strings so you always know where help is needed most. * * * Tips for Good Translations -------------------------- [Section titled “Tips for Good Translations”](https://askimo.chat/docs/contributing/contributing-localization/#tips-for-good-translations) ### Keep placeholders intact [Section titled “Keep placeholders intact”](https://askimo.chat/docs/contributing/contributing-localization/#keep-placeholders-intact) Some strings contain placeholders like `{0}` or `{1}`. These are filled in by the app at runtime with things like a username, model name, or number. You must keep them in your translation, though you can move them to a different position in the sentence if your language requires it. # Englishchat.provider.model=Provider: {0}, Model: {1} # Japanese (reordered)chat.provider.model=モデル: {1}、プロバイダー: {0} ### Match the tone [Section titled “Match the tone”](https://askimo.chat/docs/contributing/contributing-localization/#match-the-tone) Askimo uses a friendly but professional tone, like a knowledgeable colleague rather than a corporate manual. Avoid overly formal or stiff phrasing where natural language sounds better. ### Short UI strings matter most [Section titled “Short UI strings matter most”](https://askimo.chat/docs/contributing/contributing-localization/#short-ui-strings-matter-most) Buttons, labels, tooltips, and menu items are what users see constantly. If you have limited time, start there. They have the biggest impact on how polished the app feels. ### When you’re unsure, leave a comment [Section titled “When you’re unsure, leave a comment”](https://askimo.chat/docs/contributing/contributing-localization/#when-youre-unsure-leave-a-comment) Crowdin has a built-in comment system on every string. If the source text is ambiguous or you’re not sure about the right term, leave a comment. Other translators and the maintainers can weigh in before anything goes live. * * * Adding a New Language --------------------- [Section titled “Adding a New Language”](https://askimo.chat/docs/contributing/contributing-localization/#adding-a-new-language) If your language isn’t listed on Crowdin yet: 1. Open a [GitHub Discussion](https://github.com/askimo-ai/askimo/discussions) to request it 2. Mention the language name and its code (e.g. `ar` for Arabic, or `ar_SA` for Arabic, Saudi Arabia) 3. Once the language is added to the project, you’ll be notified and can start straight away * * * Checking the Result ------------------- [Section titled “Checking the Result”](https://askimo.chat/docs/contributing/contributing-localization/#checking-the-result) Once your translations are merged, you can see them in the app under **Settings → Application Language**. ![Language Selection Dropdown](https://askimo.chat/_astro/language_selection.SiA-C6Dz_Zpj5MI.webp) ![](https://askimo.chat/docs/contributing/contributing-localization/) Missing translations fall back to English, so nothing will break. If you spot a key name showing up instead of real text, it means a string hasn’t been translated yet. * * * Resources --------- [Section titled “Resources”](https://askimo.chat/docs/contributing/contributing-localization/#resources) * [Crowdin project → askimo](https://crowdin.com/project/askimo) * [ISO 639-1 Language Codes](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) Thank you for helping make Askimo accessible to users around the world. 🌍 --- # How to Contribute | Askimo [Skip to content](https://askimo.chat/docs/contributing/how-to-contribute/#_top) How to Contribute ================= We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Thank you for wanting to help make Askimo better. Contributions come in all shapes and sizes, and you definitely do not need to be a developer to make a real difference. Here are some of the ways you can get involved. * * * Star the Project on GitHub -------------------------- [Section titled “Star the Project on GitHub”](https://askimo.chat/docs/contributing/how-to-contribute/#star-the-project-on-github) This one takes about two seconds and genuinely helps. Stars make the project more visible to other people who might find it useful, and they help us understand how many people care about what we are building. **[Star Askimo on GitHub](https://github.com/askimo-ai/askimo) ** * * * Report a Bug ------------ [Section titled “Report a Bug”](https://askimo.chat/docs/contributing/how-to-contribute/#report-a-bug) If something is not working the way you expect, please let us know. A good bug report is one of the most valuable things you can give to an open source project. When reporting, try to include: * What you were doing when the issue happened * What you expected to happen * What actually happened * Your operating system and Askimo version **If you have a GitHub account:** [Open a bug report on GitHub Issues](https://github.com/askimo-ai/askimo/issues/new) **If you do not have a GitHub account:** You can reach us through the [contact form](https://askimo.chat/contact/) and just describe what went wrong. We read every message. * * * Suggest a Feature or Improvement -------------------------------- [Section titled “Suggest a Feature or Improvement”](https://askimo.chat/docs/contributing/how-to-contribute/#suggest-a-feature-or-improvement) Have an idea for something that would make Askimo more useful? We would love to hear it. **If you have a GitHub account:** [Start a discussion on GitHub](https://github.com/askimo-ai/askimo/discussions) **If you do not have a GitHub account:** Send us a message through the [contact form](https://askimo.chat/contact/) . Just describe what you would like to see and why it would be helpful to you. * * * Report a Documentation Issue ---------------------------- [Section titled “Report a Documentation Issue”](https://askimo.chat/docs/contributing/how-to-contribute/#report-a-documentation-issue) If you find something wrong in the docs, like a typo, an outdated screenshot, or a step that is unclear, please let us know. We want the documentation to be as useful as possible and small issues are easy to miss. **If you have a GitHub account:** [Open an issue on GitHub](https://github.com/askimo-ai/askimo/issues/new) and mention which page the problem is on and what should be changed. **If you do not have a GitHub account:** Use the [contact form](https://askimo.chat/contact/) and describe what you found. Just include the page URL and a short description of the issue. * * * Translate the App ----------------- [Section titled “Translate the App”](https://askimo.chat/docs/contributing/how-to-contribute/#translate-the-app) Askimo is used by people all over the world, and translations help make it accessible to more of them. Translations are managed on Crowdin, so you do not need to touch any code. Just visit the project, pick your language, and start translating strings in the browser. [Help translate Askimo on Crowdin](https://crowdin.com/project/askimo) See the [Translations guide](https://askimo.chat/docs/development/contributing-localization/) for more details on how things are organized. * * * Contribute Code --------------- [Section titled “Contribute Code”](https://askimo.chat/docs/contributing/how-to-contribute/#contribute-code) If you want to dive into the codebase, take a look at the [Development Getting Started guide](https://askimo.chat/docs/development/getting-started/) and the [CONTRIBUTING.md](https://github.com/askimo-ai/askimo/blob/main/CONTRIBUTING.md) file in the repository. Good starting points: * Issues labeled [`good first issue`](https://github.com/askimo-ai/askimo/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) are usually small and well-scoped * Issues labeled [`help wanted`](https://github.com/askimo-ai/askimo/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) are ones where outside input is especially welcome * * * Spread the Word --------------- [Section titled “Spread the Word”](https://askimo.chat/docs/contributing/how-to-contribute/#spread-the-word) If Askimo has been useful to you, telling other people about it is a genuinely helpful contribution. Share it with a friend, mention it in a forum, write a blog post, or just recommend it when someone asks about AI tools. Word of mouth is how small open source projects grow. * * * No contribution is too small. A typo fix, a kind word in a GitHub Discussion, or a star on the repository all add up. We appreciate everything. --- # Updating Askimo App | Askimo [Skip to content](https://askimo.chat/docs/desktop/updating/#_top) Updating Askimo App =================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Askimo releases updates regularly. Updating is a straightforward reinstall and your settings, sessions, and API keys are always preserved. Before You Update ----------------- [Section titled “Before You Update”](https://askimo.chat/docs/desktop/updating/#before-you-update) * **Your data is safe.** Sessions, settings, and API keys are stored in `~/.askimo/personal/` (macOS/Linux) or `%APPDATA%\askimo\` (Windows), completely separate from the app bundle. Reinstalling never touches this folder. * **No uninstall needed.** Installing the new version replaces the old one in place on all platforms. * **Check what changed** in the [GitHub release notes](https://github.com/askimo-ai/askimo/releases) before updating. Choose Your Operating System ---------------------------- [Section titled “Choose Your Operating System”](https://askimo.chat/docs/desktop/updating/#choose-your-operating-system) * [Update on macOS](https://askimo.chat/docs/desktop/updating/macos/) * [Update on Windows](https://askimo.chat/docs/desktop/updating/windows/) * [Update on Linux](https://askimo.chat/docs/desktop/updating/linux/) After Updating -------------- [Section titled “After Updating”](https://askimo.chat/docs/desktop/updating/#after-updating) Confirm the new version is active: 1. Open **Settings** (`Cmd+,` on macOS or `Ctrl+,` on Windows and Linux). 2. Navigate to **About**. 3. Verify the version number matches the [latest release](https://github.com/askimo-ai/askimo/releases/latest) . Troubleshooting (Cross-Platform) -------------------------------- [Section titled “Troubleshooting (Cross-Platform)”](https://askimo.chat/docs/desktop/updating/#troubleshooting-cross-platform) | Symptom | Action | | --- | --- | | App still shows old version after update | Make sure you quit the old app first, then reinstall | | Settings or sessions missing | Check `~/.askimo/personal/` as data is never touched by the installer | | App blocked by OS security after update | Use the OS-specific override (Gatekeeper / SmartScreen / chmod) | | App fails to start | Re-run the installer and check minimum OS requirements | For platform-specific steps see the guides above. Need Help? ---------- [Section titled “Need Help?”](https://askimo.chat/docs/desktop/updating/#need-help) * Browse [all releases and changelogs](https://github.com/askimo-ai/askimo/releases) * Join our [Discord community](https://discord.gg/askimo) * Report issues on [GitHub](https://github.com/askimo-ai/askimo/issues) --- # Update Askimo App on Windows | Askimo [Skip to content](https://askimo.chat/docs/desktop/updating/windows/#_top) Update Askimo App on Windows ============================ We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Before You Start ---------------- [Section titled “Before You Start”](https://askimo.chat/docs/desktop/updating/windows/#before-you-start) * **Quit Askimo** if it is currently running (system tray → right-click → Quit, or close the window). * Your sessions, settings, and API keys in `%APPDATA%\askimo\` are untouched by the update. * Admin rights are required for the MSI installer. Option 1: MSI Installer (Recommended) ------------------------------------- [Section titled “Option 1: MSI Installer (Recommended)”](https://askimo.chat/docs/desktop/updating/windows/#option-1-msi-installer-recommended) 1. Download the latest installer: [Askimo-Desktop-windows-x64.msi](https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-windows-x64.msi) 2. Run the downloaded `.msi` file — it upgrades the existing installation automatically. 3. If Windows SmartScreen shows **“Windows protected your PC”**: 1. Click **More info**. 2. Click **Run anyway**. 4. Follow the setup wizard. 5. Launch Askimo from the Start Menu. After this, Windows remembers your choice and will not warn you again for this version. Option 2: Universal JAR ----------------------- [Section titled “Option 2: Universal JAR”](https://askimo.chat/docs/desktop/updating/windows/#option-2-universal-jar) **Prerequisites:** Java Runtime Environment (JRE) 21 or higher. 1. Download the latest JAR: [askimo-desktop-windows-x64.jar](https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-windows-x64.jar) 2. Replace your existing JAR with the new one. 3. Restart Askimo: java -jar askimo-desktop-windows-x64.jar Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/updating/windows/#troubleshooting) | Issue | Fix | | --- | --- | | SmartScreen blocks installer | Click More info → Run anyway | | Missing DLL error | Re-run installer with admin rights | | App doesn’t launch | Check antivirus quarantine; add an exception for Askimo | | App still shows old version | Quit the old app before running the new installer | Related Guides -------------- [Section titled “Related Guides”](https://askimo.chat/docs/desktop/updating/windows/#related-guides) * [macOS update](https://askimo.chat/docs/desktop/updating/macos/) * [Linux update](https://askimo.chat/docs/desktop/updating/linux/) * [Windows installation (fresh install)](https://askimo.chat/docs/desktop/installation/windows/) --- # xAI (Grok) Setup for Askimo App | Askimo [Skip to content](https://askimo.chat/docs/desktop/providers/xai/#_top) xAI (Grok) Setup for Askimo App =============================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) xAI (Grok) Configuration ------------------------ [Section titled “xAI (Grok) Configuration”](https://askimo.chat/docs/desktop/providers/xai/#xai-grok-configuration) Connect Askimo App to xAI’s Grok models for cutting-edge AI capabilities. Looking for a comparison of Grok GUI clients? See [Best GUI for Grok (X.AI)](https://askimo.chat/app/grok/best-gui-for-grok/) or explore the [Grok provider page](https://askimo.chat/app/grok/) for an overview of Askimo’s Grok integration. ### API Configuration [Section titled “API Configuration”](https://askimo.chat/docs/desktop/providers/xai/#api-configuration) * **API Key**: Your xAI API key (required) * Get your key from [console.x.ai](https://console.x.ai/) * **Default Model**: Choose from: * `grok-2-latest` - Latest Grok model * `grok-2-vision-latest` - Multimodal capabilities * **Timeout**: Request timeout in seconds (default: 60s) ### Setting Up Your API Key [Section titled “Setting Up Your API Key”](https://askimo.chat/docs/desktop/providers/xai/#setting-up-your-api-key) 1. Visit [xAI Console](https://console.x.ai/) 2. Sign in with your account 3. Navigate to API Keys 4. Create a new API key 5. Copy the key 6. Paste it into Askimo’s xAI API Key field 7. Click “Test Connection” to verify ### Accessing Provider Settings [Section titled “Accessing Provider Settings”](https://askimo.chat/docs/desktop/providers/xai/#accessing-provider-settings) 1. Click on the menu bar 2. Select “Settings” 3. Navigate to the “AI Providers” tab 4. Select “xAI (Grok)” from the provider list **Keyboard Shortcut**: `⌘ + ,` (macOS) or `Ctrl + ,` (Windows/Linux) then click “AI Providers” ### Troubleshooting [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/providers/xai/#troubleshooting) **Connection Failed?** * Verify your API key is correct and active * Check your xAI account status * Ensure you have API access enabled * Try increasing the timeout setting **Model Unavailable?** * Some Grok models may require specific access tiers * Check your account permissions * Visit [xAI Console](https://console.x.ai/) for model availability ### See Also [Section titled “See Also”](https://askimo.chat/docs/desktop/providers/xai/#see-also) * [Grok Desktop Client Overview](https://askimo.chat/app/grok/) — Features, screenshots, and use cases for Askimo with Grok * [Best GUI for Grok (X.AI)](https://askimo.chat/app/grok/best-gui-for-grok/) — Side-by-side comparison of Grok GUI clients in 2026 * [AI Plans](https://askimo.chat/docs/desktop/plans/) — Automate multi-step workflows with Grok --- # Install Askimo App on Linux | Askimo [Skip to content](https://askimo.chat/docs/desktop/installation/linux/#_top) Install Askimo App on Linux =========================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) System Requirements ------------------- [Section titled “System Requirements”](https://askimo.chat/docs/desktop/installation/linux/#system-requirements) * 64-bit Linux distribution (Ubuntu 20.04+, Debian 11+, or equivalent) * 200MB free disk space * Internet connection for provider setup **Note:** Java Runtime Environment (JRE) 21 or higher is only required if you choose Option 2 (Universal JAR) Installation Methods -------------------- [Section titled “Installation Methods”](https://askimo.chat/docs/desktop/installation/linux/#installation-methods) ### Option 1: Debian / Ubuntu (.deb) - Recommended [Section titled “Option 1: Debian / Ubuntu (.deb) - Recommended”](https://askimo.chat/docs/desktop/installation/linux/#option-1-debian--ubuntu-deb---recommended) **Choose your architecture:** * **x64 (AMD/Intel):** Most common for desktop/laptop systems wget https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-linux-x64.debsudo dpkg -i Askimo-Desktop-linux-x64.debsudo apt-get install -f # resolve dependencies if needed * **ARM64:** For ARM-based systems (Raspberry Pi 4+, etc.) wget https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-linux-arm64.debsudo dpkg -i Askimo-Desktop-linux-arm64.debsudo apt-get install -f # resolve dependencies if needed ### Option 2: Universal JAR (All Linux Distributions) [Section titled “Option 2: Universal JAR (All Linux Distributions)”](https://askimo.chat/docs/desktop/installation/linux/#option-2-universal-jar-all-linux-distributions) For distributions other than Debian/Ubuntu, or if you prefer to run Askimo App using Java: **Prerequisites:** * Java Runtime Environment (JRE) 21 or higher must be installed * Verify your Java version: java -version * Install Java 21 or higher if needed: * **Ubuntu/Debian:** `sudo apt install openjdk-21-jre` * **Fedora/RHEL:** `sudo dnf install java-21-openjdk` * **Arch:** `sudo pacman -S jdk21-openjdk` * **Other:** Use your distribution’s package manager **Installation Steps:** **Choose your architecture:** * **x64 (AMD/Intel):** Most common for desktop/laptop systems wget https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-linux-x64.jarjava -jar askimo-desktop-linux-x64.jar * **ARM64:** For ARM-based systems (Raspberry Pi 4+, etc.) wget https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-linux-arm64.jarjava -jar askimo-desktop-linux-arm64.jar **Optional: Create an alias for easier access** Add this to your `~/.bashrc` or `~/.zshrc` (replace with your architecture): # For x64:alias askimo-desktop="java -jar /path/to/askimo-desktop-linux-x64.jar" # For ARM64:alias askimo-desktop="java -jar /path/to/askimo-desktop-linux-arm64.jar" Then reload your shell configuration: source ~/.bashrc # or source ~/.zshrc Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/installation/linux/#troubleshooting) | Issue | Fix | | --- | --- | | Missing deps (DEB) | Run `sudo apt-get install -f` | | JAR won’t run | Verify Java version: `java -version` (need 21+) | Related Guides -------------- [Section titled “Related Guides”](https://askimo.chat/docs/desktop/installation/linux/#related-guides) * [macOS installation](https://askimo.chat/docs/desktop/installation/macos/) * [Windows installation](https://askimo.chat/docs/desktop/installation/windows/) --- # Update Askimo App on Linux | Askimo [Skip to content](https://askimo.chat/docs/desktop/updating/linux/#_top) Update Askimo App on Linux ========================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Before You Start ---------------- [Section titled “Before You Start”](https://askimo.chat/docs/desktop/updating/linux/#before-you-start) * Your sessions, settings, and API keys in `~/.askimo/personal/` are untouched by the update. * No uninstall needed — `dpkg -i` upgrades in place. Option 1: Debian / Ubuntu (.deb) — Recommended ---------------------------------------------- [Section titled “Option 1: Debian / Ubuntu (.deb) — Recommended”](https://askimo.chat/docs/desktop/updating/linux/#option-1-debian--ubuntu-deb--recommended) **x64 (AMD/Intel):** wget https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-linux-x64.debsudo dpkg -i Askimo-Desktop-linux-x64.debsudo apt-get install -f # resolve any dependencies if needed **ARM64:** wget https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-linux-arm64.debsudo dpkg -i Askimo-Desktop-linux-arm64.debsudo apt-get install -f Relaunch Askimo from your application launcher or terminal when done. Option 2: Universal JAR (All Linux Distributions) ------------------------------------------------- [Section titled “Option 2: Universal JAR (All Linux Distributions)”](https://askimo.chat/docs/desktop/updating/linux/#option-2-universal-jar-all-linux-distributions) **Prerequisites:** Java Runtime Environment (JRE) 21 or higher. **Choose your architecture:** * **x64:** [askimo-desktop-linux-x64.jar](https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-linux-x64.jar) * **ARM64:** [askimo-desktop-linux-arm64.jar](https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-linux-arm64.jar) **Update steps:** 1. Download the JAR for your architecture. 2. Replace your existing JAR with the new one. 3. Restart Askimo: java -jar askimo-desktop-linux-x64.jar # x64# ORjava -jar askimo-desktop-linux-arm64.jar # ARM64 Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/updating/linux/#troubleshooting) | Issue | Fix | | --- | --- | | Dependency errors after DEB install | Run `sudo apt-get install -f` | | JAR won’t run | Verify Java version: `java -version` (need 21+) | | App still shows old version | Confirm the JAR file was actually replaced | Related Guides -------------- [Section titled “Related Guides”](https://askimo.chat/docs/desktop/updating/linux/#related-guides) * [macOS update](https://askimo.chat/docs/desktop/updating/macos/) * [Windows update](https://askimo.chat/docs/desktop/updating/windows/) * [Linux installation (fresh install)](https://askimo.chat/docs/desktop/installation/linux/) --- # Install Askimo App on Windows | Askimo [Skip to content](https://askimo.chat/docs/desktop/installation/windows/#_top) Install Askimo App on Windows ============================= We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) System Requirements ------------------- [Section titled “System Requirements”](https://askimo.chat/docs/desktop/installation/windows/#system-requirements) * Windows 10 (64-bit) or later * Admin rights for installer (Option 1 only) * 200MB free disk space * Internet connection for provider setup **Note:** Java Runtime Environment (JRE) 21 or higher is only required if you choose Option 2 (Universal JAR) Installation Methods -------------------- [Section titled “Installation Methods”](https://askimo.chat/docs/desktop/installation/windows/#installation-methods) ### Option 1: Installer (Recommended) [Section titled “Option 1: Installer (Recommended)”](https://askimo.chat/docs/desktop/installation/windows/#option-1-installer-recommended) 1. Download the latest `.msi` installer from the [releases page](https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-windows-x64.msi) . 2. Run the installer. 3. Follow the setup wizard. 4. Launch Askimo from the Start Menu. #### If Windows shows “Windows protected your PC” [Section titled “If Windows shows “Windows protected your PC””](https://askimo.chat/docs/desktop/installation/windows/#if-windows-shows-windows-protected-your-pc) Because Askimo is open-source and not code-signed with a commercial certificate, Windows SmartScreen may warn you on first launch. You can allow it: 1. When the SmartScreen dialog appears, click **More info**. 2. You will see the publisher listed as **Unknown publisher** (expected for unsigned apps). 3. Click **Run anyway**. 4. The installer will start normally. 5. Follow the setup wizard. 6. Launch Askimo from the **Start Menu**. After this, Windows will remember your choice and will not warn you again for future launches of the same version. ### Option 2: Universal JAR [Section titled “Option 2: Universal JAR”](https://askimo.chat/docs/desktop/installation/windows/#option-2-universal-jar) If you prefer to run Askimo App using Java, or if the installer doesn’t work for your system: **Prerequisites:** * Java Runtime Environment (JRE) 21 or higher must be installed * Verify your Java version in Command Prompt or PowerShell: java -version * If Java is not installed, download it from [Adoptium](https://adoptium.net/) or [Oracle](https://www.oracle.com/java/technologies/downloads/) **Installation Steps:** 1. Download the latest `askimo-desktop-windows.jar` from the [releases page](https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-windows-x64.jar) . 2. Run Askimo App with: java -jar askimo-desktop-windows-x64.jar **Optional: Create a batch file for easier access** 1. Create a file named `askimo-desktop.bat` with the following content: @echo offjava -jar "C:\path\to\askimo-desktop-windows-x64.jar" 2. Replace `C:\path\to\` with the actual path to your JAR file 3. Double-click the batch file to launch Askimo App SmartScreen / Security Prompt ----------------------------- [Section titled “SmartScreen / Security Prompt”](https://askimo.chat/docs/desktop/installation/windows/#smartscreen--security-prompt) If Windows shows a SmartScreen warning: 1. Click “More info”. 2. Click “Run anyway”. Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/installation/windows/#troubleshooting) | Issue | Fix | | --- | --- | | SmartScreen blocks app | Use More info → Run anyway | | Missing DLL error | Re-run installer with admin rights | | App doesn’t launch | Check antivirus quarantine; add exception | | Flickering or erratic refresh rate with G-Sync / FreeSync | See below | ### Flickering or erratic refresh rate (G-Sync / FreeSync) [Section titled “Flickering or erratic refresh rate (G-Sync / FreeSync)”](https://askimo.chat/docs/desktop/installation/windows/#flickering-or-erratic-refresh-rate-g-sync--freesync) If Askimo causes your monitor’s refresh rate to flicker or behave erratically when the window is in focus, this is a conflict between the hardware-accelerated renderer (Direct3D/OpenGL) and your display’s variable refresh rate (VRR) driver. **Recommended fix — in-app toggle (Askimo 1.4.7+):** 1. Open **Settings → Advanced**. 2. Turn off **Hardware Acceleration**. 3. Restart Askimo. Askimo will automatically switch to software rendering on the next launch, which resolves the VRR conflict without any performance impact for normal use. **Manual workaround (all versions):** If you are on an older version, you can apply the fix manually: 1. Navigate to `%localappdata%\Askimo\app` and open `Askimo.cfg`. 2. Add the following lines to the bottom of the `[JavaOptions]` block: java-options=-Dskiko.renderApi=SOFTWAREjava-options=-Dsun.java2d.d3d=falsejava-options=-Dsun.java2d.opengl=false 3. Save the file and relaunch Askimo. Related Guides -------------- [Section titled “Related Guides”](https://askimo.chat/docs/desktop/installation/windows/#related-guides) * [macOS installation](https://askimo.chat/docs/desktop/installation/macos/) * [Linux installation](https://askimo.chat/docs/desktop/installation/linux/) --- # Docker AI Setup for Askimo App | Askimo [Skip to content](https://askimo.chat/docs/desktop/providers/docker/#_top) Docker AI Setup for Askimo App ============================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Docker AI Configuration ----------------------- [Section titled “Docker AI Configuration”](https://askimo.chat/docs/desktop/providers/docker/#docker-ai-configuration) Connect Askimo App to AI models running in Docker containers for portable and reproducible AI deployments. ### Server Configuration [Section titled “Server Configuration”](https://askimo.chat/docs/desktop/providers/docker/#server-configuration) * **Server URL**: Docker AI container endpoint * Default: `http://localhost:12434` (Docker AI default port) * For remote containers: `http://your-server:12434` * **API Key**: (Optional) If your container requires authentication * **Timeout**: Connection timeout (default: 120s) * **Available Models**: Detected from your running Docker AI containers ### Setting Up Docker AI [Section titled “Setting Up Docker AI”](https://askimo.chat/docs/desktop/providers/docker/#setting-up-docker-ai) 1. Install Docker Desktop from [docker.com](https://www.docker.com/) 2. Enable the OpenAI-compatible API server: docker desktop enable model-runner --tcp 12434 3. Pull an AI model from Docker Hub (it will be automatically served): docker model pull ai/ 4. In Askimo, configure the provider: * **Provider Type**: OpenAI (OpenAI-compatible) * **Base URL**: `http://localhost:12434/v1` * **API Key**: (leave empty - not required for local Docker AI) * **Model**: The model name (e.g., `ai/gemma3:4B-F16`) 5. Click “Test Connection” to verify ### Accessing Provider Settings [Section titled “Accessing Provider Settings”](https://askimo.chat/docs/desktop/providers/docker/#accessing-provider-settings) Since Docker AI models run as OpenAI-compatible servers, you configure them through the OpenAI provider settings: 1. Click on the menu bar 2. Select “Settings” 3. Navigate to the “AI Providers” tab 4. Select **“OpenAI”** from the provider list 5. Configure the settings: * **Base URL**: `http://localhost:12434/v1` (or your custom port) * **API Key**: Leave empty (not required for local Docker AI) * **Model**: The name of your Docker AI model **Keyboard Shortcut**: `⌘ + ,` (macOS) or `Ctrl + ,` (Windows/Linux) then click “AI Providers” ### Docker Hub AI Models [Section titled “Docker Hub AI Models”](https://askimo.chat/docs/desktop/providers/docker/#docker-hub-ai-models) Visit [hub.docker.com/u/ai](https://hub.docker.com/u/ai) to browse available AI models. **Prerequisites:** # Enable OpenAI-compatible API server (one-time setup)docker desktop enable model-runner --tcp 12434 **Example: Running gemma3:4B-F16 model** # Pull the model (it will be automatically served)docker model pull ai/gemma3:4B-F16 # Verify it's runningdocker model ls **Configure in Askimo:** * Provider: OpenAI * Base URL: `http://localhost:12434/v1` * API Key: (leave empty) * Model: `ai/gemma3:4B-F16` ### Model Management [Section titled “Model Management”](https://askimo.chat/docs/desktop/providers/docker/#model-management) **List Pulled Models:** docker model ls **Remove a Model:** docker model rm ### Troubleshooting [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/providers/docker/#troubleshooting) **Cannot Connect?** * Ensure model-runner is enabled: `docker desktop enable model-runner --tcp 12434` * Verify models are pulled: `docker model ls` * Ensure correct base URL: `http://localhost:12434/v1` * Test endpoint: `curl http://localhost:12434/v1/models` **Model Not Available?** * Check if Docker Desktop is running * Verify model-runner is enabled (see above) * Verify the model was pulled successfully: `docker model ls` * Try pulling the model again: `docker model pull ai/` * Restart Docker Desktop if needed **Slow Performance?** * Docker AI will use GPU automatically if available * Use smaller models for faster inference * Close other resource-intensive applications * Check system resources (CPU/RAM usage) **Need Different Port?** If port 12434 is already in use, you can specify a different port when enabling model-runner: docker desktop enable model-runner --tcp 12435 Then update Askimo’s base URL to `http://localhost:12435/v1`. --- # Askimo CLI Installation Guide | Askimo [Skip to content](https://askimo.chat/docs/cli/installation/#_top) Askimo CLI Installation Guide ============================= We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Askimo can be installed in several ways depending on your operating system and preference. Choose the method that works best for your workflow. Installation Options by OS -------------------------- [Section titled “Installation Options by OS”](https://askimo.chat/docs/cli/installation/#installation-options-by-os) | Method | macOS | Linux | Windows | Notes | | --- | --- | --- | --- | --- | | **Homebrew** | ✅ | ✅ | ❌ | Easiest on macOS/Linux | | **Scoop** | ❌ | ❌ | ✅ | Easiest on Windows | | **Release Binaries** | ✅ | ✅ | ✅ | Manual install, works anywhere | | **Docker** | ✅ | ✅ | ✅ | No local install needed | * * * 1\. Homebrew (macOS / Linux) ---------------------------- [Section titled “1. Homebrew (macOS / Linux)”](https://askimo.chat/docs/cli/installation/#1-homebrew-macos--linux) The easiest way if you’re on macOS or Linux. brew tap askimo-ai/askimobrew install askimoaskimo Update later: brew upgrade askimo 2\. Scoop (Windows) ------------------- [Section titled “2. Scoop (Windows)”](https://askimo.chat/docs/cli/installation/#2-scoop-windows) The easiest way if you’re on Windows. Install Scoop if you don’t have it: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned -Forceiwr -useb get.scoop.sh | iex Add the Askimo bucket and install: scoop bucket add askimo https://github.com/haiphucnguyen/scoop-askimoscoop install askimoaskimo Update later: scoop updatescoop update askimo 3\. Download Release Binaries (macOS / Linux / Windows) ------------------------------------------------------- [Section titled “3. Download Release Binaries (macOS / Linux / Windows)”](https://askimo.chat/docs/cli/installation/#3-download-release-binaries-macos--linux--windows) Prebuilt binaries are available on the [Releases](https://github.com/askimo-ai/askimo/releases/latest) page * Download the archive for your OS. * Extract it. * Move the binary into a directory on your $PATH. Example (macOS/Linux): mv askimo /usr/local/bin/chmod +x /usr/local/bin/askimoaskimo On Windows, move askimo.exe into a folder included in your PATH. 4\. Docker (macOS / Linux / Windows) ------------------------------------ [Section titled “4. Docker (macOS / Linux / Windows)”](https://askimo.chat/docs/cli/installation/#4-docker-macos--linux--windows) Run Askimo inside a container without installing anything locally. IMAGE=ghcr.io/askimo-ai/askimo:latest # or specific tag like :v0.1.10docker run --rm -it \ -v "$HOME/.askimo:/home/nonroot/.askimo" \ -v "$PWD:/home/nonroot/work" \ -w /home/nonroot/work \ $IMAGE * ~/.askimo on your machine is mounted for local provider settings/keys. * Your current folder is mounted so Askimo can read/write your project files. Pipe input: cat logs.txt | docker run --rm -i \ -v "$HOME/.askimo:/home/nonroot/.askimo" \ -v "$PWD:/home/nonroot/work" \ -w /home/nonroot/work \ ghcr.io/askimo-ai/askimo:latest "Summarize it" * * * Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/cli/installation/#troubleshooting) * Command not found → Make sure askimo is in your $PATH. * macOS Gatekeeper blocks the binary → Run: xattr -d com.apple.quarantine askimo * Windows Execution Policy issues → Run PowerShell as Administrator and use: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser --- # Web Search | Askimo [Skip to content](https://askimo.chat/docs/desktop/web-search/#_top) Web Search ========== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Askimo includes built-in web search tools so AI can look up current information and read live web pages when your question needs up-to-date context. * * * What Web Search Does -------------------- [Section titled “What Web Search Does”](https://askimo.chat/docs/desktop/web-search/#what-web-search-does) When web search is enabled, Askimo can use two built-in tools during a chat: * **`searchWeb`**: Finds relevant links for your query * **`readWebPage`**: Opens a selected URL and extracts readable content This is useful for recent news, current prices, product comparisons, and any topic that changes over time. * * * Enable Web Search ----------------- [Section titled “Enable Web Search”](https://askimo.chat/docs/desktop/web-search/#enable-web-search) 1. Open **Settings** from the sidebar. 2. Select **Web Search**. 3. Turn on the **Enabled** switch. 4. Pick your preferred backend. 5. Configure API key or endpoint if required. 6. Click **Test** to verify the setup. * * * Choose a Backend ---------------- [Section titled “Choose a Backend”](https://askimo.chat/docs/desktop/web-search/#choose-a-backend) Askimo supports multiple backends: | Backend | API Key Needed | Notes | | --- | --- | --- | | **DuckDuckGo** | No | Zero-config option, good default for quick setup | | **Brave Search** | Yes | Requires a Brave Search API key | | **Tavily** | Yes | Requires a Tavily API key | | **SearxNG** | No (usually) | Use your own SearxNG instance endpoint | ### Backend-specific setup [Section titled “Backend-specific setup”](https://askimo.chat/docs/desktop/web-search/#backend-specific-setup) * **Brave Search**: Add your API key in **Settings → Web Search** * **Tavily**: Add your API key in **Settings → Web Search** * **SearxNG**: Enter your instance endpoint (for example, `https://your-searxng.example/search`) * * * Use Web Search in Chat ---------------------- [Section titled “Use Web Search in Chat”](https://askimo.chat/docs/desktop/web-search/#use-web-search-in-chat) 1. Open or create a chat session. 2. Open the **Tools** picker in the chat composer. 3. Enable the built-in **Web Search** tools for that conversation. 4. Ask your question normally, for example: * “Find the latest Kotlin 2.x release notes and summarize the breaking changes.” * “Compare current pricing for Gemini and Claude Sonnet.” 5. Ask follow-up questions to refine or verify sources. ![Web Search tools selection panel in Askimo chat](https://askimo.chat/_astro/search-tool-selection.B2dPbOxS_Z1320F2.webp) ![](https://askimo.chat/docs/desktop/web-search/) For best results, ask the AI to include links and cite sources in its response. * * * Test and Troubleshooting ------------------------ [Section titled “Test and Troubleshooting”](https://askimo.chat/docs/desktop/web-search/#test-and-troubleshooting) ### Test fails [Section titled “Test fails”](https://askimo.chat/docs/desktop/web-search/#test-fails) * Confirm **Web Search** is enabled in settings. * Re-check API key (Brave/Tavily) for typos or expired credentials. * For SearxNG, verify the endpoint is reachable from your machine. * If you use a proxy, ensure Askimo proxy settings are correct. ### No useful results [Section titled “No useful results”](https://askimo.chat/docs/desktop/web-search/#no-useful-results) * Use a more specific query. * Switch to another backend and test again. * Ask the AI to run web search with narrower keywords and a smaller scope. * * * Related Guides -------------- [Section titled “Related Guides”](https://askimo.chat/docs/desktop/web-search/#related-guides) * **[Askimo App Features & Workflows](https://askimo.chat/docs/desktop/features/) ** * **[Proxy Configuration](https://askimo.chat/docs/desktop/proxy-configuration/) ** * **[MCP Integration](https://askimo.chat/docs/desktop/mcp-integration/) ** --- # LM Studio Setup for Askimo App | Askimo [Skip to content](https://askimo.chat/docs/desktop/providers/lmstudio/#_top) LM Studio Setup for Askimo App ============================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) LM Studio Configuration ----------------------- [Section titled “LM Studio Configuration”](https://askimo.chat/docs/desktop/providers/lmstudio/#lm-studio-configuration) Connect Askimo App to LM Studio for reliable, private local AI model management. ### Server Configuration [Section titled “Server Configuration”](https://askimo.chat/docs/desktop/providers/lmstudio/#server-configuration) * **Server URL**: LM Studio server endpoint * Default: `http://localhost:1234/v1` * For remote servers: `http://your-server:1234/v1` * **Timeout**: Connection timeout (default: 120s) * **Available Models**: Detected from your LM Studio instance ### Setting Up LM Studio [Section titled “Setting Up LM Studio”](https://askimo.chat/docs/desktop/providers/lmstudio/#setting-up-lm-studio) 1. Download and install LM Studio from [lmstudio.ai](https://lmstudio.ai/) 2. Launch LM Studio 3. Download a model from the model browser 4. Start the local server in LM Studio: * Click on the “Local Server” tab * Click “Start Server” 5. In Askimo, the server will be auto-detected 6. Select a model from the dropdown 7. Click “Test Connection” to verify ### Accessing Provider Settings [Section titled “Accessing Provider Settings”](https://askimo.chat/docs/desktop/providers/lmstudio/#accessing-provider-settings) 1. Click on the menu bar 2. Select “Settings” 3. Navigate to the “AI Providers” tab 4. Select “LM Studio” from the provider list **Keyboard Shortcut**: `⌘ + ,` (macOS) or `Ctrl + ,` (Windows/Linux) then click “AI Providers” ### Troubleshooting [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/providers/lmstudio/#troubleshooting) **Cannot Connect?** * Verify LM Studio server is running * Check that port 1234 is not blocked * Ensure correct server URL in settings * Try restarting LM Studio **Model Not Loading?** * Check if model is fully downloaded in LM Studio * Verify sufficient RAM/VRAM available * Try a smaller model first * Check LM Studio logs for errors **Slow Inference?** * Enable GPU acceleration in LM Studio * Use quantized models (4-bit or 8-bit) * Close unnecessary applications * Monitor RAM/VRAM usage ### Advanced Configuration [Section titled “Advanced Configuration”](https://askimo.chat/docs/desktop/providers/lmstudio/#advanced-configuration) **Custom Server Port:** If using a different port in LM Studio, update the Server URL: http://localhost:YOUR_PORT/v1 **Remote LM Studio:** Connect to LM Studio running on another machine: http://REMOTE_IP:1234/v1 --- # Gemini Setup in Askimo Desktop App (API Key, Models, Troubleshooting) | Askimo [Skip to content](https://askimo.chat/docs/desktop/providers/gemini/#_top) Gemini Setup in Askimo Desktop App (API Key, Models, Troubleshooting) ===================================================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Gemini Setup Guide for Askimo Desktop App ----------------------------------------- [Section titled “Gemini Setup Guide for Askimo Desktop App”](https://askimo.chat/docs/desktop/providers/gemini/#gemini-setup-guide-for-askimo-desktop-app) Use this page to configure **Google Gemini** in Askimo quickly and correctly. Looking for a side-by-side product comparison first? See [Best Gemini Desktop App (GUI Comparison)](https://askimo.chat/app/gemini/best-gui-for-gemini/) . ### Why Use Askimo with Gemini? [Section titled “Why Use Askimo with Gemini?”](https://askimo.chat/docs/desktop/providers/gemini/#why-use-askimo-with-gemini) * **Free & Open Source** - No subscription required for the desktop client * **All Gemini Models** - Access all latest Gemini models * **Cross-Platform** - Works on macOS, Windows, and Linux * **Multiple AI Models** - Use Gemini alongside OpenAI, Claude, and Ollama * **Multimodal AI** - Text and image capabilities * **Advanced Features** - Custom directives, RAG, chat search, and themes Setting Up Gemini in Askimo Desktop App --------------------------------------- [Section titled “Setting Up Gemini in Askimo Desktop App”](https://askimo.chat/docs/desktop/providers/gemini/#setting-up-gemini-in-askimo-desktop-app) Connect Askimo App to Google’s Gemini models for multimodal AI capabilities. ### API Configuration [Section titled “API Configuration”](https://askimo.chat/docs/desktop/providers/gemini/#api-configuration) * **API Key**: Your Google AI API key (required) * Get your key from [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) * **Default Model**: Askimo supports all latest Gemini models * Choose from experimental, pro, and flash variants * Models are automatically updated as Google releases new versions * **Region**: Select closest region for better latency * Auto (default), US, Europe, Asia * **Timeout**: Request timeout in seconds (default: 60s) ### Setting Up Your API Key [Section titled “Setting Up Your API Key”](https://askimo.chat/docs/desktop/providers/gemini/#setting-up-your-api-key) 1. Visit [Google AI Studio](https://aistudio.google.com/app/apikey) 2. Sign in with your Google account 3. Click “Create API Key” 4. Copy the generated key 5. Paste it into Askimo’s Gemini API Key field 6. Click “Test Connection” to verify ### Accessing Provider Settings [Section titled “Accessing Provider Settings”](https://askimo.chat/docs/desktop/providers/gemini/#accessing-provider-settings) 1. Click on the menu bar 2. Select “Settings” 3. Navigate to the “AI Providers” tab 4. Select “Google Gemini” from the provider list **Keyboard Shortcut**: `⌘ + ,` (macOS) or `Ctrl + ,` (Windows/Linux) then click “AI Providers” ### Troubleshooting [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/providers/gemini/#troubleshooting) **Connection Failed?** * Verify your API key is valid * Check your Google Cloud project status * Ensure API is enabled in your Google Cloud Console * Try a different region if experiencing latency **Quota Exceeded?** * Gemini free tier has daily quotas * Check your usage at [Google AI Studio](https://aistudio.google.com/) * Consider upgrading to a paid plan for higher limits ### See Also [Section titled “See Also”](https://askimo.chat/docs/desktop/providers/gemini/#see-also) * [Gemini Desktop Client Overview](https://askimo.chat/app/gemini/) — Features and use cases for Askimo with Gemini * [Best GUI for Google Gemini](https://askimo.chat/app/gemini/best-gui-for-gemini/) — Side-by-side comparison of Gemini GUI clients in 2026 * [AI Plans](https://askimo.chat/docs/desktop/plans/) — Automate multi-step workflows with Gemini --- # Askimo App Features & Workflows | Askimo [Skip to content](https://askimo.chat/docs/desktop/features/#_top) Askimo App Features & Workflows =============================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Discover Askimo App’s powerful features that help you chat with AI providers, control AI behavior with custom directives, search conversations, and manage your chat history effectively. Start a Chat ------------ [Section titled “Start a Chat”](https://askimo.chat/docs/desktop/features/#start-a-chat) Begin conversations with any configured AI provider. ![Star a chat](https://askimo.chat/_astro/desktop_start_a_chat.CgMS3NkY_ZjyKl4.webp) ![](https://askimo.chat/docs/desktop/features/) ### Creating a New Chat [Section titled “Creating a New Chat”](https://askimo.chat/docs/desktop/features/#creating-a-new-chat) **Quick Start:** 1. Click the “+” button in the sidebar 2. Select your AI provider (OpenAI, Claude, Gemini, xAI, Ollama) 3. Choose a model (if multiple are available) 4. Start typing your message **Keyboard Shortcut:** * **macOS**: `⌘ + N` * **Windows/Linux**: `Ctrl + N` * * * Search in a Conversation ------------------------ [Section titled “Search in a Conversation”](https://askimo.chat/docs/desktop/features/#search-in-a-conversation) Find specific messages within your current chat conversation quickly and efficiently. ### Using In-Chat Search [Section titled “Using In-Chat Search”](https://askimo.chat/docs/desktop/features/#using-in-chat-search) **Opening Search:** * **macOS**: `⌘ + F` * **Windows/Linux**: `Ctrl + F` * Or click the search icon in the chat header **Search Features:** * **Text Search**: Find any keyword or phrase in the conversation * **Case Sensitive**: Toggle for exact case matching * **Navigate Results**: Jump between matches with next/previous buttons * **Highlight Matches**: All matching text is highlighted in the conversation **Search Navigation:** 1. Open search with `⌘/Ctrl + F` 2. Type your search query 3. Press `Esc` to close search * * * Create Custom Directives ------------------------ [Section titled “Create Custom Directives”](https://askimo.chat/docs/desktop/features/#create-custom-directives) Shape how the AI responds — set its tone, role, and output format once and have every message in the conversation follow those rules automatically. **[→ Full guide: Custom Directives](https://askimo.chat/docs/desktop/directives/) ** * * * Star a Chat Session ------------------- [Section titled “Star a Chat Session”](https://askimo.chat/docs/desktop/features/#star-a-chat-session) Star your favorite chat sessions for quick access. Starred chats stay at the top of your chat list. **How to Star:** * Right-click on a chat in the sidebar * Select “Star Chat” * Starred chats will appear at the top for quick access **How to Unstar:** * Right-click on a starred chat * Select “Unstar Chat” * * * Export a Chat Session --------------------- [Section titled “Export a Chat Session”](https://askimo.chat/docs/desktop/features/#export-a-chat-session) Export your conversations to Markdown format for backup, sharing, or documentation. **How to Export:** 1. Right-click on a chat in the sidebar 2. Select “Export to Markdown” 3. Choose a location and save as a `.md` file The exported file preserves all formatting, code blocks, timestamps, and conversation metadata. * * * Delete a Chat Session --------------------- [Section titled “Delete a Chat Session”](https://askimo.chat/docs/desktop/features/#delete-a-chat-session) Remove conversations you no longer need to keep your workspace organized. ### Deleting a Chat [Section titled “Deleting a Chat”](https://askimo.chat/docs/desktop/features/#deleting-a-chat) **From Sidebar:** 1. Right-click on the chat you want to delete 2. Select “Delete” 3. Confirm deletion * * * Explore More ------------ [Section titled “Explore More”](https://askimo.chat/docs/desktop/features/#explore-more) * **[Full Features Overview](https://askimo.chat/features/) ** - Visual showcase of all Askimo capabilities including RAG, MCP Tools, and AI Plans * **[Custom Directives](https://askimo.chat/docs/desktop/directives/) ** - Personalize AI tone, role, and output format * **[Web Search](https://askimo.chat/docs/desktop/web-search/) ** - Configure web search backends and use live web data in chat * **[RAG: Chat with your documents](https://askimo.chat/docs/desktop/rag/) ** - Build local knowledge bases from your files * **[MCP Tool Integrations](https://askimo.chat/docs/desktop/mcp-integration/) ** - Connect AI to GitHub, databases, and real-world tools * **[AI Plans](https://askimo.chat/docs/desktop/plans/) ** - Automate multi-step AI workflows * **[Download Askimo](https://askimo.chat/download/) ** - Free for macOS, Windows, and Linux --- # AI Providers Setup Guide | Askimo [Skip to content](https://askimo.chat/docs/desktop/ai-providers/#_top) AI Providers Setup Guide ======================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Welcome to Askimo App! This guide will help you configure AI providers to start using the application. Quick Start ----------- [Section titled “Quick Start”](https://askimo.chat/docs/desktop/ai-providers/#quick-start) After installing Askimo App, you’ll need to configure at least one AI provider to start chatting. ### Setup Checklist [Section titled “Setup Checklist”](https://askimo.chat/docs/desktop/ai-providers/#setup-checklist) 1. ✅ Launch Askimo App 2. ✅ Choose an AI provider from the list below 3. ✅ Configure API key or local server 4. ✅ Test connection 5. ✅ Start your first conversation * * * Accessing Provider Settings --------------------------- [Section titled “Accessing Provider Settings”](https://askimo.chat/docs/desktop/ai-providers/#accessing-provider-settings) ![AI Provider Settings](https://askimo.chat/_astro/settings.JySWqUc0_Z2vR0vn.webp) ### From Menu [Section titled “From Menu”](https://askimo.chat/docs/desktop/ai-providers/#from-menu) 1. Click on the menu bar 2. Select “Settings” 3. Navigate to the “AI Providers” tab ### Keyboard Shortcut [Section titled “Keyboard Shortcut”](https://askimo.chat/docs/desktop/ai-providers/#keyboard-shortcut) * **macOS**: `⌘ + ,` then click “AI Providers” * **Windows/Linux**: `Ctrl + ,` then click “AI Providers” * * * Supported AI Providers ---------------------- [Section titled “Supported AI Providers”](https://askimo.chat/docs/desktop/ai-providers/#supported-ai-providers) ![Select AI Provider](https://askimo.chat/_astro/select_provider.Aynu5NOh_RTJL0.webp) Choose from cloud-based or local AI providers based on your needs: OpenAI Configure the latest OpenAI models and other compatible AI models. [Setup OpenAI →](https://askimo.chat/docs/desktop/providers/openai/) Anthropic Claude Set up the latest Claude models for advanced reasoning and long-context tasks. [Setup Claude →](https://askimo.chat/docs/desktop/providers/anthropic/) Google Gemini Configure the latest Google Gemini models including multimodal and reasoning options. [Setup Gemini →](https://askimo.chat/docs/desktop/providers/gemini/) xAI (Grok) Connect to xAI’s Grok models for cutting-edge AI. [Setup xAI →](https://askimo.chat/docs/desktop/providers/xai/) Ollama Run AI models locally with complete privacy and offline access. [Setup Ollama →](https://askimo.chat/docs/desktop/providers/ollama/) LM Studio Professional local AI model management with GPU acceleration. [Setup LM Studio →](https://askimo.chat/docs/desktop/providers/lmstudio/) LocalAI Self-hosted AI server for enterprise and privacy-critical workloads. [Setup LocalAI →](https://askimo.chat/docs/desktop/providers/localai/) Docker AI Containerized AI models from Docker Hub for DevOps workflows. [Setup Docker AI →](https://askimo.chat/docs/desktop/providers/docker/) * * * Cloud vs Local Providers ------------------------ [Section titled “Cloud vs Local Providers”](https://askimo.chat/docs/desktop/ai-providers/#cloud-vs-local-providers) ### Cloud Providers [Section titled “Cloud Providers”](https://askimo.chat/docs/desktop/ai-providers/#cloud-providers) **OpenAI, Claude, Gemini, xAI** ✅ **Pros:** * Latest and most capable models * No local hardware requirements * Regular updates and improvements * Reliable uptime and performance ❌ **Cons:** * Requires internet connection * API costs per usage * Data sent to external servers * Subject to rate limits ### Local Providers [Section titled “Local Providers”](https://askimo.chat/docs/desktop/ai-providers/#local-providers) **Ollama, LM Studio, LocalAI, Docker AI** ✅ **Pros:** * Complete privacy (data stays local) * No API costs * Works offline * Full control over models ❌ **Cons:** * Requires capable hardware * Manual model management * Performance depends on your GPU/CPU * Limited to open-source models * * * Your First Conversation ----------------------- [Section titled “Your First Conversation”](https://askimo.chat/docs/desktop/ai-providers/#your-first-conversation) Once you’ve configured at least one provider, you’re ready to start! Your browser does not support the video tag. ### Starting a Chat [Section titled “Starting a Chat”](https://askimo.chat/docs/desktop/ai-providers/#starting-a-chat) 1. Click “New Chat” or press `⌘/Ctrl + N` 2. Type your first message in the input area 3. Press `Enter` to send --- # OpenAI-Compatible Provider - Connect Any OpenAI-Compatible API to Askimo | Askimo [Skip to content](https://askimo.chat/docs/desktop/providers/openai_compatible/#_top) OpenAI-Compatible Provider - Connect Any OpenAI-Compatible API to Askimo ======================================================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) OpenAI-Compatible Provider -------------------------- [Section titled “OpenAI-Compatible Provider”](https://askimo.chat/docs/desktop/providers/openai_compatible/#openai-compatible-provider) Askimo supports any server that implements the **OpenAI-compatible API**, giving you the flexibility to connect cloud-hosted providers, local inference servers, or self-hosted gateways that expose an OpenAI-style `/v1` endpoint. ### What is an OpenAI-Compatible Server? [Section titled “What is an OpenAI-Compatible Server?”](https://askimo.chat/docs/desktop/providers/openai_compatible/#what-is-an-openai-compatible-server) Many AI tools and services implement the OpenAI REST API format, meaning they accept the same request structure as `api.openai.com/v1`. Examples include: * **Cloud providers** - [OpenRouter](https://openrouter.ai/) , [Together AI](https://www.together.ai/) , [Groq](https://groq.com/) , [Mistral AI](https://mistral.ai/) , [Fireworks AI](https://fireworks.ai/) * **Local inference servers** - [vLLM](https://github.com/vllm-project/vllm) , [llama.cpp](https://github.com/ggerganov/llama.cpp) , [LocalAI](https://localai.io/) * **AI gateways and proxies** - [LiteLLM](https://litellm.ai/) , any custom proxy that forwards requests to an LLM backend ### Why Use the OpenAI-Compatible Provider? [Section titled “Why Use the OpenAI-Compatible Provider?”](https://askimo.chat/docs/desktop/providers/openai_compatible/#why-use-the-openai-compatible-provider) * **Broad compatibility** - Connect any backend that speaks the OpenAI API format, whether cloud or local * **Flexible authentication** - API key required for cloud-hosted endpoints, optional for local servers * **No vendor lock-in** - Switch between providers without changing your Askimo workflow Setting Up an OpenAI-Compatible Provider in Askimo -------------------------------------------------- [Section titled “Setting Up an OpenAI-Compatible Provider in Askimo”](https://askimo.chat/docs/desktop/providers/openai_compatible/#setting-up-an-openai-compatible-provider-in-askimo) ### Required Configuration [Section titled “Required Configuration”](https://askimo.chat/docs/desktop/providers/openai_compatible/#required-configuration) * **Base URL** - The full endpoint URL of your server, including the API version path (e.g. `/v1`) | Server | Base URL | | --- | --- | | OpenRouter | `https://openrouter.ai/api/v1` | | Together AI | `https://api.together.xyz/v1` | | Groq | `https://api.groq.com/openai/v1` | | vLLM (local) | `http://localhost:8000/v1` | | llama.cpp (local) | `http://localhost:8080/v1` | | LiteLLM proxy | `http://localhost:4000/v1` | * **API Key** - Authentication token for your server * Required for cloud-hosted endpoints (e.g. OpenRouter, Together AI, Groq) * Optional for local servers that do not enforce authentication — leave blank if your server does not require it ### Step-by-step Setup [Section titled “Step-by-step Setup”](https://askimo.chat/docs/desktop/providers/openai_compatible/#step-by-step-setup) 1. Start your server if using a local inference server (see examples below), or have your API key ready for cloud providers 2. Select the provider in the footer of the Askimo app, or go to **Settings > AI Providers** 3. Select **OpenAI Compatible** from the provider list 4. Enter the **Base URL** including the API path (e.g. `https://openrouter.ai/api/v1`) 5. Enter your **API key** if required, or leave blank for local servers 6. Askimo will automatically fetch the available models once the connection is established ### Examples by Server [Section titled “Examples by Server”](https://askimo.chat/docs/desktop/providers/openai_compatible/#examples-by-server) #### OpenRouter (cloud) [Section titled “OpenRouter (cloud)”](https://askimo.chat/docs/desktop/providers/openai_compatible/#openrouter-cloud) Sign up at [openrouter.ai](https://openrouter.ai/) and get an API key from [openrouter.ai/keys](https://openrouter.ai/keys) . Base URL in Askimo: `https://openrouter.ai/api/v1` API Key: your OpenRouter API key #### Together AI (cloud) [Section titled “Together AI (cloud)”](https://askimo.chat/docs/desktop/providers/openai_compatible/#together-ai-cloud) Sign up at [together.ai](https://www.together.ai/) and get an API key from your dashboard. Base URL in Askimo: `https://api.together.xyz/v1` API Key: your Together AI API key #### vLLM (local) [Section titled “vLLM (local)”](https://askimo.chat/docs/desktop/providers/openai_compatible/#vllm-local) # Start vLLM with a modelpython -m vllm.entrypoints.openai.api_server \ --model mistralai/Mistral-7B-Instruct-v0.2 \ --port 8000 Base URL in Askimo: `http://localhost:8000/v1` API Key: leave blank #### llama.cpp (local) [Section titled “llama.cpp (local)”](https://askimo.chat/docs/desktop/providers/openai_compatible/#llamacpp-local) # Start llama.cpp server./server -m your-model.gguf --port 8080 Base URL in Askimo: `http://localhost:8080/v1` API Key: leave blank #### LiteLLM proxy (local or cloud) [Section titled “LiteLLM proxy (local or cloud)”](https://askimo.chat/docs/desktop/providers/openai_compatible/#litellm-proxy-local-or-cloud) # Start LiteLLM proxylitellm --model ollama/llama2 --port 4000 Base URL in Askimo: `http://localhost:4000/v1` API Key: leave blank (or set one if you configured auth on your proxy) Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/providers/openai_compatible/#troubleshooting) **Could not connect to the provider?** * For cloud providers, confirm your API key is correct and has sufficient credits * For local servers, make sure the server is running and accessible * Verify the URL includes the full API path (e.g. `/v1`), not just the host and port * Check that no firewall is blocking the port **No models showing after connecting?** * Confirm the server exposes a `GET /v1/models` endpoint * Some minimal servers do not implement `/v1/models` - check your server’s documentation * For llama.cpp, make sure you started the server with `--port` and that it is fully loaded before connecting **SSL / certificate errors?** * For local HTTP servers, ensure the URL starts with `http://` not `https://` * For self-signed HTTPS, configure your system to trust the certificate Learn More ---------- [Section titled “Learn More”](https://askimo.chat/docs/desktop/providers/openai_compatible/#learn-more) * [Ollama provider guide](https://askimo.chat/docs/desktop/providers/ollama/) - For local Ollama models * [LocalAI provider guide](https://askimo.chat/docs/desktop/providers/localai/) - For LocalAI self-hosted models * [LM Studio provider guide](https://askimo.chat/docs/desktop/providers/lmstudio/) - For LM Studio local server --- # MCP (Model Context Protocol) Integration | Askimo [Skip to content](https://askimo.chat/docs/desktop/mcp-integration/#_top) MCP (Model Context Protocol) Integration ======================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) By default, Askimo answers questions using what it already knows from its training. **MCP (Model Context Protocol)** extends that by giving the AI the ability to _act_: to read your files, query a database, call an API, run code, and more, all from within your conversation. Think of MCP servers as plugins that you connect to Askimo. Each server exposes a set of **tools** (actions the AI can perform). Once connected, the AI can choose the right tool at the right moment. For example, it can look up a live database record, fetch a web page, or list files in a folder, without you having to copy and paste anything manually. You set up an **MCP instance** in **Settings → MCP Servers** by telling Askimo how to reach a server: what command to run or what URL to call. Askimo starts or connects to the server on demand and makes its tools available during your conversation. How MCP Works in Askimo ----------------------- [Section titled “How MCP Works in Askimo”](https://askimo.chat/docs/desktop/mcp-integration/#how-mcp-works-in-askimo) graph TD I1[MCP Instance\ne.g. Personal GitHub] I2[MCP Instance\ne.g. Production DB] I3[MCP Instance\ne.g. Local Filesystem] I1 --> S1[MCP Server Process] I2 --> S2[MCP Server Process] I3 --> S3[MCP Server Process] S1 & S2 & S3 -->|tools exposed to AI| AI[Askimo AI] Each **MCP instance** holds a complete set of connection details for one server: the command to run, environment variables, or a URL. Askimo starts or connects to the server when needed and exposes its tools to the AI in your conversation. Adding an MCP Instance ---------------------- [Section titled “Adding an MCP Instance”](https://askimo.chat/docs/desktop/mcp-integration/#adding-an-mcp-instance) MCP instances are managed in **Settings → MCP Servers**. From there you can add, edit, enable/disable, and delete instances that are available across your projects. 1. Click the **Settings** icon in the sidebar (or press `⌘ ,` on macOS / `Ctrl ,` on Windows & Linux). 2. Select **MCP Servers** from the left menu. 3. Click the **Add MCP Server** button. 4. Fill in the instance details in the dialog that appears. 5. Click **Test Connection** to verify the server starts and returns tools. 6. Click **Save** to add the instance. ![The Add MCP Instance dialog showing instance name, description, transport type tabs, configuration fields, and a list of discovered tools after a successful connection test.](https://askimo.chat/_astro/mcp_project_dialog.SdxXi1Mn_ZNlE1P.webp) ![](https://askimo.chat/docs/desktop/mcp-integration/) Instance Configuration ---------------------- [Section titled “Instance Configuration”](https://askimo.chat/docs/desktop/mcp-integration/#instance-configuration) ### Name and Description [Section titled “Name and Description”](https://askimo.chat/docs/desktop/mcp-integration/#name-and-description) | Field | Required | Description | | --- | --- | --- | | **Instance Name** | Yes | A recognisable label for this connection (e.g. `Personal GitHub`, `Production DB`) | | **Description** | No | A short note about what this instance does | ### Transport Type [Section titled “Transport Type”](https://askimo.chat/docs/desktop/mcp-integration/#transport-type) Choose how Askimo connects to the MCP server: * [Stdio](https://askimo.chat/docs/desktop/mcp-integration/#tab-panel-8) * [HTTP](https://askimo.chat/docs/desktop/mcp-integration/#tab-panel-9) Askimo launches a local process and communicates over stdin/stdout. | Field | Description | Example | | --- | --- | --- | | **Command** | The executable to run (can include the full command line) | `npx -y @modelcontextprotocol/server-postgres` | | **Arguments** | Additional arguments passed after the command | `--readonly` | | **Working Directory** | Optional directory the process starts in | `/home/user/projects` | | **Environment Variables** | `KEY=VALUE` pairs (one per line) passed to the server process | `DATABASE_URL=postgresql://localhost/mydb` | Askimo connects to a remote or locally running HTTP MCP endpoint. | Field | Description | Example | | --- | --- | --- | | **URL** | Full URL of the MCP server endpoint | `https://my-mcp-server.example.com/mcp` | | **Headers** | `Header-Name=value` pairs (one per line) | `Authorization=Bearer mytoken` | | **Timeout (ms)** | Request timeout in milliseconds | `60000` | Testing the Connection ---------------------- [Section titled “Testing the Connection”](https://askimo.chat/docs/desktop/mcp-integration/#testing-the-connection) Click **Test Connection** before saving to verify everything is set up correctly. Askimo will: 1. Start the server process (Stdio) or contact the URL (HTTP) using the configuration you entered. 2. Fetch the list of available tools from the server. 3. Display the tools found and show a ✅ success or ❌ failure indicator. You can save the instance even without testing first, but testing is recommended so you know the tools are reachable. Include MCP Tools in Your Conversation -------------------------------------- [Section titled “Include MCP Tools in Your Conversation”](https://askimo.chat/docs/desktop/mcp-integration/#include-mcp-tools-in-your-conversation) Once you have set up MCP instances, you can control which tools are active in any chat conversation using the **Tools** selector in the chat input bar. ![The Tools selector panel in the chat input bar showing MCP instances and built-in Askimo tools, each with a toggle to enable or disable them for the current conversation.](https://askimo.chat/_astro/mcp_selection_dialog.DDK617ql_Zxz8m1.webp) ![](https://askimo.chat/docs/desktop/mcp-integration/) Clicking the **Tools** button opens a panel listing all available tool sources. You can toggle each one on or off for the current conversation: * **MCP tools** (your connected MCP instances) are **enabled by default**. The AI will use them automatically when relevant to your question. * **Built-in Askimo tools** are **disabled by default**. You can turn them on when you want Askimo to use its own internal capabilities alongside your MCP servers. Changes to the tool selection apply to the current conversation only and do not affect your global MCP instance settings. Security: Secret Values ----------------------- [Section titled “Security: Secret Values”](https://askimo.chat/docs/desktop/mcp-integration/#security-secret-values) Askimo automatically detects sensitive field values based on their name. Any environment variable or header whose name contains `key`, `secret`, `token`, `password`, or `credential` is treated as a secret: * Its value is **never written to disk in plain text**. * It is stored in your operating system keychain and retrieved at runtime. This means a `GITHUB_TOKEN` or `DATABASE_PASSWORD` environment variable is handled securely without any extra steps on your part. Managing Existing Instances --------------------------- [Section titled “Managing Existing Instances”](https://askimo.chat/docs/desktop/mcp-integration/#managing-existing-instances) In **Settings → MCP Servers** you can: | Action | How | | --- | --- | | **View available tools** | Click the tools icon on an instance card | | **Enable / disable** | Toggle the instance on or off without deleting it | | **Edit** | Click the edit icon to update the configuration | | **Delete** | Click the delete icon and confirm | Tool Categories --------------- [Section titled “Tool Categories”](https://askimo.chat/docs/desktop/mcp-integration/#tool-categories) Askimo classifies MCP tools into categories that help the AI decide when and how to use them: | Category | Description | | --- | --- | | `DATABASE` | SQL/NoSQL queries and data operations | | `NETWORK` | HTTP requests and API calls | | `FILE_READ` | Reading files and directories | | `FILE_WRITE` | Writing, creating, or deleting files | | `VISUALIZE` | Charts, graphs, and data visualisation | | `EXECUTE` | Running code or shell commands | | `SEARCH` | Full-text and semantic search | | `TRANSFORM` | Data conversion and processing | | `VERSION_CONTROL` | Git and VCS operations | | `COMMUNICATION` | Email, messaging, notifications | | `MONITORING` | Logging and observability | | `OTHER` | Unclassified tools | Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/mcp-integration/#troubleshooting) ### “Failed to connect to MCP server” [Section titled ““Failed to connect to MCP server””](https://askimo.chat/docs/desktop/mcp-integration/#failed-to-connect-to-mcp-server) * Verify that the binary required by the command is installed and on your `PATH` (e.g. run `npx --version` or `uvx --version` in a terminal). * Double-check any environment variable names and values, especially tokens or passwords. * For HTTP servers, confirm the server is running and the URL is reachable. ### Tools list is empty after a successful connection [Section titled “Tools list is empty after a successful connection”](https://askimo.chat/docs/desktop/mcp-integration/#tools-list-is-empty-after-a-successful-connection) * Some MCP servers return an empty tool list if authentication fails silently. Double-check any token or API key values in your environment variables or headers. * Try editing the instance and clicking **Test Connection** again after correcting the values. Security Notes -------------- [Section titled “Security Notes”](https://askimo.chat/docs/desktop/mcp-integration/#security-notes) * **Secret parameters** (environment variables or headers whose names contain `key`, `secret`, `token`, `password`, or `credential`) are stored in your operating system keychain and never written to configuration files. * MCP server processes inherit Askimo’s environment. Avoid granting file-write tools access to sensitive directories. * For HTTP MCP servers, prefer HTTPS endpoints. * * * Learn More ---------- [Section titled “Learn More”](https://askimo.chat/docs/desktop/mcp-integration/#learn-more) * **[MCP Integration Guide (blog)](https://askimo.chat/blog/mcp-integration-askimo-desktop/) ** - Practical walkthrough: connect GitHub, Time Server, and real-world tool examples with screenshots * **[Askimo Features: MCP Tools](https://askimo.chat/features/) ** - Visual overview of what MCP enables in the desktop app --- # Custom Directives - Personalize AI Behavior | Askimo [Skip to content](https://askimo.chat/docs/desktop/directives/#_top) Custom Directives - Personalize AI Behavior =========================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Stop repeating yourself. A directive sets the AI’s tone, role, and rules **once** - and every message in that conversation automatically follows them. Whether you want a brutally concise debugger or a patient language tutor, directives make the AI work the way _you_ think, not the other way around. * * * What Can You Do With a Directive? --------------------------------- [Section titled “What Can You Do With a Directive?”](https://askimo.chat/docs/desktop/directives/#what-can-you-do-with-a-directive) A directive is a short instruction that runs silently before every message you send. Think of it as briefing your AI before the conversation starts. | Without a Directive | With a Directive | | --- | --- | | “Explain closures in JS” → lengthy essay | “Always reply ≤ 5 lines, no fluff” → 4-line answer | | “Help me debug this” → vague suggestions | “You are a senior Go engineer. Flag the root cause first.” → targeted answer | | “Translate to French” → awkward formal tone | “Match the casual, friendly tone of the original” → natural translation | * * * How to Use a Directive ---------------------- [Section titled “How to Use a Directive”](https://askimo.chat/docs/desktop/directives/#how-to-use-a-directive) ![Create a new directive](https://askimo.chat/_astro/desktop_new_directive.DxCXB4xA_1rxtqu.webp) ![](https://askimo.chat/docs/desktop/directives/) 1. Open any chat conversation 2. Click the ✨ directive button in the chat header (top right) 3. Pick a directive from your list - or create a new one 4. The AI immediately applies it for the rest of that session The directive stays active until you change it or set it to **None**. You can switch directives mid-conversation to change the AI’s behaviour on the fly. * * * Creating & Managing Directives ------------------------------ [Section titled “Creating & Managing Directives”](https://askimo.chat/docs/desktop/directives/#creating--managing-directives) ![Manage directives](https://askimo.chat/_astro/desktop_manage_directives.CUIqk0hd_Z1tcCV.webp) ![](https://askimo.chat/docs/desktop/directives/) * **New Directive** - name it, write the instruction, optionally apply it to the current chat immediately * **Manage Directives** - edit or delete existing directives from one place * * * Example Library --------------- [Section titled “Example Library”](https://askimo.chat/docs/desktop/directives/#example-library) Copy any of these as a starting point and tweak to fit your workflow. ### 🐛 Debugging Assistant [Section titled “🐛 Debugging Assistant”](https://askimo.chat/docs/desktop/directives/#-debugging-assistant) You are a patient debugging assistant.- Ask one clarifying question at a time if the problem is unclear- Always identify the root cause before suggesting a fix- Show the corrected code snippet, then explain what was wrong- Keep explanations under 5 lines ### ✍️ Writing Editor [Section titled “✍️ Writing Editor”](https://askimo.chat/docs/desktop/directives/#%EF%B8%8F-writing-editor) You are a copy editor for a tech blog.- Fix grammar and awkward phrasing- Keep the author's voice - don't rewrite, just polish- Flag anything ambiguous with [?] ### 🌍 Language Tutor [Section titled “🌍 Language Tutor”](https://askimo.chat/docs/desktop/directives/#-language-tutor) I am learning Spanish at B1 level.- Always reply in Spanish first, then English in parentheses- Correct my grammar mistakes at the end of each reply- Keep sentences short ### 📊 Data Analyst [Section titled “📊 Data Analyst”](https://askimo.chat/docs/desktop/directives/#-data-analyst) You are a data analyst. For every question:1. State your assumptions2. Show the formula or query3. Give the result4. Flag any data quality concerns ### 📧 Email Drafter [Section titled “📧 Email Drafter”](https://askimo.chat/docs/desktop/directives/#-email-drafter) Draft professional emails only.- Subject line first- Max 3 short paragraphs- End with a clear call to action- Tone: warm but concise ### 🎓 Study Assistant [Section titled “🎓 Study Assistant”](https://askimo.chat/docs/desktop/directives/#-study-assistant) You are a tutor helping me understand new concepts.- Explain things simply, as if I have no background in the topic- Use analogies and real-world examples- After each explanation, ask me one question to check my understanding ### 📝 Meeting Summariser [Section titled “📝 Meeting Summariser”](https://askimo.chat/docs/desktop/directives/#-meeting-summariser) You summarise meetings and discussions.- Extract: key decisions, action items, and open questions- Format output as three labelled sections- Be concise - one line per item- No commentary, just the summary ### 💡 Brainstorming Partner [Section titled “💡 Brainstorming Partner”](https://askimo.chat/docs/desktop/directives/#-brainstorming-partner) You are a creative brainstorming partner.- Generate exactly 5 ideas per prompt, no more- Each idea in one sentence- After the list, pick the most unconventional one and expand on it- Challenge assumptions, don't just agree * * * Tips for Writing Effective Directives ------------------------------------- [Section titled “Tips for Writing Effective Directives”](https://askimo.chat/docs/desktop/directives/#tips-for-writing-effective-directives) * **Lead with the role**: _“You are a …”_ sets context immediately and is the single most effective technique * **Be specific about format**: say _“reply in bullet points, max 5”_ not _“be organised”_ * **Less is more**: 3–5 clear rules outperform a 20-line essay - the AI follows shorter directives more consistently * **Name it clearly**: a directive called _“Debug – Go”_ is far easier to pick from a list than _“My directive 3”_ * **Iterate**: tweak based on actual responses - one small change can make a big difference * **One directive per context**: rather than one giant all-purpose directive, keep separate ones for different tasks (writing, coding, research) and switch as needed * * * Combining Directives With Other Features ---------------------------------------- [Section titled “Combining Directives With Other Features”](https://askimo.chat/docs/desktop/directives/#combining-directives-with-other-features) Directives work alongside Askimo’s other features - they’re not mutually exclusive: * **With RAG**: pair a directive like _“You are a technical writer”_ with a project knowledge base to get answers that are both grounded in your documents and formatted the way you want * **With MCP Tools**: a directive like _“Always confirm before executing any command”_ adds a safety layer on top of tool usage * **With Plans**: directives set the AI’s baseline behaviour; plans define the steps - together they give you full control over both style and workflow * * * Explore More ------------ [Section titled “Explore More”](https://askimo.chat/docs/desktop/directives/#explore-more) * **[RAG: Chat with your documents](https://askimo.chat/docs/desktop/rag/) ** - Ground AI answers in your own files * **[MCP Tool Integrations](https://askimo.chat/docs/desktop/mcp-integration/) ** - Connect AI to external tools and services * **[AI Plans](https://askimo.chat/docs/desktop/plans/) ** - Automate multi-step AI workflows --- # Getting Started with Askimo CLI | Askimo [Skip to content](https://askimo.chat/docs/cli/getting-started/#_top) Getting Started with Askimo CLI =============================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) After installing Askimo, choose a provider and a model, then start chatting. Askimo saves your settings locally, so you won’t need to repeat these steps next time. 👉 If you don’t choose a model, Askimo will use the default for that provider (except Ollama). Quick start (works the same for any provider) --------------------------------------------- [Section titled “Quick start (works the same for any provider)”](https://askimo.chat/docs/cli/getting-started/#quick-start-works-the-same-for-any-provider) askimo> :set-provider askimo> :models # list models available for that provideraskimo> :set-param model # optional if the provider has a defaultaskimo> "Hello! Summarize this text." * * * Using Ollama (local models) --------------------------- [Section titled “Using Ollama (local models)”](https://askimo.chat/docs/cli/getting-started/#using-ollama-local-models) 1. Install Ollama (see [ollama.com](https://ollama.com/) ) 2. Pull a model, for example: ollama pull 3. In Askimo: askimo> :set-provider ollamaaskimo> :modelsaskimo> :set-param model askimo> "Explain Redis caching in simple terms." If `:models` is empty, pull one with `ollama pull ` and try again. * * * Using OpenAI ------------ [Section titled “Using OpenAI”](https://askimo.chat/docs/cli/getting-started/#using-openai) 1. Get an API key → [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys) 2. Configure Askimo and chat: askimo> :set-provider openaiaskimo> :set-param api_key sk-...askimo> :modelsaskimo> "Explain Redis caching in simple terms." * * * Use Gemini (Google) ------------------- [Section titled “Use Gemini (Google)”](https://askimo.chat/docs/cli/getting-started/#use-gemini-google) 1. Get an API key → [https://aistudio.google.com](https://aistudio.google.com/) 2. Configure and chat: askimo> :set-provider geminiaskimo> :set-param api_key askimo> :modelsaskimo> "Give me five CLI productivity tips." * * * Use X AI (Grok) --------------- [Section titled “Use X AI (Grok)”](https://askimo.chat/docs/cli/getting-started/#use-x-ai-grok) 1. Get an API key → [https://x.ai](https://x.ai/) 2. Configure and chat: askimo> :set-provider xaiaskimo> :set-param api_key askimo> :modelsaskimo> :set-param model # optionalaskimo> "What's new in Java 21?" * * * Using Anthropic Claude ---------------------- [Section titled “Using Anthropic Claude”](https://askimo.chat/docs/cli/getting-started/#using-anthropic-claude) 1. Get an API key → [https://console.anthropic.com/](https://console.anthropic.com/) 2. Configure and chat: askimo> :set-provider anthropicaskimo> :set-param api_key askimo> :modelsaskimo> "Analyze this code for potential improvements." * * * Using Docker AI --------------- [Section titled “Using Docker AI”](https://askimo.chat/docs/cli/getting-started/#using-docker-ai) 1. Enable Docker AI model runner: docker desktop enable model-runner --tcp 12434 2. Pull a model: docker model pull 3. Configure Askimo and chat: askimo> :set-provider dockeraskimo> :modelsaskimo> :set-param model askimo> "Explain containerization concepts." 📌 Default endpoint: [http://localhost:12434](http://localhost:12434/) * * * Using LocalAI ------------- [Section titled “Using LocalAI”](https://askimo.chat/docs/cli/getting-started/#using-localai) 1. Install LocalAI (see [localai.io](https://localai.io/) ) 2. Configure and chat: askimo> :set-provider localaiaskimo> :set-param base_url http://localhost:8080 # your LocalAI endpointaskimo> :modelsaskimo> :set-param model askimo> "Help me debug this function." * * * Using LM Studio --------------- [Section titled “Using LM Studio”](https://askimo.chat/docs/cli/getting-started/#using-lm-studio) 1. Install LM Studio (see [lmstudio.ai](https://lmstudio.ai/) ) 2. Start the local server in LM Studio 3. Configure Askimo and chat: askimo> :set-provider lmstudioaskimo> :set-param base_url http://localhost:1234 # default LM Studio portaskimo> :modelsaskimo> :set-param model askimo> "Generate a regex pattern for email validation." * * * Switch any time --------------- [Section titled “Switch any time”](https://askimo.chat/docs/cli/getting-started/#switch-any-time) You can switch providers/models on the fly; Askimo remembers your last choices. askimo> :set-provider ollamaaskimo> :set-param model askimo> :set-provider openai --- # AI Model Configuration | Askimo [Skip to content](https://askimo.chat/docs/desktop/ai-model-configuration/#_top) AI Model Configuration ====================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) When you send a message in Askimo, it might feel like a single AI model is handling everything - but that is not the case. Behind the scenes, **Askimo uses several specialized models simultaneously**, each optimised for a different job. The model you pick in the main chat settings is only one of them. Think of it like a team at a company: there is a senior consultant (your main chat model) who handles the deep thinking, and a set of fast specialists who handle smaller jobs in the background - like filing paperwork, reviewing photos, or searching the knowledge base - without consuming the senior consultant’s time or budget. Askimo ships with sensible defaults for every provider so things work out of the box. But you can override each model independently to match your own priorities - whether that is **lower cost**, **faster responses**, **higher accuracy**, or **complete local privacy**. Why Multiple Models? -------------------- [Section titled “Why Multiple Models?”](https://askimo.chat/docs/desktop/ai-model-configuration/#why-multiple-models) Different tasks call for very different model characteristics: | Model Type | What it does | Why a dedicated model helps | | --- | --- | --- | | **Main Chat Model** | Answers your questions, reasons, writes code | You choose this in the main provider settings | | **Utility Model** | Fast background tasks - generating a chat title, detecting your intent, routing to the right tool | A small, cheap model is 10–100× faster and costs a fraction of the main model | | **Vision Model** | Understands images you attach to a conversation | Must support multimodal input; may differ from the chat model | | **Image Model** | Generates images from text prompts | Completely separate generation pipeline | | **Embedding Model** | Converts text to vectors for semantic search | Powers RAG (Project Knowledge) and MCP tool matching | ### A practical example [Section titled “A practical example”](https://askimo.chat/docs/desktop/ai-model-configuration/#a-practical-example) Imagine you open Askimo, type a question, and attach a screenshot: 1. **Utility model** quickly reads your message and generates a short chat title in the sidebar. 2. **Vision model** analyses the screenshot you attached. 3. **Main chat model** receives both the text and the image analysis, then writes the full response. 4. If you have a project knowledge base open, the **embedding model** silently searches it for relevant context before the main model replies. All of this happens in parallel, so you barely notice - but each step uses the model best suited for that job. ### Overriding the defaults [Section titled “Overriding the defaults”](https://askimo.chat/docs/desktop/ai-model-configuration/#overriding-the-defaults) Askimo’s defaults are chosen to work well for most users, but you may want to change them for reasons like: * **Cost** - swap the utility model to the cheapest tier; it only writes short titles, so quality barely matters * **Speed** - use a smaller, faster model for vision or utility tasks to reduce overall response time * **Accuracy** - use a larger embedding model for more precise RAG results * **Privacy** - point all models to a local Ollama instance so no data leaves your machine * * * Accessing Model Configuration ----------------------------- [Section titled “Accessing Model Configuration”](https://askimo.chat/docs/desktop/ai-model-configuration/#accessing-model-configuration) 1. Open **Settings** (`⌘ ,` on macOS / `Ctrl ,` on Windows/Linux) 2. Go to the **AI Providers** tab 3. Your active provider’s **Model Configuration** card appears below the main provider settings Each field saves automatically when you click away (you’ll see a ✓ checkmark confirm the save). * * * Model Configuration by Provider ------------------------------- [Section titled “Model Configuration by Provider”](https://askimo.chat/docs/desktop/ai-model-configuration/#model-configuration-by-provider) ![The Model Configuration card in Askimo's AI Providers settings, showing editable fields for utility model, vision model, image model, and embedding model for the selected provider.](https://askimo.chat/_astro/customize-embedding-model.DvYy_sly_5zqNI.webp) ![](https://askimo.chat/docs/desktop/ai-model-configuration/) * [OpenAI](https://askimo.chat/docs/desktop/ai-model-configuration/#tab-panel-0) * [Anthropic Claude](https://askimo.chat/docs/desktop/ai-model-configuration/#tab-panel-1) * [Google Gemini](https://askimo.chat/docs/desktop/ai-model-configuration/#tab-panel-2) * [xAI (Grok)](https://askimo.chat/docs/desktop/ai-model-configuration/#tab-panel-3) * [Ollama](https://askimo.chat/docs/desktop/ai-model-configuration/#tab-panel-4) * [LM Studio](https://askimo.chat/docs/desktop/ai-model-configuration/#tab-panel-5) * [LocalAI](https://askimo.chat/docs/desktop/ai-model-configuration/#tab-panel-6) * [Docker AI](https://askimo.chat/docs/desktop/ai-model-configuration/#tab-panel-7) ### OpenAI Model Configuration [Section titled “OpenAI Model Configuration”](https://askimo.chat/docs/desktop/ai-model-configuration/#openai-model-configuration) | Field | Default | Environment Variable | | --- | --- | --- | | Available Models | _(auto-detected)_ | `ASKIMO_OPENAI_MODELS` | | Utility Model | | `ASKIMO_OPENAI_UTILITY_MODEL` | | Utility Timeout | `45s` | `ASKIMO_OPENAI_UTILITY_TIMEOUT` | | Embedding Model | `text-embedding-3-small` | `ASKIMO_OPENAI_EMBEDDING_MODEL` | | Vision Model | | `ASKIMO_OPENAI_VISION_MODEL` | | Image Model | | `ASKIMO_OPENAI_IMAGE_MODEL` | ### Anthropic Claude Model Configuration [Section titled “Anthropic Claude Model Configuration”](https://askimo.chat/docs/desktop/ai-model-configuration/#anthropic-claude-model-configuration) | Field | Default | Environment Variable | | --- | --- | --- | | Available Models | _(auto-detected)_ | `ASKIMO_ANTHROPIC_MODELS` | | Utility Model | `claude-sonnet-4-6` | `ASKIMO_ANTHROPIC_UTILITY_MODEL` | | Utility Timeout | `45s` | `ASKIMO_ANTHROPIC_UTILITY_TIMEOUT` | | Embedding Model | _(none - see note)_ | `ASKIMO_ANTHROPIC_EMBEDDING_MODEL` | | Vision Model | | `ASKIMO_ANTHROPIC_VISION_MODEL` | | Image Model | | `ASKIMO_ANTHROPIC_IMAGE_MODEL` | ### Google Gemini Model Configuration [Section titled “Google Gemini Model Configuration”](https://askimo.chat/docs/desktop/ai-model-configuration/#google-gemini-model-configuration) | Field | Default | Environment Variable | | --- | --- | --- | | Available Models | _(auto-detected)_ | `ASKIMO_GEMINI_MODELS` | | Utility Model | | `ASKIMO_GEMINI_UTILITY_MODEL` | | Utility Timeout | `45s` | `ASKIMO_GEMINI_UTILITY_TIMEOUT` | | Embedding Model | | `ASKIMO_GEMINI_EMBEDDING_MODEL` | | Vision Model | | `ASKIMO_GEMINI_VISION_MODEL` | | Image Model | | `ASKIMO_GEMINI_IMAGE_MODEL` | ### xAI Grok Model Configuration [Section titled “xAI Grok Model Configuration”](https://askimo.chat/docs/desktop/ai-model-configuration/#xai-grok-model-configuration) | Field | Default | Environment Variable | | --- | --- | --- | | Available Models | _(auto-detected)_ | `ASKIMO_XAI_MODELS` | | Utility Model | | `ASKIMO_XAI_UTILITY_MODEL` | | Utility Timeout | `45s` | `ASKIMO_XAI_UTILITY_TIMEOUT` | | Embedding Model | _(none - see note)_ | `ASKIMO_XAI_EMBEDDING_MODEL` | | Vision Model | | `ASKIMO_XAI_VISION_MODEL` | | Image Model | | `ASKIMO_XAI_IMAGE_MODEL` | ### Ollama Model Configuration [Section titled “Ollama Model Configuration”](https://askimo.chat/docs/desktop/ai-model-configuration/#ollama-model-configuration) | Field | Default | Environment Variable | | --- | --- | --- | | Available Models | _(auto-detected)_ | `ASKIMO_OLLAMA_MODELS` | | Utility Model | _(uses selected model)_ | `ASKIMO_OLLAMA_UTILITY_MODEL` | | Utility Timeout | `45s` | `ASKIMO_OLLAMA_UTILITY_TIMEOUT` | | Embedding Model | `nomic-embed-text:latest` | `ASKIMO_OLLAMA_EMBEDDING_MODEL` | | Vision Model | | `ASKIMO_OLLAMA_VISION_MODEL` | | Image Model | | `ASKIMO_OLLAMA_IMAGE_MODEL` | ### LM Studio Model Configuration [Section titled “LM Studio Model Configuration”](https://askimo.chat/docs/desktop/ai-model-configuration/#lm-studio-model-configuration) | Field | Default | Environment Variable | | --- | --- | --- | | Available Models | _(auto-detected)_ | `ASKIMO_LMSTUDIO_MODELS` | | Utility Model | _(uses selected model)_ | `ASKIMO_LMSTUDIO_UTILITY_MODEL` | | Utility Timeout | `45s` | `ASKIMO_LMSTUDIO_UTILITY_TIMEOUT` | | Embedding Model | | `ASKIMO_LMSTUDIO_EMBEDDING_MODEL` | | Vision Model | | `ASKIMO_LMSTUDIO_VISION_MODEL` | | Image Model | | `ASKIMO_LMSTUDIO_IMAGE_MODEL` | ### LocalAI Model Configuration [Section titled “LocalAI Model Configuration”](https://askimo.chat/docs/desktop/ai-model-configuration/#localai-model-configuration) | Field | Default | Environment Variable | | --- | --- | --- | | Available Models | _(auto-detected)_ | `ASKIMO_LOCALAI_MODELS` | | Utility Model | _(uses selected model)_ | `ASKIMO_LOCALAI_UTILITY_MODEL` | | Utility Timeout | `45s` | `ASKIMO_LOCALAI_UTILITY_TIMEOUT` | | Embedding Model | | `ASKIMO_LOCALAI_EMBEDDING_MODEL` | | Vision Model | | `ASKIMO_LOCALAI_VISION_MODEL` | | Image Model | | `ASKIMO_LOCALAI_IMAGE_MODEL` | ### Docker AI Model Configuration [Section titled “Docker AI Model Configuration”](https://askimo.chat/docs/desktop/ai-model-configuration/#docker-ai-model-configuration) | Field | Default | Environment Variable | | --- | --- | --- | | Available Models | _(auto-detected)_ | `ASKIMO_DOCKER_MODELS` | | Utility Model | _(uses selected model)_ | `ASKIMO_DOCKER_UTILITY_MODEL` | | Utility Timeout | `45s` | `ASKIMO_DOCKER_UTILITY_TIMEOUT` | | Embedding Model | `ai/qwen3-embedding:0.6B-F16` | `ASKIMO_DOCKER_EMBEDDING_MODEL` | | Vision Model | | `ASKIMO_DOCKER_VISION_MODEL` | | Image Model | | `ASKIMO_DOCKER_IMAGE_MODEL` | * * * Model Types Explained --------------------- [Section titled “Model Types Explained”](https://askimo.chat/docs/desktop/ai-model-configuration/#model-types-explained) ### Utility Model [Section titled “Utility Model”](https://askimo.chat/docs/desktop/ai-model-configuration/#utility-model) The utility model handles fast, low-cost background tasks that don’t require the full power of your main chat model: * Generating chat titles automatically * Detecting user intent and routing to the correct tool * Summarizing conversation context * Running MCP tool classification **Best practice:** Choose the smallest model that still produces coherent short text. For cloud providers this is typically a “mini” or “flash” tier model. * * * ### Vision Model [Section titled “Vision Model”](https://askimo.chat/docs/desktop/ai-model-configuration/#vision-model) The vision model is called when you attach an image to a conversation. It must support multimodal (image + text) input. * Analyzing screenshots and diagrams * Reading text from images (OCR-style) * Describing uploaded photos * * * ### Image Model [Section titled “Image Model”](https://askimo.chat/docs/desktop/ai-model-configuration/#image-model) The image model is used when Askimo generates images from a text prompt. * Creating illustrations from descriptions * Generating UI mockups or diagrams on request * * * ### Embedding Model [Section titled “Embedding Model”](https://askimo.chat/docs/desktop/ai-model-configuration/#embedding-model) The embedding model converts text into vector representations used for semantic search. It powers: * **RAG (Project Knowledge)** - finding relevant document chunks for your question * **Tool vector search** - matching your intent to the right MCP tool **Embedding support by provider:** | Provider | Embedding Support | Notes | | --- | --- | --- | | OpenAI | ✅ Native | `text-embedding-3-small` (1536-d), `text-embedding-3-large` (3072-d) | | Google Gemini | ✅ Native | `gemini-embedding-001` (3072-d) | | Ollama | ✅ Native | `nomic-embed-text` (768-d), `mxbai-embed-large` (1024-d) | | Docker AI | ✅ Native | `ai/qwen3-embedding:0.6B-F16` (1536-d) | | LM Studio | ✅ Via server | Must load an embedding model in LM Studio | | LocalAI | ✅ Via server | Configure embedding backend in LocalAI | | Anthropic Claude | ❌ Not supported | Use another provider for embeddings | | xAI (Grok) | ❌ Not supported | Use another provider for embeddings | * * * Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/ai-model-configuration/#troubleshooting) **“Embedding dimension does not match store dimension”** You changed the embedding model after a RAG index was already built. The old index was created with a different vector size. Rebuild the index: 1. Go to **Settings → RAG** 2. Select the affected project 3. Click **Rebuild Index** **Utility tasks are slow** Your utility model may be too large. Switch to a smaller, faster model (e.g., `gemini-2.5-flash-lite`, `gpt-4o-mini`, `claude-haiku-3-5`, or a sub-1B local model). **Vision model returns an error for image attachments** The configured vision model does not support multimodal input. Check the provider’s documentation and update the vision model to one that accepts images. **Image generation is not available** Image generation requires provider-side support. Verify that your provider account has access to image generation endpoints and that the image model name is correct. --- # Mermaid Diagrams in Askimo | Askimo [Skip to content](https://askimo.chat/docs/desktop/mermaid-diagrams/#_top) Mermaid Diagrams in Askimo ========================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Mermaid Diagrams in Askimo ========================== [Section titled “Mermaid Diagrams in Askimo”](https://askimo.chat/docs/desktop/mermaid-diagrams/#mermaid-diagrams-in-askimo) Askimo supports rendering [Mermaid](https://mermaid.js.org/) diagrams directly in chat responses. Mermaid is a powerful diagramming and charting tool that uses simple text syntax to create various types of diagrams. What is Mermaid? ---------------- [Section titled “What is Mermaid?”](https://askimo.chat/docs/desktop/mermaid-diagrams/#what-is-mermaid) Mermaid allows you to create diagrams and visualizations using text and code. It supports many diagram types including: * **Flowcharts** - Process flows and decision trees * **Sequence Diagrams** - System interactions and workflows * **Class Diagrams** - Object-oriented design structures * **State Diagrams** - State machines and transitions * **ER Diagrams** - Database entity relationships * **Gantt Charts** - Project timelines and schedules * **Pie Charts** - Data proportions * **And many more!** ![Example of Mermaid line chart rendered in Askimo desktop application showing data visualization](https://askimo.chat/_astro/mermaid-diagram-linechart.B9KCANDi_1UXrRY.webp) ![](https://askimo.chat/docs/desktop/mermaid-diagrams/) How Askimo Renders Mermaid Diagrams ----------------------------------- [Section titled “How Askimo Renders Mermaid Diagrams”](https://askimo.chat/docs/desktop/mermaid-diagrams/#how-askimo-renders-mermaid-diagrams) Askimo renders Mermaid diagrams **locally on your machine** to protect your privacy. When an AI response includes a Mermaid diagram: 1. **With Mermaid CLI installed**: The diagram is rendered as a beautiful, interactive image 2. **Without Mermaid CLI**: The raw Mermaid syntax text is displayed (you can still copy it to use elsewhere) Prerequisites ------------- [Section titled “Prerequisites”](https://askimo.chat/docs/desktop/mermaid-diagrams/#prerequisites) To render Mermaid diagrams in Askimo, you need: 1. **Node.js** - JavaScript runtime 2. **Mermaid CLI** - Command-line tool for rendering diagrams Installation Guide ------------------ [Section titled “Installation Guide”](https://askimo.chat/docs/desktop/mermaid-diagrams/#installation-guide) ### Step 1: Check if Node.js is Already Installed [Section titled “Step 1: Check if Node.js is Already Installed”](https://askimo.chat/docs/desktop/mermaid-diagrams/#step-1-check-if-nodejs-is-already-installed) Open your terminal and run: node --version If you see a version number (e.g., `v20.11.0`), Node.js is already installed. **Skip to Step 3**. If you see an error like `command not found`, proceed to Step 2. ### Step 2: Install Node.js [Section titled “Step 2: Install Node.js”](https://askimo.chat/docs/desktop/mermaid-diagrams/#step-2-install-nodejs) #### macOS [Section titled “macOS”](https://askimo.chat/docs/desktop/mermaid-diagrams/#macos) **Option 1: Using Homebrew (Recommended)** # Install Homebrew if you don't have it/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Install Node.jsbrew install node **Option 2: Download Installer** 1. Visit [https://nodejs.org/](https://nodejs.org/) 2. Download the LTS (Long Term Support) version 3. Run the installer and follow the prompts #### Windows [Section titled “Windows”](https://askimo.chat/docs/desktop/mermaid-diagrams/#windows) **Option 1: Download Installer (Recommended)** 1. Visit [https://nodejs.org/](https://nodejs.org/) 2. Download the LTS (Long Term Support) version for Windows 3. Run the `.msi` installer 4. Follow the installation wizard (accept defaults) **Option 2: Using Chocolatey** # Run PowerShell as Administratorchoco install nodejs #### Linux [Section titled “Linux”](https://askimo.chat/docs/desktop/mermaid-diagrams/#linux) **Ubuntu/Debian:** # Using NodeSource repository (recommended for latest version)curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -sudo apt-get install -y nodejs **Fedora/RHEL/CentOS:** # Using NodeSource repositorycurl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -sudo dnf install -y nodejs **Arch Linux:** sudo pacman -S nodejs npm ### Step 3: Verify Node.js Installation [Section titled “Step 3: Verify Node.js Installation”](https://askimo.chat/docs/desktop/mermaid-diagrams/#step-3-verify-nodejs-installation) After installation, verify Node.js and npm are installed: node --versionnpm --version You should see version numbers for both commands. ### Step 4: Install Mermaid CLI [Section titled “Step 4: Install Mermaid CLI”](https://askimo.chat/docs/desktop/mermaid-diagrams/#step-4-install-mermaid-cli) Once Node.js is installed, install Mermaid CLI globally: npm install -g @mermaid-js/mermaid-cli **Note for macOS/Linux users:** If you get a permission error, you may need to use `sudo`: sudo npm install -g @mermaid-js/mermaid-cli ### Step 5: Verify Mermaid CLI Installation [Section titled “Step 5: Verify Mermaid CLI Installation”](https://askimo.chat/docs/desktop/mermaid-diagrams/#step-5-verify-mermaid-cli-installation) Check that Mermaid CLI is installed correctly: npx @mermaid-js/mermaid-cli --version You should see the Mermaid CLI version number (e.g., `10.6.1`). ### Step 6: Restart Askimo [Section titled “Step 6: Restart Askimo”](https://askimo.chat/docs/desktop/mermaid-diagrams/#step-6-restart-askimo) After installing Node.js and Mermaid CLI: 1. **Completely quit** Askimo (not just close the window) 2. **Restart** Askimo 3. Mermaid diagrams should now render automatically! Testing Mermaid Rendering ------------------------- [Section titled “Testing Mermaid Rendering”](https://askimo.chat/docs/desktop/mermaid-diagrams/#testing-mermaid-rendering) To test if Mermaid diagrams are working in Askimo, try asking the AI: Can you create a simple flowchart showing how to make coffee? Or: Create an ER diagram for a simple blog database with users, posts, and comments If everything is set up correctly, you should see a beautifully rendered diagram instead of raw text. Example Mermaid Diagrams ------------------------ [Section titled “Example Mermaid Diagrams”](https://askimo.chat/docs/desktop/mermaid-diagrams/#example-mermaid-diagrams) ### Flowchart Example [Section titled “Flowchart Example”](https://askimo.chat/docs/desktop/mermaid-diagrams/#flowchart-example) Ask the AI to create diagrams like this: **Prompt:** “Create a flowchart for a login process” flowchart TD Start([Start]) --> Input[Enter credentials] Input --> Validate{Valid credentials?} Validate -->|Yes| Success[Login successful] Validate -->|No| Retry{Retry < 3?} Retry -->|Yes| Input Retry -->|No| Lock[Account locked] Success --> End([End]) Lock --> End ### Sequence Diagram Example [Section titled “Sequence Diagram Example”](https://askimo.chat/docs/desktop/mermaid-diagrams/#sequence-diagram-example) **Prompt:** “Create a sequence diagram for a REST API call” sequenceDiagram participant User participant Browser participant API participant Database User->>Browser: Click button Browser->>API: POST /api/data API->>Database: Query data Database-->>API: Return results API-->>Browser: JSON response Browser-->>User: Display results ### ER Diagram Example [Section titled “ER Diagram Example”](https://askimo.chat/docs/desktop/mermaid-diagrams/#er-diagram-example) **Prompt:** “Create an ER diagram for an e-commerce database” erDiagram Customer ||--o{ Order : places Order ||--o{ OrderItem : contains Product ||--o{ OrderItem : "ordered in" Customer { int id PK string name string email } Order { int id PK date order_date int customer_id FK } Product { int id PK string name decimal price } OrderItem { int id PK int order_id FK int product_id FK int quantity } Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/mermaid-diagrams/#troubleshooting) ### Diagrams Not Rendering [Section titled “Diagrams Not Rendering”](https://askimo.chat/docs/desktop/mermaid-diagrams/#diagrams-not-rendering) If diagrams appear as text instead of images: 1. **Check Node.js installation:** node --version 2. **Check Mermaid CLI installation:** npx @mermaid-js/mermaid-cli --version 3. **Restart Askimo** completely (quit and reopen) 4. **Check PATH environment variable:** * On macOS/Linux: Ensure `/usr/local/bin` is in your PATH * On Windows: Ensure npm global bin directory is in your PATH ### Permission Errors on macOS/Linux [Section titled “Permission Errors on macOS/Linux”](https://askimo.chat/docs/desktop/mermaid-diagrams/#permission-errors-on-macoslinux) If you get `EACCES` permission errors when installing Mermaid CLI: **Option 1: Use sudo (Quick fix)** sudo npm install -g @mermaid-js/mermaid-cli **Option 2: Fix npm permissions (Better long-term solution)** # Create a directory for global installationsmkdir ~/.npm-global # Configure npm to use the new directorynpm config set prefix '~/.npm-global' # Add to your PATH (add this line to ~/.bashrc or ~/.zshrc)export PATH=~/.npm-global/bin:$PATH # Reload your shell configurationsource ~/.bashrc # or source ~/.zshrc # Now install without sudonpm install -g @mermaid-js/mermaid-cli ### Mermaid CLI Not Found After Installation [Section titled “Mermaid CLI Not Found After Installation”](https://askimo.chat/docs/desktop/mermaid-diagrams/#mermaid-cli-not-found-after-installation) If the installation succeeded but Askimo can’t find the CLI: 1. **Find where npm installs global packages:** npm config get prefix 2. **Ensure that directory’s `bin` folder is in your PATH** 3. **Restart your terminal and Askimo** ### Still Having Issues? [Section titled “Still Having Issues?”](https://askimo.chat/docs/desktop/mermaid-diagrams/#still-having-issues) If you’re still experiencing problems: 1. Check the Askimo logs (Settings → Advanced → View Logs) 2. Look for error messages related to “Mermaid” or “Node.js” 3. Report the issue on [Askimo’s GitHub repository](https://github.com/askimo-ai/askimo/issues) Privacy & Security ------------------ [Section titled “Privacy & Security”](https://askimo.chat/docs/desktop/mermaid-diagrams/#privacy--security) Askimo renders Mermaid diagrams **locally on your computer** using the Mermaid CLI. This means: * ✅ **Your diagrams never leave your machine** * ✅ **No external services are used** * ✅ **Complete privacy and security** * ✅ **Works offline** (after installation) This is different from many other tools that render diagrams on remote servers. Advanced Usage -------------- [Section titled “Advanced Usage”](https://askimo.chat/docs/desktop/mermaid-diagrams/#advanced-usage) ### Customizing Diagram Themes [Section titled “Customizing Diagram Themes”](https://askimo.chat/docs/desktop/mermaid-diagrams/#customizing-diagram-themes) Mermaid diagrams in Askimo automatically adapt to your theme (light/dark mode). The AI can also specify custom themes in the diagram syntax. ### Copying Diagrams [Section titled “Copying Diagrams”](https://askimo.chat/docs/desktop/mermaid-diagrams/#copying-diagrams) Even if you don’t have Mermaid CLI installed, you can: 1. **Copy the raw Mermaid syntax** from the chat 2. Paste it into online Mermaid editors like [Mermaid Live Editor](https://mermaid.live/) 3. Export as image or SVG ### Asking for Specific Diagram Types [Section titled “Asking for Specific Diagram Types”](https://askimo.chat/docs/desktop/mermaid-diagrams/#asking-for-specific-diagram-types) Be specific in your prompts to get the diagram type you want: * “Create a **flowchart** showing…” * “Make a **sequence diagram** for…” * “Draw an **ER diagram** representing…” * “Generate a **Gantt chart** for…” * “Create a **class diagram** with…” Learn More About Mermaid ------------------------ [Section titled “Learn More About Mermaid”](https://askimo.chat/docs/desktop/mermaid-diagrams/#learn-more-about-mermaid) * [Official Mermaid Documentation](https://mermaid.js.org/) * [Mermaid Live Editor](https://mermaid.live/) - Interactive online editor * [Mermaid Cheat Sheet](https://mermaid.js.org/intro/syntax-reference.html) Summary ------- [Section titled “Summary”](https://askimo.chat/docs/desktop/mermaid-diagrams/#summary) 1. Install Node.js from [nodejs.org](https://nodejs.org/) 2. Install Mermaid CLI: `npm install -g @mermaid-js/mermaid-cli` 3. Restart Askimo 4. Ask AI to create diagrams and enjoy beautiful visualizations! For questions or issues, visit the [GitHub repository](https://github.com/askimo-ai/askimo) . --- # Ollama Desktop App - Best Free Ollama Client for Mac, Windows & Linux | Askimo [Skip to content](https://askimo.chat/docs/desktop/providers/ollama/#_top) Ollama Desktop App - Best Free Ollama Client for Mac, Windows & Linux ===================================================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Ollama Desktop App - Askimo Ollama Client ----------------------------------------- [Section titled “Ollama Desktop App - Askimo Ollama Client”](https://askimo.chat/docs/desktop/providers/ollama/#ollama-desktop-app---askimo-ollama-client) Looking for the best **Ollama desktop app**? Askimo is a free, feature-rich **Ollama client** that provides a powerful GUI for managing your local AI models on Mac, Windows, and Linux. Unlike the command-line only approach, Askimo gives you a beautiful **Ollama desktop client** with advanced features for complete privacy and offline AI. ### Why Choose Askimo as Your Ollama Desktop App? [Section titled “Why Choose Askimo as Your Ollama Desktop App?”](https://askimo.chat/docs/desktop/providers/ollama/#why-choose-askimo-as-your-ollama-desktop-app) * **Best Ollama GUI** - Beautiful interface, no command line required * **100% Private** - All AI runs locally on your machine * **Cross-Platform** - Works on macOS, Windows, and Linux * **Multiple AI Models** - Use Ollama alongside OpenAI, Claude, and more * **Advanced Features** - Custom directives, RAG, chat search, and themes * **Offline Capable** - Run AI models without internet connection Setting Up Ollama in Askimo Desktop App --------------------------------------- [Section titled “Setting Up Ollama in Askimo Desktop App”](https://askimo.chat/docs/desktop/providers/ollama/#setting-up-ollama-in-askimo-desktop-app) Run AI models locally on your machine with Ollama for complete privacy and offline capabilities. ### Server Configuration [Section titled “Server Configuration”](https://askimo.chat/docs/desktop/providers/ollama/#server-configuration) * **Server URL**: Ollama server endpoint * Default: `http://localhost:11434` * For remote servers: `http://your-server:11434` * **Timeout**: Connection timeout (default: 120s) * **Auto-pull Models**: Automatically download models when selected * **Available Models**: Detected automatically from your Ollama installation ### Setting Up Ollama [Section titled “Setting Up Ollama”](https://askimo.chat/docs/desktop/providers/ollama/#setting-up-ollama) 1. Install Ollama from [ollama.ai](https://ollama.ai/) 2. Start the Ollama service 3. Pull a model: `ollama pull llama2` 4. Askimo will automatically detect your local Ollama server 5. Select a model from the dropdown 6. Click “Test Connection” to verify ### Installing Models [Section titled “Installing Models”](https://askimo.chat/docs/desktop/providers/ollama/#installing-models) Popular models you can use with Ollama: * **llama2** - Meta’s Llama 2 model * **mistral** - Mistral (fast, efficient) * **codellama** - Code-specialized Llama * **phi** - Microsoft’s Phi model * **gemma** - Google’s Gemma model * **qwen** - Alibaba’s Qwen model Install any model via terminal: ollama pull mistral List all available models: ollama list ### Accessing Provider Settings [Section titled “Accessing Provider Settings”](https://askimo.chat/docs/desktop/providers/ollama/#accessing-provider-settings) 1. Click on the menu bar 2. Select “Settings” 3. Navigate to the “AI Providers” tab 4. Select “Ollama” from the provider list **Keyboard Shortcut**: `⌘ + ,` (macOS) or `Ctrl + ,` (Windows/Linux) then click “AI Providers” ### Troubleshooting [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/providers/ollama/#troubleshooting) **Cannot Connect to Ollama?** * Ensure Ollama service is running * Check if port 11434 is accessible * Verify firewall settings * Try restarting the Ollama service **Model Not Showing?** * Pull the model first: `ollama pull ` * Refresh the model list in Askimo * Check Ollama logs: `ollama logs` **Slow Performance?** * Use smaller models (e.g., `phi`, `gemma:2b`) * Close other resource-intensive applications * Consider using a GPU-accelerated setup * Check CPU/GPU usage during inference ### Remote Ollama Server [Section titled “Remote Ollama Server”](https://askimo.chat/docs/desktop/providers/ollama/#remote-ollama-server) You can connect to a remote Ollama server: 1. Start Ollama on the remote server with network access: OLLAMA_HOST=0.0.0.0:11434 ollama serve 2. In Askimo, set the Server URL to: http://your-server-ip:11434 * * * Learn More ---------- [Section titled “Learn More”](https://askimo.chat/docs/desktop/providers/ollama/#learn-more) * **[Askimo with Ollama desktop app](https://askimo.chat/app/ollama/) ** - Why Askimo is the best GUI for Ollama * **[Best GUI for Ollama in 2026](https://askimo.chat/app/ollama/best-gui-for-ollama/) ** - Side-by-side comparison of the top Ollama GUI clients * **[Chat with your documents using Ollama & RAG](https://askimo.chat/blog/ollama-rag-chat-with-documents-local-ai/) ** - Full guide to RAG with local models * **[ChatGPT vs Claude vs Gemini vs Ollama](https://askimo.chat/blog/benefits-multi-ai-providers/) ** - How to use Ollama alongside cloud providers for cost and privacy benefits --- # Plans - AI-Powered Multi-Step Workflows | Askimo [Skip to content](https://askimo.chat/docs/desktop/plans/#_top) Plans - AI-Powered Multi-Step Workflows ======================================= We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) **Plans** are multi-step AI workflows that break complex tasks into a sequence of focused prompts, each building on the last. Instead of cramming everything into a single message and hoping the AI holds it all together, a Plan divides the work into discrete, purposeful steps that run automatically in order (or in parallel), passing results forward as context. This matters because many real-world tasks genuinely cannot be solved well in a single step. Effective reasoning often requires _stages_: gather information before drawing conclusions, outline before drafting, critique before finalising. A single prompt collapses all of that into one shot and the output quality suffers. Multi-step workflows mirror how experts actually think: research first, then analyse, then decide, then write. Plans also enable **decision-making that spans multiple concerns**. A job application plan, for instance, needs to understand the role, match it against a CV, and only then write a tailored cover letter. These are three distinct reasoning tasks where each step genuinely depends on the previous one. Doing all three at once produces generic output; doing them in sequence produces something precise and considered. Use Plans for anything that benefits from structured, multi-stage reasoning: research reports, blog posts, competitor analysis, job applications, meeting notes, and more. How Plans Work -------------- [Section titled “How Plans Work”](https://askimo.chat/docs/desktop/plans/#how-plans-work) A plan is made up of three parts: **inputs**, **steps**, and an optional **workflow**. **Inputs** are the values you provide before running a plan - things like a topic, a tone, or a URL. They are referenced inside step prompts using `{{key}}` placeholders and stay constant throughout the run. **Steps** are the core of a plan. Each step is an independent prompt sent to the AI with its own goal. Steps run in a defined order and each one can reference the outputs of any earlier step, also via `{{stepId}}` placeholders. This is what creates the chain: the result of one step becomes the raw material for the next. **Ask steps** are a special kind of step that pauses the plan mid-run and asks you a question. Instead of declaring everything up front in the input form, ask steps let the plan gather information dynamically — for example, asking a clarifying question after an initial research step has run. Your answer is injected into scope just like any other input, so later steps can reference it with `{{stepId}}`. **Workflow** controls the execution order. By default, steps run sequentially from top to bottom. For more advanced scenarios, you can define a workflow block to run steps in parallel or add conditional branching based on input values. When a plan runs, Askimo executes each step in order, collects the outputs, and presents the final step’s result. No manual copy-pasting between prompts is needed. flowchart TD I([User provides inputs]) --> S1[Step 1] S1 -->|output passed automatically| A1{Ask Step\npauses for input} A1 -->|user answer stored in scope| S2[Step 2] S2 -->|output passed automatically| S3[Step 3] S3 --> R([Final result shown in Plans view]) I -.->|inputs available to all steps| S2 I -.->|inputs available to all steps| S3 Running a Plan -------------- [Section titled “Running a Plan”](https://askimo.chat/docs/desktop/plans/#running-a-plan) ### Finding the Plans View [Section titled “Finding the Plans View”](https://askimo.chat/docs/desktop/plans/#finding-the-plans-view) Plans live in the **Plans** section of the main navigation sidebar. Click **Plans** to open the gallery. ### Selecting and Running a Plan [Section titled “Selecting and Running a Plan”](https://askimo.chat/docs/desktop/plans/#selecting-and-running-a-plan) 1. Open the **Plans** view from the sidebar. 2. Browse the gallery and click on a plan card to open it. 3. The detail view shows the plan’s description, step count, and input fields. 4. Fill in all **required** inputs (marked with `*`). Optional fields can be left blank. 5. Click **Run Plan**. The plan executes each step sequentially. You can watch progress as each step completes - a step indicator shows which step is currently running and how long it has taken. If the plan contains **ask steps**, execution pauses at each one and an inline question panel appears directly below the step progress. Type your answer and press **Enter** (or click the send button) to resume. If you have nothing to add, click **Skip** to continue with a blank answer. ![Askimo Desktop Plans view showing a running plan with step progress indicators and the final result in the output panel.](https://askimo.chat/_astro/plan_run.BGxjCHlz_Z11pUy3.webp) ![](https://askimo.chat/docs/desktop/plans/) ### Following Up on a Result [Section titled “Following Up on a Result”](https://askimo.chat/docs/desktop/plans/#following-up-on-a-result) Once a plan finishes you can refine or extend the result without re-running the full workflow: 1. Read the result in the output panel. 2. Type a follow-up instruction in the **Follow-up** text field at the bottom of the result. 3. Press **Enter** (or click the send button) to submit. The follow-up sends the full prior result as context along with your new instruction. The result is updated in place. You can follow up as many times as you like. **Example follow-ups:** * _“Make the executive summary shorter”_ * _“Translate the output to French”_ * _“Add a section on risks and mitigation”_ * _“Make the tone more formal”_ ### Run History [Section titled “Run History”](https://askimo.chat/docs/desktop/plans/#run-history) Every plan run is saved automatically. Click the **History** icon (or expand the history panel) to see previous runs for the same plan. You can: * **View** any past result. * **Restore inputs** from a past run to re-run with the same values. * **Delete** individual runs. Exporting Results ----------------- [Section titled “Exporting Results”](https://askimo.chat/docs/desktop/plans/#exporting-results) The plan result can be exported in multiple formats. Click the **Export** button in the result panel: | Format | Use case | | --- | --- | | **PDF** | Share the result as a portable document | | **Word (.docx)** | Edit the result in Microsoft Word or compatible editors | Two export modes are available: * **Export Result** - exports the final output only. * **Export Full Run** - exports all step outputs in sequence, useful for auditing or review. Built-in Plans -------------- [Section titled “Built-in Plans”](https://askimo.chat/docs/desktop/plans/#built-in-plans) Askimo ships with ready-to-use plans covering common tasks: * [Writing](https://askimo.chat/docs/desktop/plans/#tab-panel-10) * [Research](https://askimo.chat/docs/desktop/plans/#tab-panel-11) * [Productivity](https://askimo.chat/docs/desktop/plans/#tab-panel-12) | Plan | Steps | Description | | --- | --- | --- | | **Blog Post Writer** ✍️ | 4 | Outline → draft → SEO review → final polished post | | **Email Writer** 📧 | 2 | Draft → reviewed and improved email | | Plan | Steps | Description | | --- | --- | --- | | **Research Report** 📝 | 2 | Research a topic → write a structured report | | **Competitor Analysis** 🏆 | 4 | Profile → comparison → opportunities → full report | | Plan | Steps | Description | | --- | --- | --- | | **Meeting Notes Processor** 📋 | 4 | Structure → action items → summary → final minutes | | **Job Application Writer** 💼 | 5 | Job analysis → CV match → cover letter → CV tips → tailored résumé | Built-in plans are read-only. To customise one, use **Duplicate & Edit** (see below). Creating Your Own Plans ----------------------- [Section titled “Creating Your Own Plans”](https://askimo.chat/docs/desktop/plans/#creating-your-own-plans) You can create completely custom plans from the Plans gallery. There are two ways to do it: ### Option A - AI Generation (Recommended) [Section titled “Option A - AI Generation (Recommended)”](https://askimo.chat/docs/desktop/plans/#option-a---ai-generation-recommended) Describe your workflow in plain English and let the AI write the YAML for you. 1. Click the **+** button in the Plans gallery to open the New Plan editor. 2. In the **✨ Generate with AI** panel at the top, describe what you want. For example: _“A 3-step plan that researches a company, analyses its financial health, and writes an investment brief.”_ 3. Press **⌘ Enter** (macOS) or **Ctrl + Enter** (Windows/Linux), or click the send button. 4. The AI generates valid plan YAML and places it in the editor below. 5. Review the YAML, make any tweaks, and click **Save** when ready. ![Askimo Desktop Plan editor with the AI generation panel at the top, a YAML editor below, and a live schema reference panel on the right.](https://askimo.chat/_astro/plan_editor.SN2demCe_Z1oDdvD.webp) ![](https://askimo.chat/docs/desktop/plans/) ### Option B - Write YAML Directly [Section titled “Option B - Write YAML Directly”](https://askimo.chat/docs/desktop/plans/#option-b---write-yaml-directly) For full control, write the YAML yourself in the editor. A live reference panel on the right shows the schema and an example. A **View Docs** link takes you to this page. Click **+** in the Plans gallery, leave the AI panel empty, and type or paste your YAML directly into the editor. ### Duplicate & Edit a Built-in Plan [Section titled “Duplicate & Edit a Built-in Plan”](https://askimo.chat/docs/desktop/plans/#duplicate--edit-a-built-in-plan) 1. Hover over a built-in plan card in the gallery. 2. Click the **⋮ menu** and select **Duplicate & Edit**. 3. The editor opens pre-filled with the built-in’s YAML (the id is suffixed with `-copy` to avoid shadowing the original). 4. Modify as needed and click **Save**. Plan YAML Reference ------------------- [Section titled “Plan YAML Reference”](https://askimo.chat/docs/desktop/plans/#plan-yaml-reference) Plans are defined in YAML files stored in `~/.askimo//plans/`. The schema is straightforward: ### Top-level Fields [Section titled “Top-level Fields”](https://askimo.chat/docs/desktop/plans/#top-level-fields) | Field | Required | Description | | --- | --- | --- | | `id` | ✅ | Unique kebab-case identifier (also the file name) | | `name` | ✅ | Human-readable display name shown in the gallery | | `icon` | \- | A **single emoji** (e.g. `"📊"`) shown on the plan card | | `description` | \- | Short description shown in the gallery card | | `inputs` | \- | List of user-facing input fields | | `steps` | ✅ | List or map of step definitions | | `workflow` | \- | Explicit execution topology (omit for auto-sequential) | ### Inputs [Section titled “Inputs”](https://askimo.chat/docs/desktop/plans/#inputs) Each input defines a field the user fills in before running the plan. inputs: - key: topic # referenced in steps as {{topic}} label: Topic # caption shown in the UI type: text # text | multiline | toggle | number required: true # plan will not run if blank default: "" # pre-filled value hint: Enter a topic # placeholder / helper text **Input types:** | Type | UI control | | --- | --- | | `text` | Single-line text field | | `multiline` | Multi-line text area | | `toggle` | On/Off switch (value is `"true"` or `"false"`) | | `number` | Numeric input | ### Steps [Section titled “Steps”](https://askimo.chat/docs/desktop/plans/#steps) Steps can be declared two ways - both are valid: **List style** (simple and most common): steps: - id: research system: "You are a thorough researcher." message: "Research {{topic}} and summarise key findings." - id: report message: "Write a structured report. Research: {{research}}" **Map style** (useful when combined with an explicit `workflow` block): steps: research: system: "You are a thorough researcher." message: "Research {{topic}} and summarise key findings." report: message: "Write a structured report. Research: {{research}}" **Step fields:** | Field | Required | Description | | --- | --- | --- | | `id` | ✅ (list style) | Step identifier — used to reference output as `{{id}}` | | `message` | ✅ (AI steps) | The user prompt sent to the AI. Supports `{{variable}}` references | | `system` | — | Optional system prompt for this step | | `ask` | — | Interactive question shown to the user at runtime. When present, no AI call is made — the user’s answer is stored in scope under the step’s `id` | ### Ask Steps — Dynamic Mid-Run Inputs [Section titled “Ask Steps — Dynamic Mid-Run Inputs”](https://askimo.chat/docs/desktop/plans/#ask-steps--dynamic-mid-run-inputs) Ask steps let a plan gather information that can only be known _after_ earlier steps have run. Unlike the static input form shown before a plan starts, ask steps pause execution at a specific point and present a question inline. **Example** — a research plan that asks for a focus area after the initial overview: id: deep-researchname: Deep Researchicon: "🔬" inputs: - key: topic label: Topic type: text required: true steps: overview: message: "Give a broad overview of {{topic}}." clarify_focus: ask: "Based on the overview, what specific angle or aspect should we focus on?" deep_dive: message: | Write a detailed analysis of {{topic}}. Focus specifically on: {{clarify_focus}} Overview context: {{overview}} workflow: type: sequence nodes: - type: step stepId: overview - type: ask stepId: clarify_focus - type: step stepId: deep_dive When this plan runs: 1. The `overview` AI step runs automatically. 2. Execution pauses at `clarify_focus` — a question panel appears in the UI. 3. You type your answer and submit. 4. The `deep_dive` step runs with `{{clarify_focus}}` resolved to your answer. You can chain as many ask steps as needed throughout the workflow. ### Referencing Outputs [Section titled “Referencing Outputs”](https://askimo.chat/docs/desktop/plans/#referencing-outputs) Use `{{stepId}}` in a step’s `message` to inject a prior step’s output: steps: - id: research message: "Research {{topic}}." - id: report message: "Write a report using this research: {{research}}" # ↑ injects research step's output You can also reference user inputs directly: message: "Write a post about {{topic}} for {{audience}}." ### Workflow (Optional) [Section titled “Workflow (Optional)”](https://askimo.chat/docs/desktop/plans/#workflow-optional) Omit the `workflow` block for simple sequential plans - steps run top-to-bottom automatically. Add a `workflow` block when you need **parallel execution** or **conditional branching**: workflow: type: sequence nodes: - type: step stepId: assess - type: parallel # runs itinerary + flights at the same time outputKey: research nodes: - type: step stepId: itinerary - type: conditional # only runs if user toggled "include flights" condition: "include_flights == true" node: type: step stepId: flights - type: step stepId: summary **Workflow node types:** | Type | Description | | --- | --- | | `step` | Runs a single AI step. Requires `stepId`. | | `ask` | Pauses execution and presents a question to the user. Requires `stepId` (must match a step with an `ask` field). The answer is stored in scope under the step’s id. | | `sequence` | Runs child nodes one after another. | | `parallel` | Runs all child nodes concurrently. Requires `outputKey`. | | `conditional` | Runs its child node only when `condition` is true. | **Condition syntax** (evaluated against input values and prior step outputs): | Expression | Example | Matches when | | --- | --- | --- | | `key == value` | `"tone == formal"` | Input or output equals exact value | | `key == true` | `"include_flights == true"` | Toggle is on | | `key contains text` | `"topic contains AI"` | Value contains substring | Complete Example ---------------- [Section titled “Complete Example”](https://askimo.chat/docs/desktop/plans/#complete-example) A simple two-step blog post plan: id: quick-blog-postname: Quick Blog Postdescription: Research a topic and write a blog post draft.icon: "✍️" inputs: - key: topic label: Topic type: text required: true hint: e.g. "Benefits of remote work" - key: audience label: Target Audience type: text required: false hint: e.g. "software developers" steps: - id: research system: "You are a knowledgeable researcher." message: "Research the topic '{{topic}}' for an audience of {{audience}}. Provide key insights, statistics, and talking points." - id: draft message: "Write a 600-word blog post about '{{topic}}' for {{audience}} based on this research:\n\n{{research}}\n\nUse an engaging introduction, 3 main sections, and a strong conclusion." Managing Your Plans ------------------- [Section titled “Managing Your Plans”](https://askimo.chat/docs/desktop/plans/#managing-your-plans) ### Editing a Plan [Section titled “Editing a Plan”](https://askimo.chat/docs/desktop/plans/#editing-a-plan) 1. Hover over a plan card in the gallery. 2. Click the **⋮ menu** and select **Edit YAML**. 3. Modify the YAML in the editor and click **Save**. ### Deleting a Plan [Section titled “Deleting a Plan”](https://askimo.chat/docs/desktop/plans/#deleting-a-plan) 1. Hover over a plan card in the gallery. 2. Click the **⋮ menu** and select **Delete**. 3. Confirm the deletion. Built-in plans cannot be deleted - only user-created plans can be removed. ### Where Plans Are Stored [Section titled “Where Plans Are Stored”](https://askimo.chat/docs/desktop/plans/#where-plans-are-stored) User plans are saved as `.yml` files in: ~/.askimo//plans/ You can back them up, version-control them with Git, or share them with teammates by copying the YAML files. Tips and Best Practices ----------------------- [Section titled “Tips and Best Practices”](https://askimo.chat/docs/desktop/plans/#tips-and-best-practices) **Keep steps focused.** Each step should do one thing well. A step that tries to research, write, and review all at once usually produces lower quality than three dedicated steps. **Use the system prompt for persona.** Setting a `system` prompt on a step that requires expert knowledge (e.g. `"You are a senior financial analyst"`) often improves output quality significantly. **Reference earlier steps sparingly.** Only inject the previous step output when the next step genuinely needs it. Overloading a step’s context with all prior outputs can dilute focus. **Wrap all message values in double quotes.** YAML treats colons and special characters in unquoted strings as syntax. Always quote `message` and `system` values: message: "Research {{topic}}: include recent trends." # ✅ safemessage: Research {{topic}}: include recent trends. # ❌ YAML parse error **Use AI generation as a starting point.** The AI-generated YAML is often 80–90% correct. Use it as a scaffold and refine the step messages for your specific needs. Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/plans/#troubleshooting) ### “Value for the variable ‘…’ is missing” [Section titled ““Value for the variable ‘…’ is missing””](https://askimo.chat/docs/desktop/plans/#value-for-the-variable--is-missing) A required input was left blank. Fill in all fields marked with `*` before running the plan. ### “Invalid YAML: mapping values are not allowed here” [Section titled ““Invalid YAML: mapping values are not allowed here””](https://askimo.chat/docs/desktop/plans/#invalid-yaml-mapping-values-are-not-allowed-here) A `message` or `system` value contains a colon (`:`) without being quoted. Wrap the value in double quotes and escape any `"` inside with `\"`: # ❌ Causes parse errormessage: Research {{topic}}: include key metrics. # ✅ Correctmessage: "Research {{topic}}: include key metrics." ### Plan produces blank output [Section titled “Plan produces blank output”](https://askimo.chat/docs/desktop/plans/#plan-produces-blank-output) * Check that the last step’s `message` asks the AI to produce the final deliverable explicitly. * Ensure that step references like `{{research}}` match the exact `id` of the referenced step (case-sensitive). ### Steps run but the result is empty [Section titled “Steps run but the result is empty”](https://askimo.chat/docs/desktop/plans/#steps-run-but-the-result-is-empty) Verify the `id` fields in list-style steps are present and unique. If using map-style steps, the map key is the id - no separate `id` field is needed. ### Ask step times out or the plan continues with a blank answer [Section titled “Ask step times out or the plan continues with a blank answer”](https://askimo.chat/docs/desktop/plans/#ask-step-times-out-or-the-plan-continues-with-a-blank-answer) If you do not respond to an ask step within 10 minutes, the plan resumes automatically with an empty string for that answer. You can click **Skip** intentionally to continue without answering. If the downstream steps rely on that answer, consider adding a fallback in the step message — for example: message: "Write a report on {{topic}}. Focus: {{clarify_focus:-general overview}}" * * * Learn More ---------- [Section titled “Learn More”](https://askimo.chat/docs/desktop/plans/#learn-more) * **[Skills - AI Agents for Your Workspace](https://askimo.chat/docs/desktop/skills/) ** - when your task needs to read or write local files, run shell commands, or work inside a project directory, use Skills instead * **[AI Investment Research Plan (example)](https://askimo.chat/blog/ai-investment-research-plan/) ** - Real-world walkthrough of a multi-step AI Plan with RAG and MCP tools * **[Askimo Features: AI Plans section](https://askimo.chat/features/) ** - Visual overview of Plans in the desktop app --- # HiDPI & UI Scale — Sharp Display on Any Screen | Askimo [Skip to content](https://askimo.chat/docs/desktop/hidpi/#_top) HiDPI & UI Scale — Sharp Display on Any Screen ============================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Askimo is built to look sharp on every type of screen — from standard HD monitors to 4K displays and high-resolution laptops. This page explains how display scaling works and how you can take control of it if the default ever feels too small or too large. * * * What Is Display Scaling? ------------------------ [Section titled “What Is Display Scaling?”](https://askimo.chat/docs/desktop/hidpi/#what-is-display-scaling) Modern high-resolution screens pack many more pixels into the same physical space. Without scaling, everything on screen — text, buttons, icons — would appear tiny. Display scaling tells Askimo how much to enlarge the interface so it looks comfortable and readable at your screen’s native resolution. Think of it like zoom on a document: **100%** is the baseline, **150%** makes everything half-again bigger, and **200%** doubles the size — ideal for 4K monitors where 100% would be uncomfortably small. * * * How Askimo Handles Scaling Automatically ---------------------------------------- [Section titled “How Askimo Handles Scaling Automatically”](https://askimo.chat/docs/desktop/hidpi/#how-askimo-handles-scaling-automatically) Askimo tries its best to detect the right scale for your screen so you don’t have to configure anything. ### Windows [Section titled “Windows”](https://askimo.chat/docs/desktop/hidpi/#windows) On Windows, Askimo respects your system’s DPI setting. If you’ve already configured display scaling in **Windows Settings → System → Display → Scale**, Askimo honours that choice automatically. You only need to step in if Askimo’s rendering doesn’t match your expectation. ### Linux [Section titled “Linux”](https://askimo.chat/docs/desktop/hidpi/#linux) Linux display environments vary widely, so Askimo does active detection at startup. It reads hints from your desktop environment (such as `GDK_SCALE`, `QT_SCALE_FACTOR`, display DRM properties, and similar signals) to calculate the best scale for your monitor. If a non-default scale is detected, Askimo applies it silently — no action needed from you. If the auto-detected value isn’t right for your setup, you can override it in Preferences — see the next section. ### macOS [Section titled “macOS”](https://askimo.chat/docs/desktop/hidpi/#macos) * * * Setting Your Own Scale (Windows & Linux) ---------------------------------------- [Section titled “Setting Your Own Scale (Windows & Linux)”](https://askimo.chat/docs/desktop/hidpi/#setting-your-own-scale-windows--linux) If the automatic scale doesn’t feel right — perhaps text is slightly too small on a 1440p monitor, or too large on a low-DPI display — you can set it yourself. **To change the UI scale:** 1. Open **Settings** using `Ctrl + ,` (or via the menu bar) 2. Go to the **Appearance** tab 3. Scroll down to the **Display Scale** section 4. Pick your preferred scale from the dropdown 5. Restart Askimo to apply the change ### Available Scale Options [Section titled “Available Scale Options”](https://askimo.chat/docs/desktop/hidpi/#available-scale-options) **Windows** offers fine-grained steps: | Scale | Best for | | --- | --- | | 75% | Very large monitors where the default feels too big | | 100% | Standard HD (1080p) screens — the baseline | | 125% | 1440p or 13“ laptops | | 150% | 1440p or mid-size HiDPI displays | | 175% | Large HiDPI monitors | | 200% | 4K displays or small screens with high pixel density | **Linux** supports whole-number steps only, due to a limitation of the X11/XRender display pipeline: | Scale | Best for | | --- | --- | | 100% | Standard monitors | | 200% | HiDPI / 4K displays | | 300% | Very high-density displays | * * * Your Setting Always Wins ------------------------ [Section titled “Your Setting Always Wins”](https://askimo.chat/docs/desktop/hidpi/#your-setting-always-wins) Askimo uses the following priority order to determine the final scale: 1. **Your saved preference** (set in Settings → Appearance → Display Scale) 2. **JVM launch flags** (`-Dsun.java2d.uiScale` or `-Dskiko.uiScale`) — for advanced users 3. **Linux auto-detection** (only when no preference or flag is set) 4. **Platform default** This means once you pick a scale in Preferences, Askimo remembers it and won’t be overridden by system changes or restarts. * * * Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/hidpi/#troubleshooting) **Text or icons look blurry on Windows** → Try enabling a higher scale (150% or 200%) in Settings → Appearance → Display Scale, then restart. **The interface is too large after connecting an external monitor** → Lower the scale to 100% or 75% in Settings → Appearance → Display Scale, restart, and readjust. **Auto-detection picked the wrong scale on Linux** → Override it manually in Settings → Appearance → Display Scale. Your saved preference always takes priority over auto-detection. **I don’t see a Display Scale option** → You are likely on macOS, where display scaling is managed by the operating system. Adjust resolution in **System Settings → Displays** instead. --- # Askimo App Settings Overview | Askimo [Skip to content](https://askimo.chat/docs/desktop/settings/#_top) Askimo App Settings Overview ============================ We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Askimo App offers extensive customization options through two main settings categories. Choose the area you want to configure: Settings Categories ------------------- [Section titled “Settings Categories”](https://askimo.chat/docs/desktop/settings/#settings-categories) Setup & Configuration Get started with Askimo App. Configure AI providers, manage API keys, switch between OpenAI, Anthropic Claude, Gemini, xAI, Ollama, LM Studio, LocalAI, and Docker AI. Test connections and start your first conversation. [Setup & Configuration →](https://askimo.chat/docs/desktop/ai-providers/) UI Preferences Customize appearance, themes, fonts, keyboard shortcuts, window behavior, privacy settings, and performance options. [Customize Preferences →](https://askimo.chat/docs/desktop/preferences/) Updating Askimo Keep Askimo up to date on macOS, Windows, and Linux. Step-by-step instructions to install the latest version without losing your settings or sessions. [How to Update →](https://askimo.chat/docs/desktop/updating/) * * * Quick Access ------------ [Section titled “Quick Access”](https://askimo.chat/docs/desktop/settings/#quick-access) ### Opening Settings [Section titled “Opening Settings”](https://askimo.chat/docs/desktop/settings/#opening-settings) **From Menu:** 1. Click on the menu bar 2. Select “Askimo” → “Preferences” (macOS) or “Settings” (Windows/Linux) **Keyboard Shortcut:** * **macOS**: `⌘ + ,` * **Windows/Linux**: `Ctrl + ,` * * * What You’ll Find ---------------- [Section titled “What You’ll Find”](https://askimo.chat/docs/desktop/settings/#what-youll-find) ### Setup & Configuration [Section titled “Setup & Configuration”](https://askimo.chat/docs/desktop/settings/#setup--configuration) * Get started with Askimo App * Set up OpenAI, Anthropic Claude, Google Gemini, xAI, Ollama, LM Studio, LocalAI, and Docker AI * Manage API keys securely * Test connections and verify setup * Switch between providers seamlessly * Fine-tune model parameters (temperature, tokens, etc.) * Configure context windows and chat behavior * Start your first conversation ### UI Preferences [Section titled “UI Preferences”](https://askimo.chat/docs/desktop/settings/#ui-preferences) * Choose themes (Light, Dark, Auto, Custom) * Customize fonts and text sizes * Configure window behavior and startup options * Set up keyboard shortcuts * Manage privacy and data settings * Optimize performance and resource usage * Export and import settings * * * Getting Started --------------- [Section titled “Getting Started”](https://askimo.chat/docs/desktop/settings/#getting-started) New to Askimo App? Start with these guides: 1. **[Setup & Configuration](https://askimo.chat/docs/desktop/ai-providers/) ** - Get started and configure AI providers 2. **[UI Preferences](https://askimo.chat/docs/desktop/preferences/) ** - Customize the look and feel 3. **[RAG (Project Knowledge)](https://askimo.chat/docs/desktop/rag/) ** - Build project-based knowledge bases 4. **[Features & Workflows](https://askimo.chat/docs/desktop/features/) ** - Learn key features and shortcuts 5. **[Updating Askimo](https://askimo.chat/docs/desktop/updating/) ** - Keep Askimo up to date * * * Need Help? ---------- [Section titled “Need Help?”](https://askimo.chat/docs/desktop/settings/#need-help) * Check the detailed documentation for each settings area * Visit our [troubleshooting guides](https://askimo.chat/docs/desktop/troubleshooting/) * Join our [Discord community](https://discord.gg/askimo) * Report issues on [GitHub](https://github.com/askimo-ai/askimo/issues) --- # Askimo App Installation Overview | Askimo [Skip to content](https://askimo.chat/docs/desktop/installation/#_top) Askimo App Installation Overview ================================ We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Askimo App runs on macOS, Windows, and Linux. Choose your operating system below for a focused, step-by-step guide. Choose Your Operating System ---------------------------- [Section titled “Choose Your Operating System”](https://askimo.chat/docs/desktop/installation/#choose-your-operating-system) * [macOS Installation Guide](https://askimo.chat/docs/desktop/installation/macos/) * [Windows Installation Guide](https://askimo.chat/docs/desktop/installation/windows/) * [Linux Installation Guide](https://askimo.chat/docs/desktop/installation/linux/) What You’ll Install ------------------- [Section titled “What You’ll Install”](https://askimo.chat/docs/desktop/installation/#what-youll-install) The native Askimo App app provides: * Unified AI provider configuration * Local secure execution Troubleshooting (Cross-Platform) -------------------------------- [Section titled “Troubleshooting (Cross-Platform)”](https://askimo.chat/docs/desktop/installation/#troubleshooting-cross-platform) | Symptom | General Action | | --- | --- | | App blocked by OS security | Use OS-specific override (Gatekeeper / SmartScreen / chmod) | | App fails to start | Confirm minimum OS requirements and reinstall | | Unexpected crash | Check release notes; file an issue with logs | For OS-specific fixes (security prompts, permissions, package issues) see the dedicated guide for your platform. Need Help? ---------- [Section titled “Need Help?”](https://askimo.chat/docs/desktop/installation/#need-help) * Full documentation: [https://askimo.chat/docs](https://askimo.chat/docs/) * Report issues: [https://github.com/askimo-ai/askimo/issues](https://github.com/askimo-ai/askimo/issues) Already Installed? ------------------ [Section titled “Already Installed?”](https://askimo.chat/docs/desktop/installation/#already-installed) Looking to update to the latest version? See the [Updating Askimo App](https://askimo.chat/docs/desktop/updating/) guide. --- # LocalAI Setup for Askimo App | Askimo [Skip to content](https://askimo.chat/docs/desktop/providers/localai/#_top) LocalAI Setup for Askimo App ============================ We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) LocalAI Configuration --------------------- [Section titled “LocalAI Configuration”](https://askimo.chat/docs/desktop/providers/localai/#localai-configuration) Connect Askimo App to your self-hosted LocalAI instance for complete control over your AI infrastructure. ### Server Configuration [Section titled “Server Configuration”](https://askimo.chat/docs/desktop/providers/localai/#server-configuration) * **Server URL**: LocalAI server endpoint * Default: `http://localhost:8080` * For remote servers: `http://your-server:8080` * **API Key**: (Optional) If your LocalAI instance requires authentication * **Timeout**: Connection timeout (default: 120s) * **Available Models**: Detected from your LocalAI deployment ### Setting Up LocalAI [Section titled “Setting Up LocalAI”](https://askimo.chat/docs/desktop/providers/localai/#setting-up-localai) 1. Install LocalAI following the [official guide](https://localai.io/basics/getting_started/) 2. Start your LocalAI server: docker run -p 8080:8080 --name local-ai -ti localai/localai:latest 3. Deploy models to your LocalAI instance 4. In Askimo, enter your LocalAI server URL 5. Click “Test Connection” to verify ### Accessing Provider Settings [Section titled “Accessing Provider Settings”](https://askimo.chat/docs/desktop/providers/localai/#accessing-provider-settings) 1. Click on the menu bar 2. Select “Settings” 3. Navigate to the “AI Providers” tab 4. Select “LocalAI” from the provider list **Keyboard Shortcut**: `⌘ + ,` (macOS) or `Ctrl + ,` (Windows/Linux) then click “AI Providers” ### Deployment Options [Section titled “Deployment Options”](https://askimo.chat/docs/desktop/providers/localai/#deployment-options) **Docker (Recommended):** docker run -p 8080:8080 \ -v $PWD/models:/models \ localai/localai:latest **Docker Compose:** version: '3.8'services: localai: image: localai/localai:latest ports: - "8080:8080" volumes: - ./models:/models environment: - THREADS=4 ### Best Use Cases for LocalAI [Section titled “Best Use Cases for LocalAI”](https://askimo.chat/docs/desktop/providers/localai/#best-use-cases-for-localai) **Enterprise Deployments:** Process sensitive customer data with our internal AI infrastructure **Compliance Requirements:** Ensure all AI processing stays within our controlled environment **Custom Models:** Use our proprietary fine-tuned models for domain-specific tasks ### Model Management [Section titled “Model Management”](https://askimo.chat/docs/desktop/providers/localai/#model-management) **Installing Models:** LocalAI supports various model formats: * GGUF/GGML models * PyTorch models * ONNX models * Custom backends **Model Gallery:** Install models from the LocalAI gallery: curl http://localhost:8080/models/apply \ -H "Content-Type: application/json" \ -d '{ "id": "model-gallery://llama-2-7b-chat" }' ### Troubleshooting [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/providers/localai/#troubleshooting) **Cannot Connect?** * Verify LocalAI server is running * Check firewall and network settings * Ensure correct server URL and port * Test with `curl http://localhost:8080/v1/models` **Authentication Issues?** * If your LocalAI requires authentication, add API key in settings * Check LocalAI logs for auth errors * Verify API key format matches LocalAI configuration **Model Loading Failures?** * Check LocalAI logs: `docker logs local-ai` * Verify model files are in correct directory * Ensure sufficient memory for model * Try restarting LocalAI service **Slow Performance?** * Enable GPU acceleration * Use quantized models * Adjust THREADS environment variable * Consider horizontal scaling with multiple instances ### Advanced Configuration [Section titled “Advanced Configuration”](https://askimo.chat/docs/desktop/providers/localai/#advanced-configuration) **Authentication:** Configure API key authentication in LocalAI: docker run -p 8080:8080 \ -e API_KEY=your-secret-key \ localai/localai:latest Then add the API key in Askimo settings. **Custom Backend:** LocalAI supports custom backends for specialized models: name: custom-modelbackend: custom-backendparameters: model: /path/to/model **Resource Limits:** Control resource usage: docker run -p 8080:8080 \ --memory="8g" \ --cpus="4" \ localai/localai:latest --- # Askimo App UI Preferences & Settings | Askimo [Skip to content](https://askimo.chat/docs/desktop/preferences/#_top) Askimo App UI Preferences & Settings ==================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Customize Askimo App to match your workflow and preferences. This guide covers appearance settings, keyboard shortcuts, performance options, and more. Accessing Preferences --------------------- [Section titled “Accessing Preferences”](https://askimo.chat/docs/desktop/preferences/#accessing-preferences) ### From Menu [Section titled “From Menu”](https://askimo.chat/docs/desktop/preferences/#from-menu) 1. Click on the menu bar 2. Select “Askimo” → “Preferences” (macOS) or “Settings” (Windows/Linux) 3. Navigate to the “Preferences” tab ### Keyboard Shortcut [Section titled “Keyboard Shortcut”](https://askimo.chat/docs/desktop/preferences/#keyboard-shortcut) * **macOS**: `⌘ + ,` * **Windows/Linux**: `Ctrl + ,` * * * Appearance ---------- [Section titled “Appearance”](https://askimo.chat/docs/desktop/preferences/#appearance) ### Theme [Section titled “Theme”](https://askimo.chat/docs/desktop/preferences/#theme) ![Askimo desktop app theme selection interface showing light, dark, auto, and custom theme options](https://askimo.chat/_astro/desktop_theme_management.FLXwymkN_Zopsyg.webp) ![](https://askimo.chat/docs/desktop/preferences/) Choose your preferred color scheme: * **Light**: Bright, clean interface ideal for daytime use * **Dark**: Easy on the eyes, perfect for night work and reduced eye strain * **Auto**: Automatically follows your system theme * **Custom**: Create your own color scheme with custom accent colors ### Font Settings [Section titled “Font Settings”](https://askimo.chat/docs/desktop/preferences/#font-settings) ![Askimo desktop app font customization settings showing font family and size options](https://askimo.chat/_astro/desktop_font_change.C26ag2DH_Znjf2U.webp) ![](https://askimo.chat/docs/desktop/preferences/) #### Editor Font [Section titled “Editor Font”](https://askimo.chat/docs/desktop/preferences/#editor-font) * **Font Family**: Choose from system fonts or install custom ones * Popular choices: SF Pro, Inter, Roboto, Arial * **Font Size**: Adjust readability * Default: Medium --- # Claude Desktop App - Free Anthropic Claude Client for Mac, Windows & Linux | Askimo [Skip to content](https://askimo.chat/docs/desktop/providers/anthropic/#_top) Claude Desktop App - Free Anthropic Claude Client for Mac, Windows & Linux ========================================================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Claude Desktop App - Askimo Claude Client ----------------------------------------- [Section titled “Claude Desktop App - Askimo Claude Client”](https://askimo.chat/docs/desktop/providers/anthropic/#claude-desktop-app---askimo-claude-client) Looking for a **Claude desktop app**? Askimo is a free, open-source **Claude desktop client** that works seamlessly on Mac, Windows, and Linux. Unlike the official Claude app, Askimo gives you a powerful **Anthropic Claude desktop application** with advanced features, all-in-one AI chat, and complete control over your AI conversations. ### Why Choose Askimo as Your Claude App? [Section titled “Why Choose Askimo as Your Claude App?”](https://askimo.chat/docs/desktop/providers/anthropic/#why-choose-askimo-as-your-claude-app) * **Free & Open Source** - No subscription required for the desktop client * **Cross-Platform** - Works on macOS, Windows, and Linux * **All-in-One AI Chat** - Use Claude alongside OpenAI, Gemini, and more * **Privacy-Focused** - Your conversations stay on your device * **Advanced Features** - Custom directives, RAG, chat search, and themes Setting Up Claude in Askimo Desktop App --------------------------------------- [Section titled “Setting Up Claude in Askimo Desktop App”](https://askimo.chat/docs/desktop/providers/anthropic/#setting-up-claude-in-askimo-desktop-app) Connect Askimo to Anthropic’s Claude models for advanced reasoning and long-context conversations. ### API Configuration [Section titled “API Configuration”](https://askimo.chat/docs/desktop/providers/anthropic/#api-configuration) * **API Key**: Your Anthropic API key (required) * Get your key from [console.anthropic.com](https://console.anthropic.com/) * **Default Model**: Choose from: * Latest Claude models - Most capable, balanced * Compact Claude models - Fast and efficient * **API Version**: API version (default: 2023-06-01) * **Timeout**: Request timeout in seconds (default: 60s) ### Setting Up Your API Key [Section titled “Setting Up Your API Key”](https://askimo.chat/docs/desktop/providers/anthropic/#setting-up-your-api-key) 1. Visit [Anthropic Console](https://console.anthropic.com/) 2. Sign in or create an account 3. Navigate to “API Keys” 4. Click “Create Key” 5. Copy the key 6. Paste it into Askimo’s Claude API Key field 7. Click “Test Connection” to verify ### Accessing Provider Settings [Section titled “Accessing Provider Settings”](https://askimo.chat/docs/desktop/providers/anthropic/#accessing-provider-settings) 1. Click on the menu bar 2. Select “Settings” 3. Navigate to the “AI Providers” tab 4. Select “Anthropic Claude” from the provider list **Keyboard Shortcut**: `⌘ + ,` (macOS) or `Ctrl + ,` (Windows/Linux) then click “AI Providers” ### Troubleshooting [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/providers/anthropic/#troubleshooting) **Connection Failed?** * Verify your API key is correct * Check that your API key has the necessary permissions * Ensure your account has available credits * Try increasing the timeout for large responses **Rate Limiting?** * Claude has different rate limits based on your plan * Check the [Anthropic pricing page](https://www.anthropic.com/pricing) for details * Consider upgrading your plan for higher limits --- # Proxy Configuration in Askimo | Askimo [Skip to content](https://askimo.chat/docs/desktop/proxy-configuration/#_top) Proxy Configuration in Askimo ============================= We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Learn how to configure proxy settings in Askimo to connect AI providers through corporate networks, privacy tunnels, or custom proxy servers. Overview -------- [Section titled “Overview”](https://askimo.chat/docs/desktop/proxy-configuration/#overview) Askimo supports comprehensive proxy configuration for all network connections, including: * AI provider API calls (OpenAI, Anthropic, Gemini, etc.) * Web content extraction (URL scraping, PDF downloads) * Model listing and availability checks ### Supported Proxy Types [Section titled “Supported Proxy Types”](https://askimo.chat/docs/desktop/proxy-configuration/#supported-proxy-types) * **HTTP/HTTPS Proxy** - Standard corporate proxies * **SOCKS5 Proxy** - Advanced proxies, SSH tunnels, Tor * **System Proxy** - Automatically use your operating system’s proxy settings * **No Proxy** - Direct connection (default) * * * Accessing Network Settings -------------------------- [Section titled “Accessing Network Settings”](https://askimo.chat/docs/desktop/proxy-configuration/#accessing-network-settings) Navigate to the proxy configuration settings: **Opening Network Settings:** 1. Click the **Settings** icon in the sidebar (or use `⌘/Ctrl +`) 2. Select **Network** from the settings menu 3. Configure your proxy settings **Keyboard Shortcut:** * **macOS**: `⌘ +` then select Network * **Windows/Linux**: `Ctrl +` then select Network * * * Configuring Proxy Settings -------------------------- [Section titled “Configuring Proxy Settings”](https://askimo.chat/docs/desktop/proxy-configuration/#configuring-proxy-settings) ### Proxy Type Selection [Section titled “Proxy Type Selection”](https://askimo.chat/docs/desktop/proxy-configuration/#proxy-type-selection) Choose the appropriate proxy type for your network environment: **1\. No Proxy (Default)** * Direct connection to AI providers * No proxy server involved * Best for home networks or unrestricted connections **2\. System Proxy** * Automatically uses your operating system’s proxy configuration * Ideal when your OS is already configured with proxy settings * No manual configuration needed **3\. HTTP Proxy** * Standard HTTP proxy server * Most common in corporate environments * Supports optional authentication **4\. HTTPS Proxy** * Secure HTTPS proxy server * Same as HTTP but uses HTTPS protocol * Supports optional authentication **5\. SOCKS5 Proxy** * Advanced proxy protocol * Supports SSH tunnels, Tor, and privacy proxies * Authentication via system properties * * * HTTP/HTTPS Proxy Configuration ------------------------------ [Section titled “HTTP/HTTPS Proxy Configuration”](https://askimo.chat/docs/desktop/proxy-configuration/#httphttps-proxy-configuration) Configure a standard HTTP or HTTPS proxy server. ### Basic Configuration [Section titled “Basic Configuration”](https://askimo.chat/docs/desktop/proxy-configuration/#basic-configuration) **Required Settings:** 1. **Proxy Type**: Select “HTTP Proxy” or “HTTPS Proxy” 2. **Proxy Host**: Enter your proxy server address * Example: `proxy.company.com` * Example: `192.168.1.100` 3. **Proxy Port**: Enter the proxy port number * Common ports: `8080`, `3128`, `8888` ### With Authentication [Section titled “With Authentication”](https://askimo.chat/docs/desktop/proxy-configuration/#with-authentication) If your proxy requires authentication: **Optional Settings:** 1. **Username**: Your proxy username 2. **Password**: Your proxy password **Example Configuration:** Proxy Type: HTTP ProxyHost: proxy.company.comPort: 8080Username: john.doePassword: ******** * * * SOCKS5 Proxy Configuration -------------------------- [Section titled “SOCKS5 Proxy Configuration”](https://askimo.chat/docs/desktop/proxy-configuration/#socks5-proxy-configuration) Configure a SOCKS5 proxy for advanced networking or privacy. ### Basic Configuration [Section titled “Basic Configuration”](https://askimo.chat/docs/desktop/proxy-configuration/#basic-configuration-1) **Required Settings:** 1. **Proxy Type**: Select “SOCKS5 Proxy” 2. **Proxy Host**: Enter your SOCKS5 server address * Example: `localhost` (for SSH tunnels) * Example: `127.0.0.1` 3. **Proxy Port**: Enter the SOCKS5 port * Common ports: `1080`, `9050` (Tor) ### With Authentication [Section titled “With Authentication”](https://askimo.chat/docs/desktop/proxy-configuration/#with-authentication-1) **Optional Settings:** 1. **Username**: SOCKS5 username (if required) 2. **Password**: SOCKS5 password (if required) ### Common Use Cases [Section titled “Common Use Cases”](https://askimo.chat/docs/desktop/proxy-configuration/#common-use-cases) **SSH Tunnel:** # Create SSH tunnel firstssh -D 1080 user@remote-server # Then configure in Askimo:Proxy Type: SOCKS5 ProxyHost: localhostPort: 1080 **Tor Network:** # Ensure Tor is running, then:Proxy Type: SOCKS5 ProxyHost: 127.0.0.1Port: 9050 * * * System Proxy Configuration -------------------------- [Section titled “System Proxy Configuration”](https://askimo.chat/docs/desktop/proxy-configuration/#system-proxy-configuration) Let Askimo automatically use your operating system’s proxy settings. ### How It Works [Section titled “How It Works”](https://askimo.chat/docs/desktop/proxy-configuration/#how-it-works) **macOS:** * Uses proxy settings from System Preferences → Network → Advanced → Proxies * Supports HTTP, HTTPS, and SOCKS proxies configured at OS level **Windows:** * Uses proxy settings from Settings → Network & Internet → Proxy * Supports automatic proxy configuration and manual settings **Linux:** * Uses system environment variables (`http_proxy`, `https_proxy`, `all_proxy`) * Respects GNOME/KDE proxy settings ### Configuration [Section titled “Configuration”](https://askimo.chat/docs/desktop/proxy-configuration/#configuration) **Simple Setup:** 1. **Proxy Type**: Select “System Proxy” 2. That’s it! Askimo will use your OS proxy settings * * * Localhost and Private Network Bypass ------------------------------------ [Section titled “Localhost and Private Network Bypass”](https://askimo.chat/docs/desktop/proxy-configuration/#localhost-and-private-network-bypass) Askimo automatically bypasses proxy for local services to ensure optimal performance. ### Automatic Bypass [Section titled “Automatic Bypass”](https://askimo.chat/docs/desktop/proxy-configuration/#automatic-bypass) The following addresses **always bypass proxy** (direct connection): **Localhost:** * `localhost` * `127.0.0.1` * `::1` (IPv6 localhost) **Private Networks:** * `192.168.x.x` (home/office networks) * `10.x.x.x` (private networks) * `172.16.x.x` to `172.31.x.x` (private networks) * `*.local` domains ### Why This Matters [Section titled “Why This Matters”](https://askimo.chat/docs/desktop/proxy-configuration/#why-this-matters) **Local AI Providers:** * Ollama (default: `http://localhost:11434`) * LM Studio (default: `http://localhost:1234`) * LocalAI (default: `http://localhost:8080`) * Docker AI (default: `http://localhost:8080`) These local services automatically bypass your proxy configuration for faster, more reliable connections. * * * Common Proxy Scenarios ---------------------- [Section titled “Common Proxy Scenarios”](https://askimo.chat/docs/desktop/proxy-configuration/#common-proxy-scenarios) ### Corporate Network [Section titled “Corporate Network”](https://askimo.chat/docs/desktop/proxy-configuration/#corporate-network) **Scenario:** You’re behind a corporate firewall that requires an authenticated proxy. **Configuration:** Proxy Type: HTTP ProxyHost: proxy.corporate.comPort: 8080Username: your.email@company.comPassword: your-proxy-password **Applies to:** * All external AI providers (OpenAI, Anthropic, Gemini, etc.) * Web content extraction from external URLs * Model availability checks **Bypasses proxy:** * Local Ollama installation * Local LM Studio models * * * ### Privacy-Focused Setup [Section titled “Privacy-Focused Setup”](https://askimo.chat/docs/desktop/proxy-configuration/#privacy-focused-setup) **Scenario:** You want all AI requests to go through Tor for privacy. **Configuration:** # First, ensure Tor is running# Then configure:Proxy Type: SOCKS5 ProxyHost: 127.0.0.1Port: 9050 **Note:** Tor will significantly slow down responses but provides anonymity. * * * ### Home Network with VPN [Section titled “Home Network with VPN”](https://askimo.chat/docs/desktop/proxy-configuration/#home-network-with-vpn) **Scenario:** You use a VPN that requires a SOCKS5 proxy. **Configuration:** Proxy Type: SOCKS5 ProxyHost: vpn-proxy.example.comPort: 1080Username: vpn-userPassword: vpn-password * * * ### Mixed Environment [Section titled “Mixed Environment”](https://askimo.chat/docs/desktop/proxy-configuration/#mixed-environment) **Scenario:** You switch between office (with proxy) and home (without proxy). **Option 1 - System Proxy:** Proxy Type: System Proxy Configure your OS proxy at the office, disable at home. Askimo adapts automatically. **Option 2 - Manual Switching:** * At office: Configure HTTP Proxy * At home: Switch to “No Proxy” * * * Verifying Proxy Configuration ----------------------------- [Section titled “Verifying Proxy Configuration”](https://askimo.chat/docs/desktop/proxy-configuration/#verifying-proxy-configuration) ### Testing Your Setup [Section titled “Testing Your Setup”](https://askimo.chat/docs/desktop/proxy-configuration/#testing-your-setup) After configuring proxy settings, verify they work: **Quick Test:** 1. Send a message to any AI provider (e.g., ChatGPT) 2. If you receive a response, proxy is working ✓ 3. If connection fails, check your proxy settings **Common Issues:** **Connection Timeout:** * Verify proxy host and port are correct * Check if proxy server is accessible * Ensure firewall allows outbound connections **Authentication Failed:** * Double-check username and password * Try without authentication first * Contact your IT department for correct credentials **Proxy Works, Local Models Don’t:** * This is expected! Local models bypass proxy * Verify local service is running (e.g., `ollama list`) * Check local service URL in AI provider settings * * * Advanced Configuration ---------------------- [Section titled “Advanced Configuration”](https://askimo.chat/docs/desktop/proxy-configuration/#advanced-configuration) ### Environment Variables [Section titled “Environment Variables”](https://askimo.chat/docs/desktop/proxy-configuration/#environment-variables) You can also configure proxy using environment variables (takes precedence over UI settings): **macOS/Linux:** export http_proxy="http://proxy.company.com:8080"export https_proxy="http://proxy.company.com:8080"export no_proxy="localhost,127.0.0.1,*.local" # With authentication:export http_proxy="http://username:password@proxy.company.com:8080" **Windows (PowerShell):** $env:http_proxy = "http://proxy.company.com:8080"$env:https_proxy = "http://proxy.company.com:8080"$env:no_proxy = "localhost,127.0.0.1,*.local" ### Configuration File [Section titled “Configuration File”](https://askimo.chat/docs/desktop/proxy-configuration/#configuration-file) Proxy settings are stored in `~/.askimo/askimo.yml`: proxy: type: HTTP # NONE, SYSTEM, HTTP, HTTPS, SOCKS5 host: proxy.company.com port: 8080 username: "" password: "" * * * Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/proxy-configuration/#troubleshooting) ### Proxy Connection Issues [Section titled “Proxy Connection Issues”](https://askimo.chat/docs/desktop/proxy-configuration/#proxy-connection-issues) **Problem:** “Connection timeout” or “Unable to connect” **Solutions:** 1. Verify proxy host and port are correct 2. Test proxy with another application (e.g., browser) 3. Check firewall allows connections to proxy port 4. Try switching proxy type (HTTP vs SOCKS5) * * * **Problem:** “Proxy authentication required” **Solutions:** 1. Enter username and password in proxy settings 2. Verify credentials are correct (try in browser) 3. Check with IT if authentication method is supported 4. Try without authentication first to isolate issue * * * **Problem:** “Local AI providers not working” **Solutions:** 1. Verify local service is running: `curl http://localhost:11434` (for Ollama) 2. Check AI provider settings have correct local URL 3. Local services should bypass proxy automatically 4. Check service-specific documentation * * * **Problem:** “Works with some AI providers, not others” **Solutions:** 1. Some providers may have different network requirements 2. Check provider-specific base URL in settings 3. Try with “System Proxy” type 4. Verify API key is correct for the failing provider * * * ### Getting Help [Section titled “Getting Help”](https://askimo.chat/docs/desktop/proxy-configuration/#getting-help) If proxy issues persist: 1. **Check Logs:** Open Settings → Advanced → View Logs 2. **Test Without Proxy:** Temporarily set to “No Proxy” to isolate issue 3. **Contact Support:** Include proxy type (without credentials) and error messages 4. **Community:** Ask in Askimo community forums with anonymized configuration * * * Best Practices -------------- [Section titled “Best Practices”](https://askimo.chat/docs/desktop/proxy-configuration/#best-practices) ### Security [Section titled “Security”](https://askimo.chat/docs/desktop/proxy-configuration/#security) ✅ **Do:** * Use System Proxy when available for credential security * Change proxy password regularly if stored in config * Use HTTPS proxy instead of HTTP when available * Limit file permissions on `askimo.yml` (`chmod 600` on Unix) ❌ **Don’t:** * Share your `askimo.yml` file (contains credentials) * Use untrusted proxy servers * Store production credentials in plain text long-term ### Performance [Section titled “Performance”](https://askimo.chat/docs/desktop/proxy-configuration/#performance) ✅ **Do:** * Use local AI providers (Ollama, LM Studio) for best performance * Prefer System Proxy to leverage OS optimizations * Use HTTP proxy over SOCKS5 if both are available (faster) ❌ **Don’t:** * Route local services through proxy unnecessarily * Use Tor for real-time applications (very slow) * Chain multiple proxies ### Network Switching [Section titled “Network Switching”](https://askimo.chat/docs/desktop/proxy-configuration/#network-switching) ✅ **Do:** * Use System Proxy for automatic adaptation * Create network-specific configurations * Test after switching networks ❌ **Don’t:** * Forget to disable proxy when leaving corporate network * Leave old proxy settings when they’re no longer needed * * * Summary ------- [Section titled “Summary”](https://askimo.chat/docs/desktop/proxy-configuration/#summary) Askimo provides flexible proxy configuration to work in any network environment: * **Corporate Networks**: HTTP/HTTPS proxy with authentication * **Privacy**: SOCKS5 proxy, Tor support * **Convenience**: System proxy for automatic configuration * **Performance**: Automatic localhost bypass for local AI providers Configure once, and Askimo handles the rest – connecting to external AI providers through your proxy while keeping local services fast and direct. **Need Help?** Check the [Troubleshooting](https://askimo.chat/docs/desktop/proxy-configuration/#troubleshooting) section or visit our community forums. --- # Update Askimo App on macOS | Askimo [Skip to content](https://askimo.chat/docs/desktop/updating/macos/#_top) Update Askimo App on macOS ========================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Before You Start ---------------- [Section titled “Before You Start”](https://askimo.chat/docs/desktop/updating/macos/#before-you-start) * **Quit Askimo** if it is currently running (`⌘Q` or menu → Quit Askimo). * Your sessions, settings, and API keys in `~/.askimo/personal/` are untouched by the update. Option 1: DMG (Recommended) --------------------------- [Section titled “Option 1: DMG (Recommended)”](https://askimo.chat/docs/desktop/updating/macos/#option-1-dmg-recommended) **Choose your Mac type:** * **Apple Silicon (M1/M2/M3):** [Download Askimo for Apple Silicon](https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-macos-arm64.dmg) * **Intel:** [Download Askimo for Intel](https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-macos-x64.dmg) **Update steps:** 1. Download the appropriate `.dmg` file for your Mac. 2. Open the `.dmg` file. 3. Drag `Askimo` into the `Applications` folder — click **Replace** when macOS asks. 4. Eject the DMG and launch Askimo from Applications. Option 2: Universal JAR ----------------------- [Section titled “Option 2: Universal JAR”](https://askimo.chat/docs/desktop/updating/macos/#option-2-universal-jar) **Choose your Mac type:** * **Apple Silicon:** [Download JAR for Apple Silicon](https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-macos-arm64.jar) * **Intel:** [Download JAR for Intel](https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-macos-x64.jar) **Update steps:** 1. Download the `.jar` file for your Mac. 2. Replace your existing JAR with the new one. 3. Restart Askimo: java -jar askimo-desktop-macos-arm64.jar # Apple Silicon# ORjava -jar askimo-desktop-macos-x64.jar # Intel Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/updating/macos/#troubleshooting) | Issue | Fix | | --- | --- | | Gatekeeper blocks the updated app | System Settings → Privacy & Security → Open Anyway | | App won’t start | Reboot; confirm you are on macOS 10.15 or later | | App still shows old version | Quit the old version before replacing the app | Related Guides -------------- [Section titled “Related Guides”](https://askimo.chat/docs/desktop/updating/macos/#related-guides) * [Windows update](https://askimo.chat/docs/desktop/updating/windows/) * [Linux update](https://askimo.chat/docs/desktop/updating/linux/) * [macOS installation (fresh install)](https://askimo.chat/docs/desktop/installation/macos/) --- # ChatGPT Desktop App - Free OpenAI Desktop Client for Mac, Windows & Linux | Askimo [Skip to content](https://askimo.chat/docs/desktop/providers/openai/#_top) ChatGPT Desktop App - Free OpenAI Desktop Client for Mac, Windows & Linux ========================================================================= We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) ChatGPT Desktop App - Askimo OpenAI Client ------------------------------------------ [Section titled “ChatGPT Desktop App - Askimo OpenAI Client”](https://askimo.chat/docs/desktop/providers/openai/#chatgpt-desktop-app---askimo-openai-client) Looking for a **ChatGPT desktop app**? Askimo is a free, open-source **OpenAI desktop client** that works on Mac, Windows, and Linux. Get a powerful **ChatGPT desktop application** with advanced features, multiple AI models, and complete control over your AI conversations. ### Why Choose Askimo as Your ChatGPT Desktop App? [Section titled “Why Choose Askimo as Your ChatGPT Desktop App?”](https://askimo.chat/docs/desktop/providers/openai/#why-choose-askimo-as-your-chatgpt-desktop-app) * **Free & Open Source** - No subscription required for the desktop client * **All GPT Models** - Access the latest OpenAI models and more * **Cross-Platform** - Works on macOS, Windows, and Linux * **Multiple AI Models** - Use OpenAI alongside Claude, Gemini, and Ollama * **Privacy-Focused** - Your API key and conversations stay secure * **Advanced Features** - Custom directives, RAG, chat search, and themes Setting Up OpenAI in Askimo Desktop App --------------------------------------- [Section titled “Setting Up OpenAI in Askimo Desktop App”](https://askimo.chat/docs/desktop/providers/openai/#setting-up-openai-in-askimo-desktop-app) Connect Askimo to OpenAI’s powerful AI models and start using them instantly. ### API Configuration [Section titled “API Configuration”](https://askimo.chat/docs/desktop/providers/openai/#api-configuration) * **API Key**: Your OpenAI API key (required) * Get your key from [platform.openai.com/api-keys](https://platform.openai.com/api-keys) * **Organization ID**: (Optional) For team accounts * **Default Model**: Choose from the latest OpenAI models available via your API key. Askimo automatically reflects the models supported by your account — refer to the [OpenAI Models](https://platform.openai.com/docs/models) page for the current list. * **Base URL**: (Advanced) Custom endpoint for proxies * Default: `https://api.openai.com/v1` * **Timeout**: Request timeout in seconds (default: 60s) ### Setting Up Your API Key [Section titled “Setting Up Your API Key”](https://askimo.chat/docs/desktop/providers/openai/#setting-up-your-api-key) 1. Visit [OpenAI Platform](https://platform.openai.com/api-keys) 2. Sign in or create an account 3. Click “Create new secret key” 4. Copy the key (you won’t see it again!) 5. Paste it into Askimo’s OpenAI API Key field 6. Click “Test Connection” to verify ### Accessing Provider Settings [Section titled “Accessing Provider Settings”](https://askimo.chat/docs/desktop/providers/openai/#accessing-provider-settings) 1. Click on the menu bar 2. Select “Settings” 3. Navigate to the “AI Providers” tab 4. Select “OpenAI” from the provider list **Keyboard Shortcut**: `⌘ + ,` (macOS) or `Ctrl + ,` (Windows/Linux) then click “AI Providers” ### Troubleshooting [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/providers/openai/#troubleshooting) **Connection Failed?** * Verify your API key is correct * Check your internet connection * Ensure you have API credits available * Try increasing the timeout setting **Model Not Available?** * Some models require specific API access levels * Check the [OpenAI Models](https://platform.openai.com/docs/models) page for availability --- # Install Askimo App on macOS | Askimo [Skip to content](https://askimo.chat/docs/desktop/installation/macos/#_top) Install Askimo App on macOS =========================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) System Requirements ------------------- [Section titled “System Requirements”](https://askimo.chat/docs/desktop/installation/macos/#system-requirements) * macOS 10.15 (Catalina) or later * 200MB free disk space * Internet connection for provider setup Installation Methods -------------------- [Section titled “Installation Methods”](https://askimo.chat/docs/desktop/installation/macos/#installation-methods) ### Option 1: DMG (Recommended) [Section titled “Option 1: DMG (Recommended)”](https://askimo.chat/docs/desktop/installation/macos/#option-1-dmg-recommended) **Choose your Mac type:** * **Apple Silicon:** [Download Askimo for Apple Silicon](https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-macos-arm64.dmg) * **Intel:** [Download Askimo for Intel](https://github.com/askimo-ai/askimo/releases/latest/download/Askimo-Desktop-macos-x64.dmg) **Installation steps:** 1. Download the appropriate `.dmg` file for your Mac. 2. Open the `.dmg` file. 3. Drag `Askimo` to the `Applications` folder. 4. Launch Askimo from Applications. ### Option 2: Universal JAR [Section titled “Option 2: Universal JAR”](https://askimo.chat/docs/desktop/installation/macos/#option-2-universal-jar) If you prefer to run Askimo App using Java, or if the DMG doesn’t work for your system: **Prerequisites:** * Java Runtime Environment (JRE) 21 or higher must be installed * Verify your Java version: java -version **Choose your Mac type:** * **Apple Silicon:** [Download JAR for Apple Silicon](https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-macos-arm64.jar) * **Intel:** [Download JAR for Intel](https://github.com/askimo-ai/askimo/releases/latest/download/askimo-desktop-macos-x64.jar) **Installation Steps:** 1. Download the appropriate `.jar` file for your Mac. 2. Run Askimo App with: java -jar askimo-desktop-macos-arm64.jar # For Apple Silicon# ORjava -jar askimo-desktop-macos-x64.jar # For Intel **Optional: Create an alias for easier access** Add this to your `~/.zshrc` or `~/.bash_profile`: # For Apple Siliconalias askimo-desktop="java -jar /path/to/askimo-desktop-macos-arm64.jar"# OR for Intelalias askimo-desktop="java -jar /path/to/askimo-desktop-macos-x64.jar" First Launch Security --------------------- [Section titled “First Launch Security”](https://askimo.chat/docs/desktop/installation/macos/#first-launch-security) On first launch, macOS may block the app: 1. Open System Settings → Privacy & Security. 2. Scroll to the security prompt for Askimo. 3. Click “Open Anyway”. Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/installation/macos/#troubleshooting) | Issue | Fix | | --- | --- | | Gatekeeper warning | Use Open Anyway in Privacy & Security | | App won’t start | Reboot; ensure you’re on supported macOS version | | Brew cask not found | Run `brew update` then retry | Related Guides -------------- [Section titled “Related Guides”](https://askimo.chat/docs/desktop/installation/macos/#related-guides) * [Windows installation](https://askimo.chat/docs/desktop/installation/windows/) * [Linux installation](https://askimo.chat/docs/desktop/installation/linux/) --- # Askimo CLI Architecture Guide | Askimo [Skip to content](https://askimo.chat/docs/development/cli-high-level-architecture/#_top) Askimo CLI Architecture Guide ============================= We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Overview -------- [Section titled “Overview”](https://askimo.chat/docs/development/cli-high-level-architecture/#overview) The Askimo CLI is a command-line interface application that provides interactive and non-interactive modes for AI-powered assistance. It supports piped input, recipe execution, and rich terminal interactions with command history and auto-completion. ### Key Technologies [Section titled “Key Technologies”](https://askimo.chat/docs/development/cli-high-level-architecture/#key-technologies) * **Language:** Kotlin * **Terminal Framework:** JLine 3 * **Architecture Pattern:** Command Pattern + Session Management * **Concurrency:** Kotlin Coroutines * **Persistence:** Shared with Desktop module (SQLite via Exposed) Architecture Overview --------------------- [Section titled “Architecture Overview”](https://askimo.chat/docs/development/cli-high-level-architecture/#architecture-overview) The CLI application follows a **command-driven architecture** with clear separation between interactive and non-interactive modes: graph TD A[Terminal Layer
JLine Terminal & Input Processing] B[Command Layer
Command Handlers & Parsers] C[Session Layer
Session Management & Chat Service] D[Core Layer
Shared Module: Providers, Repository, Recipes] A --> B B --> C C --> D style A fill:#e1f5ff,stroke:#0288d1,stroke-width:2px style B fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style C fill:#fff3e0,stroke:#ef6c00,stroke-width:2px style D fill:#e8f5e9,stroke:#388e3c,stroke-width:2px ### Design Principles [Section titled “Design Principles”](https://askimo.chat/docs/development/cli-high-level-architecture/#design-principles) 1. **Mode Separation:** Clear distinction between interactive and non-interactive modes 2. **Command Pattern:** Each operation is encapsulated as a command handler 3. **Session-Centric:** All operations revolve around a chat session 4. **Stream-Friendly:** First-class support for piped input/output 5. **Extensibility:** Easy to add new commands and recipes Module Organization ------------------- [Section titled “Module Organization”](https://askimo.chat/docs/development/cli-high-level-architecture/#module-organization) The CLI module is organized into the following key packages: cli/├── ChatCli.kt # Application entry point and main loop├── commands/ # Command handlers│ ├── HelpCommandHandler.kt│ ├── ConfigCommandHandler.kt│ ├── SessionCommandHandlers.kt│ └── ...├── recipes/ # Recipe system│ ├── RecipeExecutor.kt│ ├── RecipeRegistry.kt│ ├── ToolRegistry.kt│ └── DefaultRecipeInitializer.kt├── util/ # Utilities│ ├── CompositeCommandExecutor.kt│ ├── NonInteractiveCommandParser.kt│ └── ...├── autocompleter/ # Terminal auto-completion│ └── CliCommandCompleter.kt├── LoadingIndicator.kt # Terminal UI feedback├── MarkdownJLineRenderer.kt # Markdown rendering in terminal└── MarkdownStreamingSink.kt # Streaming output handler ### Package Responsibilities [Section titled “Package Responsibilities”](https://askimo.chat/docs/development/cli-high-level-architecture/#package-responsibilities) | Package | Purpose | | --- | --- | | `commands/` | Command handlers for both interactive and non-interactive modes | | `recipes/` | YAML-based automation recipes and execution engine | | `util/` | Command parsing, execution, and utility functions | | `autocompleter/` | JLine auto-completion for commands | | Root package | Main entry point, rendering, and terminal interaction | Architectural Layers -------------------- [Section titled “Architectural Layers”](https://askimo.chat/docs/development/cli-high-level-architecture/#architectural-layers) ### 1\. Terminal Layer (JLine) [Section titled “1. Terminal Layer (JLine)”](https://askimo.chat/docs/development/cli-high-level-architecture/#1-terminal-layer-jline) Handles all terminal I/O, user input, and rendering. Provides rich terminal features like history, auto-completion, and multi-line input. **Key Components:** * **Terminal:** Low-level terminal control * **LineReader:** Interactive line reading with history * **Parser:** Multi-line input parsing with continuation support * **Completer:** Command and argument auto-completion **Features:** * Command history with search (Ctrl+R) * Tab completion for commands * Multi-line input with backslash continuation * Markdown rendering in terminal * Loading indicators and progress feedback ### 2\. Command Layer [Section titled “2. Command Layer”](https://askimo.chat/docs/development/cli-high-level-architecture/#2-command-layer) Implements the Command Pattern for handling user actions. Each command is a self-contained handler. **Command Types:** **Shared Commands** (available in both modes): * Help, Config, Providers, Models, Parameters, Tools, Version **Interactive-Only Commands:** * Copy, Clear Memory, Project Management, Session Management **Non-Interactive-Only Commands:** * Recipe Management (Create, List, Delete) **Command Handler Interface:** Command Handler├── keyword: String (e.g., ":help", ":config")├── handle(ParsedLine): Unit└── getDescription(): String ### 3\. Session Layer [Section titled “3. Session Layer”](https://askimo.chat/docs/development/cli-high-level-architecture/#3-session-layer) Manages the chat session lifecycle and coordinates with the Core layer. **Key Components:** * **Session:** Maintains conversation state and context * **ChatService:** Coordinates message sending and streaming * **SessionMode:** Differentiates between CLI\_INTERACTIVE and CLI\_PROMPT modes **Responsibilities:** * Maintain conversation history * Manage provider and model configuration * Handle context preparation * Coordinate streaming responses ### 4\. Core Layer (Shared Module) [Section titled “4. Core Layer (Shared Module)”](https://askimo.chat/docs/development/cli-high-level-architecture/#4-core-layer-shared-module) Shared functionality used by both CLI and Desktop applications. **Components:** * **Providers:** AI provider integrations (OpenAI, Anthropic, etc.) * **Repository:** Data persistence layer * **Session:** Core session management * **Recipes:** YAML-based automation definitions Execution Modes --------------- [Section titled “Execution Modes”](https://askimo.chat/docs/development/cli-high-level-architecture/#execution-modes) The CLI supports three distinct execution modes: ### 1\. Interactive Mode (Default) [Section titled “1. Interactive Mode (Default)”](https://askimo.chat/docs/development/cli-high-level-architecture/#1-interactive-mode-default) Launched when no arguments are provided. Provides a REPL-style interface. askimo> [user input] **Features:** * Command history and search * Tab completion * Multi-line input with `\` continuation * Session management * Real-time streaming responses ### 2\. Prompt Mode [Section titled “2. Prompt Mode”](https://askimo.chat/docs/development/cli-high-level-architecture/#2-prompt-mode) Single prompt execution with optional piped input. askimo -p "your prompt" < input.txtaskimo -p "direct prompt"echo "data" | askimo -p "analyze this" **Features:** * One-shot execution * Stdin piping support * Automatic context building from piped input ### 3\. Recipe Mode [Section titled “3. Recipe Mode”](https://askimo.chat/docs/development/cli-high-level-architecture/#3-recipe-mode) Execute YAML-defined automation recipes. askimo -r recipe-name --set key=value **Features:** * Multi-step automation * Variable substitution * External tool integration * Retry logic with exponential backoff Data Flow --------- [Section titled “Data Flow”](https://askimo.chat/docs/development/cli-high-level-architecture/#data-flow) The application follows different flows depending on the execution mode: ### Interactive Chat Flow [Section titled “Interactive Chat Flow”](https://askimo.chat/docs/development/cli-high-level-architecture/#interactive-chat-flow) graph TD A[User Input
JLine LineReader] --> B[Parser
Parse command or chat message] B -->|Command| C[CommandHandler] B -->|Chat Message| D[Session] C --> E[Execute] D --> F[Provider] F --> G[Stream Response] G --> H[Terminal Output] style A fill:#e1f5ff,stroke:#0288d1,stroke-width:2px style B fill:#fff3e0,stroke:#ef6c00,stroke-width:2px style C fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style D fill:#e8f5e9,stroke:#388e3c,stroke-width:2px style E fill:#fce4ec,stroke:#c2185b,stroke-width:2px style F fill:#e8f5e9,stroke:#388e3c,stroke-width:2px style G fill:#fff9c4,stroke:#f57f17,stroke-width:2px style H fill:#e1f5ff,stroke:#0288d1,stroke-width:2px ### Recipe Execution Flow [Section titled “Recipe Execution Flow”](https://askimo.chat/docs/development/cli-high-level-architecture/#recipe-execution-flow) graph TD A[Recipe Name] --> B[Registry] B --> C[Executor] C --> D[Steps] D --> E[Prompt Step] D --> F[Tool Step] D --> G[Loop Step] D --> H[Parallel Step] E --> I[Output/Result] F --> I G --> I H --> I style A fill:#e1f5ff,stroke:#0288d1,stroke-width:2px style B fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style C fill:#fff3e0,stroke:#ef6c00,stroke-width:2px style D fill:#e8f5e9,stroke:#388e3c,stroke-width:2px style E fill:#fce4ec,stroke:#c2185b,stroke-width:2px style F fill:#fce4ec,stroke:#c2185b,stroke-width:2px style G fill:#fce4ec,stroke:#c2185b,stroke-width:2px style H fill:#fce4ec,stroke:#c2185b,stroke-width:2px style I fill:#fff9c4,stroke:#f57f17,stroke-width:2px Key Design Patterns ------------------- [Section titled “Key Design Patterns”](https://askimo.chat/docs/development/cli-high-level-architecture/#key-design-patterns) ### 1\. Command Pattern [Section titled “1. Command Pattern”](https://askimo.chat/docs/development/cli-high-level-architecture/#1-command-pattern) Each user action is encapsulated as a command handler with a consistent interface: * Keyword-based routing * Unified handling mechanism * Easy to add new commands ### 2\. Mode-Based Architecture [Section titled “2. Mode-Based Architecture”](https://askimo.chat/docs/development/cli-high-level-architecture/#2-mode-based-architecture) The CLI adapts its behavior based on execution mode: * Interactive: Full REPL with terminal features * Prompt: One-shot execution with piping support * Recipe: Multi-step automation with tool integration ### 3\. Streaming Response Handling [Section titled “3. Streaming Response Handling”](https://askimo.chat/docs/development/cli-high-level-architecture/#3-streaming-response-handling) AI responses are streamed in real-time: * Token-by-token rendering * Markdown formatting on-the-fly * Loading indicators with elapsed time * Non-blocking terminal updates ### 4\. Recipe System [Section titled “4. Recipe System”](https://askimo.chat/docs/development/cli-high-level-architecture/#4-recipe-system) YAML-based declarative automation: * Step-by-step execution * Variable substitution and overrides * Tool allowlisting for security * Retry logic for transient failures Recipe System ------------- [Section titled “Recipe System”](https://askimo.chat/docs/development/cli-high-level-architecture/#recipe-system) The recipe system provides YAML-based automation for complex multi-step tasks. ### Recipe Structure [Section titled “Recipe Structure”](https://askimo.chat/docs/development/cli-high-level-architecture/#recipe-structure) name: exampledescription: Example recipesteps: - type: prompt prompt: "Step 1 prompt" - type: tool tool: read_file args: path: "file.txt" ### Step Types [Section titled “Step Types”](https://askimo.chat/docs/development/cli-high-level-architecture/#step-types) * **prompt:** Send a prompt to AI * **tool:** Execute a tool (file operations, code execution, etc.) * **loop:** Iterate over items * **parallel:** Execute steps concurrently ### Tool Registry [Section titled “Tool Registry”](https://askimo.chat/docs/development/cli-high-level-architecture/#tool-registry) Manages available tools and enforces security: * Default tools (file operations, search, etc.) * Tool allowlisting per recipe * Safe execution environment Platform Support ---------------- [Section titled “Platform Support”](https://askimo.chat/docs/development/cli-high-level-architecture/#platform-support) The CLI runs on multiple platforms with terminal-specific adaptations: ### Supported Platforms [Section titled “Supported Platforms”](https://askimo.chat/docs/development/cli-high-level-architecture/#supported-platforms) * **macOS:** Full terminal support with native features * **Windows:** PowerShell and CMD support * **Linux:** Bash, Zsh, and other shell support ### Terminal Features [Section titled “Terminal Features”](https://askimo.chat/docs/development/cli-high-level-architecture/#terminal-features) **Input Handling:** * Stdin piping for data processing * Multi-line input with continuation * Command history persistence * Auto-completion **Output Rendering:** * ANSI color support * Markdown rendering with syntax highlighting * Loading indicators * Streaming output Development Guidelines ---------------------- [Section titled “Development Guidelines”](https://askimo.chat/docs/development/cli-high-level-architecture/#development-guidelines) ### Adding New Commands [Section titled “Adding New Commands”](https://askimo.chat/docs/development/cli-high-level-architecture/#adding-new-commands) 1. Create a new command handler implementing `CommandHandler` 2. Define keyword (e.g., `:mycommand`) 3. Implement `handle(ParsedLine)` method 4. Add to appropriate command list (shared/interactive/non-interactive) 5. Update help text ### Creating Recipes [Section titled “Creating Recipes”](https://askimo.chat/docs/development/cli-high-level-architecture/#creating-recipes) 1. Define recipe in YAML format 2. Place in recipes directory or user config 3. Use variable substitution with `${var}` syntax 4. Test with `--set` overrides 5. Document in recipe list ### Terminal Rendering [Section titled “Terminal Rendering”](https://askimo.chat/docs/development/cli-high-level-architecture/#terminal-rendering) * Use `MarkdownJLineRenderer` for formatted output * Show loading indicators for long operations * Stream responses token-by-token for better UX * Handle terminal width and scrolling gracefully External Resources ------------------ [Section titled “External Resources”](https://askimo.chat/docs/development/cli-high-level-architecture/#external-resources) * [JLine 3 Documentation](https://github.com/jline/jline3) * [Kotlin Coroutines](https://kotlinlang.org/docs/coroutines-overview.html) * [YAML Specification](https://yaml.org/spec/) Contributing ------------ [Section titled “Contributing”](https://askimo.chat/docs/development/cli-high-level-architecture/#contributing) When contributing to the CLI module, please: 1. Follow the Command Pattern for new features 2. Support both interactive and non-interactive modes where applicable 3. Write tests for command handlers 4. Update help text and documentation 5. Follow Kotlin coding conventions --- # Create Custom Commands in Askimo CLI | Askimo [Skip to content](https://askimo.chat/docs/development/creating-new-command/#_top) Create Custom Commands in Askimo CLI ==================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) This guide explains how to implement a new command in the Askimo CLI. By following these steps, you can add custom functionality to the command-line interface. Architecture Overview --------------------- [Section titled “Architecture Overview”](https://askimo.chat/docs/development/creating-new-command/#architecture-overview) Askimo uses a simple command handling architecture with the following key components: 1. **CommandHandler**: Interface that defines the contract for all command handlers 2. **Command implementations**: Classes that implement the CommandHandler interface 3. **Command registration**: Process of adding commands to the CLI application Each command is identified by a keyword (starting with a colon) and has a description and handling logic. Implementation Steps -------------------- [Section titled “Implementation Steps”](https://askimo.chat/docs/development/creating-new-command/#implementation-steps) ### 1\. Create a New Command Handler [Section titled “1. Create a New Command Handler”](https://askimo.chat/docs/development/creating-new-command/#1-create-a-new-command-handler) First, create a new class that implements the `CommandHandler` interface. This class will handle your specific command: /** * Handles the command to [describe what your command does]. * * This class provides functionality to [explain the purpose and functionality of your command]. */class YourCommandHandler( private val session: Session, // Include any dependencies your command needs) : CommandHandler { override val keyword: String = ":yourcommand" // Command keyword (starts with colon) override val description: String = "Description of what your command does." override fun handle(line: ParsedLine) { // Implement your command logic here // Example: Access command arguments val args = line.words().drop(1) // Skip the command itself // Example: Access the current session val provider = session.getActiveProvider() val modelName = session.params.getModel(provider) // Example: Print output to the console println("✅ Your command executed successfully!") }} ### 2\. Register Your Command [Section titled “2. Register Your Command”](https://askimo.chat/docs/development/creating-new-command/#2-register-your-command) To make your command available in the CLI, add it to the list of command handlers in the `main` function in `ChatCli.kt`: // In ChatCli.kt val commandHandlers: List = listOf( HelpCommandHandler(), ConfigCommand(session), ParamsCommandHandler(session), SetParamCommandHandler(session), ListProvidersCommandHandler(), SetProviderCommandHandler(session), ModelsCommandHandler(session), CopyCommandHandler(session), ClearMemoryCommandHandler(session), YourCommandHandler(session), // Add your command here ) ### 3\. Command Implementation Example [Section titled “3. Command Implementation Example”](https://askimo.chat/docs/development/creating-new-command/#3-command-implementation-example) Let’s look at a real example: the `ClearMemoryCommandHandler` which clears the chat memory for the current provider and model: /** * Handles the command to clear the chat memory. * * This class provides functionality to reset the conversation history for the current * provider and model combination. It allows users to start fresh conversations without * changing their model configuration. */class ClearMemoryCommandHandler( private val session: Session,) : CommandHandler { override val keyword: String = ":clear" override val description: String = "Clear the current chat memory for the active provider/model." override fun handle(line: ParsedLine) { val provider = session.getActiveProvider() val modelName = session.params.getModel(provider) session.removeMemory(provider, modelName) println("🧹 Chat memory cleared for $provider / $modelName") }} This command: 1. Gets the current provider and model from the session 2. Calls the session’s `removeMemory` method to clear the chat history 3. Prints a confirmation message to the user ### 4\. Working with Command Arguments [Section titled “4. Working with Command Arguments”](https://askimo.chat/docs/development/creating-new-command/#4-working-with-command-arguments) If your command needs to handle arguments, you can access them from the `ParsedLine` object: override fun handle(line: ParsedLine) { val args = line.words().drop(1) // Skip the command itself if (args.isEmpty()) { println("❌ This command requires arguments.") println("Usage: ${keyword} ") return } val arg1 = args[0] val arg2 = args.getOrNull(1) // Safely get optional arguments // Process arguments...} ### 5\. Accessing Session Data [Section titled “5. Accessing Session Data”](https://askimo.chat/docs/development/creating-new-command/#5-accessing-session-data) The `Session` object provides access to various aspects of the application state: // Get the active providerval provider = session.getActiveProvider() // Get the current model for a providerval modelName = session.params.getModel(provider) // Get a parameter valueval paramValue = session.params.get(ParamKey.SYSTEM_PROMPT) // Set a parameter valuesession.params.set(ParamKey.SYSTEM_PROMPT, "New value") // Get the current chat modelval model = session.getChatModel() // Store the last responsesession.lastResponse = "Response text" Best Practices -------------- [Section titled “Best Practices”](https://askimo.chat/docs/development/creating-new-command/#best-practices) ### Command Naming Conventions [Section titled “Command Naming Conventions”](https://askimo.chat/docs/development/creating-new-command/#command-naming-conventions) * Command keywords should start with a colon (`:`) * Use lowercase for command names * Use simple, descriptive names that clearly indicate the command’s purpose ### Command Implementation [Section titled “Command Implementation”](https://askimo.chat/docs/development/creating-new-command/#command-implementation) * Keep commands focused on a single responsibility * Provide clear feedback to the user about what happened * Handle errors gracefully with helpful error messages * Use emojis for visual feedback (e.g., ✅, ❌, 🧹) * Include detailed documentation in the class comment ### Command Description [Section titled “Command Description”](https://askimo.chat/docs/development/creating-new-command/#command-description) * Keep descriptions concise but informative * Start with a verb (e.g., “Clear”, “Set”, “Show”) * Make sure the description clearly explains what the command does Testing Your Command -------------------- [Section titled “Testing Your Command”](https://askimo.chat/docs/development/creating-new-command/#testing-your-command) After implementing your command, you can test it by: 1. Building and running the Askimo CLI 2. Using your command with the appropriate syntax: askimo> :yourcommand [arguments] 3. Verifying that the command produces the expected output and behavior Conclusion ---------- [Section titled “Conclusion”](https://askimo.chat/docs/development/creating-new-command/#conclusion) By following these steps, you can extend the Askimo CLI with custom commands. The command handler architecture makes it easy to add new functionality while maintaining a consistent interface for users. Remember to handle errors gracefully and provide clear feedback to users when something goes wrong with your command. --- # Askimo App Architecture Guide | Askimo [Skip to content](https://askimo.chat/docs/development/desktop-high-level-architecture/#_top) Askimo App Architecture Guide ============================= We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Overview -------- [Section titled “Overview”](https://askimo.chat/docs/development/desktop-high-level-architecture/#overview) The Askimo App application is a native desktop client built with **Jetpack Compose for Desktop**. It provides a rich, responsive user interface for interacting with AI assistants across multiple providers. ### Key Technologies [Section titled “Key Technologies”](https://askimo.chat/docs/development/desktop-high-level-architecture/#key-technologies) * **UI Framework:** Jetpack Compose for Desktop * **Language:** Kotlin * **Architecture Pattern:** MVVM (Model-View-ViewModel) * **Dependency Injection:** Koin * **Concurrency:** Kotlin Coroutines * **Persistence:** Shared with CLI module (SQLite via Exposed) Architecture Overview --------------------- [Section titled “Architecture Overview”](https://askimo.chat/docs/development/desktop-high-level-architecture/#architecture-overview) The desktop application follows a **layered architecture** with clear separation of concerns: graph TD A[UI Layer
Jetpack Compose Views & Components] B[ViewModel Layer
State Management & UI Logic] C[Service Layer
Business Logic & Coordination] D[Core Layer
Shared Module: Providers, Session, Repository] A --> B B --> C C --> D style A fill:#e1f5ff,stroke:#0288d1,stroke-width:2px style B fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style C fill:#fff3e0,stroke:#ef6c00,stroke-width:2px style D fill:#e8f5e9,stroke:#388e3c,stroke-width:2px ### Design Principles [Section titled “Design Principles”](https://askimo.chat/docs/development/desktop-high-level-architecture/#design-principles) 1. **Separation of Concerns:** Each layer has a specific responsibility 2. **Unidirectional Data Flow:** Data flows down, events flow up 3. **Reactive Programming:** UI automatically updates when state changes 4. **Single Source of Truth:** State is owned by ViewModels 5. **Dependency Injection:** Loose coupling between components Module Organization ------------------- [Section titled “Module Organization”](https://askimo.chat/docs/development/desktop-high-level-architecture/#module-organization) The desktop module is organized into the following key packages: desktop/├── Main.kt # Application entry point├── viewmodel/ # ViewModels (UI state management)├── service/ # Business logic services├── ui/ # UI components│ ├── views/ # Main application views│ ├── components/ # Reusable UI components│ └── theme/ # Theming and styling├── model/ # UI data models├── di/ # Dependency injection configuration├── i18n/ # Internationalization├── keymap/ # Keyboard shortcuts└── util/ # Utility classes ### Package Responsibilities [Section titled “Package Responsibilities”](https://askimo.chat/docs/development/desktop-high-level-architecture/#package-responsibilities) | Package | Purpose | | --- | --- | | `viewmodel/` | Manages UI state and handles user actions | | `service/` | Contains business logic and coordinates operations | | `ui/views/` | Main application screens (Chat, Sessions, Settings) | | `ui/components/` | Reusable UI elements (dialogs, message bubbles, etc.) | | `ui/theme/` | Color schemes, typography, and theme management | | `model/` | Data classes for UI representation | | `di/` | Koin dependency injection modules | | `i18n/` | Multi-language support | | `keymap/` | Keyboard shortcut management | | `util/` | Helper functions and utilities | Architectural Layers -------------------- [Section titled “Architectural Layers”](https://askimo.chat/docs/development/desktop-high-level-architecture/#architectural-layers) ### 1\. UI Layer (Jetpack Compose) [Section titled “1. UI Layer (Jetpack Compose)”](https://askimo.chat/docs/development/desktop-high-level-architecture/#1-ui-layer-jetpack-compose) The presentation layer built with Compose for Desktop. Responsible for rendering the user interface and capturing user interactions. **Main Views:** * **ChatView:** Primary chat interface * **SessionsView:** Session list and management * **SettingsView:** Application configuration * **AboutView:** Application information **Reusable Components:** * Message bubbles with markdown and code highlighting * File attachment handling * Dialogs and modals * Tooltips and dropdowns * Theme-aware styling ### 2\. ViewModel Layer (MVVM Pattern) [Section titled “2. ViewModel Layer (MVVM Pattern)”](https://askimo.chat/docs/development/desktop-high-level-architecture/#2-viewmodel-layer-mvvm-pattern) Manages UI state and handles user actions. Acts as the bridge between UI and business logic. **ViewModels:** * **ChatViewModel:** Chat state, messages, streaming responses * **SessionsViewModel:** Session list, operations (star, delete, rename) * **SettingsViewModel:** Configuration and preferences **Responsibilities:** * Maintain UI state * Handle user actions * Coordinate with services * Manage lifecycle and cleanup ### 3\. Service Layer [Section titled “3. Service Layer”](https://askimo.chat/docs/development/desktop-high-level-architecture/#3-service-layer) Contains business logic and coordinates operations between ViewModels and the Core layer. **Key Services:** * **ChatService:** Chat operations and session management * **StreamingService:** AI response streaming coordination * **ThemePreferences:** User preference persistence **Responsibilities:** * Encapsulate business rules * Provide clean APIs to ViewModels * Handle concurrent operations * Manage resource lifecycle ### 4\. Core Layer (Shared Module) [Section titled “4. Core Layer (Shared Module)”](https://askimo.chat/docs/development/desktop-high-level-architecture/#4-core-layer-shared-module) Shared functionality used by both CLI and Desktop applications. Provides core AI chat capabilities. **Components:** * **Session:** Chat session management * **Providers:** AI provider integrations (OpenAI, Anthropic, etc.) * **Repository:** Data persistence layer * **Models:** Domain models ### 5\. Cross-Cutting Concerns [Section titled “5. Cross-Cutting Concerns”](https://askimo.chat/docs/development/desktop-high-level-architecture/#5-cross-cutting-concerns) **Dependency Injection (Koin):** * Manages component lifecycle * Provides loose coupling * Supports testability **Internationalization:** * Multi-language support (English, Japanese, Vietnamese) * Localized UI strings * Parameter substitution **Platform Utilities:** * OS detection (macOS, Windows, Linux) * Keyboard shortcut management * Platform-specific behaviors Data Flow --------- [Section titled “Data Flow”](https://askimo.chat/docs/development/desktop-high-level-architecture/#data-flow) The application follows a **unidirectional data flow** pattern: graph TD A[User Input] --> B[ViewModel] B --> C[Service] C --> D[Core] B -->|State Update| E[UI Update] style A fill:#e1f5ff,stroke:#0288d1,stroke-width:2px style B fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px style C fill:#fff3e0,stroke:#ef6c00,stroke-width:2px style D fill:#e8f5e9,stroke:#388e3c,stroke-width:2px style E fill:#fce4ec,stroke:#c2185b,stroke-width:2px ### Key Flows [Section titled “Key Flows”](https://askimo.chat/docs/development/desktop-high-level-architecture/#key-flows) **Sending a Message:** 1. User types message in ChatView 2. ChatViewModel processes the input 3. ChatService coordinates with Core layer 4. AI provider streams the response 5. ViewModel updates state reactively 6. UI automatically recomposes to show response **Loading a Session:** 1. User selects session from list 2. ViewModel requests session data 3. Repository loads from database 4. ViewModel updates message list 5. UI renders the chat history Key Design Patterns ------------------- [Section titled “Key Design Patterns”](https://askimo.chat/docs/development/desktop-high-level-architecture/#key-design-patterns) ### 1\. MVVM (Model-View-ViewModel) [Section titled “1. MVVM (Model-View-ViewModel)”](https://askimo.chat/docs/development/desktop-high-level-architecture/#1-mvvm-model-view-viewmodel) The application uses the MVVM pattern to separate concerns: * **View (UI):** Jetpack Compose components that display data * **ViewModel:** Manages UI state and handles user actions * **Model:** Data layer (repositories, services, domain models) ### 2\. Reactive State Management [Section titled “2. Reactive State Management”](https://askimo.chat/docs/development/desktop-high-level-architecture/#2-reactive-state-management) State changes automatically trigger UI updates: * ViewModels expose state using Compose’s `mutableStateOf` * UI observes state changes and recomposes automatically * Kotlin Flows handle streaming data ### 3\. Dependency Injection [Section titled “3. Dependency Injection”](https://askimo.chat/docs/development/desktop-high-level-architecture/#3-dependency-injection) Koin provides loose coupling between components: * Dependencies are injected via constructors * Lifecycle management is handled automatically * Easy to swap implementations for testing ### 4\. Repository Pattern [Section titled “4. Repository Pattern”](https://askimo.chat/docs/development/desktop-high-level-architecture/#4-repository-pattern) Data access is abstracted through repositories: * ViewModels don’t directly access the database * Repositories provide a clean API for data operations * Easy to add caching or remote data sources Platform Support ---------------- [Section titled “Platform Support”](https://askimo.chat/docs/development/desktop-high-level-architecture/#platform-support) The desktop application runs on multiple platforms with platform-specific adaptations: ### Supported Platforms [Section titled “Supported Platforms”](https://askimo.chat/docs/development/desktop-high-level-architecture/#supported-platforms) * **macOS:** Full native integration with system menu and keyboard shortcuts * **Windows:** Native look and feel with Windows-specific shortcuts * **Linux:** Cross-desktop environment support ### Platform Utilities [Section titled “Platform Utilities”](https://askimo.chat/docs/development/desktop-high-level-architecture/#platform-utilities) **OS Detection:** * Centralized detection of the current operating system * Platform-specific keyboard shortcuts (Command vs. Ctrl) * Adaptive UI elements based on platform conventions **Keyboard Shortcuts:** * Platform-aware shortcut management * Consistent shortcuts across platforms where possible * Platform-specific shortcuts where appropriate (e.g., ⌘+Q vs. Alt+F4) Development Guidelines ---------------------- [Section titled “Development Guidelines”](https://askimo.chat/docs/development/desktop-high-level-architecture/#development-guidelines) ### Code Organization [Section titled “Code Organization”](https://askimo.chat/docs/development/desktop-high-level-architecture/#code-organization) * **Separation of Concerns:** Keep UI, business logic, and data layers separate * **Single Responsibility:** Each class should have one clear purpose * **Dependency Injection:** Use Koin for managing dependencies * **Reactive State:** Leverage Kotlin Flows and Compose state management ### State Management [Section titled “State Management”](https://askimo.chat/docs/development/desktop-high-level-architecture/#state-management) * ViewModels own and manage UI state * State is immutable and exposed as read-only properties * UI reacts automatically to state changes * State is scoped to ViewModel lifecycle ### Asynchronous Operations [Section titled “Asynchronous Operations”](https://askimo.chat/docs/development/desktop-high-level-architecture/#asynchronous-operations) * Use Kotlin Coroutines for all async operations * Scope coroutines to ViewModel lifecycle * Handle cancellation gracefully * Use appropriate dispatchers (IO, Default, Main) ### UI Development [Section titled “UI Development”](https://askimo.chat/docs/development/desktop-high-level-architecture/#ui-development) * Keep Composables small and focused * Extract reusable components * Use theming system for consistent styling * Never put business logic in Composables Contributing ------------ [Section titled “Contributing”](https://askimo.chat/docs/development/desktop-high-level-architecture/#contributing) When contributing to the desktop module, please: 1. Follow the MVVM architecture pattern 2. Keep layers properly separated 3. Write tests for new features 4. Update documentation as needed 5. Follow Kotlin coding conventions --- # Composite Commands Reference | Askimo [Skip to content](https://askimo.chat/docs/cli/composite-commands/#_top) Composite Commands Reference ============================ We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) What are Composite Commands? ---------------------------- [Section titled “What are Composite Commands?”](https://askimo.chat/docs/cli/composite-commands/#what-are-composite-commands) Composite commands let you chain multiple Askimo actions into a single command-line invocation — extending their power for automation, scripting, and seamless workflow execution. Syntax ------ [Section titled “Syntax”](https://askimo.chat/docs/cli/composite-commands/#syntax) askimo --command1 [args] --command2 [args] --command3 [args] ... Common Patterns --------------- [Section titled “Common Patterns”](https://askimo.chat/docs/cli/composite-commands/#common-patterns) ### Quick Setup [Section titled “Quick Setup”](https://askimo.chat/docs/cli/composite-commands/#quick-setup) # Configure everything at onceaskimo --set-provider openai \ --set-param api_key sk-abc123 \ --set-param model \ --config ### Environment Switching [Section titled “Environment Switching”](https://askimo.chat/docs/cli/composite-commands/#environment-switching) # Switch to Ollama with custom settingsaskimo --set-provider ollama \ --set-param model \ --set-param temperature 0.7 ### Multiple Parameters [Section titled “Multiple Parameters”](https://askimo.chat/docs/cli/composite-commands/#multiple-parameters) # Fine-tune model parametersaskimo --set-param temperature 0.8 \ --set-param max_tokens 2000 \ --set-param top_p 0.95 ### Information Gathering [Section titled “Information Gathering”](https://askimo.chat/docs/cli/composite-commands/#information-gathering) # Get overview of available resourcesaskimo --providers --models --tools # Check configuration and versionaskimo --config --version ### Verification [Section titled “Verification”](https://askimo.chat/docs/cli/composite-commands/#verification) # Set and verify in one commandaskimo --set-provider openai --set-param model --config All Combinable Commands ----------------------- [Section titled “All Combinable Commands”](https://askimo.chat/docs/cli/composite-commands/#all-combinable-commands) | Command | Arguments | Example | | --- | --- | --- | | `--set-provider` | provider\_name | `--set-provider openai` | | `--set-param` | key value | `--set-param model ` | | `--config` | none | `--config` | | `--providers` | none | `--providers` | | `--models` | none | `--models` | | `--params` | optional: –list | `--params --list` | | `--tools` | none | `--tools` | | `--version` | none | `--version` | | `--help` | none | `--help` | | `--create-recipe` | name, -f file | `--create-recipe -f file.yml` | | `--recipes` | none | `--recipes` | | `--delete-recipe` | name or –all | `--delete-recipe old` | Tips ---- [Section titled “Tips”](https://askimo.chat/docs/cli/composite-commands/#tips) ✅ **DO**: Order commands logically (provider before parameters) askimo --set-provider openai --set-param model ✅ **DO**: End with verification commands askimo --set-param temperature 0.7 --config ✅ **DO**: Use the same command multiple times askimo --set-param key1 val1 --set-param key2 val2 --set-param key3 val3 ⚠️ **AVOID**: Mixing interactive and non-interactive modes # ❌ Won't work - :clear is interactive-onlyaskimo --config :clear --set-provider openai Shell Aliases ------------- [Section titled “Shell Aliases”](https://askimo.chat/docs/cli/composite-commands/#shell-aliases) Create convenient aliases for common combinations: # In your ~/.zshrc or ~/.bashrcalias askimo-openai='askimo --set-provider openai --set-param model 'alias askimo-claude='askimo --set-provider anthropic --set-param model 'alias askimo-local='askimo --set-provider ollama --set-param model 'alias askimo-info='askimo --version --config --providers' Usage: $ askimo-openai --config$ askimo-local --models$ askimo-info Scripting Example ----------------- [Section titled “Scripting Example”](https://askimo.chat/docs/cli/composite-commands/#scripting-example) #!/bin/bashPROVIDER="${1:-openai}"MODEL="${2:-}"API_KEY="${OPENAI_API_KEY}" askimo --set-provider "$PROVIDER" \ --set-param api_key "$API_KEY" \ --set-param model "$MODEL" \ --config echo "✅ Askimo configured: $PROVIDER with $MODEL" Usage: $ ./setup-askimo-env.sh openai $ ./setup-askimo-env.sh ollama See Also -------- [Section titled “See Also”](https://askimo.chat/docs/cli/composite-commands/#see-also) * [Full Command Reference](https://askimo.chat/docs/cli/commands/) --- # Askimo Development & Customization Guide | Askimo [Skip to content](https://askimo.chat/docs/development/getting-started/#_top) Askimo Development & Customization Guide ======================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Welcome to the Askimo development hub. These guides show you how to extend and customize Askimo—whether you’re adding a new CLI command, integrating a new AI model provider, building reusable prompt recipes, or contributing localization for a new language. Project Structure ----------------- [Section titled “Project Structure”](https://askimo.chat/docs/development/getting-started/#project-structure) Askimo uses a **monorepo architecture** with three main modules: askimo/├── cli/ # Command-line interface (GraalVM Native Image)├── desktop/ # Desktop application (Compose Multiplatform)├── desktop-shared/ # UI shared component (Compose Multiplatform)├── shared/ # Shared core logic, models, and providers└── docs/ # Documentation ### Module Overview [Section titled “Module Overview”](https://askimo.chat/docs/development/getting-started/#module-overview) * **`cli/`**: Terminal-based REPL for interactive AI conversations and automation scripts. Built with GraalVM Native Image for fast startup and single-binary distribution. * **`desktop/`**: Native desktop application with Material Design 3 UI. Built with Compose Multiplatform for a modern, responsive user experience. * **`desktop-shared/`**: Native ui components with Material Design 3 UI. * **`shared/`**: Core business logic shared between CLI and Desktop, including: * AI provider implementations (OpenAI, Anthropic, Gemini, X AI, Ollama) * Chat models and message handling * Configuration and parameter management * Security utilities What You Can Customize ---------------------- [Section titled “What You Can Customize”](https://askimo.chat/docs/development/getting-started/#what-you-can-customize) ### Desktop Customization [Section titled “Desktop Customization”](https://askimo.chat/docs/development/getting-started/#desktop-customization) * **Localization**: Add support for new languages (see [Contributing a New Locale](https://askimo.chat/docs/development/contributing-localization/) ) * **UI Components**: Extend the Compose UI with new views and dialogs * **Themes**: Customize colors and typography ### Shared Customization [Section titled “Shared Customization”](https://askimo.chat/docs/development/getting-started/#shared-customization) * **Model Providers**: Plug in any chat model API via a factory * **Parameters & Presets**: Tune style, verbosity, and provider-specific settings * **Chat Models**: Implement custom model behaviors ### CLI Customization [Section titled “CLI Customization”](https://askimo.chat/docs/development/getting-started/#cli-customization) * **Commands**: Add new `:yourcommand` interactions in the REPL * **Recipes**: Create reusable YAML-based prompt workflows * **Projects & RAG**: Index local codebases for retrieval-augmented chat Prerequisites ------------- [Section titled “Prerequisites”](https://askimo.chat/docs/development/getting-started/#prerequisites) Before extending Askimo, make sure you can build and run it locally: git clone git@github.com:askimo-ai/askimo.gitcd askimo./gradlew build **Requirements:** * JDK 21 or higher * Gradle 8.x or higher * For GraalVM Native Image (CLI): GraalVM distribution Development Conventions ----------------------- [Section titled “Development Conventions”](https://askimo.chat/docs/development/getting-started/#development-conventions) * Keep public APIs documented (KDoc for Kotlin classes). * Use clear, emoji-enhanced user feedback (✅, ⚠️, ❌, 🧹, 📦). * Favor small, focused handlers/factories. * Fail fast with helpful messages when configuration is missing. * Avoid hardcoding secrets—use parameters (e.g., `api_key`). Code Formatting --------------- [Section titled “Code Formatting”](https://askimo.chat/docs/development/getting-started/#code-formatting) Askimo uses [Spotless](https://github.com/diffplug/spotless) with ktlint to enforce consistent formatting. **All code must be formatted before committing.** ### Install the Git Hook (recommended) [Section titled “Install the Git Hook (recommended)”](https://askimo.chat/docs/development/getting-started/#install-the-git-hook-recommended) Run the one-time setup script to install a pre-commit hook that automatically formats your code before every commit: ./tools/git/pre-commit After installation, every `git commit` will: 1. Run `./gradlew spotlessApply` to auto-format all changed files 2. Re-stage any files that were reformatted 3. Proceed with the commit ### Manual Formatting [Section titled “Manual Formatting”](https://askimo.chat/docs/development/getting-started/#manual-formatting) If you prefer not to use the hook, you can format manually before committing: ./gradlew spotlessApply # auto-fix formatting./gradlew spotlessCheck # verify only (no changes) ### CI Safety Net [Section titled “CI Safety Net”](https://askimo.chat/docs/development/getting-started/#ci-safety-net) Even without the local hook, every pull request runs `spotlessCheck` via GitHub Actions. **PRs with formatting violations are blocked** until fixed. Install the hook to avoid the round-trip. Building and Testing -------------------- [Section titled “Building and Testing”](https://askimo.chat/docs/development/getting-started/#building-and-testing) ### Build All Modules [Section titled “Build All Modules”](https://askimo.chat/docs/development/getting-started/#build-all-modules) Build the entire project: ./gradlew build Build specific modules: ./gradlew :cli:build # CLI only./gradlew :desktop:build # Desktop only./gradlew :shared:build # Shared library only ### Run the Applications [Section titled “Run the Applications”](https://askimo.chat/docs/development/getting-started/#run-the-applications) **CLI (Development Mode):** ./gradlew :cli:run **Desktop:** ./gradlew :desktop:run ### Testing Your Changes [Section titled “Testing Your Changes”](https://askimo.chat/docs/development/getting-started/#testing-your-changes) Run the test suite for all modules: ./gradlew test ### CLI: Building Native Image [Section titled “CLI: Building Native Image”](https://askimo.chat/docs/development/getting-started/#cli-building-native-image) The CLI can be built as a GraalVM Native Image for single-binary distribution. This is ideal for CLI tools: ultra-fast cold startup, lower memory footprint, simpler installation (just drop the `askimo` executable in PATH), reduced attack surface (no dynamic classloading), and predictable runtime behavior. **Benefits at a glance:** * 🚀 **Startup speed**: Native image avoids JVM warm-up * 📦 **Single file distribution**: Easier for Homebrew, archives, Docker slim images * 🧠 **Lower memory**: Only reachable code is compiled in; smaller RSS for short-lived commands * 🔒 **Security**: Fewer moving parts (no runtime bytecode loading) **Build steps:** # Ensure you have a GraalVM distribution compatible with the Gradle build.# (If using SDKMAN or Homebrew, set JAVA_HOME accordingly.)./gradlew :cli:nativeCompile The resulting executable will appear here: ls cli/build/native/nativeCompile/askimo./cli/build/native/nativeCompile/askimo --help Distribute it by copying `cli/build/native/nativeCompile/askimo` into a release archive or a package manager formula. End users can run it directly without installing Java. **Troubleshooting:** * If the native build fails due to missing resources, check `cli/src/main/resources` and reflection config. * Increase memory for the build if needed: export JAVA_TOOL_OPTIONS="-Xmx4G"./gradlew :cli:nativeCompile * On Linux distributions without `glibc`, consider building inside a container matching target libc. ### Desktop: Creating Distributable Package [Section titled “Desktop: Creating Distributable Package”](https://askimo.chat/docs/development/getting-started/#desktop-creating-distributable-package) Create platform-specific packages: # Create distributable packages (DMG for macOS, MSI for Windows, DEB/RPM for Linux)./gradlew :desktop:packageDistributionForCurrentOS # Or create a runtime image./gradlew :desktop:createDistributable The packages will be in `desktop/build/compose/binaries/`. Testing Your Changes in Context ------------------------------- [Section titled “Testing Your Changes in Context”](https://askimo.chat/docs/development/getting-started/#testing-your-changes-in-context) ### Testing CLI Commands [Section titled “Testing CLI Commands”](https://askimo.chat/docs/development/getting-started/#testing-cli-commands) # Start the CLI./gradlew :cli:run # Test commandsaskimo> :yourcommandaskimo> :set-provider YOUR_PROVIDERaskimo> :set-param api_key sk-***askimo> :modelsaskimo> :set-param model my-modelaskimo> Explain vector embeddings in 2 sentences. ### Testing Desktop Features [Section titled “Testing Desktop Features”](https://askimo.chat/docs/development/getting-started/#testing-desktop-features) # Start the desktop app./gradlew :desktop:run # Navigate through:# - Chat interface# - Settings dialog# - Session management# - Localization (if you added a new locale) Feedback & Contribution ----------------------- [Section titled “Feedback & Contribution”](https://askimo.chat/docs/development/getting-started/#feedback--contribution) If you build a new provider or command that others may benefit from: 1. Fork the repo. 2. Add your feature + docs under this section. 3. Open a pull request following CONTRIBUTING.md. Happy hacking! 🚀 --- # Askimo CLI Commands Reference | Askimo [Skip to content](https://askimo.chat/docs/cli/commands/#_top) Askimo CLI Commands Reference ============================= We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) This document lists all available Askimo commands, their purpose, parameters, and usage examples. Command Modes ------------- [Section titled “Command Modes”](https://askimo.chat/docs/cli/commands/#command-modes) Askimo supports two modes of operation: ### 🖥️ Interactive Mode (REPL) [Section titled “🖥️ Interactive Mode (REPL)”](https://askimo.chat/docs/cli/commands/#%EF%B8%8F-interactive-mode-repl) Start the interactive shell by running `askimo` without arguments. Commands use the `:keyword` format: askimoaskimo> :helpaskimo> :models ### ⚡ Non-Interactive Mode (CLI) [Section titled “⚡ Non-Interactive Mode (CLI)”](https://askimo.chat/docs/cli/commands/#-non-interactive-mode-cli) Run commands directly from your terminal using the `--flag` format: askimo --helpaskimo --modelsaskimo --tools Available Commands ------------------ [Section titled “Available Commands”](https://askimo.chat/docs/cli/commands/#available-commands) ### Commands Available in BOTH Modes [Section titled “Commands Available in BOTH Modes”](https://askimo.chat/docs/cli/commands/#commands-available-in-both-modes) The following commands work in both interactive (`:keyword`) and non-interactive (`--flag`) modes: * `:help` / `--help` - Show available commands * `:config` / `--config` - Show current provider, model, and settings * `:providers` / `--providers` - List all supported model providers * `:set-provider` / `--set-provider` - Set the current model provider * `:models` / `--models` - List available models for the current provider * `:params` / `--params` - Show current model parameters or list available param keys * `:set-param` / `--set-param` - Set a model parameter * `:tools` / `--tools` - List all available tools * `:version` / `--version` - Show detailed version and build information ### Non-Interactive Mode Only Commands [Section titled “Non-Interactive Mode Only Commands”](https://askimo.chat/docs/cli/commands/#non-interactive-mode-only-commands) The following commands are only available in non-interactive mode (CLI flags): * `--create-recipe` - Create a provider-agnostic recipe from a YAML template * `--recipes` - List all registered recipes in ~/.askimo/recipes * `--delete-recipe` - Delete a registered recipe ### Interactive Mode Only Commands [Section titled “Interactive Mode Only Commands”](https://askimo.chat/docs/cli/commands/#interactive-mode-only-commands) The following commands are only available in interactive mode: * `:clear` - Clear the current chat memory * `:copy` - Copy the last AI response to the clipboard * `:sessions` - List all saved sessions * `:new-session` - Start a new chat session * `:resume-session` - Resume a previous chat session * * * Command Reference ================= [Section titled “Command Reference”](https://askimo.chat/docs/cli/commands/#command-reference) :help / –help ------------- [Section titled “:help / –help”](https://askimo.chat/docs/cli/commands/#help--help) **Description:** Display all available commands and their short descriptions. **Syntax:** # Interactive mode:help # Non-interactive modeaskimo --help :clear ------ [Section titled “:clear”](https://askimo.chat/docs/cli/commands/#clear) **Description:** Clear the chat history for the current session. This does not reset provider, model, or session parameters - only the conversation context is removed. **Availability:** Interactive mode only **Syntax:** :clear :copy ----- [Section titled “:copy”](https://askimo.chat/docs/cli/commands/#copy) **Description:** Copy the last AI response to your system clipboard. This is useful for quickly pasting the output into another application without manually selecting it. **Availability:** Interactive mode only **Syntax:** :copy :params / –params ----------------- [Section titled “:params / –params”](https://askimo.chat/docs/cli/commands/#params--params) **Description:** Display the current session parameters, including: * Active provider * Selected model * All configurable parameters available for `:set-param` / `--set-param` **Syntax:** # Interactive mode:params:params --list # Non-interactive modeaskimo --paramsaskimo --params --list **Example:** askimo> :params --listAvailable parameter keys for latest-model (OPENAI): model (String) – Model name to use (e.g., openai-model, llama3) style (Enum(precise|balanced|creative)) – Output style (determinism vs. creativity) verbosity (Enum(short|normal|long)) – Controls response length/cost api_key (String) – OpenAI API key **Notes:** * The list under “Available parameters” shows what can be changed with `:set-param` or `--set-param` * Parameter names and defaults may vary depending on the active provider :set-param / –set-param ----------------------- [Section titled “:set-param / –set-param”](https://askimo.chat/docs/cli/commands/#set-param--set-param) **Description:** Set a parameter for the current AI provider. Available parameters depend on the provider and can be viewed using `:params` or `--params`. **Syntax:** # Interactive mode:set-param # Non-interactive modeaskimo --set-param **Parameters:** * `` - Name of the parameter (e.g., `model`, `style`) * `` - New value to assign to the parameter **Example:** # Interactive modeaskimo> :set-param model # Non-interactive mode$ askimo --set-param model :config / –config ----------------- [Section titled “:config / –config”](https://askimo.chat/docs/cli/commands/#config--config) **Description:** Display the current Askimo configuration values. **Syntax:** # Interactive mode:config # Non-interactive modeaskimo --config **Example:** askimo> :config🔧 Current configuration: Provider: OPENAI Model: Settings: apiKey: sk-pr*** presets: Presets(style=BALANCED, verbosity=NORMAL) :providers / –providers ----------------------- [Section titled “:providers / –providers”](https://askimo.chat/docs/cli/commands/#providers--providers) **Description:** List all AI providers supported by Askimo. **Syntax:** # Interactive mode:providers # Non-interactive modeaskimo --providers **Notes:** * The list may vary depending on your installation and configuration * Use `:set-provider ` or `askimo --set-provider ` to switch to one of the available providers :set-provider / –set-provider ----------------------------- [Section titled “:set-provider / –set-provider”](https://askimo.chat/docs/cli/commands/#set-provider--set-provider) **Description:** Switch to a different AI provider for the current session. **Syntax:** # Interactive mode:set-provider # Non-interactive modeaskimo --set-provider **Notes:** * Switching providers may change the available parameters and models * After switching, you can use `:models` or `--models` to see available models for the new provider :models / –models ----------------- [Section titled “:models / –models”](https://askimo.chat/docs/cli/commands/#models--models) **Description:** List all models available for the current provider. The list is retrieved dynamically based on the active provider’s settings. **Syntax:** # Interactive mode:models # Non-interactive modeaskimo --models **Notes:** * The available models depend on the provider and your local/remote configuration * Use `:set-param model ` or `--set-param model ` to change the active model for the session –create-recipe -------------- [Section titled “–create-recipe”](https://askimo.chat/docs/cli/commands/#create-recipe) **Description:** Create a provider-agnostic recipe from a YAML template file. Recipes are reusable prompt templates that can be used across different AI providers. **Availability:** Non-interactive mode only **Syntax:** askimo --create-recipe [name] -f askimo --create-recipe [name] -i **Parameters:** * `[name]` - Optional name for the recipe (can also be specified in the YAML file) * `-f, --file` - Path to the YAML template file * `-i, --interactive` - Create recipe interactively with guided prompts **Example:** $ askimo --create-recipe myrecipe -f ~/templates/code-review.yml **Notes:** * If the name is not provided as an argument, it must be specified in the YAML file’s `name:` field * The recipe will be saved to ~/.askimo/recipes/ * Use `askimo -r ` to run the recipe from the command line –recipes -------- [Section titled “–recipes”](https://askimo.chat/docs/cli/commands/#recipes) **Description:** List all registered recipes stored in ~/.askimo/recipes. **Availability:** Non-interactive mode only **Syntax:** askimo --recipes **Example:** $ askimo --recipes📦 Registered recipes (3)────────────────────────────code-review - Review code for bugs and improvementsdocumentation - Generate documentation for coderefactoring - Suggest refactoring improvements –delete-recipe -------------- [Section titled “–delete-recipe”](https://askimo.chat/docs/cli/commands/#delete-recipe) **Description:** Delete a registered recipe from ~/.askimo/recipes, or delete all recipes at once. **Availability:** Non-interactive mode only **Syntax:** askimo --delete-recipe askimo --delete-recipe --all **Parameters:** * `` - Name of the recipe to delete * `--all` - Delete all registered recipes **Examples:** # Delete a specific recipe$ askimo --delete-recipe myrecipe # Delete all recipes$ askimo --delete-recipe --all **Notes:** * You will be prompted to confirm the deletion * When using `--all`, you’ll see a list of all recipes before confirmation * This operation cannot be undone :tools / –tools --------------- [Section titled “:tools / –tools”](https://askimo.chat/docs/cli/commands/#tools--tools) **Description:** List all available tools that can be used in recipes and by the AI agent. This includes tools from GitTools and LocalFsTools. **Syntax:** # Interactive mode:tools # Non-interactive modeaskimo --tools **Example:** $ askimo --tools🔧 Available Tools────────────────────────────── 📦 GitTools • branch Current branch name • commit Write .git/COMMIT_EDITMSG and run git commit -F - • stagedDiff Unified diff of staged changes (git diff --cached) • status Concise git status (-sb) 📦 LocalFsTools • readFile Read text file from path • writeFile Write text file to path • runCommand Run shell commands in a persistent terminal... • searchFileContent Search for text content within files in a directory... • searchFilesByGlob Search for files by name/pattern with smart matching... (and more...) ──────────────────────────────Total: 14 tools **Notes:** * Tools are organized by their provider class (GitTools, LocalFsTools) * Each tool shows its name and description * These tools can be invoked by recipes or used by AI agents during code generation :sessions --------- [Section titled “:sessions”](https://askimo.chat/docs/cli/commands/#sessions) **Description:** List all saved chat sessions for the current provider and model. **Availability:** Interactive mode only **Syntax:** :sessions **Example:** askimo> :sessions💬 Saved Sessions: 1. [2025-11-06 14:30] Session with 15 messages 2. [2025-11-05 09:15] Session with 8 messages 3. [2025-11-04 16:45] Session with 23 messages **Notes:** * Sessions are saved automatically during interactive chat * Each session is tied to a specific provider and model combination * Use `:resume-session` to continue a previous conversation :new-session ------------ [Section titled “:new-session”](https://askimo.chat/docs/cli/commands/#new-session) **Description:** Start a new chat session, clearing the current conversation history and creating a fresh context. **Availability:** Interactive mode only **Syntax:** :new-session **Example:** askimo> :new-session✨ Started new session **Notes:** * This command clears the current conversation context * The previous session is saved and can be resumed later with `:resume-session` * Provider, model, and configuration settings are preserved :resume-session --------------- [Section titled “:resume-session”](https://askimo.chat/docs/cli/commands/#resume-session) **Description:** Resume a previous chat session by selecting from your saved sessions. **Availability:** Interactive mode only **Syntax:** :resume-session:resume-session **Parameters:** * `` - Optional session ID to resume directly **Example:** # Interactive selectionaskimo> :resume-session💬 Saved Sessions: 1. [2025-11-06 14:30] Session with 15 messages 2. [2025-11-05 09:15] Session with 8 messagesSelect session to resume [1-2]: # Direct resumeaskimo> :resume-session 1 **Notes:** * If no session ID is provided, you’ll be prompted to select from available sessions * Resuming a session loads all previous messages and context * Sessions are specific to the provider and model they were created with :version / –version ------------------- [Section titled “:version / –version”](https://askimo.chat/docs/cli/commands/#version--version) **Description:** Show detailed version and build information for Askimo. **Syntax:** # Interactive mode:version # Non-interactive modeaskimo --version --- # RAG - Retrieval-Augmented Generation | Askimo [Skip to content](https://askimo.chat/docs/desktop/rag/#_top) RAG - Retrieval-Augmented Generation ==================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) Askimo App includes powerful RAG (Retrieval-Augmented Generation) capabilities that allow you to create project-based knowledge bases. Whether you’re a developer working with code, a writer managing documents, or a researcher organizing data, Askimo’s Lucene-powered indexing helps your AI conversations access and reference your files automatically. * * * What is RAG? ------------ [Section titled “What is RAG?”](https://askimo.chat/docs/desktop/rag/#what-is-rag) RAG (Retrieval-Augmented Generation) enhances AI conversations by: * **Accessing Your Project Files**: AI can reference your local documents, code, research papers, or any other files * **Accurate Responses**: Answers are grounded in your actual content, not just the AI’s training data * **Privacy-First**: All indexing and retrieval happens locally on your machine * **Fast Search**: Lucene-powered indexing provides lightning-fast retrieval across thousands of files ### How RAG Works in Askimo [Section titled “How RAG Works in Askimo”](https://askimo.chat/docs/desktop/rag/#how-rag-works-in-askimo) Here’s how Askimo processes and retrieves information from your project files: graph TB subgraph "1. Ingestion Process" A[Project Files] --> B[File Parser] B --> C{File Type Detection} C -->|Code| D[Code Parser] C -->|PDF| E[PDF Text Extractor] C -->|Office Docs| F[Office Parser] C -->|Text/Markdown| G[Text Parser] D --> H[Text Chunks] E --> H F --> H G --> H end subgraph "2. Indexing & Storage" H --> I[Document Chunker
256-2048 tokens] I --> J[Embedding Generator] J --> K[(JVector Store
Vector Embeddings)] J --> L[(Lucene Index
Full-Text Search)] end subgraph "3. Query & Retrieval" M[User Query] --> N[Query Embedding] N --> O[ContentRetriever] O --> K O --> L K --> P[Vector Similarity Search] L --> Q[Keyword Search] P --> R[Top-K Results] Q --> R end subgraph "4. Context Injection" R --> S[ContentInjector] S --> T[Rank & Filter Results] T --> U[Context Window Manager] U --> V[Inject into AI Prompt] V --> W[AI Model] W --> X[Enhanced Response] end style K fill:#e1f5ff style L fill:#e1f5ff style O fill:#fff4e6 style S fill:#f3e8ff style W fill:#e8f5e9 **The Process:** 1. **Ingestion**: Files are parsed based on their type (code, PDF, Office docs, text) 2. **Indexing**: Content is split into chunks, embedded as vectors (JVector), and indexed for full-text search (Lucene) 3. **Retrieval**: When you ask a question, ContentRetriever searches both vector embeddings and full-text index 4. **Injection**: ContentInjector ranks results, manages context window, and injects relevant chunks into your AI conversation All of this happens **locally on your machine**—no data ever leaves your computer. * * * Creating a Project with RAG --------------------------- [Section titled “Creating a Project with RAG”](https://askimo.chat/docs/desktop/rag/#creating-a-project-with-rag) ### Step 1: Create a New Project [Section titled “Step 1: Create a New Project”](https://askimo.chat/docs/desktop/rag/#step-1-create-a-new-project) 1. **Open Project Manager** * Click the “Projects” icon in the sidebar * Or use keyboard shortcut: `⌘/Ctrl + P` 2. **Create New Project** * Click “+ New Project” button * Enter a project name (e.g., “My Web App”, “Research Papers”, “Novel Draft”, “Marketing Documents”) * Optionally add a description 3. **Select Project Directory** * Click “Select Folder” to choose the project root directory * This directory and its subdirectories will be indexed automatically ### Step 2: Automatic Indexing [Section titled “Step 2: Automatic Indexing”](https://askimo.chat/docs/desktop/rag/#step-2-automatic-indexing) **Indexing starts automatically** when you create a project: 1. Askimo detects the project type (Gradle, Maven, Python, Node.js, etc.) 2. Indexing begins immediately in the background 3. Monitor indexing progress in the status bar 4. Wait for indexing to complete (typically 10-60 seconds depending on project size) **What Gets Indexed:** Askimo automatically indexes: * All text-based source files * PDF files (text content extracted) * Microsoft Office documents (.docx, .xlsx, .pptx) * OpenOffice documents (.odt, .ods, .odp) * Email files (.eml, .msg) * Documentation files (.md, .txt, .rst, etc.) * Configuration files (.json, .yaml, .xml, etc.) **What Gets Excluded:** Askimo intelligently excludes: * Common build artifacts (build/, dist/, target/, .gradle/, etc.) * Dependencies (node\_modules/, vendor/, venv/, etc.) * Files listed in `.gitignore` * Binary files (except supported document types) * Files larger than 5 MB * IDE-specific directories (.idea/, .vscode/, etc.) * * * Using RAG in Chat Sessions -------------------------- [Section titled “Using RAG in Chat Sessions”](https://askimo.chat/docs/desktop/rag/#using-rag-in-chat-sessions) ### Creating a New Chat in a Project [Section titled “Creating a New Chat in a Project”](https://askimo.chat/docs/desktop/rag/#creating-a-new-chat-in-a-project) When you create a chat session within a project, **RAG is automatically enabled** to provide context from your indexed files. 1. **Navigate to Your Project** * Open the project in the sidebar * Your indexed project is ready to use 2. **Start a New Chat** * Click the “+” button within the project * Or use `⌘/Ctrl + N` while in project view 3. **Chat with Context** * RAG is enabled by default - no need to toggle! * The AI automatically retrieves relevant context from your indexed files * A small indicator shows which project’s knowledge is active Moving Existing Chats to Projects --------------------------------- [Section titled “Moving Existing Chats to Projects”](https://askimo.chat/docs/desktop/rag/#moving-existing-chats-to-projects) You can organize existing chat sessions by moving them into projects. Once moved, RAG is automatically enabled. 1. **Select Chat Session** * Find the chat you want to move in the sidebar 2. **Move to Project** * Right-click the chat in the sidebar * Select “Move to Project” * Choose the target project 3. **RAG Automatically Enabled** * Once moved, RAG is automatically enabled for this chat * The AI now has access to the project’s knowledge base * The chat will use the project’s indexed files for context * * * Managing RAG Index ------------------ [Section titled “Managing RAG Index”](https://askimo.chat/docs/desktop/rag/#managing-rag-index) ### Re-indexing the Project [Section titled “Re-indexing the Project”](https://askimo.chat/docs/desktop/rag/#re-indexing-the-project) When you make significant changes to your project: 1. Open the project settings 2. Click “Re-index Project” 3. Wait for indexing to complete **When to Re-index:** * After major code refactoring * When adding/removing large numbers of files * If search results seem outdated ### Incremental Updates [Section titled “Incremental Updates”](https://askimo.chat/docs/desktop/rag/#incremental-updates) Askimo automatically detects file changes and updates the index: * **File Modified**: Re-indexes the changed file * **File Added**: Indexes the new file * **File Deleted**: Removes from index ### Index Storage [Section titled “Index Storage”](https://askimo.chat/docs/desktop/rag/#index-storage) RAG indexes are stored locally: * **Location**: `~/.askimo/personal/projects//index/` * **Size**: Typically 10-30% of your source files * **Format**: Lucene index format * * * Embedding Model Configuration ----------------------------- [Section titled “Embedding Model Configuration”](https://askimo.chat/docs/desktop/rag/#embedding-model-configuration) RAG (Retrieval-Augmented Generation) relies on **embedding models** to convert your documents and queries into vector representations. These embeddings enable semantic search, allowing the AI to find relevant content based on meaning rather than just keyword matching. ### Why Embedding Models Matter [Section titled “Why Embedding Models Matter”](https://askimo.chat/docs/desktop/rag/#why-embedding-models-matter) When you create a project with RAG: 1. **Document Ingestion**: Your files are split into chunks and converted into numerical vectors (embeddings) using an embedding model 2. **Semantic Search**: When you ask a question, your query is also converted into an embedding 3. **Similarity Matching**: The system finds the most semantically similar document chunks by comparing vector embeddings 4. **Context Injection**: Relevant chunks are injected into the AI’s context window to generate accurate, grounded responses The quality and compatibility of the embedding model directly impact RAG’s ability to retrieve relevant information from your project files. ### Selecting an Embedding Model [Section titled “Selecting an Embedding Model”](https://askimo.chat/docs/desktop/rag/#selecting-an-embedding-model) Askimo lets you choose the embedding model for each provider. When you open the embedding model selector in Settings, it lists **all models available from that provider**—including both chat models and embedding models. **Suggested starting points by provider:** | Provider | Recommended Embedding Model | | --- | --- | | **OpenAI** | `text-embedding-3-small` (fast & affordable) or `text-embedding-3-large` (higher quality) | | **Google Gemini** | `text-embedding-004` or `gemini-embedding-exp-03-07` | | **Ollama** | `nomic-embed-text:latest` (pull first: `ollama pull nomic-embed-text`) | | **LM Studio / LocalAI** | Search for `nomic-embed-text` or `mxbai-embed-large` in the model browser | | **Docker AI** | `ai/qwen3-embedding:0.6B-F16` | ### Setting Up Local Embedding Models [Section titled “Setting Up Local Embedding Models”](https://askimo.chat/docs/desktop/rag/#setting-up-local-embedding-models) For local AI providers (Ollama, LM Studio, LocalAI, Docker AI), you must **manually pull the embedding model** before using RAG: **For Ollama:** ollama pull nomic-embed-text:latest **For LM Studio:** 1. Open LM Studio 2. Search for “nomic-embed-text” 3. Download the model **For LocalAI:** # Pull the model using LocalAI's CLI or APIcurl http://localhost:8080/models/apply -H "Content-Type: application/json" -d '{ "id": "nomic-embed-text:latest"}' **For Docker AI:** # Pull the Qwen embedding modeldocker exec -it pull ai/qwen3-embedding:0.6B-F16 ### Customizing Embedding Models [Section titled “Customizing Embedding Models”](https://askimo.chat/docs/desktop/rag/#customizing-embedding-models) You can change the default embedding model for any provider: 1. **Open Settings** * Go to **Settings** (⌘/Ctrl + ,) 2. **Navigate to RAG Configuration** * Select **AI Provider** tab * Scroll down to **Embeddings Model By Provider** ![Askimo RAG configuration settings showing customizable embedding models for different AI providers](https://askimo.chat/_astro/customize-embedding-model.DvYy_sly_5zqNI.webp) ![](https://askimo.chat/docs/desktop/rag/) **Tips for finding the right model:** * In the model dropdown, **type `embed`** in the search box to filter out chat models and show only embedding models * Pick the most recent version available—newer embedding models consistently outperform older ones * For local providers, make sure the model is already pulled/downloaded before selecting it here (see “Setting Up Local Embedding Models” above) **Example selections:** | Provider | Model to select | | --- | --- | | OpenAI | `text-embedding-3-large` (higher quality) or `text-embedding-3-small` (faster/cheaper) | | Gemini | `text-embedding-004` or `gemini-embedding-exp-03-07` | | Ollama | `mxbai-embed-large:latest` (alternative to nomic-embed-text) | ### Verifying Your Embedding Model [Section titled “Verifying Your Embedding Model”](https://askimo.chat/docs/desktop/rag/#verifying-your-embedding-model) Askimo automatically validates your embedding model when you: * **Create a new RAG project**, or * **Re-index an existing project** (right-click project > “Re-index Project”) During the indexing process, Askimo will check if the configured embedding model is available and valid. If the embedding model is invalid or unavailable, you’ll receive a clear error notification indicating the issue. **Common validation errors:** * **Local providers (Ollama, LM Studio, LocalAI, Docker AI)**: Model not downloaded/pulled * **Cloud providers (OpenAI, Gemini)**: Invalid API key or model name * **Anthropic/X.AI users**: No embedding model configured (these providers don’t offer embedding APIs) **If you encounter an embedding model error:** 1. **Review the error message** to identify the specific issue 2. **For local providers**: Make sure you’ve manually pulled the embedding model (see “Setting Up Local Embedding Models” above) 3. **For cloud providers**: Verify your API key is valid and the model name is correct 4. **Re-attempt indexing**: After fixing the issue, try creating a new project or re-indexing your existing project 5. **Still having issues?** Post a detailed issue report on the [Askimo GitHub Issues page](https://github.com/askimo-ai/askimo/issues) including: * Your AI provider * The embedding model name you’re using * The exact error message * Your operating system ### Indexing Is Slow [Section titled “Indexing Is Slow”](https://askimo.chat/docs/desktop/rag/#indexing-is-slow) If indexing takes much longer than expected, the most common cause is a low **Embedding Batch Size**. By default, Askimo sends 50 text segments per request to the embedding model—a safe value for local models but conservative for remote providers. **To speed up indexing with a remote provider (OpenAI, Gemini):** 1. Go to **Settings** → **Advanced** 2. Find **Embedding Batch Size** under the RAG / Indexing section 3. Increase it to a value between **100–500** 4. Re-index your project **Other things to check if indexing is slow:** * **Project size**: Projects with tens of thousands of files will take longer on first index. Subsequent updates are incremental and much faster. * **Concurrent indexing threads**: In **Settings → Advanced**, you can increase the number of concurrent indexing threads if your machine has spare CPU cores. * **Max file size**: Reducing the **Max File Size** limit skips large files that generate many chunks and slow down indexing. * * * ### Supported File Types [Section titled “Supported File Types”](https://askimo.chat/docs/desktop/rag/#supported-file-types) Askimo can index a wide variety of file types: **Source Code Files:** * `.java`, `.kt`, `.js`, `.ts`, `.jsx`, `.tsx` * `.py`, `.rb`, `.go`, `.rs`, `.c`, `.cpp`, `.h`, `.hpp` * `.cs`, `.php`, `.swift`, `.scala`, `.clj` * `.sql`, `.sh`, `.bash`, `.ps1` **Documentation Files:** * `.md`, `.mdx`, `.txt`, `.rst`, `.adoc`, `.org` * PDF files (text content extracted) **Office Documents:** * **Microsoft Office**: `.docx`, `.xlsx`, `.pptx`, `.doc`, `.xls`, `.ppt` * **OpenOffice**: `.odt`, `.ods`, `.odp` **Email Files:** * `.eml`, `.msg` **Configuration & Data Files:** * `.json`, `.yaml`, `.yml`, `.toml`, `.ini` * `.xml`, `.csv`, `.properties` **Build & Project Files:** * `pom.xml`, `build.gradle`, `package.json`, `requirements.txt` * `Cargo.toml`, `go.mod`, `composer.json` **Automatically Detected Project Types:** * **Java**: Maven (`pom.xml`), Gradle (`build.gradle`, `settings.gradle`) * **JavaScript/TypeScript**: Node.js (`package.json`), npm, yarn, pnpm * **Python**: pip (`requirements.txt`), Poetry (`pyproject.toml`), virtualenv * **Go**: Go modules (`go.mod`, `go.sum`) * **Rust**: Cargo (`Cargo.toml`) * **PHP**: Composer (`composer.json`) * **Ruby**: Bundler (`Gemfile`) * **.NET**: NuGet, MSBuild projects * * * Privacy & Security ------------------ [Section titled “Privacy & Security”](https://askimo.chat/docs/desktop/rag/#privacy--security) ### Local-Only Processing [Section titled “Local-Only Processing”](https://askimo.chat/docs/desktop/rag/#local-only-processing) All RAG operations happen locally on your machine: * **No Data Upload**: Your code never leaves your computer * **No Cloud Dependencies**: Works completely offline * **Secure Storage**: Indexes stored in your local Askimo directory * * * See RAG in Action ----------------- [Section titled “See RAG in Action”](https://askimo.chat/docs/desktop/rag/#see-rag-in-action) * **[Chat with your documents using Ollama & RAG](https://askimo.chat/blog/ollama-rag-chat-with-documents-local-ai/) ** - Step-by-step guide with real examples: research papers, company policies, writing projects * **[Askimo Features: RAG section](https://askimo.chat/features/) ** - Visual overview of what RAG enables in the desktop app --- # Skills - AI Agents for Your Workspace | Askimo [Skip to content](https://askimo.chat/docs/desktop/skills/#_top) Skills - AI Agents for Your Workspace ===================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) **Skills** are AI agents that run directly on your local machine, with full access to your files, terminal, and project directories. Unlike the built-in chat which sends messages to a remote model, a Skill delegates execution to an external agent runtime that can read files, write code, run commands, and browse the web on your behalf. Supported runtimes today ------------------------ [Section titled “Supported runtimes today”](https://askimo.chat/docs/desktop/skills/#supported-runtimes-today) | Runtime | Provider | Setup | | --- | --- | --- | | **Gemini CLI** | Google | Install the CLI, then add a Gemini API key in Askimo (free tier available with a Google account) | | **Claude Code** | Anthropic | Install the CLI, then run `claude login` to authenticate with your Anthropic account or Claude subscription | | **Codex CLI** | OpenAI | Install the CLI, then add an OpenAI API key in Askimo | More agent runtimes will be supported in future releases. This matters when the task is inherently local: reviewing a codebase, refactoring files, generating scaffolding, or analysing logs. These jobs require an agent that can navigate your directory tree and make changes in place. Skills bring that capability directly into Askimo’s interface without leaving your workspace. Each Skill is a plain Markdown file that defines: * A **system prompt** that tells the agent what role to play and how to behave. * Optional **supplemental files** (additional context merged into the prompt). * A **frontmatter block** with metadata such as name, description, and visibility. Skills are stored as files on disk, so you can write them in any text editor, version-control them with Git, and share them with your team. Skills vs Plans --------------- [Section titled “Skills vs Plans”](https://askimo.chat/docs/desktop/skills/#skills-vs-plans) Askimo has two ways to automate AI work. Choosing the right one depends on whether your task is about **local files** or **structured reasoning**. | | Skills | Plans | | --- | --- | --- | | **What it does** | Runs an agent on your local machine with file system access | Chains multiple AI prompts in a defined sequence | | **Requires install** | Yes - Gemini CLI or Claude Code | No - uses Askimo’s built-in AI | | **File access** | Full read/write access to your working directory | None - text in, text out | | **Best for** | Code review, refactoring, scaffolding, log analysis | Research reports, blog posts, job applications, meeting notes | | **Output** | Changes made directly to your files + streamed output | A final text result shown in the app | | **Defined by** | A `SKILL.md` file with a system prompt | A YAML file with steps and inputs | | **Runs in** | A local subprocess (the agent runtime) | Askimo’s built-in AI | **Use a Skill when** the task requires reading or writing local files, running shell commands, or navigating a project directory. **Use a Plan when** the task is a multi-step reasoning workflow that takes text inputs and produces a text result, with no need to touch the file system. For example: * _“Review all TypeScript files in my project for type errors”_ - Skill (needs file access) * _“Write a blog post about remote work”_ - Plan (pure text reasoning) * _“Refactor my API routes to follow REST conventions”_ - Skill (reads and rewrites files) * _“Generate a competitor analysis report for my SaaS product”_ - Plan (structured multi-step reasoning) Prerequisites ------------- [Section titled “Prerequisites”](https://askimo.chat/docs/desktop/skills/#prerequisites) Skills require at least one external agent runtime to be installed and reachable on your `PATH`. Askimo currently supports **Gemini CLI** and **Claude Code**, with more runtimes planned. * [Gemini CLI](https://askimo.chat/docs/desktop/skills/#tab-panel-13) * [Claude Code](https://askimo.chat/docs/desktop/skills/#tab-panel-14) * [Codex CLI](https://askimo.chat/docs/desktop/skills/#tab-panel-15) **Install:** npm install -g @google/gemini-cli **Verify:** gemini --version Gemini CLI offers a **free tier** with a Google account. Sign in once with `gemini` before using Skills. [Gemini CLI on GitHub →](https://github.com/google-gemini/gemini-cli) **Install:** npm install -g @anthropic-ai/claude-code **Verify:** claude --version Claude Code requires an Anthropic API key or a Claude subscription. Follow the setup prompts the first time you run `claude`. [Claude Code docs →](https://docs.anthropic.com/en/docs/claude-code) **Install:** npm install -g @openai/codex **Verify:** codex --version Codex CLI requires an OpenAI API key. Add it in Askimo when you select Codex as the agent runtime. [Codex CLI on GitHub →](https://github.com/openai/codex) Once installed, Askimo detects the runtime automatically. You can see which runtimes are available in **Settings → Skills**. Creating a Skill ---------------- [Section titled “Creating a Skill”](https://askimo.chat/docs/desktop/skills/#creating-a-skill) Before you can run a skill, you need one in your library. There are two ways to get started. ### Option A - Create from the UI [Section titled “Option A - Create from the UI”](https://askimo.chat/docs/desktop/skills/#option-a---create-from-the-ui) 1. Open **Skills** in the sidebar. 2. Click the **+** button (or navigate to **Settings → Skills**). 3. Fill in the skill name and description. 4. Write the system prompt in the editor. 5. Click **Save**. Askimo creates the folder and `SKILL.md` file automatically. ![Askimo Desktop Skills editor showing the skill name, description, and system prompt fields for creating a new skill.](https://askimo.chat/_astro/skill_editor.B4yJLUUt_1B3WMI.webp) ![](https://askimo.chat/docs/desktop/skills/) ### Option B - Import from GitHub [Section titled “Option B - Import from GitHub”](https://askimo.chat/docs/desktop/skills/#option-b---import-from-github) The community shares skill packs as public GitHub repositories: ready-made agents for code review, writing, data analysis, and more. Importing one gives you a head start with battle-tested prompts instead of starting from scratch. 1. Go to **Settings → Skills**. 2. Click **Import from GitHub**. 3. Paste the GitHub repository URL (e.g. `https://github.com/user/my-skills`). 4. Click **Import**. Askimo runs `git clone` and places the repository inside `~/.askimo//skills/`. Because it is a full git clone, you can pull updates as the community improves the skills: cd ~/.askimo/personal/skills/my-skillsgit pull **Supported URL formats:** * `https://github.com/user/repo` - imports the entire repository as a skill pack. * `https://github.com/user/repo/tree/main/skills` - imports from a subdirectory within the repo. Skill File Anatomy ------------------ [Section titled “Skill File Anatomy”](https://askimo.chat/docs/desktop/skills/#skill-file-anatomy) A skill lives in its own folder inside `~/.askimo//skills/`. The folder must contain a file named `SKILL.md` (`skill.md` and `Skill.md` are also accepted). ~/.askimo/personal/skills/├── coding/ ← category folder (no SKILL.md)│ └── code-reviewer/ ← skill folder│ ├── SKILL.md ← required entry point│ ├── examples.md ← supplemental context (merged into prompt)│ └── SampleOutput.java ← supplemental file (copied, not merged)└── writing/ └── blog-writer/ └── SKILL.md **Rules:** * A **skill** is any folder that contains `SKILL.md`. * Plain folders without `SKILL.md` are transparent **category** containers used for organisation. * All `.md` files inside a skill folder (except reserved names) are merged into the system prompt as additional context. * Sub-folders of a skill folder are **not** treated as separate skills. * Reserved filenames (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`, `README.md`) are never merged. ### The `SKILL.md` File [Section titled “The SKILL.md File”](https://askimo.chat/docs/desktop/skills/#the-skillmd-file) A `SKILL.md` file has two parts separated by a `---` frontmatter block: ---name: Code Reviewerdescription: Reviews code for bugs, style, and best practicesvisibility: private--- You are an expert code reviewer. When given a file path or code snippet, you: 1. Identify bugs and potential issues2. Suggest improvements for readability and performance3. Check for security vulnerabilities4. Provide actionable, specific feedback with code examples Always explain *why* something is a problem, not just *that* it is. ### Frontmatter Fields [Section titled “Frontmatter Fields”](https://askimo.chat/docs/desktop/skills/#frontmatter-fields) | Field | Required | Description | | --- | --- | --- | | `name` | \- | Display name shown in the gallery. Defaults to the folder name (kebab-case to Title Case). | | `description` | \- | Short description shown on the skill card. | | `visibility` | \- | `private` (default) or `public`. Private skills never sync to other devices. | The body (everything after the closing `---`) is used verbatim as the **system prompt** sent to the agent. ### Supplemental Files [Section titled “Supplemental Files”](https://askimo.chat/docs/desktop/skills/#supplemental-files) Any additional `.md` file inside the skill folder is automatically merged into the system prompt after `SKILL.md`. This is useful for: * **Examples:** `examples.md` with annotated sample inputs and outputs. * **Reference material:** `api-reference.md` with domain knowledge. * **Rules:** `style-guide.md` with project conventions. Files are merged in sorted order (alphabetical). The combined prompt includes a directory listing so the agent knows what files are available. Running a Skill --------------- [Section titled “Running a Skill”](https://askimo.chat/docs/desktop/skills/#running-a-skill) ### Finding the Skills View [Section titled “Finding the Skills View”](https://askimo.chat/docs/desktop/skills/#finding-the-skills-view) Skills live in the **Skills** section of the main navigation sidebar. Click **Skills** to open the gallery. ### Selecting and Running a Skill [Section titled “Selecting and Running a Skill”](https://askimo.chat/docs/desktop/skills/#selecting-and-running-a-skill) ![Askimo Desktop Skills view showing the executor panel with a selected skill, working directory picker, task input field, and live agent output streaming in real time.](https://askimo.chat/_astro/skill_run.BHnsmk5v_q5eUR.webp) ![](https://askimo.chat/docs/desktop/skills/) 1. Open the **Skills** view from the sidebar. 2. Browse the gallery and click on a skill card to open it. 3. The executor view shows the skill’s description, its system prompt, and a task input field. 4. Select the **agent runtime** (Gemini CLI or Claude Code) from the dropdown. 5. Set the **working directory** - the folder the agent will operate in. This is typically your project root. 6. Type your task in the input field (or leave it blank to let the system prompt guide the agent). 7. Click **Run**. The agent starts immediately. You can watch its output stream in real time in the output panel. Tool calls (file reads, writes, shell commands) appear as status messages as they happen. ### How Skills Work Under the Hood [Section titled “How Skills Work Under the Hood”](https://askimo.chat/docs/desktop/skills/#how-skills-work-under-the-hood) When you run a Skill, Askimo: 1. Reads the `SKILL.md` file and any supplemental `.md` files in the skill folder. 2. Merges them into a combined system prompt. 3. Launches the selected agent runtime (Gemini CLI or Claude Code) as a subprocess in the skill’s **working directory**. 4. Streams the agent’s output back into the Skills view in real time. 5. Saves the run to the history panel. flowchart LR U([You type a task]) --> A[Askimo] A -->|system prompt + task| R[Agent runtime\nGemini CLI / Claude Code] R -->|reads & writes| F[Your local files] R -->|streams output| A A --> H[Run saved to history] ### Run History [Section titled “Run History”](https://askimo.chat/docs/desktop/skills/#run-history) Every skill run is saved automatically in the history panel on the right. Click any entry to review its output. You can delete individual records using the **delete** icon that appears on hover. Writing Effective Skills ------------------------ [Section titled “Writing Effective Skills”](https://askimo.chat/docs/desktop/skills/#writing-effective-skills) ### Give the Agent a Clear Role [Section titled “Give the Agent a Clear Role”](https://askimo.chat/docs/desktop/skills/#give-the-agent-a-clear-role) Start your system prompt with a role definition. This anchors the agent’s behaviour for the entire session: You are a senior TypeScript engineer specialising in React and Next.js.Your job is to review code for correctness, performance, and maintainability. ### Be Explicit About Output Format [Section titled “Be Explicit About Output Format”](https://askimo.chat/docs/desktop/skills/#be-explicit-about-output-format) Agents tend to produce better results when you tell them exactly what format you want: For each issue found, output:- **File**: path/to/file.ts (line N)- **Severity**: Critical / Warning / Suggestion- **Issue**: one-sentence description- **Fix**: the corrected code snippet ### Use Supplemental Files for Context [Section titled “Use Supplemental Files for Context”](https://askimo.chat/docs/desktop/skills/#use-supplemental-files-for-context) Heavy reference material (API docs, style guides, example outputs) belongs in supplemental `.md` files rather than in `SKILL.md`. This keeps the entry point readable and lets you update reference material independently. my-skill/├── SKILL.md ← role + behaviour instructions├── style-guide.md ← coding standards reference└── examples.md ← annotated good/bad examples ### Set the Working Directory Correctly [Section titled “Set the Working Directory Correctly”](https://askimo.chat/docs/desktop/skills/#set-the-working-directory-correctly) The agent operates relative to the working directory you set at run time. For code tasks, set it to the project root so the agent can navigate the full directory tree. For document tasks, set it to the folder containing the files you want to work with. ### Keep Skills Focused [Section titled “Keep Skills Focused”](https://askimo.chat/docs/desktop/skills/#keep-skills-focused) A skill that does one thing well outperforms one that tries to handle everything. If you find yourself writing “and also…” in the system prompt, consider splitting into two skills. Managing Skills --------------- [Section titled “Managing Skills”](https://askimo.chat/docs/desktop/skills/#managing-skills) ### Editing a Skill [Section titled “Editing a Skill”](https://askimo.chat/docs/desktop/skills/#editing-a-skill) Open the skill in the executor view and click the **Edit** button, or edit `SKILL.md` directly in any text editor. Changes are picked up immediately - no restart needed. ### Deleting a Skill [Section titled “Deleting a Skill”](https://askimo.chat/docs/desktop/skills/#deleting-a-skill) 1. Right-click the skill card in the gallery (or use the **menu**). 2. Select **Delete**. 3. Confirm the deletion. This deletes the entire skill folder from disk. ### Where Skills Are Stored [Section titled “Where Skills Are Stored”](https://askimo.chat/docs/desktop/skills/#where-skills-are-stored) ~/.askimo//skills/ Skills are plain files - back them up, version-control them, or share them by copying the folder. Tips and Best Practices ----------------------- [Section titled “Tips and Best Practices”](https://askimo.chat/docs/desktop/skills/#tips-and-best-practices) **Set the working directory to your project root.** The agent uses the working directory as its anchor for file navigation. A wrong working directory is the most common source of “file not found” errors. **Trust directories in Gemini CLI.** On first run in a new directory, Gemini CLI may ask for permission to access files. Use `/permissions trust .` to trust the current directory, or configure trusted paths in the Gemini settings. **Permission prompts are suppressed automatically.** Askimo passes `--dangerously-skip-permissions` to Claude Code and `--yolo` to Gemini CLI so the agent never blocks waiting for interactive approval during a skill run. **Keep the system prompt under ~4,000 words.** Very long prompts can dilute the agent’s focus. If you need extensive reference material, split it across supplemental files - the agent receives a directory listing and can request specific files as needed. **Version-control your skills with Git.** Since skills are plain files, a `git init` inside `~/.askimo//skills/` (or a subfolder) gives you full history and makes it easy to roll back changes. Troubleshooting --------------- [Section titled “Troubleshooting”](https://askimo.chat/docs/desktop/skills/#troubleshooting) ### “No agent runtime found” [Section titled ““No agent runtime found””](https://askimo.chat/docs/desktop/skills/#no-agent-runtime-found) Neither Gemini CLI nor Claude Code is installed or not on `PATH`. Install at least one runtime: npm install -g @google/gemini-cli # Gemini CLInpm install -g @anthropic-ai/claude-code # Claude Code Restart Askimo after installation. ### The agent hangs or produces no output [Section titled “The agent hangs or produces no output”](https://askimo.chat/docs/desktop/skills/#the-agent-hangs-or-produces-no-output) * Check that the working directory exists and is accessible. * For Gemini CLI, ensure you are signed in (`gemini` in a terminal to trigger sign-in). * For Claude Code, check that your API key or subscription is active (`claude doctor`). ### “SKILL.md not found” or skill does not appear in gallery [Section titled ““SKILL.md not found” or skill does not appear in gallery”](https://askimo.chat/docs/desktop/skills/#skillmd-not-found-or-skill-does-not-appear-in-gallery) Verify that the skill folder contains a file named `SKILL.md` (or `skill.md` / `Skill.md` - all are accepted). A file placed at the wrong depth will not be detected. ### Agent edits the wrong files [Section titled “Agent edits the wrong files”](https://askimo.chat/docs/desktop/skills/#agent-edits-the-wrong-files) The agent operates in the working directory you set. Double-check that the correct project folder is selected before running the skill. ### Supplemental file not included in prompt [Section titled “Supplemental file not included in prompt”](https://askimo.chat/docs/desktop/skills/#supplemental-file-not-included-in-prompt) Ensure the supplemental file: * Is inside the skill folder (not a sub-folder of the skill folder). * Is not named `CLAUDE.md`, `GEMINI.md`, `AGENTS.md`, or `README.md` - these are reserved and ignored. * * * Learn More ---------- [Section titled “Learn More”](https://askimo.chat/docs/desktop/skills/#learn-more) * **[MCP Integration](https://askimo.chat/docs/desktop/mcp-integration/) ** - extend your agent with external tools via the Model Context Protocol * **[Plans](https://askimo.chat/docs/desktop/plans/) ** - multi-step AI workflows for tasks that don’t require local file access * **[Settings](https://askimo.chat/docs/desktop/settings/) ** - configure agent runtimes and skill storage paths --- # Integrate New AI Providers in Askimo | Askimo [Skip to content](https://askimo.chat/docs/development/creating-new-chat-provider/#_top) Integrate New AI Providers in Askimo ==================================== We welcome all contributions, big or small. [See how you can help →](https://askimo.chat/docs/contributing/how-to-contribute/) This guide explains how to implement a new chat model provider in Askimo. By following these steps, you can integrate any chat model API with the Askimo CLI and Desktop. Architecture Overview --------------------- [Section titled “Architecture Overview”](https://askimo.chat/docs/development/creating-new-chat-provider/#architecture-overview) Askimo uses a modular architecture for chat models with the following key components: 1. **ChatClient**: Interface that defines the contract for all chat models (created by LangChain4j’s AiServices) 2. **ChatClientImpl**: Wrapper that adds session management and memory persistence to ChatClient 3. **ChatModelFactory**: Generic interface for creating chat model instances with type parameter `` 4. **ProviderSettings**: Interface for model-specific configuration with methods for validation, field management, and deep copying 5. **ModelProvider**: Enum that identifies different model providers (OpenAI, XAI, Gemini, Ollama, Anthropic, LocalAI, LMStudio, Docker) 6. **ProviderRegistry**: Central registry that manages all model factories using a map-based structure 7. **AiServiceBuilder**: Centralized builder that assembles the full `ChatClient` stack (memory, tools, RAG, directives) 8. **TokenAwareSummarizingMemory**: Advanced memory implementation that automatically summarizes conversation history when approaching token limits ### Factory Responsibility [Section titled “Factory Responsibility”](https://askimo.chat/docs/development/creating-new-chat-provider/#factory-responsibility) Each factory is responsible for creating the raw model objects only: * `createStreamingModel()` — returns a `StreamingChatModel` for the main chat loop * `createSecondaryModel()` / `createModel()` — returns a `ChatModel` for utility/structured tasks * `create()` — delegates to `AiServiceBuilder.buildChatClient()` passing the models above **Session management, tool wiring, RAG, directives, and memory are all handled centrally by `AiServiceBuilder`** — you do not implement these in your factory. Implementation Steps -------------------- [Section titled “Implementation Steps”](https://askimo.chat/docs/development/creating-new-chat-provider/#implementation-steps) ### 1\. Add LangChain4j Dependency [Section titled “1. Add LangChain4j Dependency”](https://askimo.chat/docs/development/creating-new-chat-provider/#1-add-langchain4j-dependency) Add the appropriate LangChain4j dependency to the `build.gradle.kts` file: dependencies { implementation("dev.langchain4j:langchain4j:1.2.0") // Add your provider's LangChain4j module implementation("dev.langchain4j:langchain4j-your-provider:1.2.0")} Check the [LangChain4j GitHub repository](https://github.com/langchain4j/langchain4j) or Maven Central for available provider modules. If none exists, you can adapt `OpenAiCompatibleModelFactory` if your provider exposes an OpenAI-compatible API. ### 2\. Add a New Provider Enum Value [Section titled “2. Add a New Provider Enum Value”](https://askimo.chat/docs/development/creating-new-chat-provider/#2-add-a-new-provider-enum-value) Add your provider to the `ModelProvider` enum in `io.askimo.core.providers.ModelProvider`: @Serializableenum class ModelProvider { @SerialName("OPENAI") OPENAI, @SerialName("XAI") XAI, @SerialName("GEMINI") GEMINI, @SerialName("OLLAMA") OLLAMA, @SerialName("ANTHROPIC") ANTHROPIC, @SerialName("LOCALAI") LOCALAI, @SerialName("LMSTUDIO") LMSTUDIO, @SerialName("DOCKER") DOCKER, @SerialName("YOUR_PROVIDER") YOUR_PROVIDER, // Add here @SerialName("UNKNOWN") UNKNOWN,} ### 3\. Create Provider Settings [Section titled “3. Create Provider Settings”](https://askimo.chat/docs/development/creating-new-chat-provider/#3-create-provider-settings) Create a settings class that implements `ProviderSettings`. Use marker interfaces like `HasApiKey` or `HasBaseUrl` for common configuration patterns: @Serializabledata class YourProviderSettings( override var apiKey: String = "", override val defaultModel: String = "your-default-model",) : ProviderSettings, HasApiKey { override fun describe(): List { // Return human-readable description of settings (mask sensitive data) } override fun getFields(): List { // Return configurable fields for the UI } override fun updateField(fieldName: String, value: String): ProviderSettings { // Update a field and return a new settings instance } override fun validate(): Boolean { // Validate that settings are properly configured (e.g., API key is non-blank) } override fun getSetupHelpText(): String { // Return helpful guidance for first-time setup } override fun getConfigFields(): List { // Return fields for the provider setup wizard } override fun applyConfigFields(fields: Map): ProviderSettings { // Apply configuration field values and return a new settings instance } override fun deepCopy(): ProviderSettings = copy()} **For complete implementation examples, refer to:** * `OpenAiSettings.kt` — API key with secure keychain storage * `OllamaSettings.kt` — base URL configuration ### 4\. Implement the Model Factory [Section titled “4. Implement the Model Factory”](https://askimo.chat/docs/development/creating-new-chat-provider/#4-implement-the-model-factory) Create a factory class that implements `ChatModelFactory`. The factory creates the raw model objects; `AiServiceBuilder` handles everything else. class YourProviderModelFactory : ChatModelFactory { private val log = logger() override fun getProvider(): ModelProvider = YOUR_PROVIDER override fun availableModels(settings: YourProviderSettings): List { val apiKey = settings.apiKey.takeIf { it.isNotBlank() } ?: return emptyList() return fetchModels(apiKey = apiKey, url = "https://api.yourprovider.com/v1/models", providerName = YOUR_PROVIDER) .map { ModelDTO.of(YOUR_PROVIDER, it) } } override fun defaultSettings(): YourProviderSettings = YourProviderSettings() override fun getNoModelsHelpText(): String = """ Make sure you have provided a valid API key in Settings. Get your API key from: https://yourprovider.com/api-keys """.trimIndent() override fun create( sessionId: String?, settings: YourProviderSettings, toolProvider: ToolProvider?, retriever: ContentRetriever?, executionMode: ExecutionMode, chatMemory: ChatMemory?, ): ChatClient = AiServiceBuilder.buildChatClient( sessionId = sessionId, settings = settings, provider = YOUR_PROVIDER, chatModel = createStreamingModel(settings), secondaryChatModel = createSecondaryModel(settings), chatMemory = chatMemory, toolProvider = toolProvider, retriever = retriever, executionMode = executionMode, ) override fun createStreamingModel(settings: YourProviderSettings): StreamingChatModel { val httpClientBuilder = ProxyUtil.configureProxy(HttpClient.newBuilder()) val jdkHttpClientBuilder = JdkHttpClient.builder().httpClientBuilder(httpClientBuilder) val telemetry = AppContext.getInstance().telemetry return YourProviderStreamingChatModel.builder() .httpClientBuilder(jdkHttpClientBuilder) .apiKey(safeApiKey(settings.apiKey)) .modelName(settings.defaultModel) .timeout(Duration.ofSeconds(AppConfig.models.timeouts.defaultModelTimeoutSeconds)) .logger(log) .logRequests(log.isDebugEnabled) .logResponses(log.isTraceEnabled) .listeners(listOf(TelemetryChatModelListener(telemetry, YOUR_PROVIDER.name.lowercase()))) .build() } override fun createSecondaryModel(settings: YourProviderSettings): ChatModel { val httpClientBuilder = ProxyUtil.configureProxy(HttpClient.newBuilder()) val jdkHttpClientBuilder = JdkHttpClient.builder().httpClientBuilder(httpClientBuilder) return YourProviderChatModel.builder() .httpClientBuilder(jdkHttpClientBuilder) .apiKey(safeApiKey(settings.apiKey)) .modelName(AppConfig.models[YOUR_PROVIDER].utilityModel.ifBlank { settings.defaultModel }) .timeout(Duration.ofSeconds(AppConfig.models.timeouts.utilityModelTimeoutSeconds)) .build() } override fun createModel(settings: YourProviderSettings): ChatModel { val httpClientBuilder = ProxyUtil.configureProxy(HttpClient.newBuilder()) val jdkHttpClientBuilder = JdkHttpClient.builder().httpClientBuilder(httpClientBuilder) val telemetry = AppContext.getInstance().telemetry return YourProviderChatModel.builder() .httpClientBuilder(jdkHttpClientBuilder) .apiKey(safeApiKey(settings.apiKey)) .modelName(settings.defaultModel) .timeout(Duration.ofSeconds(AppConfig.models.timeouts.defaultModelTimeoutSeconds)) .logger(log) .logRequests(log.isDebugEnabled) .logResponses(log.isTraceEnabled) .listeners(listOf(TelemetryChatModelListener(telemetry, YOUR_PROVIDER.name.lowercase()))) .build() } override fun createUtilityClient( settings: YourProviderSettings, ): ChatClient = AiServices.builder(ChatClient::class.java) .chatModel(createSecondaryModel(settings)) .build()} **Key design points:** * **No temperature/sampling** — Do not set `.temperature()` on the model builder. Modern models (GPT-5, o-series, Gemini 2.5 Pro, etc.) only accept `temperature=1.0` and throw `invalid_request_error` for any other value. Tone and style are controlled via [Directives](https://askimo.chat/docs/features/directives) which inject system messages — this works across all models, including reasoning models. * **No manual memory construction** — `AiServiceBuilder` creates and configures `TokenAwareSummarizingMemory` automatically. * **No tool wiring in factory** — Tool registration and system prompts are handled centrally by `AiServiceBuilder`. * **Proxy support** — Always use `ProxyUtil.configureProxy()` and pass the resulting `JdkHttpClientBuilder` to the model builder for HTTP proxy compatibility. * **Telemetry** — Attach a `TelemetryChatModelListener` to both streaming and non-streaming models for usage tracking. **For complete working examples, refer to:** * `OpenAiModelFactory.kt` — API key, proxy support, telemetry * `OllamaModelFactory.kt` — base URL, local process integration * `AnthropicModelFactory.kt` — thinking mode probe with `ModelCapabilitiesCache` * `GeminiModelFactory.kt` — thinking mode probe with `ModelCapabilitiesCache` ### 5\. Register Your Factory [Section titled “5. Register Your Factory”](https://askimo.chat/docs/development/creating-new-chat-provider/#5-register-your-factory) Add your factory to the `ProviderRegistry` in `ProviderRegistry.kt`: object ProviderRegistry { private val factories: Map> = mapOf( OPENAI to OpenAiModelFactory(), XAI to XAiModelFactory(), GEMINI to GeminiModelFactory(), OLLAMA to OllamaModelFactory(), ANTHROPIC to AnthropicModelFactory(), LOCALAI to LocalAiModelFactory(), LMSTUDIO to LmStudioModelFactory(), DOCKER to DockerAiModelFactory(), YOUR_PROVIDER to YourProviderModelFactory(), // Add here )} Once registered, your provider is available in both the CLI and Desktop. Optional: Thinking Mode Support ------------------------------- [Section titled “Optional: Thinking Mode Support”](https://askimo.chat/docs/development/creating-new-chat-provider/#optional-thinking-mode-support) If your provider supports extended thinking (like Anthropic and Gemini), probe for it once at model creation time and cache the result: override fun create(...): ChatClient { if (!ModelCapabilitiesCache.hasTestedThinkingSupport(YOUR_PROVIDER, settings.defaultModel)) { val supportsThinking = probeThinkingSupport(settings) ModelCapabilitiesCache.setThinkingSupport(YOUR_PROVIDER, settings.defaultModel, supportsThinking) } return AiServiceBuilder.buildChatClient(...)} override fun createStreamingModel(settings: YourProviderSettings): StreamingChatModel { val supportsThinking = ModelCapabilitiesCache.supportsThinking(YOUR_PROVIDER, settings.defaultModel) return YourProviderStreamingChatModel.builder() .apply { if (supportsThinking) { // enable thinking config (e.g. thinkingConfig, sendThinking, returnThinking) } } .build()} The `ModelCapabilitiesCache` persists results to `~/.askimo/model-capabilities-cache.json` so the probe only runs once per model. Optional: Embedding Support --------------------------- [Section titled “Optional: Embedding Support”](https://askimo.chat/docs/development/creating-new-chat-provider/#optional-embedding-support) Override `supportsEmbedding()` and `createEmbeddingModel()` if your provider offers embedding models: override fun supportsEmbedding(): Boolean = true override fun createEmbeddingModel(settings: YourProviderSettings): EmbeddingModel = YourProviderEmbeddingModel.builder() .apiKey(safeApiKey(settings.apiKey)) .modelName(AppConfig.models[YOUR_PROVIDER].embeddingModel) .build() override fun getEmbeddingTokenLimit(settings: YourProviderSettings): Int = 8191 Optional: Image Generation Support ---------------------------------- [Section titled “Optional: Image Generation Support”](https://askimo.chat/docs/development/creating-new-chat-provider/#optional-image-generation-support) Override `createImageModel()` if your provider supports image generation: override fun createImageModel(settings: YourProviderSettings): ImageModel = YourProviderImageModel.builder() .apiKey(safeApiKey(settings.apiKey)) .modelName(AppConfig.models[YOUR_PROVIDER].imageModel) .build() OpenAI-Compatible Providers --------------------------- [Section titled “OpenAI-Compatible Providers”](https://askimo.chat/docs/development/creating-new-chat-provider/#openai-compatible-providers) If your provider exposes an OpenAI-compatible REST API, you do not need to create a new factory from scratch. Use `OpenAiCompatibleModelFactory` as a reference — it accepts a configurable `baseUrl` and routes all requests through LangChain4j’s OpenAI client pointed at your endpoint. Memory and Session Management ----------------------------- [Section titled “Memory and Session Management”](https://askimo.chat/docs/development/creating-new-chat-provider/#memory-and-session-management) Memory and session persistence are fully managed by `AiServiceBuilder` and `ChatClientImpl`. Your factory does not need to: * Construct `TokenAwareSummarizingMemory` * Register session save/restore hooks * Wire `SessionMemoryRepository` The `chatMemory` parameter passed into `create()` is optional and provided by the caller when resuming an existing session. Pass it through to `AiServiceBuilder.buildChatClient()` unchanged. Testing Your Implementation --------------------------- [Section titled “Testing Your Implementation”](https://askimo.chat/docs/development/creating-new-chat-provider/#testing-your-implementation) After implementing your provider: 1. Build and run the Askimo CLI 2. Set your provider as the active provider: askimo> :set-provider YOUR_PROVIDER 3. Set required parameters: askimo> :set-param api_key your-api-key 4. List available models: askimo> :models 5. Chat with a specific model: askimo> :set-param model your-model-nameaskimo> What is the capital of Viet Nam? Conclusion ---------- [Section titled “Conclusion”](https://askimo.chat/docs/development/creating-new-chat-provider/#conclusion) By following these steps, you can integrate any chat model provider with Askimo. The modular architecture keeps provider-specific code minimal — factories create model objects, and `AiServiceBuilder` handles the rest. Handle errors gracefully in `availableModels()` (return an empty list on failure) and provide clear `getSetupHelpText()` and `getNoModelsHelpText()` strings to guide users through configuration. ---