synsh

synsh

The AI-native shell. SynapseOS boots into it. Type a command like any shell — or just say what you want, and it asks synapd.

⚡ AI online — type naturally or use shell commands

If the banner doesn't say AI online, synapd isn't reachable: check systemctl status synapd and that the model is in /var/lib/synapd/models/synapse.gguf.

---

Shell features

Real GNU readline (line editing, history), aliases, built-ins that work outside the REPL, redirection and pipes for built-ins, and command lists — ;, &&, ||.

Several of those are more recent than you'd expect, because they were quietly broken:

• Aliases were never expanded at all until pkgrel 8.
• readline was a phantom dependency — declared but never actually linked, so you got no line editing. Genuinely enabled in pkgrel 7.
• Built-ins didn't work outside the REPL and couldn't redirect or pipe.

---

Colour output

synsh used to emit colour unconditionally: --no-color was dead code, and the escape sequences leaked into pipes, corrupting anything that parsed its output. Fixed in pkgrel 6 (9681fa6).

If you see escape codes in a pipeline, you are running something older than pkgrel 6.

---

⚠️ synsh has two incompatible tokenizers

This is the single most important thing to know before touching the parser. A change to quoting, splitting or expansion must be made in both or you get behaviour that differs between code paths — and the divergence is silent.

---

Terminal setup

Applies to main and the next ISO. On 0.2.4 and earlier, and on any system installed from one, the default terminal is foot — nothing rewrites a user's synuirc on upgrade.

The default terminal is kitty. foot is kept as the rescue terminal and is still installed: it is 793 KiB against kitty's 65 MiB, and it renders on the CPU where kitty needs working OpenGL — which is what you want in a VM on llvmpipe, or when a GPU driver has just broken. It is second in every fallback chain, and systems installed before the switch still have it as their default.

Change it with terminal = <name> in ~/.config/synui/synuirc.

kitty's transparency needs dynamic_background_opacity yes set from its FIRST launch. kitty's own documentation is explicit that the option cannot be enabled by reloading the config, and that a background_opacity change on reload only works if dynamic opacity was already on when kitty started. A kitty.conf shipped without it leaves the transparency slider permanently inert for that install, and writing the setting afterwards does not repair it — kitty has to be restarted.

Both terminals' configs are generated in more than one place (live ISO, installed user, packaged default); if you change one, change them all.

A past failure worth recognising: foot silently refused its own config because [cursor].color had been removed upstream. The symptom was a terminal that came up with default colours and no explanation.

See also: synapd, Troubleshooting.