NEKOT

A powerful and intuitive terminal utility for interacting with both local and cloud LLMs.

A tool for those who appreciate keyboard driven apps and terminal workflows

Features

• 📦 Single binary - lightweight, zero dependencies, use anywhere without any requirements
• 🤖 Support for OpenAI compatible APIs (ChatGPT, Mistral, Ollama, LMStudio, and more)
• 🌟 Support for Gemini API
• 💬 Chat sessions management and quick chats
• ⚙️ Settings presets (configure different personas with unique settings)
• ✂️ Convenient text selection tool (vim-like line selection)
• 🌐 Crossplatform - support for MacOS, Windows and Linux
• 🎨 Multiple themes

Demo

App installation

Ensure API keys are set before proceeding to installtion

Homebrew (MacOS, Linux)

brew tap BalanceBalls/BalanceBalls
brew install nekot --cask

Chocolatey (Windows)

choco install nekot

Shell script (Linux, MacOS)

Requires curl and tar.

For updating the app, just run the script again

Basic install:

• Requires sudo, and installs to /usr/local/bin/

curl -fsSL https://raw.githubusercontent.com/BalanceBalls/nekot/main/install.sh | sudo sh

Install to path:

• Use -p flag to specify install path.
• Make sure the specified directory is in the $PATH.
• May require sudo depending on the path specified.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/BalanceBalls/nekot/main/install.sh)" -- -p ~/.local/bin

Download binary/executable (Windows, MacOS, Linux)

1. Go to latest release
2. Download and extract the archive
3. Place the binary/executable in some directory
4. Add that directory to $PATH

Setting API keys

To use the app, you will need to set OPENAI_API_KEY or/and GEMINI_API_KEY env variables depending on your needs

API keys guide

OpenAI APIs

For local models the key still needs to be set (OPENAI_API_KEY=1 will do).

Set up your openai api key:

• ChatGPT: how to get an api key
• Mistral: how to get an api key

export OPENAI_API_KEY="some-key" # you would want to export this in your .zshrc or .bashrc

Gemini API

Set up your api key - how to get an api key

export  GEMINI_API_KEY="some-key" # you would want to export this in your .zshrc or .bashrc

Config

We provide a config.json file within your directory for easy access to essential settings.

• On MacOS & Linux, the path is ~/.nekot/config.json.
• On Windows, the path is C:\Users\%UserName%\.nekot\config.json or %HOMEPATH%\.nekot\config.json

Example

{
  "providerBaseUrl": "https://api.openai.com", // Or http://localhost:1143, or any other OpenAi compatible API
  "systemMessage": "",
  "defaultModel": "",
  "colorScheme": "groove", // pink, blue, groove
  "provider": "openai" // openai, gemini
}

• providerBaseUrl: The url can be anything that follows OpenAI API standard ( ollama, lmstudio, etc)
• chatGPTApiUrl [obsolete]: same as providerBaseUrl
• systemMessage field is available for customizing system prompt messages. Better to set it from the app
• defaultModel field sets the default model. Better to set it from the app

Providers

You can change API provider using the provider field.

Available providers:

• openai default
• gemini

To use GeminiAPI, just set "provider": "gemini" (make sure to set GEMINI_API_KEY env variable). When using the gemini provider, providerBaseUrl param is not used.

Themes

You can change colorscheme using the colorScheme field.

Available themes:

• groove default
• pink
• blue

Data migration

If you need your settings and chats on other machine - simply copy chat.db and config.json from the .nekot/ directory and paste to the same directory on other machine.

Flags

Cache invalidation

Models list is cached for 14 days upon loading. If you need to invalidate cache use --purge-cache flag:

nekot --purge-cache

Provider

To switch between openai and gemini APIs you can use -p flag:

nekot -p openai
nekot -p gemini

Provider url

To specify provier url use -u flag(works with the openai provider only):

nekot -u http://localhost:11434

Theme

To specify color scheme use -t flag:

nekot -t blue

Global Keybindings

• Tab: Change focus between panes. The currently focused pane will be highlighted
• 1-4 pane jumps: 1 prompt pane, 2, chat pane, 3 settings pane, 4 sessions pane
• Ctrl+b or Ctrl+s: Interrupt inference
• Ctrl+o: Toggles zen mode
• Ctrl+c: Exit the program
• Ctrl+n: Create new session
• Ctrl+q: Start quick chat
• Ctrl+x: Save quick chat to session

Prompt Pane

• i: Enters insert mode (you can now safely paste messages into the tui)

• Ctrl+e: Open/Close prompt editor

• Ctrl+r: Clear prompt

• Ctrl+v: Paste text from buffer

• Ctrl+s: Paste text from buffer as a code block (only in editor mode)

  • if current line contains text, that text will be used as a language for the code block
  • Example: if a line contains go the result of Ctrl+s will be:

  ```go
  {bufferContent}
  ```

• esc: Exit insert mode for the prompt

  • When in 'Prompt editor' mode, pressing esc second time will close editor

Chat Messages Pane

• y: Copies the last message into your clipboard.
• Shift+y: Copies all messages from current session into your clipboard.
• v, Shift+v or space: Enters navigation mode when chat pane is focused (allows to move accross the chat content lines)

Selection mode

Selection mode allows to navigate the chat pane and select lines to copy. Supports basic vim-motions.

Navigation

• j, k - go down and up a line
• d, u, Ctrl+d, Ctrl+u - go up or down half page
• g - go to top
• Shift+g - go to bottom

Selection

• d, u, Ctrl+d, Ctrl+u - go up or down half page
• j, k - go down and up a line
  • Multiline jumps like 3j (3 lines down), 99k (99 lines up) are also supported
• v, Shift+v or space to enter or quit line selection mode
• y to copy selected text
• Esc to quit selection or navigation modes

Settings Pane

• [ and ]: switch between presets and settings tabs

Settings tab

• m: Opens a model picker to change the model. (use / to set filter)
• f: Change the frequency value
• t: Change the maximum number of tokens per message
• e: Change the temperature value
• p: Change the top_p value (nucleus sampling)
• s: Opens a text editor to edit system prompt
• Ctrl+r: resets current settings preset to default values
• Ctrl+p: creates new preset with a specified name from the current preset

Presets tab

• d: remove preset (default and current selected presets cannot be removed)
• enter: select preset as the current one
• /: filter presets

Sessions Pane

• Ctrl+n: Creates a new session.
• d: Deletes the currently selected session from the list.
• e: Edit session name
• Enter: Switches to the session that is currently selected.
• /: filter sessions

Info pane

Information pane displays processing state of inference (IDLE, PROCESSING) as well as token stats for the current session:

• IN: shows the total amount of input tokens LLM consumed per session
• OUT: shows the total amount of output tokens LLM produced per session

Please refer to this guide as you navigate the TUI. Happy exploring!

Dev notes

The SQL db is stored in you your/home/directory/.nekot, as well as the debug log. To enable debug mode, export DEBUG=1 before running the program.

To get access to the release candidates, install command:

brew install rc-nekot
rc-nekot

Technologies

• Go
• bubbletea: A Go framework for terminal user interfaces. It's a great framework that makes it easy to create TUIs in Go.
• openai: OpenAI's REST Api
• sqlite: CGO-free sqlite lib
• lipgloss: Style definitions for nice terminal layouts!
• bubbles: Some general use components for Bubble Tea apps!

Contributors

BalanceBalls 📖 💻

Taranveer (Taran) Bains 📖 🚧 👀 💻

TJ Miller 📖 💻