Metadata-Version: 2.3
Name: opencommand
Version: 0.1.5
Summary: 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.
Author: DSiENT
Author-email: DSiENT <w.caskey7@gmail.com>
Requires-Dist: asciimatics>=1.15.0
Requires-Dist: click>=8.4.2
Requires-Dist: playwright>=1.61.0
Requires-Dist: pyautogui>=0.9.54
Requires-Dist: pynput>=1.8.2
Requires-Dist: requests>=2.34.2
Requires-Dist: mss>=9.0.0
Requires-Dist: pillow>=11.0.0
Requires-Dist: llama-cpp-python>=0.3.33
Requires-Dist: huggingface-hub>=0.30.0
Requires-Dist: watchdog>=6.0.0
Requires-Dist: ntfy>=2.7.1
Requires-Dist: yara-python>=4.5.0
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/D5-Interactive/OpenCommand
Project-URL: Repository, https://github.com/D5-Interactive/OpenCommand
Description-Content-Type: text/markdown

# 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

```bash
# 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:
> ```bat
> 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

```bash
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):

```bash
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

```bash
# 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:
> ```bat
> 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

```bash
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:

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

### 3. Configure (interactive menu)

```bash
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

```bash
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

```bash
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

```bash
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.

 
