Skip to main content
This example shows the simplest direct HoloDesktop CLI workflow: run a desktop task from the command line, let the CLI operate normal apps, and verify the result with deterministic checks. The task is intentionally concrete. HoloDesktop CLI reads three staged receipt files, adds one expense row per receipt to a LibreOffice Calc ledger, saves the spreadsheet, and creates an unsent Mail draft with the sheet attached.

​
What this teaches

The Claude Code example shows HoloDesktop CLI inside an agent host. This example removes the host and shows the CLI as a standalone desktop operator:
  • the CLI starts the run;
  • the harness prepares the desktop state;
  • HoloDesktop CLI observes receipts and controls apps visually;
  • verifiers decide whether the run actually worked;
  • run artifacts explain what happened step by step.
Use this pattern for local demos, eval harnesses, and release smoke checks that need real desktop behavior rather than only API calls.

​
Before you run it

This is a real desktop automation run, not a tiny hello world. It may take several minutes. On a first run, macOS or the apps may show permission and onboarding dialogs. During the run:
  • do not use the machine for other work;
  • expect Finder, LibreOffice, Preview or QuickLook, and Mail to come to the foreground;
  • allow app permissions if macOS asks for access to Desktop files;
  • do not click Send in Mail if you take over manually.
If you only want to inspect what the harness will do, use --dry-run first.

​
Prerequisites

From the holo-desktop checkout, install the workspace: 
uv sync --all-groups
The example currently targets macOS and expects:
  • LibreOffice installed at /Applications/LibreOffice.app;
  • Mail available locally;
  • HoloDesktop CLI configured for hosted mode or local model mode;
  • the managed hai-agent-runtime installed, or available on PATH.
If you have not run HoloDesktop CLI before, a first real run may download the pinned desktop runtime under: 
~/.holo/runtime/
For hosted mode, sign in before running the demo: 
uv run holo login
For local mode, start your OpenAI-compatible model server and pass --base-url and --model to the demo command.

​
Install the demo skill

The demo includes a small HoloDesktop CLI skill that gives the agent task-specific guidance for expense-report work. Install it once: 
cd examples/holo-demos
uv run holo-demo install-skills
The installer copies the bundled skill into: 
~/.holo/skills/expense-report/
It is safe to rerun. If you edit the bundled skill later, pass --force to overwrite the installed copy.

​
Pin the fixtures

The receipts and spreadsheet template come from OSWorld fixtures hosted on Hugging Face. The manifest pins every downloaded file by sha256, so the verifier checks known inputs rather than a drifting dataset. 
uv run holo-demo pin-fixtures manifests/expense_report.toml
The fixtures are written under: 
examples/holo-demos/fixtures/expense_report/
The demo only stages the first three receipts to keep the run short.
Finder showing three staged receipt files in the holo-demo-receipts folder

​
Dry-run first

Run a dry-run to see the app launch plan, focus target, prompt, and runtime options without letting HoloDesktop CLI control the desktop: 
uv run holo-demo run expense_report --dry-run
You should see output like: 
[dry-run] expense_report: would launch ['com.apple.finder', 'org.libreoffice.script', 'com.apple.mail']
[dry-run] expense_report: would focus 'org.libreoffice.script'
[dry-run] expense_report: output would go to runs/expense_report
Use this to inspect the harness before running the actual task.

​
Run the demo

Start the real run: 
uv run holo-demo run expense_report
For a hosted model, the run uses your HoloDesktop CLI login. For a local OpenAI-compatible server, pass the model connection explicitly: 
uv run holo-demo run expense_report \
  --base-url http://localhost:8000/v1 \
  --model Hcompany/Holo-3.1-35B-A3B
You can also adjust the cap: 
uv run holo-demo run expense_report --max-steps 60

​
What HoloDesktop CLI does

Before HoloDesktop CLI starts acting, the harness copies files into predictable Desktop locations: 
~/Desktop/holo-demo-receipts/
~/Desktop/holo-demo-bookkeeping.xlsx
It then opens Finder, LibreOffice Calc, and Mail, and focuses LibreOffice so the agent begins from the ledger.
LibreOffice bookkeeping ledger before the receipt rows are added
The task asks HoloDesktop CLI to:
  • inspect each receipt or invoice using QuickLook or Preview;
  • identify what was bought and the grand total;
  • append a row with Description, Category, Type, and Amount;
  • record expenses as negative amounts;
  • save the spreadsheet;
  • create a new Mail draft to expenses@example.com;
  • set the subject to Expenses;
  • attach the saved spreadsheet;
  • leave the message in Drafts.
A receipt opened from Finder while HoloDesktop CLI reads the visible total
On a normal run, the three staged receipts should produce rows like:
DescriptionCategoryTypeAmount
GroceryFoodExpense-186.93
Cash OutOtherExpense-3670.00
SoupFoodExpense-5.70
LibreOffice bookkeeping ledger after HoloDesktop CLI adds receipt expense rows
Mail draft addressed to expenses@example.com with the saved spreadsheet attached

​
How verification works

The example does not rely on a human watching the desktop and deciding whether it looked right. After the run, deterministic verifiers inspect the artifacts. The ledger_rows verifier opens the spreadsheet with openpyxl and checks:
  • exactly one new row exists per staged receipt;
  • the new amount values match the pinned receipt totals;
  • amounts are compared sign-insensitively with a one-cent tolerance.
The mail_draft verifier uses AppleScript to check:
  • there is a draft addressed to expenses@example.com;
  • the subject is Expenses;
  • the draft has at least one attachment.
A passing run should report a verification summary like: 
verify_pass=2/2
If Mail automation permission is denied, the Mail check fails as a harness failure rather than as evidence that HoloDesktop CLI made the wrong UI decision.

​
Run artifacts

Each run writes a timestamped directory under: 
examples/holo-demos/runs/expense_report/
The important files are:
FileWhat it is for
events.jsonlOne runtime event per line: observations, model reasoning, tool calls, and step timing.
task.jsonThe task prompt, result, status, verification results, and run metadata.
runs/summary-demos.csvOne summary row per demo run, including verification status.
Interrupted runs are still useful. If you stop the run early, the summary shows it as interrupted and verification may be skipped or incomplete, but events.jsonl still records what HoloDesktop CLI saw and did. After verification, staged Desktop files are moved into: 
~/.holo/runs/expense_report-quarantine/
That keeps the touched files available for inspection without leaving the Desktop cluttered between runs.

​
Troubleshooting

If the run gets distracted by another app, stop it and rerun from a quiet desktop session. HoloDesktop CLI controls the visible desktop, so foreground apps matter. If LibreOffice shows a welcome or file-access dialog, allow it and let the run continue. These first-run dialogs are normal on a fresh machine. If Mail shows a privacy or onboarding dialog, complete the prompt before expecting the Mail verifier to pass. If fixture download fails, rerun: 
uv run holo-demo pin-fixtures manifests/expense_report.toml
If the verifier reports a spreadsheet mismatch, inspect the quarantined workbook and compare it with events.jsonl to see whether HoloDesktop CLI read the receipt incorrectly, typed into the wrong cell, or was interrupted before saving.

​
Adapt the pattern

The reusable pattern is:
  1. Stage known inputs in predictable locations.
  2. Launch the apps the task needs.
  3. Focus the app where HoloDesktop CLI should begin.
  4. Give HoloDesktop CLI a concrete desktop task.
  5. Verify the output with code.
  6. Keep the run artifacts for debugging and evaluation.
That pattern works well for demos and evals because it separates visible desktop behavior from pass/fail logic. HoloDesktop CLI does the user-visible work; deterministic verifiers decide whether the work met the contract.
Animated GIF of HoloDesktop CLI opening receipts and updating a LibreOffice bookkeeping ledger