opencode-llama-cpp-launcher 0.1.0__tar.gz

opencode_llama_cpp_launcher-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    name: Test and build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Install dependencies
+        run: uv sync --frozen --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  github-release:
+    name: Create GitHub release
+    runs-on: ubuntu-latest
+    needs: build
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create GitHub release
+        run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  pypi-publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/opencode-llama-cpp-launcher/
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

opencode_llama_cpp_launcher-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+
+opencode-llama.yaml
+.opencode-llama.yaml
+.opencode-llama.yml
+
+# Build and packaging output.
+build/
+dist/
+*.egg-info/

opencode_llama_cpp_launcher-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ribomo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opencode_llama_cpp_launcher-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: opencode-llama-cpp-launcher
+Version: 0.1.0
+Summary: One command launcher for running OpenCode with a local llama.cpp model.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic-coding,cli,llama-cpp,local-llm,opencode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# OpenCode llama.cpp Launcher
+
+A one command solution for launching [OpenCode](https://opencode.ai/) with any
+local LLM that `llama-server` can serve, including models like Qwen, DeepSeek,
+and Gemma. This launcher starts `llama-server`, waits for it to become ready,
+wires the OpenAI compatible provider config into OpenCode, and cleans up when
+the local agentic coding session ends.
+
+## Requirements
+
+- Python 3.12+
+- OpenCode
+- llama.cpp's `llama-server`
+- A local model supported by `llama-server`, for example Qwen, DeepSeek, or
+  Gemma
+
+The launcher finds `llama-server` on `PATH`, or you can set `llama_server` in
+your config.
+
+## Install
+
+From this repository:
+
+```bash
+uv sync --dev
+```
+
+Check that the required external binaries are available:
+
+```bash
+uv run opencode-llama doctor
+```
+
+## Configure
+
+Create a project-local config in the project where you want OpenCode to run:
+
+```bash
+cp opencode-llama.example.yaml opencode-llama.yaml
+```
+
+Then edit `opencode-llama.yaml`:
+
+```yaml
+model: /absolute/path/to/model.gguf
+llama_server: /optional/path/to/llama-server
+port: 8080
+ctx_size: 8192
+```
+
+Config lookup order:
+
+1. The path passed with `--config`
+2. `opencode-llama.yaml` or `opencode-llama.yml` in the project directory
+3. `~/.config/opencode-llama.yaml`
+
+## Usage
+
+Run with an explicit config file:
+
+```bash
+uv run opencode-llama --config opencode-llama.yaml
+```
+
+Or pass the model directly:
+
+```bash
+uv run opencode-llama --model /absolute/path/to/model.gguf
+```
+
+Useful options:
+
+```bash
+uv run opencode-llama --help
+uv run opencode-llama --dry-run
+uv run opencode-llama --config opencode-llama.yaml
+uv run opencode-llama --port 9001
+uv run opencode-llama --ctx-size 8192
+uv run opencode-llama --llama-server /absolute/path/to/llama-server
+```
+
+If `llama-server` fails before becoming healthy, the launcher includes a bounded
+tail of the server's startup output in the error message. Successful runs stay
+quiet.
+
+## Development
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+Before publishing, check for local files:
+
+```bash
+git status --short --ignored
+```
+
+Do not commit local launcher configs, virtual environments, caches, build
+artifacts, or model paths.
+
+## License
+
+MIT

opencode_llama_cpp_launcher-0.1.0/README.md

@@ -0,0 +1,105 @@
+# OpenCode llama.cpp Launcher
+
+A one command solution for launching [OpenCode](https://opencode.ai/) with any
+local LLM that `llama-server` can serve, including models like Qwen, DeepSeek,
+and Gemma. This launcher starts `llama-server`, waits for it to become ready,
+wires the OpenAI compatible provider config into OpenCode, and cleans up when
+the local agentic coding session ends.
+
+## Requirements
+
+- Python 3.12+
+- OpenCode
+- llama.cpp's `llama-server`
+- A local model supported by `llama-server`, for example Qwen, DeepSeek, or
+  Gemma
+
+The launcher finds `llama-server` on `PATH`, or you can set `llama_server` in
+your config.
+
+## Install
+
+From this repository:
+
+```bash
+uv sync --dev
+```
+
+Check that the required external binaries are available:
+
+```bash
+uv run opencode-llama doctor
+```
+
+## Configure
+
+Create a project-local config in the project where you want OpenCode to run:
+
+```bash
+cp opencode-llama.example.yaml opencode-llama.yaml
+```
+
+Then edit `opencode-llama.yaml`:
+
+```yaml
+model: /absolute/path/to/model.gguf
+llama_server: /optional/path/to/llama-server
+port: 8080
+ctx_size: 8192
+```
+
+Config lookup order:
+
+1. The path passed with `--config`
+2. `opencode-llama.yaml` or `opencode-llama.yml` in the project directory
+3. `~/.config/opencode-llama.yaml`
+
+## Usage
+
+Run with an explicit config file:
+
+```bash
+uv run opencode-llama --config opencode-llama.yaml
+```
+
+Or pass the model directly:
+
+```bash
+uv run opencode-llama --model /absolute/path/to/model.gguf
+```
+
+Useful options:
+
+```bash
+uv run opencode-llama --help
+uv run opencode-llama --dry-run
+uv run opencode-llama --config opencode-llama.yaml
+uv run opencode-llama --port 9001
+uv run opencode-llama --ctx-size 8192
+uv run opencode-llama --llama-server /absolute/path/to/llama-server
+```
+
+If `llama-server` fails before becoming healthy, the launcher includes a bounded
+tail of the server's startup output in the error message. Successful runs stay
+quiet.
+
+## Development
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
+Before publishing, check for local files:
+
+```bash
+git status --short --ignored
+```
+
+Do not commit local launcher configs, virtual environments, caches, build
+artifacts, or model paths.
+
+## License
+
+MIT

opencode_llama_cpp_launcher-0.1.0/opencode-llama.example.yaml

@@ -0,0 +1,15 @@
+# Example launcher config.
+# Rename to .opencode-llama.yaml in the project where you want OpenCode to run.
+
+# Absolute path to your local GGUF model file.
+model: /absolute/path/to/model.gguf
+
+# Optional absolute path to llama-server. Omit this to use PATH lookup.
+llama_server: /optional/path/to/llama-server
+
+# Preferred llama-server port. If this port is busy, the launcher will choose
+# an available port automatically.
+port: 8080
+
+# llama-server context size.
+ctx_size: 8192

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/__init__.py

@@ -0,0 +1,3 @@
+"""OpenCode llama.cpp launcher package."""
+
+__version__ = "0.1.0"

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI entrypoints."""

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/cli/entrypoint.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from opencode_llama_cpp_launcher.services.binaries import require_binary
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+from opencode_llama_cpp_launcher.services.launch_config_loader import LaunchConfigLoader
+from opencode_llama_cpp_launcher.services.launcher import Launcher
+
+
+app = typer.Typer(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    invoke_without_command=True,
+    no_args_is_help=False,
+    help="Launch OpenCode against a local llama.cpp GGUF model.",
+)
+
+
+@app.callback()
+def launch_callback(
+    ctx: typer.Context,
+    model: Path | None = typer.Option(
+        None,
+        "--model",
+        "-m",
+        help="GGUF model path. Overrides YAML config.",
+    ),
+    llama_server: Path | None = typer.Option(
+        None,
+        "--llama-server",
+        help="llama-server binary path. Overrides YAML config and PATH lookup.",
+    ),
+    project: Path = typer.Option(
+        Path("."),
+        "--project",
+        "-p",
+        help="Project directory where OpenCode should run.",
+    ),
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        "-f",
+        help="Path to opencode-llama.yaml.",
+    ),
+    port: int | None = typer.Option(
+        None,
+        "--port",
+        help="Preferred llama-server port.",
+    ),
+    ctx_size: int | None = typer.Option(
+        None,
+        "--ctx-size",
+        help="llama-server context size.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print resolved commands and generated config without launching.",
+    ),
+) -> None:
+    if ctx.invoked_subcommand is not None:
+        return
+
+    try:
+        launch_config = LaunchConfigLoader().load(
+            model=model,
+            llama_server=llama_server,
+            project=project,
+            config=config,
+            port=port,
+            ctx_size=ctx_size,
+            dry_run=dry_run,
+        )
+        raise typer.Exit(_shell_exit_code(Launcher().run(launch_config)))
+    except LauncherError as exc:
+        _print_error(str(exc))
+        raise typer.Exit(1) from exc
+
+
+@app.command()
+def doctor() -> None:
+    """Check whether required external binaries are available."""
+    failed = False
+
+    for binary_name in ("llama-server", "opencode"):
+        try:
+            binary_path = require_binary(binary_name)
+            typer.echo(f"OK {binary_name}: {binary_path}")
+        except LauncherError as exc:
+            failed = True
+            typer.echo(f"Missing {binary_name}: {exc}", err=True)
+
+    if failed:
+        raise typer.Exit(1)
+
+
+def _print_error(message: str) -> None:
+    typer.echo(f"Error: {message}", err=True)
+
+
+def _shell_exit_code(return_code: int) -> int:
+    if return_code >= 0:
+        return return_code
+    return 128 + abs(return_code)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/models/__init__.py

@@ -0,0 +1 @@
+"""Data models for launcher configuration and status."""

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/models/launch_config.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8080
+MAX_PORT = 65535
+DEFAULT_CTX_SIZE = 8192
+
+
+@dataclass(frozen=True)
+class LaunchConfig:
+    project: Path
+    model_path: Path
+    llama_server_path: Path | None = None
+    port: int = DEFAULT_PORT
+    ctx_size: int = DEFAULT_CTX_SIZE
+    host: str = DEFAULT_HOST
+    dry_run: bool = False
+
+
+@dataclass(frozen=True)
+class LlamaServerConfig:
+    model_path: Path
+    command: list[str]
+    selected_port: int
+    root_url: str
+    base_url: str
+
+
+@dataclass(frozen=True)
+class OpenCodeConfig:
+    command: list[str]
+    config: dict
+
+
+@dataclass(frozen=True)
+class BuiltLaunchConfig:
+    project: Path
+    llama_server: LlamaServerConfig
+    opencode: OpenCodeConfig

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/models/launch_status.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class LaunchStatus(StrEnum):
+    IDLE = "Idle"
+    CHECKING_PREREQUISITES = "Checking prerequisites"
+    STARTING_LLAMA_SERVER = "Starting llama-server"
+    WAITING_FOR_LLAMA_SERVER = "Waiting for llama-server"
+    DETECTING_MODEL = "Detecting model"
+    STARTING_OPENCODE = "Starting OpenCode"
+    READY = "Ready"
+    ERROR = "Error"

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/services/__init__.py

@@ -0,0 +1 @@
+"""Launcher services."""

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/services/binaries.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import shutil
+
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+
+
+def require_binary(name: str) -> str:
+    binary_path = shutil.which(name)
+    if binary_path is None:
+        raise LauncherError(f"`{name}` was not found in PATH.")
+    return binary_path

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/services/errors.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+class LauncherError(RuntimeError):
+    """Expected user-facing launcher failure."""

opencode_llama_cpp_launcher-0.1.0/opencode_llama_cpp_launcher/services/health.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+
+from opencode_llama_cpp_launcher.services.errors import LauncherError
+
+
+def wait_for_health(
+    root_url: str,
+    timeout_seconds: float = 120.0,
+    interval_seconds: float = 0.5,
+    is_server_running: Callable[[], bool] | None = None,
+) -> None:
+    deadline = time.monotonic() + timeout_seconds
+    last_error: Exception | None = None
+
+    while time.monotonic() < deadline:
+        if is_server_running is not None and not is_server_running():
+            raise LauncherError("llama-server exited before becoming ready.")
+
+        try:
+            with urllib.request.urlopen(f"{root_url}/health", timeout=2.0) as response:
+                if response.status == 200:
+                    return
+        except OSError as exc:
+            last_error = exc
+
+        if is_server_running is not None and not is_server_running():
+            raise LauncherError("llama-server exited before becoming ready.")
+
+        time.sleep(interval_seconds)
+
+    suffix = f" Last error: {last_error}" if last_error else ""
+    raise LauncherError(f"llama-server did not become ready at {root_url}.{suffix}")
+
+
+def fetch_first_model_id(base_url: str) -> str:
+    try:
+        with urllib.request.urlopen(f"{base_url}/models", timeout=5.0) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except urllib.error.URLError as exc:
+        raise LauncherError(f"Could not query llama-server models: {exc}") from exc
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise LauncherError("llama-server returned invalid JSON from /v1/models.") from exc
+
+    data = payload.get("data") if isinstance(payload, dict) else None
+    if not isinstance(data, list) or not data:
+        raise LauncherError("No models returned from llama-server /v1/models.")
+
+    first_model = data[0]
+    model_id = first_model.get("id") if isinstance(first_model, dict) else None
+    if not isinstance(model_id, str) or not model_id:
+        raise LauncherError("First llama-server model entry did not include an id.")
+
+    return model_id