premote

Remote CLI & KVM controller for Google Antigravity (agy) and desktop applications in isolated Docker noVNC containers.

AI Cost Tracking

• 🤖 LLM usage: $0.0271 (1 commits)
• 👤 Human dev: ~$100 (1.0h @ $100/h, 30min dedup)

Generated on 2026-09-17 using openrouter/qwen/qwen3-coder-next

---

Overview

premote allows you to control, monitor, and automate AI coding agents (specifically Google Antigravity CLI agy) and desktop GUI applications running inside Docker noVNC containers directly from your host PC terminal.

It provides two operation layers:

1. Direct Headless / CLI Layer: Fast, non-interactive execution of prompts with auto-approval of permissions (--dangerously-skip-permissions), JSON output, session continuation, and live quota queries (/quota).
2. KVM / Desktop GUI Layer: Live simulation of mouse and keyboard events on the X11 desktop displayed in noVNC (http://127.0.0.1:<port>/vnc.html), including window focus, keystrokes, mouse clicks, and screen capture.

---

Installation

# Clone the repository
git clone https://github.com/subactor/premote.git
cd premote

# Install locally in editable mode
pip install -e .

---

Usage

Syntax

premote <account> <command> [arguments...]

CLI / Agent Commands

1. Check Model Quotas & Limits

View live remaining quota percentages and reset timers (Gemini, Claude, GPT):

premote prototypowanie quota

Output:

GRUPA / BUCKET                 POZOSTAŁO    RESET                   
--------------------------------------------------------------------
[Gemini Models]
  Weekly Limit Remaining       98%          2026-09-24T10:15:12Z    
  Five Hour Limit Remaining    90%          2026-09-17T15:15:12Z    

[Claude and GPT models]
  Weekly Limit Remaining       100%         2026-09-24T13:27:31Z    
  Five Hour Limit Remaining    100%         2026-09-17T18:27:31Z    

For automation / JSON parsing:

premote prototypowanie quota-json

2. Execute Prompt with Auto-Approval

Run a prompt with --dangerously-skip-permissions so it never blocks waiting for confirmation:

premote prototypowanie prompt "Napisz oneliner w bashu sprawdzający zużycie dysku"

Structured JSON response with token usage and conversation ID:

premote prototypowanie prompt-json "Podaj 3 zalety Dockera"

3. Continue Previous Conversation

premote prototypowanie continue "Rozwiń drugi punkt"

4. List Available AI Models

premote prototypowanie models

5. Interactive Terminal / TUI

# Interactive bash shell inside container
premote prototypowanie terminal

# Interactive agy TUI in your terminal
premote prototypowanie agy-interactive

---

KVM / Desktop GUI Commands (noVNC)

1. List Open Windows

premote prototypowanie kvm-windows

2. Focus Window

premote prototypowanie kvm-focus "Terminal"

3. Type Text into Active Window

premote prototypowanie kvm-type "echo 'Wpisane z PC' && agy models"

4. Send Key Strokes (Navigation, Enter, Approvals)

# Press Enter
premote prototypowanie kvm-key Return

# Select option with Down arrow and Enter
premote prototypowanie kvm-key Down
premote prototypowanie kvm-key Return

# Approve with 'y'
premote prototypowanie kvm-key y
premote prototypowanie kvm-key Return

5. Click at Coordinates (X, Y)

premote prototypowanie kvm-click 800 500

6. Read Text from Screen (OCR)

Fast OCR extraction (under 4s) of terminal or any GUI window content:

# Read whole desktop
premote prototypowanie screen-text

# Read specific window by X11 window ID
premote prototypowanie screen-text 0x01600003

7. Take Screenshot of noVNC Desktop

premote prototypowanie kvm-capture screen.png

---

Unattended Execution & Permissions

To run fully autonomous agents without any user prompts for shell execution, package installation, or code edits:

# Automatically configures ~/.gemini/antigravity-cli/settings.json permissions
# and creates aliases (agy, gemini -y, claude, aider) for unattended operation:
premote prototypowanie auto-approve-all

---

Planfile / Long-Cycle Task Automation

Execute structured multi-sprint task plans (planfile.yaml) autonomously:

# 1. List tasks in planfile.yaml
premote prototypowanie planfile-tasks [path/to/planfile.yaml]

# 2. View generated agent prompt for a specific task
premote prototypowanie planfile-prompt ticket-101 [path/to/planfile.yaml]

# 3. Execute specific task with Antigravity
premote prototypowanie planfile-run ticket-101 [path/to/planfile.yaml]

# 4. Automatically run the next task
premote prototypowanie planfile-next [path/to/planfile.yaml]

---

Python API

You can also use premote directly inside Python applications:

from premote import ContainerClient, AntigravityClient, KVMController

# Connect to container
container = ContainerClient("prototypowanie")
agy = AntigravityClient(container)
kvm = KVMController(container)

# 1. Ask Antigravity a question
result = agy.prompt("Napisz prostą funkcję hello world w Pythonie")
print("Response:", result.response)

# 2. Check model limits
quota = agy.quota()
for group in quota.groups:
    print(f"Group: {group.name}")
    for bucket in group.buckets:
        print(f"  {bucket.name}: {bucket.remaining_percent}% (Resets: {bucket.reset_time})")

# 3. Simulate GUI typing in noVNC
kvm.focus("Terminal")
kvm.type_text("ls -la")
kvm.key("Return")

---

License

Licensed under Apache-2.0.