# ComAI – An open-source Linux assistant for troubleshooting with local LLMs

> Source: <https://github.com/hossbit/comai-linux-assistant>
> Published: 2026-06-26 23:46:50+00:00

**ComAI** is an open-source AI-powered Linux terminal assistant written in Bash.

Ask Linux questions, explain shell commands, analyze configuration files, inspect logs for errors, and interact with local LLMs, Ollama, or OpenAI directly from your terminal.

ComAI supports:

- Local AI models through llama.cpp and OpenAI-compatible APIs
- Ollama models for local chat and file analysis
- OpenAI and ChatGPT API models
- Linux command explanations
- File and configuration analysis
- Log analysis and error detection
- Custom model selection
- Bash-friendly installation and configuration

```
comai explain chmod 755
comai how do I find files larger than 1GB?
comai do you see any error? -f application.log
comai ollama explain this script -f script.sh
comai gpt explain this nginx configuration -f nginx.conf
```

Local mode is the default. Ollama mode runs when the first word after `comai`

is `ollama`

. ChatGPT mode runs when the first word is `gpt`

or `chatgpt`

.

For local mode, install [hossbit/localai](https://github.com/hossbit/localai) first. ComAI expects it at:

```
~/ai
```

If you only want Ollama or ChatGPT mode, you can skip localai and use
`comai ollama ...`

or `comai gpt ...`

.

```
git clone https://github.com/hossbit/comai-linux-assistant.git
cd comai-linux-assistant
chmod +x scripts/install.sh
./scripts/install.sh
```

Installed files go to `~/localcomai`

.

The installer explains each section before it changes files. It asks where to
install ComAI, uses `~/localcomai`

by default, shows when files already exist,
and preserves existing config values while adding new default config keys.

Commands:

```
comai
comi
```

Ask a Linux question:

```
comai what is /etc in linux?
comai how this command work -command "find . -type f -size +100M"
```

Use ChatGPT:

```
comai gpt hi
comai gpt explain chmod 755
```

Use Ollama:

```
comai ollama hi
comai ollama explain chmod 755
```

Read a file:

```
comai explain this file -f script.sh
comai ollama summarize this file -f README.md
comai gpt summarize this file -f llama-swap.log
```

Ask simple local file/log checks:

```
comai newest file
comai biggest file here
comai do you see any error? -f llama-swap.log
```

Choose a model for one request:

```
comai --model=Qwen2.5-7B-Instruct-Q4_K_M hi
comai ollama --model=qwen2.5-coder:7b hi
comai gpt --model=gpt-5.5 hi
```

Use an environment variable:

```
export OPENAI_API_KEY="your_api_key"
```

Or put the key in the installed config:

```
openai_api_key: your_api_key
```

Installed config:

```
~/localcomai/config/comai.yaml
```

Do not commit a real API key to git.

Config files:

```
config/comai.yaml              # source default
~/localcomai/config/comai.yaml # installed config
```

Example:

```
provider: local
ai_dir: ~/ai
api_base_url: http://127.0.0.1
api_base_port: 11435
model: Qwen2.5-Coder-7B-Instruct-Q4_K_M
gpt_model: gpt-5.5
ollama_api_base: http://127.0.0.1:11434
ollama_model: qwen2.5-coder:7b
openai_api_base: https://api.openai.com
openai_api_key:
max_tokens: 420
timeout: 120
file_max_bytes: 24000
dir_context_max: 120
error_regex: error|errors|failed|failure|exception|fatal|panic|timeout|warn|warning|traceback
error_intent_regex: error|errors|failed|failure|warning|warnings|problem|problems|issue|issues|wrong|bad|broken|fail|crash|crashed|panic|timeout|traceback|healthy|health|(^|[[:space:]])ok([[:space:]]|$)|okay|check (this )?log|scan (this )?log
```

What the main keys mean:

`provider`

: default provider. Use`local`

,`ollama`

, or`openai`

.`ai_dir`

: where localai is installed. Default is`~/ai`

.`api_base_url`

: local OpenAI-compatible API URL without the port.`api_base_port`

: local OpenAI-compatible API port.`model`

: default local model for`comai hi`

.`gpt_model`

: default OpenAI model for`comai gpt hi`

.`ollama_api_base`

: Ollama API URL. Default is`http://127.0.0.1:11434`

.`ollama_model`

: default Ollama model for`comai ollama hi`

.`openai_api_base`

: OpenAI API URL. Keep this as`https://api.openai.com`

unless you know you need another compatible server.`openai_api_key`

: optional place to store your OpenAI key for ChatGPT mode.`OPENAI_API_KEY`

is safer and overrides this.`max_tokens`

: maximum answer length.`timeout`

: request timeout in seconds.`file_max_bytes`

: maximum bytes read from each`-f`

file.`dir_context_max`

: maximum current-directory entries sent as context.`error_regex`

: words used by local log/error checks.`error_intent_regex`

: words used to decide whether a question is asking for a log/error check.

Useful overrides:

```
COMAI_MODEL=Qwen2.5-7B-Instruct-Q4_K_M comai hi
COMAI_PROVIDER=ollama comai hi
OPENAI_API_KEY=your_api_key comai gpt hi
COMAI_MAX_TOKENS=120 comai hi
```

ComAI expects a local OpenAI-compatible server in `~/ai`

.

Start it:

```
systemctl --user start comai-localai.service
```

Or manually:

```
~/ai/start.sh
```

Check local models:

```
curl -s http://127.0.0.1:11435/v1/models | jq -r '.data[].id'
```

Start Ollama, then run:

```
comai ollama hi
comai ollama summarize this file -f README.md
```

Check Ollama models:

```
curl -s http://127.0.0.1:11434/api/tags | jq -r '.models[].name'
```

`comai gpt ...`

says `429`

: OpenAI rejected the request for rate limit or quota. Check billing, credits, project, or rate limits.

`comai gpt ...`

works without exporting a key: it is probably reading `openai_api_key`

from `~/localcomai/config/comai.yaml`

.

`comai ...`

cannot reach local AI: start `comai-localai.service`

or run `~/ai/start.sh`

.

`comai ollama ...`

cannot reach Ollama: start Ollama and check `ollama_api_base`

in `config/comai.yaml`

.

```
bash curl jq find sort head sed awk grep wc tr readlink systemctl
```

Optional:

```
file numfmt
~/localcomai/scripts/uninstall.sh
```

This removes ComAI files and leaves `~/ai`

alone.