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.
- 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.
- Start your agent in a terminal and paste the text.
- 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.
- Let the agent work. It writes the file in a temporary folder, checks it until
ting-micro checkreportsok, moves it into~/.config/ting/micro/, and checksconfig.jsonwithting-micro check-config. - 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- Open Settings › Bindings, choose + › Micro-app and pick Sort lines, or start it by name from launcha.
- Copy a few lines and press the key. The first time, approve the file with Command-Return.
- 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
| Key | Meaning |
|---|---|
format | Always ting.microapp/2. |
id, name | The id is kebab-case (sort-lines), by default the file name. The name is shown in menus. |
description | One line, required. |
params | Values Ting asks for before the run: text or choice. Required ones are always shown; optional ones need a default and sit behind Command-O. |
input | clipboard (the text goes to the first step) or none. |
context | What Ting reads at the start: app, finder, browser, selection, window (see “What you were working on”). |
command or steps | One shell command, or a list of steps (below). |
output | to: [clipboard, panel] (or app: pasted into the app you came from) and as: markdown | console | text | code. Without output, nothing is shown or copied. |
timeout | Seconds for the whole run: 60 by default, at most 300. |
tools | Programs the code needs on PATH, such as [dig, jq]. |
hidden, remember | hidden: 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.
| Step | Does |
|---|---|
command | Shell code for /bin/sh -c: input on stdin, result on stdout. |
python | Python code for python3 (standard library; needs the Xcode Command Line Tools). |
url | An HTTP request: method, query, headers, body (text or JSON) or form. The output is the response body. |
ai | A message to openai or anthropic, or any OpenAI-compatible server through base_url (Ollama, LM Studio, OpenRouter). The answer streams into the panel. |
text | Text with variables. |
json | A field of the input JSON, such as items.0.name. |
open | Opens a URL or a file, optionally in a given app. |
notify | Shows a notification. |
call | Runs a library (see “Libraries”). |
keys | Presses keys in the app you came from, such as cmd+t or [cmd+a, return]. |
paste | Pastes 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: markdownAn 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: codeformat: 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: 60Ting 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:
| Variable | Value |
|---|---|
${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.
| Source | Values | Permission |
|---|---|---|
app | name, bundle, path, pid of the active app | none |
finder | selection (one path per line) and folder of the front Finder window, also when Finder is in the background | Automation for Finder |
browser | url, title of the front tab and name of the browser: Safari, Chrome, Arc, Brave, Edge, Vivaldi or Chromium | Automation for the browser |
selection | text: the selected text; where Accessibility gives none, Ting presses Command-C and puts the clipboard back | Accessibility |
window | title and document of the front window | Accessibility |
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: returnmacOS 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: textInherit 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: GermanOr 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" -wand 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-configcheck-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.