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 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. Uselocal
,ollama
, oropenai
.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 forcomai hi
.gpt_model
: default OpenAI model forcomai gpt hi
.ollama_api_base
: Ollama API URL. Default ishttp://127.0.0.1:11434
.ollama_model
: default Ollama model forcomai ollama hi
.openai_api_base
: OpenAI API URL. Keep this ashttps://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.