bobuk.io
← All apps

Ting / Micro-apps

Micro-apps: your own tools behind a key

A micro-app is a small YAML file that Ting runs from a key: it reads the clipboard or what you were working on, asks for a few values, runs shell or Python code, HTTP requests or an AI model, and shows, copies or pastes the result. The easiest way to get one is to ask a coding agent to write it for you.

Ask a coding agent (recommended)

You do not have to learn the format. A coding agent such as Claude Code, Codex or pi reads the format guide shipped inside Ting.app, writes the file, checks it with ting-micro and puts it in place. It can also add the key binding to your config.json.

  1. In the Ting menu-bar menu, choose Copy Agent Prompt (also in Settings › Advanced). It copies a ready text with the paths of your Mac.
  2. Start your agent in a terminal and paste the text.
  3. After the last line, “My task:”, write what you want in plain words: which key, what goes in, what should happen and where the result goes.
  4. Let the agent work. It writes the file in a temporary folder, checks it until ting-micro check reports ok, moves it into ~/.config/ting/micro/, and checks config.json with ting-micro check-config.
  5. Press the key. Ting shows the full file once; Command-Return approves it, Esc refuses.

A request can be as short as this:

Write a new Ting micro-app: Leader t a should translate the
clipboard into German and copy the translation.

Without Copy Agent Prompt, start the agent with this text and add your task:

Change my Ting setup. Read /Applications/Ting.app/Contents/Resources/CONFIGURING.md
and follow it; for micro-apps it points to FORMAT.md. Check every file with
ting-micro before you finish. Never put API keys into files and never touch
~/Library/Application Support/Ting/.

My task:

Tips for good results:

  • Name the key sequence, for example “Leader t a”. The agent asks before it replaces a binding you already have.
  • Say where the result goes: copied to the clipboard, shown in the panel, or both.
  • Never paste an API key into the chat. Keep keys in your shell environment or the keychain (see “Keys and secrets”) and tell the agent their names.
  • Ask it to reuse a library when you want a family of similar tools, such as one translate key per language.
  • The agent should ask you before it tries a micro-app that calls a paid API or changes files.

The full guides the agent follows are CONFIGURING.md (https://github.com/bobuk-io/ting/blob/v0.7.6/docs/CONFIGURING.md) and FORMAT.md (https://github.com/bobuk-io/ting/blob/v0.7.16/docs/micro-apps/FORMAT.md).

Your first micro-app by hand

Save this as ~/.config/ting/micro/sort-lines.yaml. Ting loads the folder at once; there is nothing to restart.

format: ting.microapp/2
id: sort-lines
name: Sort lines
description: Sort the clipboard lines and drop duplicates.

input: clipboard
command: LC_ALL=en_US.UTF-8 sort -u
output:
  to: [clipboard, panel]
  as: text
  1. Open Settings › Bindings, choose + › Micro-app and pick Sort lines, or start it by name from launcha.
  2. Copy a few lines and press the key. The first time, approve the file with Command-Return.
  3. The sorted lines are on the clipboard and in the panel.

If the file has a mistake, Ting does not use it: the menu-bar menu warns, Settings › Advanced lists the problem with its line, and ~/.config/ting/micro-errors.log holds it.

The file

KeyMeaning
formatAlways ting.microapp/2.
id, nameThe id is kebab-case (sort-lines), by default the file name. The name is shown in menus.
descriptionOne line, required.
paramsValues Ting asks for before the run: text or choice. Required ones are always shown; optional ones need a default and sit behind Command-O.
inputclipboard (the text goes to the first step) or none.
contextWhat Ting reads at the start: app, finder, browser, selection, window (see “What you were working on”).
command or stepsOne shell command, or a list of steps (below).
outputto: [clipboard, panel] (or app: pasted into the app you came from) and as: markdown | console | text | code. Without output, nothing is shown or copied.
timeoutSeconds for the whole run: 60 by default, at most 300.
toolsPrograms the code needs on PATH, such as [dig, jq].
hidden, rememberhidden: true keeps it out of launcha; remember: false does not offer the last values.

Parameters reach shell and Python code as environment variables: domain becomes $TING_DOMAIN.

params:
  - name: domain              # read as ${params.domain} or $TING_DOMAIN
    type: text
    required: true
    prompt: Domain
  - name: record
    type: choice
    required: false
    default: A
    choices: [A, AAAA, MX, TXT]

input: none
command: dig +noall +answer "$TING_DOMAIN" "$TING_RECORD"

Steps

Instead of one command, a micro-app can run a list of steps. The output of each step is the input of the next one, like a shell pipe; the output of the last step is the result. A failing step stops the run and the panel shows which step failed and why.

StepDoes
commandShell code for /bin/sh -c: input on stdin, result on stdout.
pythonPython code for python3 (standard library; needs the Xcode Command Line Tools).
urlAn HTTP request: method, query, headers, body (text or JSON) or form. The output is the response body.
aiA message to openai or anthropic, or any OpenAI-compatible server through base_url (Ollama, LM Studio, OpenRouter). The answer streams into the panel.
textText with variables.
jsonA field of the input JSON, such as items.0.name.
openOpens a URL or a file, optionally in a given app.
notifyShows a notification.
callRuns a library (see “Libraries”).
keysPresses keys in the app you came from, such as cmd+t or [cmd+a, return].
pastePastes text into that app and puts the clipboard back.

Every step can have an id (later steps read its output as ${steps.ID}), its own stdin, timeout and params. stream: true lets a command or python step read the output of the step before it while it comes.

This micro-app asks Wikipedia for the clipboard word and shows the summary with its link:

format: ting.microapp/2
name: Wikipedia summary
description: Show the Wikipedia summary of the clipboard word or title.

input: clipboard
steps:
  - url: https://en.wikipedia.org/api/rest_v1/page/summary/${input|trim|url}
    id: page
  - json: extract
    id: extract
  - json: content_urls.desktop.page
    stdin: ${steps.page}
  - text: |
      ${steps.extract}

      ${input}
output:
  to: [panel]
  as: markdown

An AI step and a Python step:

steps:
  - ai: ${input}
    provider: anthropic
    model: claude-haiku-5-5
    key: ${keychain.anthropic}
    system: Answer in one short paragraph.
steps:
  - python: |
      import json, sys
      data = json.load(sys.stdin)
      print(json.dumps(data, indent=2, sort_keys=True, ensure_ascii=False))

Read a lowkey window’s status

Requires a Ting build whose bundled FORMAT.md lists the lowkey step, and lowkey with lowkeyctl in /Applications. Replace notes with your saved alias. This example reports window state without opening a page. To list controls in an already-open window, change status to inspect. Starting with Ting 0.7.16 and lowkey 0.1.2, the second example exports an open demo site to A4 PDF using print styles. It requires the saved origin, never overwrites an existing file, and does not load lazy content or expand virtualized lists.

format: ting.microapp/2
description: Show the state of a saved lowkey window.
input: none
steps:
  - lowkey: notes
    action: status
    as: json
output:
  to: [panel]
  as: code
format: ting.microapp/2
description: Save a demo page as PDF.
input: none
timeout: 60
steps:
  - lowkey: demo
    action: save-pdf
    file: ~/Desktop/demo-page.pdf
    timeout: 60

Ting 0.7.4: choose and ask

Ting 0.7.4 adds these interactive steps. Use the FORMAT.md shipped with your installed Ting to check which steps it supports.

choose shows a filterable list from the previous step: one nonempty line per option, or a JSON array of strings or objects with title, optional subtitle and string value. It passes the chosen value to the next step. Up/Down selects, Return confirms; even one option needs confirmation. An empty list stops the run.

ask requests text at that point in the run. It accepts default (with variables), placeholder, multiline and required. The default is an empty, required, single-line field. Set default: ${input} explicitly to edit the previous output. Return continues; with multiline: true, Return adds a line and Command-Return continues.

Both answers can be read later as ${steps.ID} when the step has an id. Esc cancels the whole run, answers are not remembered, and waiting pauses execution timeouts, including in libraries. These steps require the Ting panel: ting-micro check validates them, but ting-micro run rejects the file before any step runs.

format: ting.microapp/2
description: Choose a question and write notes.
input: none
steps:
  - text: |
      What should change?
      What already works?
  - choose: Choose a question
    id: question
  - ask: Your notes
    placeholder: Enter details
    multiline: true
    required: false
  - text: |
      Question: ${steps.question}
      Notes: ${input}
output:
  to: [panel]

Ting 0.7.6: Clipbawd history

Use ${clipboard[-1]} for the newest entry, ${clipboard[-2]} for the preceding entry and ${clipboard[-3]} for the third newest. Only negative integers are accepted. Use the full ${clipboard[-1]} syntax, not $clipboard[-1].

Starting with Ting 0.7.17, Settings has searchable sidebar navigation. Micro-app errors, the folder, Copy Agent Prompt and Accessibility move to Settings › Micro-apps; the menu command moves to Tools › Copy Agent Prompt. Clipbawd gains opt-in history between launches, with defaults of 100 entries, 50 MiB and 30 days. History snapshots can include videos; video entries fail explicitly in text templates, like images.

An approved run takes a fixed snapshot after its parameter form; copying during the run does not change the indices. Text, links and colors give text; files give newline-separated paths. Images, missing entries, disabled history and headless ting-micro run fail explicitly. Indices count images too, without skipping them. Clipbawd exclusions still apply; the approval panel identifies history access.

Use templates in step fields or env:, never interpolate history into shell or Python code. Quote the shell variable. Filters work too: ${clipboard[-1]|trim|url}.

format: ting.microapp/2
description: Show the preceding clipboard history entry
input: none
steps:
  - command: 'printf "%s" "$CLIP"'
    env:
      CLIP: ${clipboard[-2]}
output:
  to: [panel]

Variables

Every value of a step, except shell and Python code, can hold variables:

VariableValue
${input}The input of the step.
${params.NAME}A parameter.
${steps.ID}The output of an earlier step.
${NAME}A variable of your login shell, such as ${OPENAI_API_KEY}.
${keychain.SERVICE}A password from your login keychain.
${context.SOURCE.FIELD}A value of the context, such as ${context.app.name}.

Filters after |: url (percent-encode), json (escape for a JSON string), trim, base64. For example ${input|trim|url}.

Ting never puts text into shell or Python code. The code reads the same values from the environment: $TING_NAME for parameters, $TING_STEP_ID for step outputs, $TING_CONTEXT_SOURCE_FIELD for the context, and the variables you set with env:. This keeps clipboard text from becoming a command.

What you were working on

Since Ting 0.6.0 a micro-app can read the moment it starts: list the sources in context:, and Ting reads only those, before the parameter panel. Steps read a value as ${context.SOURCE.FIELD}, code as $TING_CONTEXT_SOURCE_FIELD.

SourceValuesPermission
appname, bundle, path, pid of the active appnone
finderselection (one path per line) and folder of the front Finder window, also when Finder is in the backgroundAutomation for Finder
browserurl, title of the front tab and name of the browser: Safari, Chrome, Arc, Brave, Edge, Vivaldi or ChromiumAutomation for the browser
selectiontext: the selected text; where Accessibility gives none, Ting presses Command-C and puts the clipboard backAccessibility
windowtitle and document of the front windowAccessibility

A micro-app can also send input to the app you came from: keys presses keys, paste pastes text, and output with to: [app] pastes the result. This one sorts the selected lines in place:

format: ting.microapp/2
name: Sort selected lines
description: Sort the lines of the selected text and put them in place of the selection.
tools: [sort]

context: [selection]
input: none
steps:
  - command: LC_ALL=en_US.UTF-8 sort
    stdin: ${context.selection.text}
output:
  to: [app]

And this one opens a new browser tab and searches there for the clipboard text:

input: clipboard
steps:
  - keys: cmd+t
  - paste: ${input|trim}
  - keys: return

macOS asks once to let Ting control Finder or the browser; without that, the micro-app does not start and the panel says what to allow. Without Accessibility, Ting opens a window that shows how to turn it on: drag the Ting icon from it into System Settings › Privacy & Security › Accessibility. Settings › Advanced shows whether Ting has it.

Libraries

Steps that several micro-apps share live once in ~/.config/ting/micro/libs/NAME.yaml, with format: ting.microlib/1. A library has no key and is not listed in launcha.

# ~/.config/ting/micro/libs/translate.yaml
format: ting.microlib/1
description: Translate the input text with OpenAI.
params:
  - name: language
    type: text
    required: false
    default: English
input: clipboard
steps:
  - ai: ${input}
    id: translate
    provider: openai
    model: gpt-4.1-mini
    system: Translate the text into ${params.language}. Answer with the translation only.
output:
  to: [clipboard, panel]
  as: text

Inherit a library to make a variant that differs only in values. This file is the library with German fixed, so it asks nothing:

# ~/.config/ting/micro/translate-german.yaml
format: ting.microapp/2
inherit: translate
id: translate-german
name: Translate to German
description: Translate the clipboard text into German.
steps:
  - id: translate
    params:
      language: German

Or run a library as one step with call and pass its parameters:

steps:
  - call: translate
    params:
      language: ${params.language}

A micro-app is approved together with its libraries. When you change a library, Ting asks you again for every micro-app that uses it.

Keys and secrets

Never write an API key into a micro-app file. Ting runs steps with the environment of your login shell, so a key exported in your shell profile works as ${OPENAI_API_KEY} or ${ANTHROPIC_API_KEY}; the ai step uses those two by default. Or keep the key in the keychain:

security add-generic-password -s anthropic -a "$USER" -w

and read it as ${keychain.anthropic}. Do not type secrets into parameters that Ting remembers: remembered values are stored as plain text.

Check and run in the terminal

ting-micro inside Ting.app checks and runs micro-apps without the panels. run reads the input from stdin and prints the result; it never touches the clipboard, your config or the approvals. open and notify steps run only with --allow-effects. It reads no context: give values with --context app.name=Safari. keys and paste steps never send anything there.

MICRO=/Applications/Ting.app/Contents/MacOS/ting-micro
"$MICRO" check sort-lines.yaml
printf 'b\na\nb\n' | "$MICRO" run sort-lines.yaml
"$MICRO" run dns-lookup.yaml --param domain=example.com --verbose
"$MICRO" run sort-selection.yaml --context "selection.text=$(printf 'b\na')"
"$MICRO" check-config

check-config checks config.json: JSON errors, keys used twice, bad URLs and micro-app ids that do not load. A micro-app binding looks like this:

{ "key": "t", "label": "Translate", "items": [
  { "key": "a", "label": "Translate to German", "micro": "translate-german" }
]}

Safety

A micro-app runs as you, with your full rights and no sandbox: it can read and change your files, use the network and start programs. That is why Ting runs a file only after you approve its exact text, and asks again after any change of the file or of a library it uses. Approve only what you understand, and keep ~/.config/ting/ writable only by your account. A micro-app that presses keys or pastes can do in the app in front what you can do with the keyboard: approve it as carefully as code.