opencommand 0.1.3__tar.gz → 0.1.5__tar.gz

opencommand-0.1.5/PKG-INFO

@@ -0,0 +1,207 @@
+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.
+
+ 

opencommand-0.1.5/README.md

@@ -0,0 +1,183 @@
+# 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.
+
+ 

{opencommand-0.1.3 → opencommand-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "opencommand"
-version = "0.1.3"
+version = "0.1.5"
 description = "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."
 readme = "README.md"
 authors = [
@@ -31,7 +31,7 @@ Homepage = "https://github.com/D5-Interactive/OpenCommand"
 Repository = "https://github.com/D5-Interactive/OpenCommand"
 
 [dependency-groups]
-dev = ["pytest>=8.0"]
+dev = ["pytest>=8.0", "ruff>=0.11.0"]
 
 [tool.uv]
 package = true