ploop 0.1.0

Ploop (Proactive Loop), a lightweight local proactive agent for Apple Silicon.

Ploop

Ploop stands for Proactive Loop. It is a local, proactive, autonomous AI agent running entirely on-device via MLX (Apple Silicon). No cloud calls: the model runs locally, the agent decides on its own what to do on every cycle, and everything is controllable from the ploop CLI.

The project rule is to stay proactive, lightweight, and small: prefer a few explicit standard-library functions over agent frameworks, broad abstractions, or extra dependencies. New code should earn its lines by directly improving the proactive loop, safety, or local runtime behavior.

On every "cycle" the agent reads its own open goals and recent history, asks the model — without a specific prompt from the user — "what do you do now?", and the model picks a tool to run (write a note, read/write a file, close a goal that's been reached, or just wait). In loop mode this repeats at regular intervals, indefinitely: this is the autonomous mode, meant to run in the background without supervision.

By default the agent operates in the directory where you launch it. Use -C /path/to/project to point it at another directory; its state and notes live in that directory's hidden .ploop/ folder.

Requirements

• macOS on Apple Silicon (arm64) — MLX requires the Apple Silicon GPU.
• Python 3.10+
• ~3 GB of free disk space for the model weights (downloaded automatically on first run from Hugging Face for the default model: mlx-community/Qwen3-4B-Instruct-2507-4bit)

Installation

Install from PyPI:

python3 -m pip install ploop

This installs the ploop CLI command.

For local development from this source checkout:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

The repo-local ./bin/ploop wrapper also works for development.

Quick start

ploop run "Inspect this folder and write a short note with the next useful step."
ploop status        # shows what it did

To run one cycle against another folder:

ploop -C /path/to/project run "Inspect this project and write the next useful step."

To let it run continuously in the background:

ploop loop "Monitor this folder and write useful notes when there is something worth doing next." --interval 60

Model

The default model is mlx-community/Qwen3-4B-Instruct-2507-4bit, chosen because it is small and supports the tool-call format Ploop expects. You can override it with any MLX-compatible Hugging Face model id or local model directory:

ploop run "Inspect this folder" --model /Users/me/models/my-mlx-model
ploop model set /Users/me/models/my-mlx-model
ploop model show

Model priority is: --model, saved project setting, PLOOP_MODEL, then the default model. Ploop intentionally stays single-backend for now: GGUF/Ollama/llama.cpp models need a future backend adapter rather than extra framework code in the core loop.

Documentation

The full reference (CLI commands, tools available to the model, architecture, security, testing, troubleshooting) lives in the docs/ folder:

Document	Content
docs/architecture.md	How the project is built and how the proactive cycle works
docs/cli.md	Full reference of every CLI command
docs/agent-tools.md	The tools the model can invoke
docs/security.md	Sandboxing and what to know before running it unsupervised
docs/test.md	How to run the tests
docs/troubleshooting.md	Known issues and fixes
CHANGELOG.md	Release history

Project structure

agent/          — agent code (llm.py, tools.py, state.py, core.py, cli.py)
bin/ploop       — CLI wrapper (uses `.venv` if present, then runs `python -m agent`)
bin/agent       — compatibility wrapper that delegates to `bin/ploop`
pyproject.toml — local editable install and `ploop` CLI entry point
tests/          — unit tests + end-to-end smoke test
docs/           — full documentation