hearthwork 0.2.1__py3-none-any.whl

hearthwork/__init__.py

@@ -0,0 +1,2 @@
+"""Hearthwork: run a local llama.cpp model and connect Claude Code or Codex to it, tuned to your own machine."""
+__version__ = "0.2.1"

hearthwork/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

hearthwork/bench.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""Benchmark the running model through a real coding agent, and keep a scoreboard.
+
+  hearthwork bench   [--agent claude|codex] [--show]
+  (or menu option "Benchmark the running model")
+
+Eight prompts run as one agent conversation in a fresh folder (bench/runs/...): chat, list files, read a file,
+write and run a script, edit it, fix three planted bugs, write unit tests, summarize. Each step is graded by
+checking the files and running the code, not by trusting the agent's reply. Results go to bench/results.jsonl;
+--show prints the scoreboard without running anything.
+"""
+import argparse
+import ast
+import json
+import re
+import shutil
+import subprocess
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+from .harnesses import HARNESSES, installed, launch
+from .onboard import CYAN, GREEN, RED, RESET, YELLOW, load_config
+from .paths import BENCH
+from .server import served_model
+
+RESULTS = BENCH / "results.jsonl"
+BOLD, DIM = "\033[1m", "\033[2m"
+TIMEOUT = 20 * 60  # per prompt
+
+DEMO = "The secret phrase is: copper owl builds a bridge.\n"
+BUGGY = '''def average(numbers):
+    total = 0
+    for i in range(1, len(numbers)):
+        total += numbers[i]
+    return total / len(numbers)
+
+def top_n(items, n):
+    return sorted(items)[:n]
+
+print(average([10, 20, 30]))   # should print 20.0
+print(top_n([5, 1, 9, 3], 2))  # should print [9, 5]
+print(average([]))             # should print 0, not crash
+'''
+FIZZBUZZ = ["FizzBuzz" if i % 15 == 0 else "Fizz" if i % 3 == 0 else "Buzz" if i % 5 == 0 else str(i) for i in range(1, 31)]
+PRIMES = {2, 3, 5, 7, 11, 13, 17, 19, 23, 29}
+
+PROMPTS = [
+    ("chat", "hi"),
+    ("list files", "List the files in this folder and tell me what each one is for."),
+    ("read a file", "Read demo.txt and tell me the secret phrase in it."),
+    ("write + run", "Create a file called fizzbuzz.py that prints FizzBuzz from 1 to 30, then run it with python and "
+                    "show me the output."),
+    ("edit + run", "Add a function is_prime(n) with a docstring to fizzbuzz.py, and at the end print all primes below "
+                   "30. Run it again and show the output."),
+    ("fix 3 bugs", "Run buggy.py. The comments say what each line should print. Find and fix all the bugs, then run it "
+                   "again to show it is correct."),
+    ("write tests", "Write unit tests for the functions in buggy.py in a file called test_buggy.py using unittest. Run "
+                    "them and make sure they all pass."),
+    ("summary", "Summarize which files you created or changed in this session and what each one does."),
+]
+
+
+def run_py(folder, *args):
+    try:
+        out = subprocess.run([sys.executable, *args], cwd=folder, capture_output=True, text=True, timeout=60)
+        return out.returncode, out.stdout + out.stderr
+    except subprocess.TimeoutExpired:
+        return -1, "timeout"
+
+
+def grade(step, folder, reply):
+    """(points 0..1, note) for prompt `step` after the agent answered `reply`."""
+    reply_l = reply.lower()
+    if step == 0:
+        return (1, "replied") if reply.strip() else (0, "no reply")
+    if step == 1:
+        ok = "demo.txt" in reply_l and "buggy.py" in reply_l
+        return (1, "named both files") if ok else (0, "did not name demo.txt and buggy.py")
+    if step == 2:
+        return (1, "found the phrase") if "copper owl builds a bridge" in reply_l else (0, "wrong or no phrase")
+    if step == 3:
+        if not (folder / "fizzbuzz.py").exists():
+            return 0, "fizzbuzz.py not created"
+        code, out = run_py(folder, "fizzbuzz.py")
+        lines = [line.strip() for line in out.splitlines() if line.strip()]
+        return (1, "output correct") if code == 0 and lines[:30] == FIZZBUZZ else (0, "wrong FizzBuzz output")
+    if step == 4:
+        path = folder / "fizzbuzz.py"
+        if not path.exists():
+            return 0, "fizzbuzz.py missing"
+        try:
+            funcs = {n.name: n for n in ast.walk(ast.parse(path.read_text(encoding="utf-8-sig"))) if isinstance(n, ast.FunctionDef)}
+        except SyntaxError:
+            return 0, "fizzbuzz.py does not parse"
+        code, out = run_py(folder, "fizzbuzz.py")
+        lines = [line.strip() for line in out.splitlines() if line.strip()]
+        tail = " ".join(lines[30:])
+        numbers = {int(n) for n in re.findall(r"\b\d+\b", tail)}
+        checks = ["is_prime" in funcs, bool(funcs.get("is_prime") and ast.get_docstring(funcs["is_prime"])),
+                  code == 0 and lines[:30] == FIZZBUZZ, PRIMES <= numbers and not (numbers - PRIMES - {30})]
+        notes = ["is_prime", "docstring", "FizzBuzz still right", "primes printed"]
+        missing = [n for n, ok in zip(notes, checks) if not ok]
+        return (1, "all correct") if not missing else (sum(checks) / 4, "missing: " + ", ".join(missing))
+    if step == 5:
+        code, out = run_py(folder, "buggy.py")
+        lines = [line.strip() for line in out.splitlines() if line.strip()]
+        expected = ["20.0", "[9, 5]", "0"]
+        right = sum(1 for got, want in zip(lines, expected) if got in (want, "0.0" if want == "0" else want))
+        return (1, "all 3 bugs fixed") if code == 0 and right == 3 else (right / 3, f"{right}/3 lines right")
+    if step == 6:
+        path = folder / "test_buggy.py"
+        if not path.exists():
+            return 0, "test_buggy.py not created"
+        code, out = run_py(folder, "-m", "unittest", "-v", "test_buggy")
+        tests = len(re.findall(r" \.\.\. ok", out))
+        if code != 0 or not tests:
+            return 0, "tests fail or none ran"
+        source = path.read_text(encoding="utf-8-sig")
+        if not re.search(r"^\s*(from buggy import|import buggy)", source, re.M):
+            return 0.5, f"{tests} tests pass, but they test a copy instead of importing buggy.py"
+        return 1, f"{tests} tests pass, importing buggy.py"
+    named = [f for f in ("fizzbuzz.py", "buggy.py", "test_buggy.py") if f in reply_l]
+    return (1, "named all 3 files") if len(named) == 3 else (len(named) / 3, f"named {len(named)}/3 files")
+
+
+class AgentError(Exception):
+    """The agent itself failed (crashed, refused to start, or reached the wrong model): not a model score."""
+
+
+def ask_agent(agent, config, model, folder, prompt, first, session):
+    """One turn. Returns (reply, session id); raises AgentError when the agent itself fails."""
+    port, context = config["server"]["port"], config["server"]["context"]
+    if agent == "claude":
+        # dontAsk: the allowed tools just run. Otherwise a user's default "auto" mode asks the (local, slow) model to
+        # classify every command first; with GLM-4.7-Flash those checks timed out and blocked the commands.
+        args = ["-p", prompt, "--output-format", "json", "--permission-mode", "dontAsk",
+                "--allowedTools", "Read Write Edit Bash Glob Grep"]
+        if not first:
+            args.append("--continue")
+        result = launch("claude", port, model, context, capture=True, cwd=folder, timeout=TIMEOUT, args=args)
+        try:
+            data = json.loads(result.stdout.strip().splitlines()[-1])
+        except (ValueError, IndexError):
+            raise AgentError(f"Claude Code exited with {result.returncode}: {(result.stdout + result.stderr)[-400:]}")
+        if data.get("is_error") and not data.get("result"):
+            raise AgentError(f"Claude Code reported an error: {str(data)[:400]}")
+        return data.get("result") or "", session
+    last = folder / ".codex-last-message.txt"
+    last.unlink(missing_ok=True)  # never grade a turn on the previous turn's reply
+    # `codex exec resume` has no -s flag; the sandbox is set as config, which both forms accept.
+    common = ["--skip-git-repo-check", "-c", 'sandbox_mode="workspace-write"', "-o", str(last)]
+    args = ["exec", *common, prompt] if first else ["exec", "resume", *common, session, prompt]
+    result = launch("codex", port, model, context, capture=True, cwd=folder, timeout=TIMEOUT, args=args)
+    output = result.stdout + result.stderr
+    provider = re.search(r"^provider:\s*(\S+)", output, re.M)
+    if provider and provider.group(1) != "llamacpp":
+        raise AgentError(f"Codex used provider '{provider.group(1)}' instead of the local model; stopped.")
+    if first:
+        found = re.search(r"session id:\s*([0-9a-f-]{36})", output)
+        session = found.group(1) if found else None
+        if not session:
+            raise AgentError(f"Codex did not start a session (exit {result.returncode}): {output[-400:]}")
+    if result.returncode != 0 and not last.exists():
+        raise AgentError(f"Codex exited with {result.returncode}: {output[-400:]}")
+    reply = last.read_text(encoding="utf-8", errors="replace") if last.exists() else ""
+    return reply, session
+
+
+def scoreboard():
+    if not RESULTS.exists():
+        print("No benchmark results yet.")
+        return
+    runs = [json.loads(line) for line in RESULTS.read_text(encoding="utf-8").splitlines() if line.strip()]
+    runs.sort(key=lambda r: (-r["score"], r["seconds"]))
+    print(f"\n{BOLD}Scoreboard{RESET}  {DIM}({RESULTS}){RESET}")
+    print(f"  {'model':<48} {'agent':<12} {'score':>7} {'time':>8}   date")
+    for r in runs:
+        color = GREEN if r["score"] >= 7 else YELLOW if r["score"] >= 5 else RED
+        print(f"  {r['model'][:48]:<48} {r['agent']:<12} {color}{r['score']:>5.1f}/8{RESET} {r['seconds'] / 60:>6.1f} m   {r['date']}")
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="hearthwork bench", description="Benchmark the running model through a coding agent.")
+    parser.add_argument("--agent", choices=sorted(HARNESSES), default="claude")
+    parser.add_argument("--show", action="store_true", help="only print the scoreboard")
+    args = parser.parse_args(argv)
+    if args.show:
+        return scoreboard()
+    config = load_config()
+    model = served_model(config["server"]["port"])
+    if not model:
+        sys.exit("No model is running. Start one first (hearthwork menu: Start / switch model).")
+    if not installed(args.agent):
+        sys.exit(f"{HARNESSES[args.agent]['title']} is not installed.")
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    folder = BENCH / "runs" / f"{stamp}-{args.agent}-{model}"
+    folder.mkdir(parents=True)
+    (folder / "demo.txt").write_text(DEMO, encoding="utf-8")
+    (folder / "buggy.py").write_text(BUGGY, encoding="utf-8")
+    title = HARNESSES[args.agent]["title"]
+    print(f"\n{BOLD}Benchmark{RESET}: {model} via {title}  {DIM}(8 prompts, one conversation; folder {folder}){RESET}\n")
+
+    steps, session, started = [], None, time.time()
+    for i, (name, prompt) in enumerate(PROMPTS):
+        print(f"  {i + 1}. {name:<12}", end=" ", flush=True)
+        t0 = time.time()
+        try:
+            reply, session = ask_agent(args.agent, config, model, folder, prompt, i == 0, session)
+        except subprocess.TimeoutExpired:
+            reply = ""
+        except AgentError as error:
+            print(f"\n\n  {RED}{error}{RESET}\n  Not recorded: this is an agent problem, not a model score.")
+            sys.exit(1)
+        seconds = time.time() - t0
+        points, note = grade(i, folder, reply)
+        color = GREEN if points == 1 else YELLOW if points > 0 else RED
+        print(f"{color}{points:>4.2g}{RESET}  {seconds:6.0f} s   {DIM}{note}{RESET}")
+        steps.append({"step": name, "points": points, "seconds": round(seconds, 1), "note": note})
+
+    total = sum(s["points"] for s in steps)
+    seconds = time.time() - started
+    record = {"date": datetime.now().strftime("%Y-%m-%d %H:%M"), "model": model, "agent": title,
+              "score": round(total, 2), "seconds": round(seconds), "steps": steps, "folder": str(folder)}
+    BENCH.mkdir(exist_ok=True)
+    with open(RESULTS, "a", encoding="utf-8") as f:
+        f.write(json.dumps(record) + "\n")
+    print(f"\n  {BOLD}Score {total:.1f}/8{RESET} in {seconds / 60:.1f} min")
+    scoreboard()
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\nStopped.")

hearthwork/check.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Hearthwork check: will a local model for coding agents be worth it on this computer, and which one?
+
+Run it without installing anything:
+  uvx --from git+https://github.com/BillyMRX1/hearthwork hearthwork-check
+or, once installed:  hearthwork check      (--json for scripts)
+
+Read-only: it checks the hardware and installed agents, gives the same verdict Hearthwork's setup gives, and
+looks up live file sizes on Hugging Face to pick the best version of each suggested model that fits.
+"""
+import argparse
+import json
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+from .onboard import CYAN, GREEN, RED, RESET, WINDOWS, YELLOW, detect, judge, lmstudio_folders, memory_gb
+
+BOLD, DIM = "\033[1m", "\033[2m"
+REPO = "https://github.com/BillyMRX1/hearthwork"
+
+# Coding models with tool-calling chat templates (checked on Hugging Face, 2026-10). "moe": only a few experts run
+# per token, so the model stays usable when part of it sits in system RAM. Measured on the reference PC
+# (RTX 5060 Ti 16 GB + 22.6 GB RAM, 64K context): MoE Qwen3-Coder-30B partly in RAM 18-31 tokens/s; dense
+# Qwen3.8-27B partly in RAM ~6 tokens/s.
+# "tested": Hearthwork benchmark (bench.py, 8 graded coding tasks) on the reference PC, Q4_K_M, 2026-10-07.
+MODELS = [
+    {"repo": "unsloth/Qwen3.5-35B-A3B-GGUF", "name": "Qwen3.5-35B-A3B", "moe": True, "tested": True,
+     "note": "best in the benchmark: 8/8 with Codex (2.6 min) and Claude Code (3.6 min)"},
+    {"repo": "unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF", "name": "Qwen3-Coder-30B-A3B", "moe": True, "tested": True,
+     "note": "8/8 with Claude Code (3.9 min) and Codex (4.2 min); a bit smaller"},
+    {"repo": "unsloth/GLM-4.7-Flash-GGUF", "name": "GLM-4.7-Flash (30B MoE)", "moe": True, "tested": True,
+     "note": "8/8 with Codex (4.5 min), 7.7/8 with Claude Code (missed one bug)"},
+    {"repo": "ggml-org/gpt-oss-20b-GGUF", "name": "gpt-oss-20b", "moe": True, "note": "small and fast; good at tool use"},
+    {"repo": "unsloth/Devstral-Small-2-24B-Instruct-2512-GGUF", "name": "Devstral-Small-2-24B", "moe": False,
+     "note": "coding agent (dense: needs to fit the GPU to be fast)"},
+    {"repo": "unsloth/Qwen3.5-27B-GGUF", "name": "Qwen3.5-27B", "moe": False, "note": "dense"},
+    {"repo": "unsloth/Qwen3-Coder-Next-GGUF", "name": "Qwen3-Coder-Next (80B MoE)", "moe": True,
+     "note": "strongest here; needs a big machine"},
+    {"repo": "lmstudio-community/Qwen3.5-9B-GGUF", "name": "Qwen3.5-9B", "moe": False,
+     "note": "small machines only; much weaker with agents' tools"},
+]
+# Best quality first. Below Q3, answers get noticeably worse.
+QUANTS = ["Q4_K_M", "UD-Q4_K_XL", "MXFP4", "Q4_K_S", "Q3_K_M", "UD-Q3_K_XL", "Q3_K_S", "UD-Q2_K_XL", "Q2_K"]
+KV_GB_64K = 3.4  # KV cache for a 64K context at q8_0, measured with Qwen3-Coder-30B (varies by model)
+
+
+def version(binary):
+    path = shutil.which(binary)
+    if not path:
+        return None
+    try:
+        out = subprocess.run([path, "--version"], capture_output=True, text=True, timeout=20).stdout.strip()
+        return out.splitlines()[0] if out else "installed"
+    except (OSError, subprocess.SubprocessError):
+        return "installed"
+
+
+def quant_sizes(repo):
+    """{quant: GB} from Hugging Face (multi-part files summed); None when offline."""
+    url = f"https://huggingface.co/api/models/{repo}/tree/main?recursive=true"
+    try:
+        with urllib.request.urlopen(urllib.request.Request(url, headers={"User-Agent": "hearthwork-check"}), timeout=20) as r:
+            files = json.load(r)
+    except Exception:
+        return None
+    sizes = {}
+    for f in files:
+        path = f.get("path", "")
+        if not path.endswith(".gguf") or "mmproj" in path.lower():
+            continue
+        name = re.sub(r"-\d{5}-of-\d{5}", "", Path(path).name)
+        for quant in QUANTS:
+            if name.upper().endswith(f"-{quant.upper()}.GGUF") or name.upper().endswith(f"_{quant.upper()}.GGUF"):
+                sizes[quant] = sizes.get(quant, 0) + (f.get("lfs") or {}).get("size", f.get("size", 0)) / 2**30
+    return sizes
+
+
+def place(model, sizes, gpu_room, ram_room):
+    """Best quantization for this machine -> (quant, GB, fit) with fit in fast / good / slow, or None if too big."""
+    if model["moe"]:  # MoE stays fast partly in RAM: best quality that fits at all
+        for quant in QUANTS:
+            if quant in sizes and sizes[quant] <= gpu_room + ram_room:
+                return quant, sizes[quant], "fast" if sizes[quant] <= gpu_room else "good"
+        return None
+    for quant in QUANTS:  # dense: fitting the GPU entirely matters most
+        if quant in sizes and sizes[quant] <= gpu_room:
+            return quant, sizes[quant], "fast"
+    for quant in QUANTS:  # then GPU + RAM
+        if quant in sizes and sizes[quant] <= gpu_room + ram_room:
+            return quant, sizes[quant], "good" if model["moe"] else "slow"
+    return None
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="hearthwork check", description="Will Hearthwork (local models for coding agents) be worth it here?")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args(argv)
+
+    hw = detect()
+    verdict, reasons, expect = judge(hw)
+    ram_total, ram_free = memory_gb()
+    home_disk = shutil.disk_usage(Path.home()).free / 2**30
+    agents = {"Claude Code": version("claude"), "Codex": version("codex")}
+    vram = hw.get("vramGB") or 0
+    if hw["backend"] == "metal":
+        gpu_room, ram_room = max(0.0, hw["ramGB"] * 0.75 - 1.5 - KV_GB_64K), 0.0
+    else:
+        gpu_room = max(0.0, vram - 1.5 - KV_GB_64K) if hw["backend"] in ("cuda", "vulkan") else 0.0
+        ram_room = max(0.0, hw["ramGB"] - 6)
+
+    picks = []
+    offline = False
+    for model in MODELS:
+        sizes = quant_sizes(model["repo"])
+        if sizes is None:
+            offline = True
+            continue
+        fit = place(model, sizes, gpu_room, ram_room)
+        picks.append({**model, "quant": fit[0] if fit else None, "sizeGB": round(fit[1], 1) if fit else None,
+                      "fit": fit[2] if fit else "too big"})
+    rank = {"fast": 0, "good": 1, "slow": 2, "too big": 3}
+    picks.sort(key=lambda p: (p["fit"] == "too big", not p.get("tested"), rank[p["fit"]], MODELS.index(next(m for m in MODELS if m["repo"] == p["repo"]))))
+
+    if args.json:
+        print(json.dumps({"hardware": hw, "ramFreeGB": round(ram_free, 1), "diskFreeGB": round(home_disk, 1),
+                          "verdict": verdict, "reasons": reasons, "expect": expect, "agents": agents,
+                          "models": picks, "offline": offline}, indent=2))
+        return
+
+    print(f"\n{BOLD}Hearthwork check{RESET}  {DIM}(local models for Claude Code / Codex){RESET}\n")
+    print(f"{BOLD}Your computer{RESET}")
+    print(f"  OS       {platform.system()} {platform.release()} ({hw['arch']})   Python {platform.python_version()}")
+    print(f"  CPU      {hw['cpuThreads']} threads")
+    print(f"  RAM      {ram_total:.1f} GB ({ram_free:.1f} GB free now)")
+    gpus = ", ".join(hw["gpus"]) or "no usable GPU"
+    print(f"  GPU      {gpus}" + (f"  ({vram:.1f} GB)" if hw["backend"] == "vulkan" and vram else "")
+          + f"   ->  llama.cpp {hw['backend']}" + (f", driver CUDA {hw['cudaDriver']}" if hw.get("cudaDriver") else ""))
+    print(f"  Disk     {home_disk:.0f} GB free in your home drive"
+          + (f"; LM Studio models: {lmstudio_folders()[0]}" if lmstudio_folders() else ""))
+
+    color = {"recommended": GREEN, "limited": YELLOW}.get(verdict, RED)
+    print(f"\n{BOLD}Verdict{RESET}  {color}{BOLD}{verdict.upper()}{RESET}")
+    for reason in reasons:
+        print(f"  - {reason}")
+    print(f"  {expect}")
+
+    print(f"\n{BOLD}Coding agents{RESET}")
+    for name, found in agents.items():
+        print(f"  {name:12} " + (f"{GREEN}{found}{RESET}" if found else f"{YELLOW}not installed{RESET}"))
+    if not any(agents.values()):
+        print(f"  {YELLOW}Install at least one: Claude Code (https://code.claude.com) or Codex "
+              f"(https://developers.openai.com/codex).{RESET}")
+
+    print(f"\n{BOLD}Models for this computer{RESET}  {DIM}(best version that fits; sizes live from Hugging Face){RESET}")
+    labels = {"fast": f"{GREEN}fits the GPU: fast{RESET}", "good": f"{GREEN}GPU + RAM: good (MoE){RESET}",
+              "slow": f"{YELLOW}GPU + RAM: slow (dense){RESET}", "too big": f"{RED}too big{RESET}"}
+    for p in picks:
+        size = f"{p['quant']:<10} {p['sizeGB']:5.1f} GB" if p["quant"] else " " * 19
+        tested = f" {CYAN}[tested]{RESET}" if p.get("tested") else ""
+        print(f"  {p['name']:<28} {size}  {labels[p['fit']]}{tested}")
+        print(f"  {DIM}{'':<28} {p['note']}{RESET}")
+    if offline:
+        print(f"  {YELLOW}Some models could not be looked up (offline?).{RESET}")
+    print(f"  {DIM}Measured on an RTX 5060 Ti 16 GB + 22.6 GB RAM: MoE partly in RAM 18-31 tokens/s, "
+          f"dense partly in RAM ~6 tokens/s.{RESET}")
+
+    best = next((p for p in picks if p["fit"] in ("fast", "good")), None)
+    print(f"\n{BOLD}Next step{RESET}")
+    if verdict == "not recommended" or not best:
+        print("  A local model would be too slow or too weak for coding on this computer. Cloud Claude Code / Codex is the"
+              " better choice here.")
+    else:
+        print(f"  1. Install Hearthwork:  {CYAN}uv tool install hearthwork{RESET}   (or: pipx install hearthwork)")
+        print(f"  2. Download a model:    {CYAN}hearthwork model {best['repo']}{RESET}   "
+              f"(pick {best['quant']}, {best['sizeGB']} GB)")
+        print(f"  3. From your project folder, run {CYAN}hearthwork{RESET}: setup takes a minute, then pick your agent.")
+    print()
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        sys.exit(130)

hearthwork/cli.py

@@ -0,0 +1,133 @@
+"""The `hearthwork` command.
+
+  hearthwork                    menu (run it from the project you want the agent to work on)
+  hearthwork claude [args...]   Claude Code with the local model (starts one if needed); args go to `claude`
+  hearthwork codex [args...]    Codex with the local model; args go to `codex`
+  hearthwork start [--model X]  start the model in the background     hearthwork stop
+  hearthwork serve [--model X]  run the model server in this terminal (Ctrl+C stops it)
+  hearthwork status             what is running
+  hearthwork model <link>       download a GGUF model from Hugging Face
+  hearthwork bench              8 graded coding tasks through an agent, with a scoreboard
+  hearthwork check              is this computer suited, and which models fit
+  hearthwork setup              hardware check, llama.cpp download/update, models folder
+  hearthwork update             update Hearthwork itself
+"""
+import shutil
+import subprocess
+import sys
+
+from . import __version__
+from .harnesses import HARNESSES
+from .onboard import CYAN, GREEN, RESET, load_config, offer_import, onboard, setup_complete
+from .paths import HOME
+
+REPO = "git+https://github.com/BillyMRX1/hearthwork"
+USAGE = __doc__.split("\n", 2)[2]
+
+
+def configured(interactive=True):
+    """config, running first-time setup (or importing an older setup) when needed."""
+    config = load_config()
+    if setup_complete(config):
+        return config
+    config = offer_import(config)
+    if setup_complete(config):
+        return config
+    config = onboard(config)
+    if interactive:
+        input("\nPress Enter to continue...")
+    return config
+
+
+def model_args(argv, name):
+    import argparse
+    parser = argparse.ArgumentParser(prog=f"hearthwork {name}")
+    parser.add_argument("--model", help="part of a model file name; skips the model menu")
+    parser.add_argument("--context", type=int, help="context size (default: chosen by setup)")
+    return parser.parse_args(argv)
+
+
+def update():
+    """Upgrade with whichever tool installed Hearthwork."""
+    if shutil.which("uv") and "uv" in sys.executable.replace("\\", "/").split("/"):
+        return subprocess.call(["uv", "tool", "upgrade", "hearthwork"])
+    if shutil.which("pipx") and "pipx" in sys.executable.replace("\\", "/"):
+        return subprocess.call(["pipx", "upgrade", "hearthwork"])
+    print(f"Upgrade with the tool you installed Hearthwork with, e.g.\n  uv tool upgrade hearthwork\n"
+          f"  pipx upgrade hearthwork\n  pip install --upgrade hearthwork")
+    return 0
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    command, rest = (argv[0], argv[1:]) if argv else ("menu", [])
+    try:
+        if command in ("-h", "--help", "help"):
+            print(USAGE)
+        elif command in ("-V", "--version", "version"):
+            print(f"hearthwork {__version__}  (data: {HOME})")
+        elif command == "menu":
+            from . import menu
+            menu.main(configured())
+        elif command in HARNESSES:  # every following argument belongs to the agent (e.g. -p "...")
+            from .menu import run_agent
+            sys.exit(run_agent(configured(), command, rest, back_to_menu=False))
+        elif command in ("start", "serve"):
+            from .server import choose_and_remember, run_foreground, start_background
+            args = model_args(rest, command)
+            config = configured()
+            model = choose_and_remember(config, args.model)
+            if not model:
+                sys.exit(1)
+            if command == "start":
+                ok = start_background(config, model, args.context)
+                if ok:
+                    print(f"{CYAN}Now run `hearthwork claude` or `hearthwork codex` from your project.{RESET}")
+                sys.exit(0 if ok else 1)
+            print(f"\nStarting {model.name}   context: {args.context or config['server']['context']}   "
+                  f"port: {config['server']['port']}")
+            print(f"{CYAN}When it says 'listening on', run `hearthwork claude` or `hearthwork codex` "
+                  f"from your project.{RESET}\n", flush=True)
+            run_foreground(config, model, args.context)
+        elif command == "stop":
+            from .server import stop
+            stop(load_config())
+        elif command == "status":
+            from .server import served_model
+            config = load_config()
+            port = config.get("server", {}).get("port", 8001)
+            running = served_model(port)
+            print(f"hearthwork {__version__}   data: {HOME}")
+            print(f"model: {GREEN + running + RESET if running else 'not running'}" + (f"  (port {port})" if running else ""))
+            print(f"models folder: {config.get('modelsDir', '-')}")
+        elif command == "model":
+            from . import model
+            configured()
+            model.main(rest)
+        elif command == "bench":
+            from . import bench
+            if "--show" not in rest:
+                from .menu import ensure_server
+                if not ensure_server(configured()):
+                    sys.exit(1)
+            bench.main(rest)
+        elif command == "check":
+            from . import check
+            check.main(rest)
+        elif command == "setup":
+            from . import onboard as setup
+            setup.main(rest)
+        elif command == "update":
+            sys.exit(update())
+        else:
+            print(f"Unknown command: {command}\n\n{USAGE}")
+            sys.exit(2)
+    except KeyboardInterrupt:
+        print()
+        sys.exit(130)
+
+
+def check_main():
+    """`hearthwork-check`: the checker on its own, e.g. `uvx --from git+https://github.com/BillyMRX1/hearthwork hearthwork-check`."""
+    from . import check
+    check.main()