Add "external script" paste method

[piec]

Thanks for making Handy, I've only discovered a few days ago and it's awesome.
A few months ago I searched for something like this but couldn't find anything.

Before Submitting This PR

Please confirm you have done the following:

• I have searched existing issues and pull requests (including closed ones) to ensure this isn't a duplicate
• I have read CONTRIBUTING.md

Human Written Description

Adds a new paste method that uses an external script.
That gives me the flexibility to post process the text as I want without adding complexity to Handy.
Examples:

• when the focused window/tab is a chat I don't want capitals, or a final dot
• depending on the language typography rules are not the same (space before "?")

Related Issues/Discussions

I'm noticing these after making the PR oops :)
But they complement each other:

• feat: add text replacements feature #455
• Transcript post-processing #168

Testing

I have tested it for a few days on an Arch Linux / xorg / i3 setup.
I think it should work on windows / macos too but cannot test on these platforms.

Simple external script example

#!/usr/bin/env python
import sys
import os
import subprocess

if len(sys.argv) <= 1:
        os.exit(1)

text = sys.argv[1]

# subprocess.run(['notify-send', '--', text])

# Make first character lowercase
if text:
    text = text[0].lower() + text[1:]

# Remove trailing period (but keep other punctuation)
if text.endswith('.'):
    text = text[:-1]

# French convention: add space before "?" and "!"
import re
text = re.sub(r'(?<! )([?!])', r' \1', text)

subprocess.run(['xdotool', 'type', '--', text], check=True)

I also have a more complex script where I change the behavior depending on the focused windows. With `xdotool getactivewindow getwindowname`.

Screenshots/Videos (if applicable)

AI Assistance

• No AI was used in this PR
• AI was used (please describe below)

If AI was used:

• Tools used: Claude code
• How extensively: Claude did the initial boilerplate for settings layout, which I simplified aferwards.

[cjpais]

Can we make this a Linux only thing?

[piec]

Yes, but wouldn't it be useful to macos too?
Windows users probably aren't used to do stuff like this.

[cjpais]

I would rather keep options fairly slim where possible. For me everything works more or less perfect on MacOS. It's my primary machine and I have very few if any issues

[piec]

@cjpais done
I only hid it in the UI, if in any case someone wants force it using the conf file

[gabenasci]

Imo it would be nice to still be able to select one of the pre-existing paste methods but also run the script as well (for other use-cases other than just custom paste, like a custom post-transcription script that will run x y z commands). Lots of scripting possibilities here regardless of platform.

If the user were to use this script to handle only pasting, they could set the paste method to none + add their script that will run after transcription with their own custom pasting method.

Maybe this could be hidden inside "experimental features" instead? Just a thought!

[piec]

Hi @gabenasci, maybe we need 2 things:

• This PR: an "external script" paste method which can let users insert text with a custom tool. The intended usage is to insert text not to process text.
• Another PR: an "external script" for post-processing, handy runs it, captures the command output and carries on with other post processing and pasting.

[cjpais]

@piec if you want this, could you rebase, I'll merge it as an option for Linux users

[piec]

OK, will do :)

[piec]

Hi @cjpais, rebased I also added the translations I knew but there are missing ones.

[piec]

Related to this previous comment #638 (comment)

Are you interested by a PR for processing recognized text in an external command?

[cjpais]

@piec not at the moment, I'm mostly interested in PR's which are contributing to fixing the stability issues of the app. I will be putting a pause on most new features coming in.

[suuuehgi]

@cjpais Either this is not working on my computer or or I don't get how it's supposed to be used.

I created a small test script /tmp/test.sh

#!/bin/bash
while IFS= read -r line; do
  echo "$line" >> /tmp/test.log
done

and set the paste method to the external script but no /tmp/test.log appears.

[cjpais]

@piec please take a look, I am unable to test this

[piec]

Hi @suuuehgi, is the script executable? chmod +x ...

Edit: Hmm also actually the text is passed as $1, not to stdin
It might have been better to pass it as process stdin to avoid cmdline max size, it's really huge these days though

[suuuehgi]

Edit: Hmm also actually the text is passed as $1, not to stdin

That was it. I just assumed it to read from stdin as there's no documentation about this feature whatsoever.

Regarding stdin / $1 off the top of my head, I don't have any preferences on this.

Arbitrarily long strings should use stdin but at the same time we're speaking about life transcriptions. That's probably a couple of sentences at max.
I think there's a hard limit of 128 KiB for arguments by the kernel but thats quite a bit of plaintext.

[piec]

The only documentation so far is the python example in a collapsible section in the text of the PR at the top of the page 🙂

[suuuehgi]

in a collapsible section

Well hidden. 😅 I always overlooked that when skimming through it.

[AlexanderYastrebov]

Hi, I think this is a useful feature (for macos users as well).

Adds a new paste method that uses an external script.
That gives me the flexibility to post process the text as I want without adding complexity to Handy.

The original need seems to be about processing the transcription rather that pasting it differently. Therefore I think this feature might be evolved/improved in the following way:

1. pass transcription to the script using stdin - this is a standard unix practice
2. in case exit code is 0, read script stdout and if its not empty - paste using selected method. This way script may preprocess transcription without bothering about paste method as well as use custom paste method by returning empty stdout. AI post processing or what not could be done by such a script as well.

[cjpais]

I agree, but if you are advanced enough you can use it on macOS by editing the settings file. This is not a setting for average users and it shouldn't be in the UI

[piec]

Hi I also thought making an additional PR to modify the code in order use stdin instead of the arg

[AlexanderYastrebov]

Therefore I think this feature might be evolved/improved

I've created #930

[piec]

Hello @AlexanderYastrebov, I also did something like this but a bit differently, I will share it on my fork :)