@hasna/computer

Open-source computer use for AI agents. Control your Mac with Anthropic Claude or OpenAI.

CLI + MCP Server + REST API + SDK

What it does

An AI model sees your screen (via screenshots) and controls your mouse and keyboard to complete tasks — like a remote human operator, but powered by AI.

# Tell the AI to do something on your Mac
computer run "open Safari and search for 'weather in NYC'"

# Take a screenshot
computer screenshot -o screen.png

# View past sessions
computer sessions

Features

• Multi-provider — Anthropic (Claude computer use) or OpenAI (CUA)
• macOS native — Uses screencapture + cliclick for zero-dependency screen control
• MCP server — Other AI agents can use your computer as a tool
• REST API — Integrate from any language
• Session logging — Every action logged in SQLite, fully replayable
• SDK — Import and use programmatically in TypeScript/Bun

Install

bun install -g @hasna/computer

Prerequisites:

• macOS (Apple Silicon or Intel)
• Bun runtime
• cliclick — brew install cliclick
• Accessibility permissions (System Settings > Privacy & Security > Accessibility)
• An API key: ANTHROPIC_API_KEY or OPENAI_API_KEY

CLI

computer run <task>              # Run a computer use task
computer run <task> -p openai    # Use OpenAI instead of Anthropic
computer run <task> -s 30        # Limit to 30 steps
computer open <app> [options]    # Open an app deterministically via its driver
computer apps                    # List app drivers + availability
computer screenshot              # Capture current screen
computer sessions                # List past sessions
computer session <id>            # Show session details + action log
computer stats                   # Usage statistics

Apps

Beyond AI-driven tasks (computer run), computer ships deterministic app drivers that open and arrange desktop apps with zero AI in the loop — windows, tabs, pane grids, and a command per pane.

computer apps                    # List registered drivers and availability
computer open <app> [options]    # Open/orchestrate an app via its driver

Options for computer open:

Option	Description
--grid RxC	Split the window into R rows x C cols (panes fill row-major: left-to-right, top-to-bottom)
--tabs "spec1,spec2,..."	Multiple tabs in one window, each with its own grid (e.g. "2x2,1x2,1x2")
--run <cmd>	Command for the next pane in order (repeatable); with --tabs, commands flow across tabs
--all	Run the single --run command in every pane
--dir <path>	Working directory — every pane cds there first
--max	Maximize the new window (not native fullscreen)

Examples:

# 2x2 grid, run codewith in all four panes, maximized
computer open ghostty --grid 2x2 --run "codewith" --all --max

# 2x2 grid with a different command per pane
computer open ghostty --grid 2x2 --run "htop" --run "btop" --run "vim" --run "bun dev"

# Three tabs (2x2, then two 1x2), every pane cd'd into the project
computer open ghostty --tabs "2x2,1x2,1x2" --dir ~/Workspace/myproject

Drivers:

• ghostty — Ghostty terminal (macOS, Ghostty 1.3+). Uses Ghostty's native AppleScript dictionary for windows, tabs, and splits. Requires /Applications/Ghostty.app (or ghostty on PATH).

Drivers are app-generic: each implements available() (with a reason when unavailable, e.g. on Linux) and open(spec). New drivers register in src/apps/registry.ts.

The same surface is exposed over MCP via computer_open_app (params: app, grid, tabs, run[], all, dir, max — falls back to a plain macOS app launch for apps without a driver) and computer_list_apps.

MCP Server

Add to your Claude Code config:

{
  "mcpServers": {
    "computer": {
      "command": "computer-mcp"
    }
  }
}

HTTP mode

Shared Streamable HTTP transport for multi-agent sessions (stdio remains the default):

computer-mcp --http              # http://127.0.0.1:8806/mcp
MCP_HTTP=1 computer-mcp          # same via env
computer-mcp --http --port 9000    # override port

• Health: GET http://127.0.0.1:8806/health → {"status":"ok","name":"computer"}
• MCP endpoint is also mounted on computer-serve at /mcp.

Available tools:

• computer_run_task — Run a full computer use task
• computer_screenshot — Capture the screen
• computer_click — Click at coordinates
• computer_type — Type text
• computer_key — Press keys
• computer_scroll — Scroll
• computer_mouse_move — Move the mouse
• computer_open_url — Open a URL
• computer_open_app — Open an app
• computer_screen_size — Get screen resolution
• computer_list_sessions — List sessions
• computer_get_session — Get session details
• computer_stats — Usage stats

REST API

computer-serve  # Starts on port 19450

# Run a task
curl -X POST localhost:19450/run -d '{"task":"open calculator"}'

# Take a screenshot
curl localhost:19450/screenshot

# Execute a single action
curl -X POST localhost:19450/action -d '{"type":"click","point":{"x":500,"y":300}}'

# List sessions
curl localhost:19450/sessions

SDK

import { runTask, captureScreenshot, createMacDriver } from "@hasna/computer";

// Run a full task
const session = await runTask({
  task: "open Notes and create a new note",
  provider: "anthropic",
  maxSteps: 20,
  onStep: (step, response, result) => {
    console.log(`Step ${step}: ${response.action?.type}`);
  },
});

// Or control manually
const driver = createMacDriver();
const screenshot = await driver.screenshot();
const result = await driver.execute({
  type: "click",
  point: { x: 500, y: 300 },
});

How it works

1. Screenshots your screen
2. Sends the screenshot to the AI model (Claude or GPT)
3. The model analyzes what's on screen and returns an action (click, type, scroll, etc.)
4. The action is executed on your Mac
5. A new screenshot is taken
6. Repeat until the task is done (or max steps reached)

Providers

Provider	Model	Tool
Anthropic	Claude Sonnet 4.5 (default)	computer_20250124
OpenAI	computer-use-preview	CUA Responses API

Data

Sessions and action logs are stored in ~/.hasna/computer/computer.db (SQLite).

Storage Sync

Optional Postgres sync is available through package-local commands:

export HASNA_COMPUTER_DATABASE_URL=postgres://...
computer storage status
computer storage push
computer storage pull
computer storage sync

The MCP server also exposes storage_status, storage_push, storage_pull, and storage_sync.

COMPUTER_DATABASE_URL is accepted as the non-Hasna fallback database URL.

License

Apache-2.0