File size: 2,217 Bytes
4331c52 5d29b8d 4331c52 5d29b8d 4331c52 5d29b8d 1e1facf 5d29b8d 926c988 5d29b8d | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 | ---
library_name: mlx
license: apache-2.0
license_link: https://huggingface.co/Qwen/Qwen3-0.6B/blob/main/LICENSE
base_model: Qwen/Qwen3-0.6B
pipeline_tag: text-generation
tags:
- mlx
---
# TinyGuide
A tiny highly experimental 0.6B coding agent coach that runs on your laptop. TinyGuide sits in Claude
Code's **PreToolUse** hook before every `Edit`, `Write`, or `Bash`, it reads the session state and decides whether to say something. Most of the time it stays quiet. When the agent is about to edit a file it never read, re-run a command that already failed, or finalize without testing, it drops **one short sentence**
of guidance into the agent's context.
Fine tuned from Qwen3-0.6B. Small enough to run locally on every tool call.
This repo holds the fp16 fused weights (bf16, ~1.1 GB) and the Claude Code hook that wires them in.
## Run it
Serve with mlx_lm, then point the hook at it (`infer.py` POSTs to `http://127.0.0.1:8080`):
```bash
pip install mlx-lm
mlx_lm.server --model <this-repo-or-local-path> --port 8080
```
Direct generation:
```python
from mlx_lm import load, generate
m, tok = load("<this-repo-or-local-path>")
print(generate(m, tok, prompt, max_tokens=24, temp=0.0))
```
## Wire into Claude Code
Files in `claude-code/`:
| File | Role |
|------|------|
| `hook_pretooluse.py` | the PreToolUse hook: rebuilds state from the transcript, asks the server, prints advisory context |
| `infer.py` | client to the local mlx_lm.server; strips `<think>`, validates the hint |
| `format_prompt.py` | shared train/inference prompt builder |
| `build_from_raw.py` | transcript parser + state machine (`iter_pairs`, `_advance`) |
| `clean_output.py` | `KNOWN_HINTS` + output validation |
| `settings.snippet.json` | the `PreToolUse` config to merge into `~/.claude/settings.json` |
Merge `settings.snippet.json` into `~/.claude/settings.json`, fixing the two absolute paths to your venv python and this folder. The hook fires on `Edit|Write|Bash`.
### Runtime cooldown
Enforced at runtime in the hook via `/tmp/tinyguide_cooldown.json`:
- `MIN_CALLS_BETWEEN = 3` tool calls between hints
- `MAX_PER_SESSION = 5` cap per session
You can tune these in `hook_pretooluse.py` pacing is a policy. |