opencommand 0.1.5

Local-first swarm agent framework: a Commander plans and dispatches a swarm of Workers that research, code, test, and interactively drive the computer to complete long-horizon codebase goals.

OpenCommand

Local-first swarm agent framework. A Commander model plans and dispatches a swarm of Workers that research, code, test, and interactively drive the computer (mouse, keyboard, screen) to complete long-horizon codebase goals.

Everything runs embedded — models are GGUF files loaded directly with llama-cpp-python (no API servers, no network at runtime). Designed for Python 3.14 (free-threaded).

Install

# Run without installing (ephemeral):
uv tool run opencommand --help

# Or install globally:
uv tool install opencommand
playwright install   # optional, for the playwright tool

Note: the llama-cpp-python prebuilt CPU wheel may crash on older CPUs (illegal-instruction). If so, rebuild from source with AVX2:

call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
set CMAKE_ARGS=-DGGML_AVX2=ON
uv pip install --no-binary llama-cpp-python --no-cache llama-cpp-python

Usage

opencommand models list                 # list built-in embedded models
opencommand models pull all             # download GGUF models into ./models
opencommand config                      # interactive menu: workers, batch size, GPU, etc.
opencommand run "Add unit tests for the engine module."
opencommand run --goal-file Goal.md    # run from a Goal.md spec (intended state)
opencommand run "Build a Panda3D FPS" --pipeline advanced --verify "uv run pytest -q"
opencommand tui                         # live swarm dashboard
opencommand cron add healthcheck "every 1h" "echo ok"

Goal.md spec

Instead of an inline goal, point run at a Goal.md file that defines the intended end state / requirements for the session. Its contents become the goal fed to the swarm (and the advanced pipeline's review gate checks against it):

opencommand run --goal-file Goal.md

The file name is configurable via opencommand config (default Goal.md).

Built-in models

Role	Model
commander	deepreinforce-ai/Ornith-1.0-9B-GGUF
worker	unsloth/Qwen3-4B-Instruct-2507-GGUF
vision	unsloth/Qwen3-VL-4B-Instruct-GGUF
vision_small	openbmb/MiniCPM-V-4.6-gguf

Links

• DESIGN.md — full architecture & research notes
• TODO.md — roadmap tracker

Micro-wiki: running & configuring OpenCommand on any system

OpenCommand is local-first and cross-platform (Windows, Linux, macOS). Everything runs embedded — no API keys, no external servers. The only hard requirement is Python 3.14+ and enough RAM for the GGUF models.

1. Install

# Ephemeral (no install):
uv tool run opencommand --help

# Global install (recommended):
uv tool install opencommand
playwright install        # optional, only for the playwright tool

CPU illegal-instruction crash? The llama-cpp-python prebuilt wheel is built with a newer ISA than some CPUs (e.g. Zen 3 / Ryzen 5000). Rebuild from source with your ISA flags:

call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
set CMAKE_ARGS=-DGGML_AVX2=ON
uv pip install --no-binary llama-cpp-python --no-cache llama-cpp-python

2. Scaffold a workspace

opencommand init            # creates README.md, TODO.md, .opencommand/ + GOAL.md

init is idempotent — it never overwrites existing files, so re-running it is safe. Fill out .opencommand/GOAL.md with the intended end state, then run the full advanced pipeline against it:

opencommand run --goal-file .opencommand/GOAL.md --pipeline advanced

3. Configure (interactive menu)

opencommand config

Sets: vision on/off, vision model (vision = Qwen3-VL-4B, vision_small = MiniCPM-V-4.6 0.8B for low-RAM), max workers, batch size, retries, pipeline, live-verify, GPU layers, goal file, desktop safety policy, and per-role device placement.

4. Device placement (low-VRAM hosts)

Models can be pinned per role to GPU (offload all layers) or CPU+RAM (RAM only) via opencommand config → "Model device placement". Roles: commander, worker, vision, vision_small. Example for an 8 GB VRAM / 32 GB RAM machine:

Role	Device	Why
commander	GPU	Small planner; keep it fast & resident on GPU
worker	CPU	Heavy pool; scales with RAM, not VRAM
vision	GPU	VL desktop agent needs the GPU for screen理解
vision_small	GPU	Lightweight fallback for the desktop agent

Roles you don't pin fall back to the legacy global n_gpu_layers (-1 = all GPU, 0 = CPU). During live-verify the Commander is unloaded from the GPU while the VL desktop agent runs (freeing VRAM), then re-loaded to review the agent's report and continue the loop.

5. Run modes

opencommand run "Add unit tests for the engine module."          # inline goal
opencommand run --goal-file .opencommand/GOAL.md                 # from spec
opencommand run "Build a Panda3D FPS" --pipeline advanced \
    --verify "uv run pytest -q"                                # verify gate
opencommand run "..." --live-verify                            # interactive desktop check
opencommand tui                                                  # live dashboard

• standard pipeline: plan → research → workers.
• advanced pipeline: scaffold → research loop (until accurate) → workers → test+debug loop → Commander review gate → optional live-verify.

6. Desktop safety

The desktop agent drives the real mouse/keyboard, so it is the most dangerous capability. opencommand config exposes a safety policy that the Commander enforces before every action: allow/deny mouse, keyboard, typing; require confirmation for risky-but-permitted actions; max steps; pause between actions; and a built-in deny-list of destructive actions (restart/shutdown), dangerous key combos (win+r, ctrl+alt+del), and typed tokens (rm -rf, sudo, curl | sh). OS-specific safe-operation skills ship for Windows / Linux / macOS.

7. Scheduling

opencommand cron add healthcheck "every 1h" "echo ok"   # shell command
opencommand cron add build "daily 09:00" "uv run pytest -q"  # cron expr
opencommand cron edit healthcheck --schedule "every 30m"  # change without remove+add
opencommand cron list / remove / status / start

Persisted jobs auto-boot with run / cron start and dispatch goals through the Commander or run shell commands.

8. Security tooling

opencommand run "Scan the workspace for stray scripts" --goal-file Goal.md

The system tool lists processes, watches paths (watchdog), and scans files / directories / live processes with YARA (yara-python, with a bundled default ruleset detecting stray agent loops, obfuscation, suspicious PowerShell, and known malware markers). Falls back to the yara CLI if the binding is absent.