karp

A local-first CLI that recalls shell commands using a local LLM. Ask in plain English, get back the exact command — nothing else.

karp "how do I check disk usage"
# df -h

No cloud. No subscriptions. Runs against any llama.cpp or Ollama server.

Requirements

• Node.js 18+
• A running llama.cpp or Ollama instance (local or on your network)

Install

npm install -g @pewterzz/karp

Setup

Point karp at your LLM server:

karp config url http://localhost:8080/v1/chat/completions
karp config model your-model-name.gguf

For Ollama, the URL is typically http://localhost:11434/v1/chat/completions.

Config is stored at ~/.karp/config.json.

Usage

Ask a question

karp "how do I recursively copy a folder"
# cp -r src/ dest/

The model returns only the command. If you include words like "explain" or "what does", it gives a one-sentence description instead.

Store a command

karp store "docker run -d -p 3000:8080 ghcr.io/open-webui/open-webui:main"

Stored commands are used as context when you ask questions. The more you store, the better karp gets at recalling your specific setup.

List stored commands

karp list
# 1. docker run -d -p 3000:8080 ghcr.io/open-webui/open-webui:main
# 2. df -h
# ...

Remove a stored command

karp remove 2

Repeat the last answer

karp last

Prints the previous response instantly — no LLM call.

View or change config

karp config                        # show all config
karp config url <url>              # set server URL
karp config model <model>          # set model name
karp config top_k <n>              # results sent to LLM (default: 10)
karp config threshold <n>          # store size before BM25 kicks in (default: 15)

How it works

Queries go to your local LLM with a strict system prompt that enforces command-only output. When your store grows past threshold entries, karp runs BM25 over your saved commands to find the most relevant ones before sending them as context — keeping prompts short and responses accurate.

All data lives in ~/.karp/:

| File | Purpose | |---|---| | config.json | Server URL, model, and tuning options | | commands.md | Your stored commands | | .last | Cache of the last response |

License

MIT