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, asks for a few values, runs shell or Python code, HTTP requests or an AI model, and shows or copies 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.5.0/docs/CONFIGURING.md) and FORMAT.md (https://github.com/bobuk-io/ting/blob/v0.5.0/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. |
command or steps | One shell command, or a list of steps (below). |
output | to: [clipboard, panel] 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”). |
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))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. |
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, and the variables you set with env:. This keeps clipboard text from becoming a command.
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.
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" 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.