ttypedesk-apps

Catalog of installable apps for TTYPE Desk's App Store. Point the App Store at this repo (it's the default source) or fork it to run your own.

Format

The App Store fetches index.json from the repo root over plain HTTPS (raw.githubusercontent.com) — no auth, no git required on the client.

{
  "apps": [
    {
      "id": "unique-id",
      "name": "Display Name",
      "description": "One line shown in the store.",
      "icon": "🌐",
      "detect": {
        "which": "binary-name",
        "paths": ["~/.local/bin/binary-name"]
      },
      "install": { "script": "apps/your-app/install.sh" },
      "register": [
        {
          "id": "stable-program-id",
          "name": "Start Menu label",
          "command": "shell command to run",
          "icon": "🌐",
          "menu": "programs",
          "set_role": "filemgr"
        }
      ]
    }
  ]
}

• detect — how the store checks whether the app is already installed. which runs a PATH lookup; paths checks literal file paths (~ expanded). Either or both can be set; any match counts as installed.
• install.script — a path within this repo to a shell script. The store downloads it, saves it to a temp file, and runs it in a normal terminal window (not sandboxed, not silent) — your script can freely use sudo; since it's a real interactive terminal, the user will just be prompted for their password in that window like any other terminal command. Print progress with echo as you go — it's shown live.
• register — one or more launchers to add to Start ▸ Programs once detect reports success after an install. id should be a stable, unique string you won't change later — the store matches on it to update the entry in place on repeat installs instead of duplicating it. If your chosen name collides with some other program already on the user's system, the store suffixes it (Name-store, Name-store-2, …) rather than overwriting it.
• register[].set_role (optional) — e.g. "filemgr". Points the desktop's corresponding default (Start menu entry, desktop icons, "open this folder") at this program instead of the built-in one — a real swap, not just an extra Programs entry. Valid values: filemgr, editor, browser, terminal, image.
• register[].command is always a plain command name/line — no launch- action prefix syntax (pty:, etc). By default it runs as $SHELL -c "<command>" in a normal terminal window, unless one of the two flags below is set (at most one should be):
  • register[].bridge: true — launches command through TTYPE Desk's GUI-TUI Bridge instead: a real X11 app, half-block rendered as a window like everything else. Use this when your app is an X11 GUI program (none of this catalog's current entries need it — browsh is already terminal-native, not an X11 app — but it's there for one that does).
  • register[].ext_app: true — launches command as an out-of-process App SDK binary (NDJSON over stdio) instead. Use this when your app is itself a TTYPE Desk app built to run standalone, not an arbitrary CLI tool — see the matrixchat entry for a real example, including its apps/matrixchat/install.sh.

Adding your own repo as a source

In ~/.config/ttypedesk/config.json, add to app_sources:

"app_sources": [
  { "repo": "RetroCodeRamen/ttypedesk-apps", "branch": "main" },
  { "repo": "yourname/your-catalog", "branch": "main" }
]

Any public GitHub repo with an index.json at its root in this format works.

Versioning

MAJOR.MINOR.YYMMNN — e.g. 0.1.260706. MAJOR.MINOR lives in VERSION, bumped by hand; YYMMNN is computed by scripts/version.sh (year, month, and a count of commits so far this calendar month).

Every commit gets tagged automatically via a post-commit hook, once set up (one-time per clone):

git config core.hooksPath .githooks