AlpieLocal

AlpieLocal is a command-line coding agent for exploring repositories, editing code, debugging, and running verification commands. It supports online inference through a configured endpoint and offline inference with local GGUF models through llama.cpp.

Requirements

• Python 3.9 or newer. Python 3.11 or 3.12 is a practical choice for native runtime compatibility.
• Windows, Linux, or macOS with a compatible Python architecture.
• Internet access for package installation and the initial model/runtime downloads.
• Sufficient disk space, RAM, and optional GPU memory for the selected model and context size.
• Your project's own tools, such as Git, Node.js, or a test runner, when the task requires them.

Offline hardware guidance

The default Q3 text weights occupy approximately 4.4 GiB, and the vision projector adds approximately 0.86 GiB. Loading also needs memory for context/KV cache, compute buffers, the operating system, and project tools.

These are planning estimates for text tasks at 4,096–8,192 tokens, not certified minimum specifications:

Execution mode	Practical starting configuration	Preferred configuration
CPU only	Compatible 64-bit CPU, 4 or more cores, 16 GB system RAM	Modern CPU with 8 or more cores and 32 GB RAM
NVIDIA CUDA	16 GB system RAM and 6 GB VRAM with partial GPU offload	32 GB system RAM and 8 GB or more VRAM
Apple Silicon Metal	Native arm64 Python and 16 GB unified memory	24–32 GB or more unified memory

Reserve at least 15 GB of free disk space for model assets, the environment, and download caches; source builds and project dependencies can need more. Machines with 8 GB RAM may run into memory pressure and are not the recommended baseline. Larger contexts, images, and video frames increase memory use; the configured 262,144-token ceiling is not a laptop memory recommendation.

A dedicated GPU is optional. CPU inference is slower, and the runtime must match the CPU architecture and instruction support. Bundled CPU wheels cover supported Windows x64 and Linux x64/ARM64 platforms; Intel Macs require a compatible manual build. Apple Silicon uses shared memory rather than separate GPU VRAM. Development probes loaded the model on an RTX 3050 with 6 GB VRAM using partial offload and a 16,384-token context; this does not establish compatibility with every 6 GB GPU.

To force CPU operation, set the variable before starting chat:

# Windows PowerShell
$env:ALPIELOCAL_CPU = "1"
alpielocal chat --offline --no-thinking --ctx-size 8192

# Linux or macOS
ALPIELOCAL_CPU=1 alpielocal chat --offline --no-thinking --ctx-size 8192

Installation

Global command with pipx

pipx makes alpielocal available across projects while keeping its Python dependencies in a dedicated environment.

Windows PowerShell

py -m pip install --user pipx
py -m pipx ensurepath

Linux, Ubuntu or Debian

sudo apt update
sudo apt install pipx
pipx ensurepath

macOS, with Homebrew

brew install pipx
pipx ensurepath

Open a new terminal, then install and check the command:

pipx install alpielocal
alpielocal --version

For other Linux distributions, use the pipx installation guide linked above. A pipx installation is available from your terminal without activating a project environment.

Python virtual environment

Windows PowerShell

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install alpielocal

If PowerShell blocks activation, install and run through the environment's interpreter directly:

.\.venv\Scripts\python.exe -m pip install alpielocal
.\.venv\Scripts\alpielocal.exe --version

Linux or macOS

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install alpielocal

On Debian or Ubuntu, install python3-venv if creating the environment fails. Use an installed Python version in place of py -3.12 when necessary.

Install with uv

Install uv using the command for your platform.

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux or macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

Open a new terminal. To make AlpieLocal available across projects in a managed tool environment:

uv tool install --python 3.12 alpielocal
uv tool update-shell

Reopen the terminal if PATH was updated, then run alpielocal --version. Alternatively, create a project environment:

uv venv --python 3.12 .venv

Activate .venv using the Windows or Linux/macOS activation command above, then run:

uv pip install alpielocal
alpielocal --version

uv environments do not need pip installed to use uv pip. Choose either a global tool installation or a project environment so it is clear which CLI and runtime you are using. See the uv tools guide for details.

Existing environments

Activate your existing venv, virtualenv, Conda, uv, or Poetry environment, then install into its Python interpreter:

python -m pip install --upgrade alpielocal
python -c "import sys; print(sys.executable)"
alpielocal --version

If the environment has no pip, use its package manager; for example, uv pip install alpielocal or poetry add alpielocal. AlpieLocal does not require a uv-created environment. Its runtime installer may use uv when available, but targets the interpreter running AlpieLocal.

From this repository

From the repository root, with your chosen environment activated:

python -m pip install -e .
alpielocal --version

For a global command from the checkout, use pipx install . instead. Source installation includes changes that may not yet be available in a published package.

First use

Start interactive chat

Run AlpieLocal from the project you want to work on:

cd path/to/project
alpielocal

The explicit chat command is equivalent:

alpielocal chat

After completing offline initialization, start local chat with:

alpielocal chat --offline --no-thinking --ctx-size 8192

Type your request at the prompt. Use /help for chat commands, /status for session diagnostics, and exit or quit to leave. If installed into a virtual environment, activate it before starting chat.

Run a single task

Submit a task directly when an interactive conversation is unnecessary:

alpielocal run "Investigate the failing tests, make a targeted fix, and verify it."

Online mode uses the configured inference endpoint. To select your own deployment:

alpielocal run "Explain this repository." --endpoint "https://your-server.example/v1" --model "your-model"

Offline mode requires the setup below.

Offline setup

Initialize models and llama.cpp

While connected to the internet, run this once from your intended workspace:

alpielocal init

Initialization saves configuration, downloads missing model files, and installs or checks llama-cpp-python, the Python binding used to run llama.cpp. A separate llama.cpp CLI installation is not required.

The default assets are:

Asset	File
Text model	alpie-vl-text-q3_k_m.gguf
Vision projector	alpie-vl-mmproj-f16.gguf
Model repository	169Pi/alpie_learn_gguf
Automatic runtime version	llama-cpp-python 0.3.35

The default model distribution resolves its built-in credential automatically; users do not normally need to enter HF_TOKEN. Downloads still require valid repository access. Custom private repositories require an authorized Hugging Face login or token.

The automatic installer selects compatible, hash-checked wheels and checks that the runtime imports. It does not compile native code. Setup can be cancelled and rerun; completed downloads are reused. An import check does not establish model generation or task accuracy.

Windows

Use 64-bit Python for the bundled Windows x64 wheels. In PowerShell, activate the environment where AlpieLocal is installed, then run:

alpielocal init
alpielocal run "Say hello" --offline --no-thinking --ctx-size 8192

The installer tries compatible NVIDIA CUDA, Vulkan, and CPU runtimes. GPU use depends on the selected wheel and installed drivers. Native Windows and WSL have separate Python environments and runtime installations; run setup inside the environment you will use.

Linux

Activate your environment and run:

alpielocal init
alpielocal run "Say hello" --offline --no-thinking --ctx-size 8192

The installer selects wheels matching the interpreter architecture and Linux platform. NVIDIA systems can use CUDA; compatible Vulkan and CPU builds are also considered. Linux ARM64 CPU wheels are included for supported platforms.

macOS

On Apple Silicon, use a native arm64 Python installation. Check its architecture:

python -c "import platform; print(platform.machine())"
alpielocal init
alpielocal run "Say hello" --offline --no-thinking --ctx-size 8192

Apple Silicon should report arm64; setup tries Metal, then CPU. An x86_64 Python running under Rosetta does not match the bundled arm64 wheels. The pinned automatic runtime has no Intel Mac wheel; Intel users need a compatible manual runtime installation.

Manual llama.cpp runtime installation

Use alpielocal init first. If your platform has no supported bundled wheel, install a compatible llama-cpp-python into the same environment, then rerun initialization.

The commands below target an activated Python environment. In an activated uv environment without pip, replace python -m pip with uv pip.

NVIDIA CUDA: Windows x64

Check that nvidia-smi detects your GPU. The pinned runtime uses a CUDA 12.4 build and needs a compatible NVIDIA driver and GPU. Install the matching wheel:

python -m pip install --force-reinstall --no-cache-dir --only-binary=:all: "https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.35-cu124/llama_cpp_python-0.3.35-py3-none-win_amd64.whl#sha256=84f7218c1e9cf21014b9770c65064c5a3674dd2f4fbc312c5d6bb40cec0fb269"

NVIDIA CUDA: Linux x64

This bundled CUDA wheel targets glibc 2.35 or newer. On another platform, let initialization select an alternative or use the upstream build instructions.

python -m pip install --force-reinstall --no-cache-dir --only-binary=:all: "https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.35-cu124/llama_cpp_python-0.3.35-py3-none-manylinux_2_35_x86_64.whl#sha256=62fc788a4ecee5a579f40708ccfe0c4d566dd5c9959497bdc0544dbba94d82aa"

Apple Silicon: macOS Metal

Use native arm64 Python and install the Metal wheel. CUDA is for NVIDIA GPUs; Apple Silicon acceleration uses Metal.

python -m pip install --force-reinstall --no-cache-dir --only-binary=:all: "https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.35-metal/llama_cpp_python-0.3.35-py3-none-macosx_11_0_arm64.whl#sha256=faf9a2b38df5cbf9427a074f974c00abbb799185753c474672fd461c198b7a0a"

CPU or source build

For an available CPU wheel, try:

python -m pip install --only-binary=:all: llama-cpp-python==0.3.35 --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu

If no compatible wheel exists, a source build requires a native compiler and build tools. A CPU build can be installed with:

python -m pip install --no-binary=llama-cpp-python llama-cpp-python==0.3.35

Source builds require a C/C++ toolchain on Windows, GCC or Clang on Linux, or Xcode command-line tools on macOS. See the upstream llama-cpp-python installation documentation for CUDA, Metal, and other build options.

Verify the environment afterward:

python -c "from llama_cpp import Llama; print('Runtime import OK')"
alpielocal init

For pipx installations, use pipx runpip alpielocal install in place of python -m pip install so the runtime is installed into AlpieLocal's environment. For a global uv tool installation, prefer alpielocal init, which targets that environment automatically. For manual installation, run uv tool dir, locate alpielocal/bin/python on Linux/macOS or alpielocal/Scripts/python.exe on Windows beneath that directory, and use uv pip install --python "/full/path/to/that/python" with the wheel URL above.

To check whether the installed runtime supports GPU offload:

python -c "import llama_cpp; print('GPU offload support:', llama_cpp.llama_supports_gpu_offload())"

This reports build capability. Confirm actual device use in the model-loading output when starting offline chat. Run import checks through the same environment's Python; a global tool environment is separate from your project's Python.

Run without networking

Once the package, model files, runtime, and project dependencies are installed:

alpielocal --offline --no-thinking --ctx-size 8192
alpielocal run "Fix the failing tests and verify the changes." --offline --no-thinking --ctx-size 8192

Use alpielocal --network-policy deny init to check existing setup assets without downloading them. Offline inference does not provide online services or download missing project dependencies.

--network-policy deny disables network-aware agent tools and selects local inference. Arbitrary shell subprocesses require operating-system isolation for an enforced network boundary. On Linux with bubblewrap installed:

alpielocal run "Inspect and repair the failing test." --offline --no-thinking --sandbox --ctx-size 8192

The configured context ceiling is 262,144 tokens in both modes, with a maximum output setting of 65,537 tokens. Actual generation is constrained by task budgets, available context, model support, and memory. The smaller examples above reduce local memory requirements. Native offline structured tool calls currently require non-thinking generation; use --no-thinking for local coding tasks.

Essential commands

Command	Purpose
alpielocal	Start interactive chat in the current directory
alpielocal run "TASK"	Execute a task
alpielocal plan "TASK"	Prepare a plan without editing files
alpielocal explain path/to/file.py	Explain a file or concept
alpielocal diff	Inspect recorded changes
alpielocal undo	Restore file-tool changes from the last session where possible
alpielocal sessions	List saved sessions
alpielocal resume SESSION_ID	Resume a saved session
alpielocal doctor	Check the environment and available tools
alpielocal --help	Show available commands and options

Use --workdir path/to/project to select another workspace. In chat, /help lists commands and /status shows the active model, mode, context usage, and attachments.

Images, video, and optional tools

Attach media to a task using quoted paths:

alpielocal run "Explain the error shown in this screenshot." --image "screenshot.png"
alpielocal run "Summarize the concepts shown in this video." --video "lesson.mp4" --offline --no-thinking --ctx-size 16384

In chat, use /image "path/to/image.png" or /video "path/to/video.mp4", then submit your request. Image understanding requires a working vision model/projector. Video analysis samples frames; it does not establish full video or audio understanding. Video extraction uses system FFmpeg when available, otherwise the included imageio-ffmpeg binary on supported platforms.

Optional integrations:

Tool	Installation or prerequisite
Browser interaction checks	python -m pip install "alpielocal[browser]", then python -m playwright install chromium
PDF text extraction	python -m pip install "alpielocal[documents]"
Local speech transcription	Installed whisper-cli, FFmpeg, and local weights selected by ALPIELOCAL_WHISPER_MODEL
Language-server diagnostics	An installed server configured through ALPIELOCAL_LSP_COMMAND as a JSON argument list

For pipx, expose Playwright's command when installing browser support:

pipx inject --include-apps alpielocal playwright
playwright install chromium
pipx inject alpielocal pypdf

Optional runtimes and weights must also be prepared before disconnecting. See the pipx inject reference for environment management.

Configuration

Configuration normally lives in .alpielocal/config.json under the setup directory. Existing .alpiecode configuration and caches remain readable. Model lookup reuses existing home-directory caches or the workspace cache; setup prints the selected path.

Environment variable	Purpose
ALPIELOCAL_HOME	State and configuration directory
ALPIELOCAL_MODELS_DIR	Model cache directory
ALPIELOCAL_MODEL_PATH	Explicit local text-model GGUF file
ALPIELOCAL_BASE_URL	Online inference endpoint
ALPIELOCAL_API_KEY	Online endpoint authentication
ALPIELOCAL_MODEL	Online model identifier
ALPIELOCAL_CPU=1	Disable GPU offload

Set a persistent ALPIELOCAL_HOME before initialization if you want to share one setup across workspaces. Keep credentials out of version control.

Troubleshooting

• Command not found: reopen the terminal after pipx ensurepath, or activate the environment containing AlpieLocal. Check its interpreter with python -c "import sys; print(sys.executable)".
• Runtime installed in another environment: install or initialize using the same interpreter as the CLI. A pipx installation and a project virtual environment are separate.
• Wheel extraction or hash error: the installer retries a fresh download once. If it still fails, check the reported asset and platform, update AlpieLocal, and rerun alpielocal init. Do not bypass integrity checks.
• Model authentication error: cached models may work even when fresh downloads cannot authenticate. Check repository access and the installed distribution's credential configuration.
• Insufficient memory: reduce --ctx-size, reduce GPU offload with ALPIELOCAL_GPU_LAYERS, or select CPU mode with ALPIELOCAL_CPU=1.
• Video extraction unavailable: install or update imageio-ffmpeg in the environment running AlpieLocal.

Upgrade AlpieLocal

Use the upgrade command matching your installation method:

Installation	Upgrade command
Global uv tool	uv tool upgrade alpielocal
Global pipx tool	pipx upgrade alpielocal
Python/pip environment	python -m pip install --upgrade alpielocal
Activated uv environment	uv pip install --upgrade alpielocal
Editable source checkout	Update the checkout, then run python -m pip install -e . or uv pip install -e .

Close existing AlpieLocal sessions before upgrading. Activate the relevant environment for environment-based installs, then verify and check offline setup:

alpielocal --version
alpielocal init

Initialization reuses valid cached model files. Upgrading the CLI does not automatically replace existing model weights or guarantee a different runtime build; use the runtime installation instructions when changing acceleration backends.

Verification

AlpieLocal records file mutations and command results, requires behavioral acceptance checks for coding completion, and reruns relevant verification. Review the resulting diff and tests before relying on generated changes. Undo protects detected concurrent edits, but does not cover every arbitrary shell mutation or external side effect.