1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# garble
8
9[](https://api.reuse.software/info/git.secluded.site/garble)
10[](https://liberapay.com/Amolith/)
11
12Transform stdin with an LLM. Pipe text in, get transformed text out.
13
14## tl;dr
15
16Mostly made to simplify [Voxtype's post-processing step](https://github.com/peteonrails/voxtype/blob/main/docs/USER_MANUAL.md#post-processing-with-llms), so I've only tried it with voice transcriptions. Happy to accept patches tuning the fairly minimal current prompts.
17
18```bash
19# Fix typos and grammar
20echo "teh quikc brown fox" | garble --directions "fix typos"
21
22# Translate
23cat letter.txt | garble --directions "translate to Pirate"
24
25# Reformat
26pbpaste | garble --directions "convert to markdown table" | pbcopy
27```
28
29## Installation
30
31```bash
32# Clone and install to ~/.local/bin
33git clone https://git.secluded.site/garble
34cd garble
35make install
36
37# Or install elsewhere
38make install PREFIX=/usr/local
39```
40
41Requires Erlang/OTP and the Gleam toolchain.
42
43## Usage
44
45```bash
46garble [--provider PROVIDER] [--model MODEL] [--directions "..."]
47```
48
49All flags are optional if configured in `~/.config/garble/config.toml`.
50
51### Flags
52
53| Flag | Description | Example values |
54| -------------- | ------------------------------------------- | ------------------------------------------- |
55| `--provider` | Provider ID | `openai`, `anthropic`, `google` |
56| `--model` | Model ID | `gpt-4o`, `claude-3-opus`, `gemini-1.5-pro` |
57| `--directions` | Instructions for how to transform the input | `"fix grammar and spelling"` |
58
59Valid provider and model IDs are listed at https://catwalk-fe.secluded.site (an unofficial frontend for Charm's [Catwalk](https://github.com/charmbracelet/catwalk) service).
60
61### Configuration
62
63Create `~/.config/garble/config.toml`:
64
65```toml
66provider = "anthropic"
67model = "claude-sonnet-4-20250514"
68directions = "fix grammar and spelling"
69
70# API key options (in order of precedence):
71# 1. Run a command to get the key
72api_key_cmd = "op read 'op://Private/Anthropic/credential'"
73
74# 2. Or set it directly (not recommended)
75# api_key = "sk-..."
76```
77
78If neither `api_key_cmd` nor `api_key` is set, garble falls back to the
79provider's environment variable (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`).
80
81CLI flags override config file values.
82
83Here's my config.
84
85```toml
86provider = "synthetic"
87model = "hf:deepseek-ai/DeepSeek-V3.2"
88directions = """
89Correct the transcription to match how I would actually type, after edits and corrections.
90
91- Follow inline dictation instructions, example follows in the section below
92- Remove filler words like "um", "uh", "like", "you know", "so" (when meaningless)
93- Correct words from the transcription engine when the context makes obvious what the word should be, example follows in the section below
94- Remove false starts and repeated words
95- Preserve my intended meaning without rephrasing or "improving" my words
96- No markdown, no formatting, just clean plain text
97
98<dictation_interpretation_example>
99<in>
100This is. An example of speaks, an audio compression codec. Specifically tuned for reproducing. Specifically tuned for the reproduction of the human voice. No, human speech.
101</in>
102<out>
103This is an example of SPEEX, an audio compression codec specifically tuned for the reproduction of human speech.
104</out>
105</dictation_interpretation_example>
106"""
107```
108
109## Contributions
110
111Patch requests are in [amolith/llm-projects] on [pr.pico.sh]. You don't
112need a new account to contribute, you don't need to fork this repo, you
113don't need to fiddle with `git send-email`, you don't need to faff with
114your email client to get `git request-pull` working...
115
116You just need:
117
118- Git
119- SSH
120- An SSH key
121
122```sh
123# Clone this repo, make your changes, and commit them
124# Create a new patch request with
125git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/llm-projects
126# After potential feedback, submit a revision to an existing patch request with
127git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
128# List patch requests
129ssh pr.pico.sh pr ls amolith/llm-projects
130```
131
132See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
133complete example workflow.
134
135[amolith/llm-projects]: https://pr.pico.sh/r/amolith/llm-projects
136[pr.pico.sh]: https://pr.pico.sh
137
138---
139
140Some other tools if this one interested you
141
142- [formatted-commit](https://git.secluded.site/formatted-commit) - CLI that turns LLM input into well-formatted Conventional Commits
143- [agent-skills](https://git.secluded.site/agent-skills) - collection of Agent Skills for extending LLM capabilities
144
145## License
146
147AGPL-3.0-or-later