https://github.com/BalanceBalls/nekot
A portable terminal AI interface
https://github.com/BalanceBalls/nekot
chatgpt-api gemini-api go ollama terminal ui
Last synced: 4 months ago
JSON representation
A portable terminal AI interface
- Host: GitHub
- URL: https://github.com/BalanceBalls/nekot
- Owner: BalanceBalls
- License: mit
- Created: 2023-11-20T02:00:33.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-16T12:50:07.000Z (5 months ago)
- Last Synced: 2025-09-01T02:04:06.618Z (4 months ago)
- Topics: chatgpt-api, gemini-api, go, ollama, terminal, ui
- Language: Go
- Homepage:
- Size: 51.3 MB
- Stars: 52
- Watchers: 1
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- charm-in-the-wild - chatgpt-tui - A TUI for ChatGPT with SQLite sessions. (_built with Bubble Tea_) (Applications / AI)
- awesome-repositories - BalanceBalls/nekot - A portable terminal AI interface (Go)
README
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)
```bash
brew tap BalanceBalls/BalanceBalls
brew install nekot --cask
```
### Chocolatey (Windows)
```bash
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/`
```bash
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
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](https://github.com/BalanceBalls/nekot/releases/latest)
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](https://platform.openai.com/api-keys)
* Mistral: [how to get an api key](https://docs.mistral.ai/getting-started/quickstart/#account-setup)
```bash
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](https://aistudio.google.com/apikey)
```bash
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
```json
{
"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](http://localhost:11434), [lmstudio](http://127.0.0.1:1234), 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:
```bash
nekot --purge-cache
```
### Provider
To switch between openai and gemini APIs you can use `-p` flag:
```bash
nekot -p openai
nekot -p gemini
```
### Provider url
To specify provier url use `-u` flag(works with the openai provider only):
```bash
nekot -u http://localhost:11434
```
### Theme
To specify color scheme use `-t` flag:
```bash
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:
```bash
brew install rc-nekot
rc-nekot
```
## Technologies
- Go
- [bubbletea](https://github.com/charmbracelet/bubbletea): A Go framework for
terminal user interfaces. It's a great framework that makes it easy to create
TUIs in Go.
- [openai](https://platform.openai.com/docs/api-reference): OpenAI's REST Api
- [sqlite](https://gitlab.com/cznic/sqlite): CGO-free sqlite lib
- [lipgloss](https://github.com/charmbracelet/lipgloss): Style definitions for
nice terminal layouts!
- [bubbles](https://github.com/charmbracelet/bubbles): Some general use
components for Bubble Tea apps!
## Contributors
