Skip to main content

Examples

Step-by-step workflows demonstrating both interaction paths and post-processing.

Interactive Workflow​

Record a Terminal session step by step using individual tool calls.

Step 1: Check Permissions​

{
  "method": "tools/call",
  "params": { "name": "check_permissions", "arguments": {} }
}

Response:

{ "screen_recording": true, "accessibility": true, "note": "All required permissions granted." }

Step 2: Open an Application​

{
  "method": "tools/call",
  "params": { "name": "open_app", "arguments": { "app": "Terminal" } }
}

Response:

{ "window_id": 12345, "app": "Terminal", "title": "zsh" }

Step 3: Start Recording​

{
  "method": "tools/call",
  "params": {
    "name": "start_recording",
    "arguments": { "window_id": 12345, "fps": 30, "duration": 5 }
  }
}

Response:

{ "session_id": "rec-a1b2c3d4", "recording": true }

Step 4: Simulate Input​

{
  "method": "tools/call",
  "params": { "name": "type_text", "arguments": { "text": "echo Hello!", "enter": true } }
}
{
  "method": "tools/call",
  "params": { "name": "type_text", "arguments": { "text": "ls -la", "enter": true } }
}

Step 5: Stop Recording​

{
  "method": "tools/call",
  "params": { "name": "stop_recording", "arguments": { "session_id": "rec-a1b2c3d4" } }
}

Response:

{ "session_id": "rec-a1b2c3d4", "frames": 150, "elapsed": 5.0 }

Step 6: Render GIF​

{
  "method": "tools/call",
  "params": {
    "name": "render_gif",
    "arguments": {
      "session_id": "rec-a1b2c3d4",
      "output": "demo.gif",
      "max_width": 800,
      "transforms": { "cursor_smoothing": true, "keystroke_badges": true }
    }
  }
}

Response:

{ "path": "demo.gif", "size_mb": 1.2, "dimensions": "800x450", "frames": 150 }

Script-Based Workflow​

Write and execute a .qgif script using the scripting reference.

Step 1: Read the Scripting Reference​

{
  "method": "resources/read",
  "params": { "uri": "quikgif://docs/scripting-reference" }
}

This returns the complete DSL reference so the AI can learn the syntax.

Step 2: Validate the Script​

{
  "method": "tools/call",
  "params": {
    "name": "validate_script",
    "arguments": {
      "script": "set output \"demo.gif\"\nset max-width 800\nopen \"Terminal\"\ncapture-window app \"Terminal\" as $t\nresize 800 400\nclear\nrecord $t duration 3 continue\ntype \"echo Hello\" enter\nremain\nrender"
    }
  }
}

Response:

{ "valid": true, "instruction_count": 10, "warnings": [] }

Step 3: Execute the Script​

{
  "method": "tools/call",
  "params": {
    "name": "execute_script",
    "arguments": {
      "script": "set output \"demo.gif\"\nset max-width 800\nopen \"Terminal\"\ncapture-window app \"Terminal\" as $t\nresize 800 400\nclear\nrecord $t duration 3 continue\ntype \"echo Hello\" enter\nremain\nrender"
    }
  }
}

Response:

{ "path": "demo.gif", "size_mb": 1.2 }
tip

You can also read an example script first with quikgif://examples/hello to use as a starting point, then modify it for your needs.

Post-Processing Workflow​

Resize and speed up an existing GIF file.

Speed Up and Resize​

{
  "method": "tools/call",
  "params": {
    "name": "process_gif",
    "arguments": {
      "input": "recording.gif",
      "output": "optimized.gif",
      "max_width": 600,
      "speed": 1.5
    }
  }
}

Response:

{ "path": "optimized.gif", "size_mb": 0.8, "dimensions": "600x338", "frames": 120 }

Cut Idle Time​

{
  "method": "tools/call",
  "params": {
    "name": "process_gif",
    "arguments": {
      "input": "recording.gif",
      "output": "trimmed.gif",
      "idle_strategy": "cut",
      "idle_threshold": 1.5
    }
  }
}

Optimize Palette​

{
  "method": "tools/call",
  "params": {
    "name": "process_gif",
    "arguments": {
      "input": "recording.gif",
      "output": "optimized.gif",
      "palette_strategy": "global"
    }
  }
}

Permissions & Troubleshooting​

Common Errors​

ErrorCauseFix
"Screen Recording permission is required"TCC not grantedGrant in System Settings > Privacy & Security > Screen Recording, then restart quikgif
"Window ID N not found"Window closed or wrong IDCall list_windows to get current window IDs
"No window found for app 'X'"App not running or no visible windowCall open_app first
"No active recording with session ID 'X'"Already stopped or wrong IDCheck session_id from start_recording response
"No completed recording with session ID 'X'"Not stopped yet or already renderedCall stop_recording first
"File not found"Script file path doesn't existUse absolute paths or the inline script parameter
"Script execution failed"Runtime error in .qgif scriptUse validate_script first to check syntax

Permission Requirements​

FeatureScreen RecordingAccessibility
list_windowsRequired--
start_recording / record_regionRequired--
type_text / click / key_press----
cursor_smoothing transform--Required
click_indicators transform--Required
keystroke_badges transform--Required
type_smoothing transform--Required
info

Input simulation tools (type_text, click, key_press, move_cursor, scroll) use CGEvent posting, which does not require Accessibility permission. The Accessibility requirement applies only to the recording transforms that capture and process event data.

Checking Permissions Programmatically​

Always call check_permissions before starting a recording workflow:

{
  "method": "tools/call",
  "params": { "name": "check_permissions", "arguments": {} }
}

Or read the live permission resource:

{
  "method": "resources/read",
  "params": { "uri": "quikgif://status/permissions" }
}