Files
skills/public/hanzo-operative.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

305 lines
20 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hanzo-operative</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hanzo-operative.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hanzo-operative">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hanzo-operative.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hanzo-operative</h1><p class="lede">Hanzo Operative (hanzo-operative) is an autonomous computer use agent that enables AI to control desktop environments via screenshots, mouse, keyboard, and bash commands.</p><h1>Hanzo Operative - Computer Use Agent</h1>
<p><strong>Category</strong>: Hanzo Ecosystem <strong>Related Skills</strong>: <code>hanzo/hanzo-agent.md</code>, <code>hanzo/hanzo-mcp.md</code></p>
<h2>Overview</h2>
<p>Hanzo Operative (<code>hanzo-operative</code>) is an <strong>autonomous computer use agent</strong> that enables AI to control desktop environments via screenshots, mouse, keyboard, and bash commands. It uses Anthropic&#x27;s Claude API with computer use tool definitions to analyze screenshots and execute actions. The entry point is a Streamlit web UI. Fork of Anthropic&#x27;s computer-use demo.</p>
<h3>What it actually is</h3>
<ul><li>Python package <code>hanzo-operative</code> v0.1.1</li><li><strong>Requires Python &gt;= 3.14</strong></li><li>Streamlit UI (<code>operative/operative.py</code>) as the primary entry point</li><li>Tool-based architecture in <code>operative/tools/</code>:</li><li><code>computer.py</code> -- Screenshot, mouse, keyboard via xdotool/scrot</li><li><code>bash.py</code> -- Shell command execution</li><li><code>edit.py</code> -- File editing</li><li><code>base.py</code> -- Base tool class</li><li><code>collection.py</code> -- Tool collection registry</li><li><code>groups.py</code> -- Tool grouping</li><li><code>run.py</code> -- Tool execution runner</li><li>Agent loop (<code>operative/loop.py</code>) -- orchestrates Claude API calls with tool results</li><li>System prompt (<code>operative/prompt.py</code>)</li><li>Three Dockerfiles in <code>docker/</code>:</li><li><code>Dockerfile</code> -- Main image (builds on xvfb image)</li><li><code>Dockerfile.desktop</code> -- Desktop environment image</li><li><code>Dockerfile.xvfb</code> -- Xvfb virtual display image</li><li>Docker images: <code>ghcr.io/hanzoai/operative:latest</code>, <code>ghcr.io/hanzoai/xvfb:latest</code>, <code>ghcr.io/hanzoai/desktop:latest</code></li><li>No compose.yml in the repo</li></ul>
<h3>What it is NOT</h3>
<ul><li>No programmatic Python API like <code>from operative import Operative</code> with <code>op.click()</code>, <code>op.type()</code> etc.</li><li>No <code>op.execute_task()</code> high-level task runner</li><li>Tools are invoked by Claude via the Anthropic API tool use protocol, not called directly by user code</li><li>VNC port 6080 is exposed in the Makefile&#x27;s docker run commands</li></ul>
<h2>When to use</h2>
<ul><li>Automating desktop workflows via AI vision</li><li>AI-driven UI testing across any desktop application</li><li>Screen scraping with AI understanding</li><li>RPA (Robotic Process Automation) with Claude reasoning</li><li>Remote desktop automation via VNC</li></ul>
<h2>Quick reference</h2>
<p>| Item | Value | |------|-------| | Repo | <code>github.com/hanzoai/operative</code> | | Package | <code>hanzo-operative</code> (PyPI) | | Version | 0.1.1 | | Upstream | Anthropic computer-use demo | | Python | &gt;= 3.14 | | UI | Streamlit (port 8501) | | VNC | Port 5900 (native), 6080 (noVNC web) | | Docker images | <code>ghcr.io/hanzoai/operative</code>, <code>ghcr.io/hanzoai/xvfb</code>, <code>ghcr.io/hanzoai/desktop</code> | | Dev (native) | <code>make run</code> (runs <code>uv run -- python3 -m streamlit run operative/operative.py</code>) | | Dev (Docker) | <code>make dev</code> | | Setup | <code>make setup</code> (creates venv with uv, Python 3.14) | | Test | <code>make test</code> (pytest) | | Test + coverage | <code>make test-cov</code> | | Lint | <code>make lint</code> (ruff) | | Format | <code>make format</code> (ruff) | | License | MIT |</p>
<h2>Project structure</h2>
<pre><code>hanzoai/operative/
pyproject.toml # Package config (hanzo-operative 0.1.1, python &gt;= 3.14)
requirements.txt # Pinned deps
Makefile # Build, run, test, Docker targets
operative/
__init__.py
operative.py # Streamlit UI entry point
loop.py # Agent loop (Claude API + tool orchestration)
prompt.py # System prompt
requirements.txt # Operative-specific deps
tools/
__init__.py # Tool exports
base.py # Base tool class
computer.py # Computer use (screenshot, mouse, keyboard)
bash.py # Bash command execution
edit.py # File editing tool
collection.py # Tool collection registry
groups.py # Tool grouping definitions
run.py # Tool execution runner
docker/
Dockerfile # Main operative image
Dockerfile.desktop # Desktop environment image
Dockerfile.xvfb # Xvfb virtual display base image
image/ # Docker image assets
tests/ # Test suite
docs/ # Documentation</code></pre>
<h2>Dependencies</h2>
<p>From <code>pyproject.toml</code>:</p>
<ul><li><code>anthropic &gt;= 0.84.0</code> -- Claude API client</li><li><code>streamlit &gt;= 1.43.0</code> -- Web UI framework</li><li><code>httpx &gt;= 0.28.0</code> -- HTTP client</li><li><code>pillow &gt;= 12.1.1</code> -- Image processing</li><li><code>certifi &gt;= 2025.1.31</code> -- TLS certificates</li></ul>
<p>Dev/test extras: pytest, pytest-cov, pytest-mock, pytest-asyncio, ruff, black</p>
<h2>Quickstart</h2>
<h3>Docker (recommended)</h3>
<pre><code class="lang-bash">git clone https://github.com/hanzoai/operative.git
cd operative
# Run with Docker (includes Xvfb, xdotool, VNC, Streamlit)
make dev
# Requires: ANTHROPIC_API_KEY env var
# Access Streamlit UI
open http://localhost:8501
# Access VNC (view desktop)
open http://localhost:6080 # noVNC web client
# or connect VNC client to localhost:5900</code></pre>
<h3>Native (requires Python 3.14)</h3>
<pre><code class="lang-bash">git clone https://github.com/hanzoai/operative.git
cd operative
# Setup with uv (creates .venv with Python 3.14)
make setup
# Install system deps (Ubuntu/Debian)
sudo apt install xdotool xvfb scrot
# Start Xvfb if headless
Xvfb :99 -screen 0 1920x1080x24 &amp;
export DISPLAY=:99
# Run
make run
# Equivalent to: uv run -- python3 -m streamlit run operative/operative.py</code></pre>
<h2>Docker ports</h2>
<p>The <code>make dev</code> and <code>make run-docker</code> commands expose:</p>
<p>| Port | Service | |------|---------| | 5900 | VNC (native) | | 6080 | noVNC (web) | | 8080 | HTTP | | 8501 | Streamlit UI |</p>
<h2>How it works</h2>
<ol><li>User enters a task in the Streamlit UI</li><li>The agent loop (<code>loop.py</code>) sends the task to Claude with computer use tool definitions</li><li>Claude responds with tool calls (screenshot, click, type, bash, edit)</li><li>Tools execute against the X11 display (via xdotool/scrot) or shell</li><li>Results (screenshots, output) are sent back to Claude</li><li>Loop continues until task is complete or user stops it</li></ol>
<p>The tools are structured as Anthropic API tool definitions -- they are NOT a user-facing Python SDK. Claude decides when and how to use them based on visual analysis of screenshots.</p>
<h2>Makefile targets</h2>
<p>| Target | Purpose | |--------|---------| | <code>make setup</code> | Create venv with uv + Python 3.14, install deps | | <code>make run</code> | Run Streamlit locally | | <code>make dev</code> | Run Docker container with all ports | | <code>make build</code> | Build operative Docker image | | <code>make build-desktop</code> | Build desktop Docker image | | <code>make build-xvfb</code> | Build xvfb Docker image | | <code>make test</code> | Run pytest | | <code>make test-cov</code> | Run pytest with coverage | | <code>make lint</code> | Run ruff check | | <code>make format</code> | Run ruff format | | <code>make install-dev</code> | Install with dev extras | | <code>make install-test</code> | Install with test extras |</p>
<h2>Related Skills</h2>
<ul><li><code>hanzo/hanzo-agent.md</code> -- Agent framework (can use operative for computer use)</li><li><code>hanzo/hanzo-mcp.md</code> -- MCP integration</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2026-03-13 <strong>Category</strong>: Hanzo Ecosystem <strong>Related</strong>: computer-use, automation, desktop, x11, xdotool, vision, streamlit <strong>Prerequisites</strong>: Python &gt;= 3.14, Docker (recommended), Anthropic API key</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hanzo-operative.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>