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, 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.

  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.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
  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.
command or stepsOne shell command, or a list of steps (below).
outputto: [clipboard, panel] 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”).

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))

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.

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: 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.

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-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.