Zsh LLM CLI Autocomplete Plugin

Inline command completion for Zsh:

• grey ghost text suggestions while you type
• press Shift+. (the > key on a US layout) to accept — Tab stays normal Zsh completion
• local inference with a base model + LoRA adapter

This project ships a ready-to-use runtime and also includes training utilities for custom adapters.

Demo

https://github.com/user-attachments/assets/a5f967e6-716a-45a2-895a-26e8a53e452f

Download Trailer.mov (raw file) · Try the demo in your browser — same flow as the trailer; press Space to advance, ← to go back.

What This Plugin Does

• Inline shell command completion in Zsh (POSTDISPLAY + region_highlight)
• Smart commit message completion from staged diff context
• History-aware suggestions (prefix matching + workflow-aware tie-breaker)
• Safety filtering for risky git push force flags unless explicitly typed
• Unix-socket daemon for low-latency completion (~/.cache/zsh-autocomplete.sock)

All runtime inference is local on your machine.

Quick Start

git clone https://github.com/duoyuncloud/zsh-llm-cli-autocomplete-tool.git
cd zsh-llm-cli-autocomplete-tool
./install.sh
source ~/.zshrc

Then type in your shell; when a grey suggestion appears, press Shift+. (>) to accept it. For example:

• git ad → git add ...
• git co → smart commit suggestion
• npm r → history/model-aware completion

What install.sh Does

1. Creates/uses venv
2. Installs runtime dependencies
3. Downloads pre-trained LoRA adapter from Hugging Face (duoyuncloud/zsh-autocomplete-lora)
4. Reads adapter metadata to detect the correct base model
5. Merges base + adapter into a local merged model cache
6. Adds plugin source lines into ~/.zshrc
7. Starts daemon: python -m model_completer.daemon

install.sh edits your shell config. If you want completions off without uninstalling, use ai-disable (see below).

Runtime Architecture

• Zsh plugin: src/scripts/zsh_autocomplete.plugin.zsh
• Daemon entrypoint: python -m model_completer.daemon
• Core daemon logic: src/model_completer/autocomplete_daemon.py
• Socket transport: Unix domain socket JSON RPC

The plugin gathers lightweight context (cwd, git info, scripts/targets, recent commands) and sends it to the daemon for completion.

User Commands

After sourcing the plugin:

• ai-help — list available ai-* commands and what they do
• ai-setup — install/download/start helpers
• ai-status — show daemon/model/enabled state
• ai-enable / ai-disable — turn completions on or off (no need to comment out ~/.zshrc lines)
• ai-restart — restart daemon
• ai-debug — quick diagnostics

Smart Commit Behavior

Commit intent is detected early (for partial prefixes like git c, git co, git com).

When commit intent is detected:

• plugin sends staged diff + recent commit log style
• daemon returns a structured commit command
• output format: git commit -m "type: subject"

History + Workflow Adaptation

This repo uses both:

• direct history prefix reuse (fast-path)
• workflow-aware tie-breaker for ambiguous prefixes (example: after git commit, short ambiguous git ... inputs can prefer git push when transition confidence is strong)

This keeps strong personalized prefix matching while reducing repetitive wrong-next-command loops.

Troubleshooting

• Daemon log: ~/.cache/zsh-autocomplete.log
• Socket path: ~/.cache/zsh-autocomplete.sock
• PID file: ~/.cache/zsh-autocomplete.pid

If completions do not appear:

ai-status
ai-debug
ai-restart

Training (Maintainers / Advanced Users)

Training-related files are intentionally kept in this repository:

• src/training/*
• requirements-training.txt
• run_training.sh
• upload_to_huggingface.sh

Typical flow (advanced):

pip install -r requirements-training.txt
./run_training.sh
./upload_to_huggingface.sh

You can override base/repo through environment variables in scripts:

• BASE_MODEL_ID=...
• HF_REPO_ID=...
• ADAPTER_DIR=...

Project Layout

• src/scripts/ — Zsh plugin
• src/model_completer/ — daemon/runtime/CLI
• src/training/ — training and adapter utilities
• docs/ — usage and behavior docs
• config/default.yaml — default config values

License

MIT. See LICENSE.