FlowOS Documentation

flowos-desktop/
├── flowos.py           # CLI entry point — --store flag for GUI
├── tools.py            # Core tool definitions + handlers
├── plugin_manager.py   # Plugin registry, config, setup wizard
├── session.py          # Session persistence (~/.flowos/sessions/)
├── plugins/
│   ├── base.py         # Plugin base class
│   ├── git_plugin.py
│   ├── docker_plugin.py
│   ├── ssh_plugin.py
│   ├── browser_plugin.py
│   ├── spotify_plugin.py
│   ├── homeserver_plugin.py
│   ├── notes_plugin.py
│   ├── weather_plugin.py
│   └── clipboard_plugin.py
├── gui/
│   ├── server.py       # FastAPI backend
│   └── store.html      # Plugin store UI
├── iso/
│   ├── build.sh        # ISO build entry point
│   ├── Dockerfile
│   ├── initramfs/init  # Custom boot init
│   ├── grub/grub.cfg
│   ├── scripts/        # rootfs, initramfs, ISO assembly
│   └── overlay/        # Files baked into the rootfs
└── docs/               # projectaquarius.space (GitHub Pages)

# Clone the repo
git clone https://github.com/Mattjhagen/FlowOS-Project-Aquarius.git
cd FlowOS-Project-Aquarius

# Install dependencies
pip3 install -r requirements.txt

# Set your API key
export ANTHROPIC_API_KEY=your_key_here

# Run
python3 flowos.py

python3 flowos.py

python3 flowos.py --resume

python3 flowos.py --store

# Linux — replace sdX with your USB device
sudo dd if=flowos.iso of=/dev/sdX bs=4M status=progress && sync

# macOS — replace diskN with your USB disk number
diskutil unmountDisk /dev/diskN
sudo dd if=flowos.iso of=/dev/rdiskN bs=4m

while True:
    response = client.messages.create(
        model="claude-sonnet-4-5",
        tools=all_tools,          # core + active plugins
        messages=messages
    )

    for block in response.content:
        if block.type == "text":
            render_markdown(block.text)
        elif block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            tool_results.append(result)

    if response.stop_reason == "end_turn":
        break                          # Claude is done

    messages.append(tool_results)  # feed results back

# Enable a plugin
→ enable docker

# Disable a plugin
→ disable weather

# Interactive toggle menu
→ plugins

# Reload without restarting
→ reload plugins

# plugins/hello_plugin.py
from plugins.base import Plugin

class HelloPlugin(Plugin):
    name = "hello"
    description = "Greets people and tells the time"
    version = "1.0.0"

    @classmethod
    def tool_definitions(cls):
        return [{
            "name": "say_hello",
            "description": "Greet someone by name",
            "input_schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string", "description": "Person's name"}
                },
                "required": ["name"]
            }
        }]

    @classmethod
    def tool_handlers(cls):
        return {
            "say_hello": lambda name: f"Hello, {name}!"
        }

AVAILABLE_PLUGINS = {
    # ... existing plugins ...
    "hello": ("plugins.hello_plugin", "HelloPlugin", "Greets people"),
}

→ enable hello

{
    "name": "tool_name",               # snake_case, globally unique
    "description": "...",              # Claude reads this to decide when to call the tool
    "input_schema": {
        "type": "object",
        "properties": {
            "param": {
                "type": "string",        # string | integer | boolean | array
                "description": "...",
                "enum": ["a", "b"]      # optional: constrain to values
            }
        },
        "required": ["param"]           # omit for optional params
    }
}

git clone https://github.com/Mattjhagen/FlowOS-Project-Aquarius.git
cd FlowOS-Project-Aquarius
./iso/build.sh

# Force full rebuild (clears cache)
./iso/build.sh --no-cache

python3 flowos.py --store