Custom Actions

Create your own actions by adding .yaml files to ~/.vibe-action/actions/. Any subdirectory works — the engine loads all files recursively.

Hello World

name: hello
about: Say hello
actions:
  - tag: tag_hello
    run: value
    expect: string
    action: Hello, World!

Shell Command

name: disk
about: Show disk usage
actions:
  - tag: tag_disk
    run: cmd
    expect: string
    action: df -h /

With Arguments

name: greet
about: Greet someone
args:
  - name: name
    short: n
    input: string
    help: Name to greet
    default: World
actions:
  - tag: tag_greeting
    run: value
    expect: string
    action: Hello, {name}!

Using System Tags

System tags provide context from your environment. See System Tags for the full list.

actions:
  - tag: tag_info
    run: value
    expect: string
    action: |
      User: {system_user}
      OS: {system_os}
      PWD: {system_dir_pwd}
      Date: {system_date}

LLM Call

args:
  - name: query
    short: q
    input: string
actions:
  - tag: tag_answer
    run: small
    expect: string
    action: |
      Explain this concept in simple terms:
      {query}

Vision Call

args:
  - name: image
    short: f
    input: string
    default: '{system_clipboard_image}'
actions:
  - tag: tag_description
    run: vision
    expect: string
    action: |
      {image|load|text}

      Describe this image in detail.

Fetch Web or PDF

args:
  - name: source
    short: s
    input: string
actions:
  - tag: tag_description
    run: small
    expect: string
    action: |
      Summarize this document:
      {source|load|text}

Scan Codebase

name: my-scan
about: Scan project codebase as JSON
args:
  - name: path
    short: p
    input: string
    default: .
actions:
  - tag: tag_validate
    run: cmd
    expect: string
    action:
      - when: '{path|is_dir}'
        then: echo "{path}"
      - when: '{path|is_dir:not}'
        then: echo "'{path}' is not a directory" && exit 1
  - tag: tag_resolve
    run: value
    expect: string
    action: '{tag_validate|resolve}'
  - tag: tag_ast
    run: value
    expect: list
    action: '{tag_resolve|scan|ast:brief}'
  - tag: tag_json
    run: value
    expect: string
    action: '{tag_ast|format:json}'

IDE Integration (VS Code / IntelliJ)

Define how IDE plugins should handle your action using the api block. This example replaces the selected text with its uppercase version:

name: upper
about: Convert text to UPPERCASE
api:
  output: replace # replace | clipboard | dialog
  args:
    text: selection # automatically pass selected text to 'text' arg
args:
  - name: text
    short: t
    input: string
    default: '{system_clipboard}'
actions:
  - tag: tag_upper
    run: value
    expect: string
    action: '{text|upper}'

Clipboard

Use the clipboard modifier to copy values at any pipeline step:

- tag: tag_copy
  run: value
  expect: string
  action: '{tag_data|format:json|clipboard}'

Conditional Actions (When/Then)

actions:
  - tag: tag_changed
    run: cmd
    expect: list
    action: git diff --name-only

  - tag: tag_commit
    run: cmd
    expect: string
    action:
      - when: '{tag_changed|empty:not}'
        then: git add . && git commit -m "auto: updates"
      - when: '{tag_changed|empty}'
        then: echo "Nothing to commit."

Multi-Step Pipeline

actions:
  - tag: tag_content
    run: cmd
    expect: string
    action: cat {file}

  - tag: tag_summary
    run: small
    expect: string
    action: |
      Summarize this file in 2-3 sentences:
      {tag_content}

Tips

• Tag naming: use tag_ prefix for consistency with built-in actions
• Dependencies: the engine sorts steps by {tag} references, not YAML order
• Validation: add check: ".+" to ensure non-empty output
• Debugging: set VIBE_LOG_TYPE=tracing VIBE_TRACE_LEVEL=debug to see each step’s input and output
• Clipboard: use {tag|clipboard} to copy any value to clipboard mid-pipeline
• Images: use {image|load|text} for vision flows — works with files, URLs, and clipboard
• System tags: see System Tags for all available environment variables
• Notifications: add notify: true to show desktop notification on completion