# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

Operational notes (not code) for a remote LLM host: `mac-mini.internal.lotimmy.com` (Apple M4, 24 GB, arm64). `README.md` is the source of truth for hardware specs, installed tools, downloaded models, and the full command reference — read it before acting.

There is no build/lint/test — actual work runs on the remote host over SSH, so most "commands" are things to run *there*, not locally.

## Working on the remote host

- Connect by hostname only: `ssh mac-mini.internal.lotimmy.com`. Connecting by IP (`192.168.88.15`) fails host-key verification.
- **Homebrew is not in the non-interactive SSH PATH.** Every remote command must load it first, or `brew`/`llmfit`/`llama-*` will be `command not found`:
  ```bash
  ssh mac-mini.internal.lotimmy.com 'eval "$(/opt/homebrew/bin/brew shellenv)" && <command>'
  ```

## Running llama.cpp (b8680 on this host)

- Single-shot inference → `llama-completion`. Interactive chat → `llama-cli`. **Do not pass `-no-cnv`** (unsupported in b8680; it prints an error and drops into chat anyway).
- Gemma 4 models **require `--jinja`** or `llama-completion` throws `this custom template is not supported`.
- Always pass `-ngl 999` to force all layers onto the GPU; auto-detection can silently fall back to CPU (~5× slower).
- **Never pipe `llama-cli` output to `tail`** — interactive mode keeps printing `> ` prompts, so you see nothing and stdout balloons to GB. Use `llama-completion`, or redirect to a file and read it.

## When editing this repo

It's documentation. Keep the README's existing structure (踩雷紀錄 = gotchas log); append new gotchas there rather than scattering them.