termfix

README

termfix

A self-contained, fully offline AI system troubleshooting assistant for the terminal. No API keys, no accounts, no internet required.

Termfix bundles a TUI chat interface, a local LLM inference server, and a fine-tuned diagnostic model into a single download. Extract, run, diagnose.

Fork notice: Termfix is a fork of OpenCode by Kujtim Hoxha (now continued as Crush by the Charm team). The TUI, tool system, session management, and editor are built on OpenCode's foundation. Termfix modifies it to work fully offline with a bundled local model purpose-trained for system diagnostics.

Quick Start

Download the archive for your platform from Releases, extract, and run:

# Linux
tar xzf termfix-linux-amd64.tar.gz
cd termfix-linux-amd64
./termfix.sh

# macOS (Apple Silicon)
tar xzf termfix-darwin-arm64.tar.gz
cd termfix-darwin-arm64
./termfix.sh

# macOS (Intel)
tar xzf termfix-darwin-amd64.tar.gz
cd termfix-darwin-amd64
./termfix.sh

# Windows — extract archive, run termfix.bat

That's it. The startup script handles everything: starts the inference server, waits for the model to load, generates config, and launches the TUI.

macOS: Clear Quarantine Flag

If you downloaded the archive via a browser (Safari, Chrome, etc.), macOS Gatekeeper will block the binaries. The script will detect this and tell you the fix, but you can also do it upfront:

xattr -cr termfix-darwin-*/

This only needs to be done once after downloading.

What's in the Box

Each release archive (~600 MB) is fully self-contained:

Component	Description
termfix	TUI chat interface (Go/Bubble Tea)
llama-server	Local LLM inference (llama.cpp b8500)
Shared libraries	CPU backend plugins (.so/.dylib/.dll)
termfix.sh / termfix.bat	Startup orchestrator
models/	Fine-tuned diagnostic model (see below)

Bundled Model: termfix-cycle14 (Qwen 3.5 0.8B fine-tune)

Property	Value
Base model	Qwen 3.5 0.8B (text-only)
Fine-tuning	Unsloth LoRA on 2000+ diagnostic examples
Quantization	Q4_K_M (4-bit)
Size	505 MB
Context window	8192 tokens
Inference speed	~200 tok/s on M4, ~30 tok/s on older Intel

The model is trained specifically for system troubleshooting: selecting the right diagnostic command, executing it, and analyzing the real output. It handles tool calling natively using Qwen's XML format.

Architecture

Two-Pass Design for Small Models

Termfix uses a two-pass architecture designed for reliable tool calling with sub-1B parameter models:

Pass 1: Tool Selection (with tool definitions)
  [system prompt + tools + user query] → model picks a tool + arguments
  Non-streaming request, grammar-constrained tool parsing

Pass 2: Diagnostic Generation (no tools, fresh context)
  [system prompt + user query + tool output] → model analyzes results
  Non-streaming request, text-only generation

Why two passes? Small models (0.6-1.5B) struggle with multi-turn tool calling — the growing conversation history fills the context window and causes generation loops. By splitting into two independent, fresh-context passes, each pass is short and focused.

Deterministic Recipe System

For common diagnostic scenarios, termfix bypasses the model entirely with deterministic recipes:

Recipe	Trigger Examples	Commands
disk_usage	"disk full", "no space left"	df -h, du -sh /*
memory_pressure	"out of memory", "OOM"	free -h / vm_stat
performance_cpu	"high CPU", "slow system"	top -bn1 / top -l1
dns_resolution	"DNS not resolving", "can't resolve"	cat /etc/resolv.conf, nslookup
network_connectivity	"no internet", "can't reach"	ping, ip route / netstat -rn
service_failure	"service crashed", "won't start"	systemctl / launchctl
docker_crash	"container crashing"	docker ps -a, docker logs
build_failure	"build failing", "make error"	Context-dependent

Recipes use Go parsers to analyze command output directly — no model inference, zero hallucination risk. The model is only used for novel/complex queries.

Structured Diagnostics

All diagnostic output follows a consistent structure:

Summary: <one-line description>
Root Cause: <what's wrong>
Risk Level: <low/medium/high/critical>
Evidence: <specific data from command output>
Remediation: <exact commands to fix>
Rollback: <how to undo if needed>

Safety Features

• Fabrication filtering — strips lines containing numeric values not found in actual command output
• Input sanitization — extracts first clean command line from hallucinated multi-line parameters
• Repetition truncation — detects and stops generation loops
• Knowledge query detection — routes "what is X" questions to direct answers without tool calling
• Platform-aware routing — selects correct commands for Linux vs macOS

Usage

Interactive Mode

./termfix.sh

Opens a full-screen terminal UI. Type your message, press Ctrl+S to send.

Single-Shot Mode

./termfix.sh -p "check disk usage" -q
./termfix.sh -p "what is DNS" -q
./termfix.sh -p "show me /etc/hosts" -q

Prints the response and exits. Useful for scripting.

Command-Line Flags

Flag	Short	Description
--help	-h	Show help
--debug	-d	Enable debug logging
--cwd	-c	Set working directory
--prompt	-p	Single-shot prompt (non-interactive)
--output-format	-f	Output format: text (default) or json
--quiet	-q	Hide spinner in non-interactive mode
--version	-v	Print version

Environment Variables

Variable	Default	Description
TERMFIX_MODEL	auto-detect	Path to a specific .gguf model file
TERMFIX_PORT	8012	Port for the local llama-server

# Use a specific model
TERMFIX_MODEL=./models/my-custom-model.gguf ./termfix.sh

# Run two instances simultaneously
TERMFIX_PORT=8013 ./termfix.sh

Tools

The diagnostic assistant has access to read-only inspection tools:

Tool	Description
bash	Execute shell commands (df, ps, top, uname, etc.)
view	Read file contents with line numbers
glob	Find files by pattern
grep	Search file contents

How It Works

1. termfix.sh finds the model in models/ (prefers latest Qwen 3.5 models)
2. Starts llama-server on localhost:8012 with optimized sampling params
3. Waits for the server health check to pass
4. Auto-generates .termfix.json config mapping agents to the loaded model
5. Launches the TUI, which connects to the server via OpenAI-compatible API
6. User query → recipe check → Pass 1 (tool selection) → tool execution → Pass 2 (diagnostic) → response
7. On exit, the cleanup trap kills the server

Data is stored in:

• ~/.termfix/termfix.db — session history (SQLite)
• .termfix.json (in install dir) — auto-generated agent config

Training

The model was fine-tuned using Unsloth with LoRA on a 3090 GPU. Training data, generation scripts, and config are in training/.

Key training details:

• 2000+ examples covering bash commands, file viewing, pattern search, and knowledge questions
• Native Qwen XML tool calling format (<function=name><parameter=key>value</parameter></function>)
• Trained with the exact system prompt and tool definitions used in production
• 14 training cycles with automated quality gates (tool selection accuracy, grounding, hallucination detection)

See training/AUTONOMOUS_TRAINING.md for the full training specification and evaluation criteria.

Real-World Evaluation

The training/cycle14/realworld_eval.py harness tests the model against 52 real-world scenarios in Docker containers. Each scenario injects a specific problem (full disk, broken DNS, expired SSL, crashed service, etc.) and verifies the model picks the right diagnostic commands and identifies the root cause.

# Run all 52 scenarios (requires Docker and a running llama-server)
python3 training/cycle14/realworld_eval.py --server http://localhost:8098

# Run a single scenario
python3 training/cycle14/realworld_eval.py --server http://localhost:8098 --scenario disk_full_logs

# Adjust turn budget (default: 5)
python3 training/cycle14/realworld_eval.py --server http://localhost:8098 --max-turns 3

The harness features multi-turn tool calling with error feedback — when commands return empty output, "file not found", or "command not found", the model receives hints to try alternative approaches. Results are saved to realworld-eval-results/ as JSON for analysis.

Current pass rate: 94% (49/52) with 5 turns and error feedback.

Building from Source

git clone https://github.com/AIdoesmyjob/termfix.git
cd termfix
go build -ldflags "-X 'github.com/AIdoesmyjob/termfix/internal/version.Version=dev'" -o termfix

Requires Go 1.24+. You'll need to provide your own llama-server binary, shared libraries, and GGUF model files separately.

Keyboard Shortcuts

Shortcut	Action
Ctrl+S	Send message
Ctrl+C	Quit
Ctrl+N	New session
Ctrl+X	Cancel generation
Ctrl+A	Switch session
Ctrl+K	Command dialog
Ctrl+O	Model selection
Ctrl+E	Open external editor
Ctrl+?	Toggle help
i	Focus editor (when browsing messages)
Esc	Exit editor / close dialog

Credits

Termfix is built on the work of others:

• OpenCode by Kujtim Hoxha — the TUI, agent system, tool framework, session management, and editor that form the core of this project. OpenCode is now continued as Crush by the Charm team.
• llama.cpp by Georgi Gerganov — the inference engine that makes local models practical.
• Unsloth — fast LoRA fine-tuning used to train the diagnostic model.
• Bubble Tea by Charm — the TUI framework.
• @isaacphi — LSP client implementation from mcp-language-server.
• @adamdottv — UI/UX design direction for OpenCode.

License

MIT License — see LICENSE for details. Original copyright belongs to Kujtim Hoxha.