Skip to main content
Display the current system status including platform information, agent-desktop version, accessibility permission state, and the number of refs in the last snapshot.

​
Usage

agent-desktop status

​
Parameters

This command takes no parameters.

​
Response

​
platform
string
required
Operating system name ("macos", "windows", or "linux")
​
version
string
required
agent-desktop version string (e.g., "0.1.0")
​
permissions
object
required
Accessibility permission status
​
ref_count
number
Number of element refs in the last snapshot. Omitted if no snapshot has been taken yet.

​
Examples

​
Status with Permission Granted

agent-desktop status

{
  "version": "1.0",
  "ok": true,
  "command": "status",
  "data": {
    "platform": "macos",
    "version": "0.1.0",
    "permissions": {
      "granted": true
    },
    "ref_count": 14
  }
}

​
Status with Permission Denied

agent-desktop status

{
  "version": "1.0",
  "ok": true,
  "command": "status",
  "data": {
    "platform": "macos",
    "version": "0.1.0",
    "permissions": {
      "granted": false,
      "suggestion": "Open System Settings > Privacy & Security > Accessibility and add your terminal app"
    }
  }
}

​
Status Before Any Snapshot

agent-desktop status

{
  "version": "1.0",
  "ok": true,
  "command": "status",
  "data": {
    "platform": "macos",
    "version": "0.1.0",
    "permissions": {
      "granted": true
    }
  }
}

​
Use Cases

Verify agent-desktop is working before running commands:
STATUS=$(agent-desktop status)
if [ "$(echo $STATUS | jq -r '.data.permissions.granted')" = "true" ]; then
  echo "Ready to proceed"
else
  echo "Permission required"
  exit 1
fi
Verify agent-desktop version in scripts:
VERSION=$(agent-desktop status | jq -r '.data.version')
echo "Using agent-desktop $VERSION"
Check how many refs are available:
REF_COUNT=$(agent-desktop status | jq -r '.data.ref_count')
echo "Last snapshot has $REF_COUNT interactive elements"
Detect the current platform:
PLATFORM=$(agent-desktop status | jq -r '.data.platform')
if [ "$PLATFORM" = "macos" ]; then
  echo "Running on macOS"
fi

​
Permission State

The permissions.granted field indicates whether macOS accessibility permission is granted. If false, the suggestion field provides instructions: 
{
  "permissions": {
    "granted": false,
    "suggestion": "Open System Settings > Privacy & Security > Accessibility and add your terminal app"
  }
}
To grant permission:
  1. Open System Settings
  2. Go to Privacy & Security > Accessibility
  3. Add your terminal app (e.g., Terminal, iTerm2)
  4. Run agent-desktop status again to verify
Alternatively, use the permissions command with --request to trigger the system dialog: 
agent-desktop permissions --request

​
Ref Count

The ref_count field shows how many element refs were allocated in the last snapshot:
  • Omitted: No snapshot has been taken yet
  • 0: Last snapshot had no interactive elements (or was run with --interactive-only on a static UI)
  • N > 0: N interactive elements have refs (@e1 through @eN)
This is useful for:
  • Verifying refs are available before using them in commands
  • Debugging empty snapshots
  • Monitoring UI complexity

​
Platform Support

The platform field indicates the current OS:
ValueOS
macosmacOS (fully supported)
windowsWindows (Phase 2)
linuxLinux (Phase 2)
Currently, only macos is fully implemented.
  • permissions - Check or request accessibility permission
  • version - Show version information only
  • snapshot - Take a snapshot to populate ref_count

Build docs developers (and LLMs) love

Get started for freeTalk to us