GTK/VTE TERMINAL · BASH PREFLIGHT · DEBIAN / UBUNTU · V1.2.1

Bash gets a preflight check.

SPLICE checks the line when you press Enter. Valid commands run untouched. An unknown command word is matched locally against your PATH, builtins, aliases, functions, and typo cache — and if there is a fix, SPLICE asks before anything runs. No model call, no network, no login. The terminal absorbs the mistake before Bash can print an error.

INSTALL ON DEBIAN / UBUNTU READ HOW THE TRAP WORKS

Ctrl+Space — ask for one editable command
Ctrl+B — choose exactly what the model sees
no claude CLI — still a full terminal, still local rescue

SPLICE⌁

hank@shop:~/claudecode$ git status

On branch main

nothing to commit, working tree clean

hank@shop:~/claudecode$ sudo ap-get update

⌁ did you mean: sudo apt-get update ? [Y/n] y

Hit:1 http://deb.debian.org/debian trixie InRelease

Get:2 https://git.hankelsner.tech/apt ./ InRelease [1,891 B]

Fetched 1,891 B in 0.4s (4,719 B/s)

Reading package lists... Done

hank@shop:~/claudecode$

cache miss → fuzzy hit · 12 ms · 0 model tokens FIG. 1 — VALID COMMAND PASSES THROUGH · TYPO VETOED BEFORE BASH ERRORS

Model calls are last resort.

Cache, fuzzy match, and typo table run on this machine before SPLICE ever asks Claude.

Commands require approval.

Rescue waits on [Y/n]. Ask results can RUN, TYPE, or DISMISS — the default is TYPE, so you edit first.

AUTO cannot override your context.

Pinned cards stay fixed. AUTO may only manage default and ai selections.

DEBUG TRAP · EXTDEBUG VETO · <300 MS · 0 TOKENS

Typo rescue is local. Bash never sees the error.

A DEBUG trap with extdebug inspects each command the instant you press Enter. Valid commands hit a type -t check and pass through with zero overhead. A miss runs a local pipeline against your real PATH, builtins, aliases, and functions — the corrected line replaces the typo in history and runs on Y (default yes).

−sudo ap-get update → vetoed · “command not found” never prints

+sudo apt-get update → replaces the typo in history · runs on Y

ENTERtype -t valid? → pass through untouched — the trap costs nothing when you type correctly0 ms0 TOK

STAGE 1suggest cache — repeat typos, hits AND misses, keyed by cmdline<1 ms0 TOK

STAGE 2difflib fuzzy vs PATH executables + builtins + your aliases/functions<300 ms0 TOK

STAGE 3curated typo table — gti→git, grpe→grep, pyhton3→python3, sl→ls…<1 ms0 TOK

STAGE 4haiku — only if every local stage misses; the answer is cached so it never re-bills~1 s~40 TOK

WHAT THE TRAP WILL NOT DO

Touch a valid command. type -t hits return immediately — the rescue layer costs nothing when you type correctly.
Run anything unasked. The rescue is a [Y/n] prompt on /dev/tty; n lets Bash do its normal thing.
Guess in prose. The model contract is “ONLY the corrected command, or NONE.” One line or nothing.
Bill twice. Negative results are cached too — a command SPLICE can’t fix never costs a second call.

WRAPPER-AWARE

Leading VAR=val assignments and wrappers — sudo, env, nohup, time, watch… — are skipped, so the real command word gets corrected, not the prefix.

CTRL+SPACE · CMD / CHAT · INSERT, NOT EXECUTE

Ask for a shell line. Edit before Enter.

The ask bar drops from the header. CMD mode answers a task with exactly one shell command — the prompt contract is “ONLY the shell command, no backticks, no prose” — shown in a result row for your decision. CHAT mode answers questions with your selected context attached, concise, no preamble.

SPLICE⌁ ⌁ASK CTX ~880 tok

⌁ which package owns the vte widget this terminal uses CMD CHAT

⌁ dpkg -S /usr/lib/*/libvte-2.91.so.* RUN TYPE DISMISS

READY · ASK_MODEL: DEFAULT · CTX ~880t ATTACHED

hank@shop:~/claudecode$

FIG. 2 — Ctrl+Space TOGGLES THE BAR · THE RESULT ROW IS A PROPOSAL, TYPE IS THE DEFAULT

THREE EXITS, ALL YOURS

TYPE — drops the command at your prompt without a newline, so you edit flags before committing. The default Enter action.
RUN — feeds the command to the shell with Enter. One click, executed, on your explicit choice.
DISMISS — discards it. Nothing entered the terminal.

WHY IT ANSWERS WELL

CMD asks ship with the context blob you selected in the sidebar — your machine, your projects, your conventions — capped at the token budget. So “redeploy the site” comes back as your rsync line, not a generic guess.

All model work runs in threads; the terminal never blocks. A status line reports what the engine is doing, in the interface’s voice: READY, THINKING…, claude CLI not found — install/login first.

CTRL+B · CONTEXTS · SET_BY: DEFAULT / AI / USER

You choose the context. AUTO cannot uncheck a pin.

The sidebar lists every context SPLICE discovered — Claude memory cards, project MEMORY.md files, workspace docs — each with a live token estimate. Only checked contexts are sent. AUTO lets the AI pick a relevant set for your cwd (it sends titles only — never bodies), but a box you set by hand is locked against it.

SPLICE⌁ ⌁ASK CTX ~880 tok

hank@shop:~/claudecode$ splice-ctx auto --cwd applications/splice-terminal

auto: model picked 3 of 24 contexts (titles only sent)

enabled applications/splice-terminal/MEMORY.md (by ai)

enabled claudecode/PLAYBOOK.md (by ai)

⌁ respecting user override: memory/user-hank-nti.md

hank@shop:~/claudecode$

CONTEXTS AUTO RESCAN

memory/user-hank-nti.md~180t · user PIN

splice-terminal/MEMORY.md~460t · ai

claudecode/PLAYBOOK.md~240t · ai

applications/trading/MEMORY.md~310t · default

applications/ledger/MEMORY.md~150t · default

applications/asbuilt/MEMORY.md~200t · default

3 ENABLED · ~880t OF 6,000 CAP · COST VISIBLE BEFORE SEND

FIG. 3 — Ctrl+B TOGGLES THE SIDEBAR · THE PINNED CARD SURVIVES AUTO

THE OVERRIDE RULE — WHO MAY FLIP A CHECKBOX
STATE	MEANING	AI MAY FLIP IT?
set_by: default	discovered by `scan`, untouched	yes
set_by: ai	`AUTO` picked it for this cwd	yes
set_by: user	you set it by hand — pinned	never — prints `respecting user override`
release	un-pins a card without changing its checkbox	back to AI-manageable

WHAT GETS DISCOVERED

Memory cards from your Claude memory directory.
Project cards — every applications/*/MEMORY.md, plus workspace docs like CLAUDE.md.
Anything else — splice-ctx add <path> pins an arbitrary file.

Estimates are chars/4, shown per card and totaled in the header chip — the cost of an ask is visible before you send it.

LEDGER · COST CONTROLS · LOCAL FIRST, TOKENS LAST

Every token accounted for.

An AI terminal that bills you for typing would be a bad tool. SPLICE treats tokens like any other metered utility and shows you the meter.

MEASURE	MECHANISM	COST
Local-first rescue	cache → difflib fuzzy → curated typo table; a model only when all three miss	0 TOK
Negative cache	misses are cached too — a repeat miss never re-bills	0 TOK
Model tiering	`fix_model: haiku` for cheap corrections; `ask_model` of your choice for real asks	TIERED
Input cap	context blob trimmed to `max_context_tokens` (6,000), per-card estimates visible in the sidebar	BOUNDED
Output contract	prompts demand “ONLY the command” / “be concise, no preamble” — no essay tax	TERSE
AUTO sends titles	context auto-pick sends the id + title list, never file bodies	1 CHEAP CALL

V1.3.0 · IN BUILD · SPEC LOCKED 2026-07-05

v1.3 is built against measured pain.

The spec did not start from a feature wishlist. It started from Stack Exchange view counts, GitHub issue-title counts, and disaster postmortems — then kept only what a terminal can fix locally, deterministically, for zero tokens. The numbers below are the actual research inputs.

THE EVIDENCE — WHAT PEOPLE ACTUALLY SUFFER, AND WHAT SHIPS FOR IT
MEASURED SIGNAL	SIZE	WHAT V1.3 SHIPS
Error classes fixable by local rules — archives, `cp -r`, permissions, ports, disk-full, apt locks, “command not found”	~70M viewsStack Exchange clusters	Rescue Engine v2 + Doctors — exit-code-aware strip with the one-line fix, or an expandable diagnosis card
“How do I exit Vim?” — the most famous UX failure in terminal history	3.3M views · 5,546 votesStack Overflow · >1M devs	Editor lifeline — a dismissible overlay strip when vim traps you; zero bytes injected into the pty
`thefuck`, a purely local typo fixer — proof users prefer instant local fixes over an LLM call	96.5k starsGitHub	category validation — SPLICE’s hot path stays 100% local and extends to exit-code errors
Session loss and broken resume — the single biggest measured friction in claude-code	5,943 + 1,307 titles'session' + 'resume' issues	Durable tabs — cwd, scrollback tail, AI conversation, and pinned cards survive a crash
Permission-prompt fatigue → blind approval → the Dec-2025 `rm -rf ~/` incident	2,245 titles · 93% blind-approve'permission' issues	AI Command Sentry — read-only inserts green, mutating amber, destructive never one-key
Token and cost anxiety, surprise drains	711 titles'usage limit' issues	Token ledger — live session meter, pre-send estimates, a “saved by local” counter

SPLICE⌁

hank@shop:~/downloads$ tar -xvf project-src.tar.gz

gzip: stdin: not in gzip format

tar: Child returned status 1

tar: Error is not recoverable: exiting now

hank@shop:~/downloads$ tar -xzvf project-src.tar.gz

project-src/

project-src/Makefile

project-src/src/main.c

hank@shop:~/downloads$ sudo rm -rf $STAGING/*

⌁ GUARD — blocked before execution0 TOKENS

$STAGING is unset — this line expands to: sudo rm -rf /*

protected path / — hard veto; the raw text is not what you were about to run

e edit line Esc abort — nothing runs until you choose

aborted — nothing was run.

hank@shop:~/downloads$

⌁ try: tar -xzvf project-src.tar.gz — .gz needs -z Tab insert · Space explain · A ask AI · Esc dismiss 0 TOKENS

guard veto — deterministic, shell-side, pre-exec FIG. 4 — V1.3 RESCUE STRIP (EXIT-CODE MATCH) + GUARD (EXPANDED-COMMAND VETO)

THE V1.3 RELEASE SHAPE — NINE FEATURES, ZERO TOKENS ON THE HOT PATH
#	FEATURE	TOKENS
F1	Rescue Engine v2 — exit-code-aware strip; ~40 launch rules tested against the literal Stack Exchange error text	0
F2	Doctors — permission, port, disk, apt-lock, apt-locate: `stat`-level diagnosis, minimal fix, never 777, never “delete the lock file”	0
F3	Guardrails — pre-exec veto for rm/dd/mkfs/chmod -R/curl\|bash/pkill classes, computed on the expanded command	0
F4	AI Command Sentry — every AI-suggested command classified before insertion; destructive is never one-key	0 added
F5	Ask-about-this — `Ctrl`+`Shift`+`A` attaches the last command + output; no copy-paste, estimate before send	EXPLICIT ASK
F6	Explain-before-run — `Ctrl`+`Shift`+`E` breaks the line down per token from local man pages	0 LOCAL
F7	Durable tabs — session persistence and one-key restore, with AI-conversation rehydrate on demand	0
F8	Editor lifeline — the exit-vim overlay; pure GTK chrome, tmux/vim untouched	0
F9	Token ledger — live meter, per-ask breakdown, daily budget with no hard lockout	0

THE GUARD RULES ARE BINDING

Never auto-execute. AI output’s ceiling is insertion into the prompt line; your Enter is the only trigger.
Approve the expanded command. Confirmations show what actually runs after variable and glob expansion — the raw text is not what you’re approving.
Approve consequences, not syntax. Every destructive confirm carries a locally computed effect statement: N files, sizes, devices, reversible or not.
Destructive classes are never one-key. rm -rf, dd, mkfs, curl|bash, git push -f — no allowlist applies, doubly so when AI-suggested.
The guard is deterministic, not a model. Pure pattern + stat logic that file or web content cannot talk its way past.
Prefer reversible. Trash before rm, TERM before -9, backup before truncate, typed device names for raw writes.
Two independent gates. Sentry chip at insertion time AND the DEBUG-trap guard at Enter time; neither trusts the other ran.
Everything works with AI off. Eight of nine features need no claude CLI at all.

APT · SIGNED REPO · GIT.HANKELSNER.TECH

Install from the apt repo.

Three commands on any Debian or Ubuntu box. The repo is signed; the keyring lands in /usr/share/keyrings. Installing registers the launcher icon, so SPLICE shows up in your Activities grid — and every future release arrives with a plain sudo apt upgrade.

1 TRUST THE SIGNING KEY

$ curl -fsSL https://git.hankelsner.tech/apt/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/hankelsner.gpg

2 ADD THE SOURCE

$ echo 'deb [signed-by=/usr/share/keyrings/hankelsner.gpg] https://git.hankelsner.tech/apt ./' | sudo tee /etc/apt/sources.list.d/hankelsner.list

3 INSTALL

$ sudo apt update && sudo apt install splice-terminal

✓ VERIFY

$ apt-cache policy splice-terminal

Done. Launch SPLICE from the Activities grid or run splice. Updates: sudo apt upgrade — same as everything else on your system.

ALTERNATIVE — DIRECT .DEB

Grab the latest package from git.hankelsner.tech/releases and install it directly (no repo, no automatic updates):

$ sudo apt install ./splice-terminal_1.2.1_all.deb

REQUIREMENTS

Debian 12+/Ubuntu 22.04+ · python3 (≥3.10), python3-gi, gir1.2-gtk-3.0, gir1.2-vte-2.91, bash ≥5 — apt pulls them all in. Wayland and X11 both work.

AI features use your local claude CLI and its login. No claude CLI? The terminal, the local typo rescue, and (in v1.3) the rescue strip, doctors, and guardrails all work in full.

REFERENCE · KEYS · CLIS · DEGRADED MODE

Reference.

KEYBINDINGS — 1.3 = SHIPS IN V1.3.0
KEYS	ACTION
`Ctrl`+`Space`	toggle the ask bar (CMD / CHAT)
`Ctrl`+`B`	toggle the context sidebar
`Ctrl`+`Shift`+`A` 1.3	ask about this — opens the ask bar with the last command + output attached (visible chip, token estimate, one-click removable)
`Ctrl`+`Shift`+`E` 1.3	explain the command in the prompt line, token by token, from local man pages
rescue strip: `Tab` / `Space` / `A` / `Esc` 1.3	insert the fix at the prompt / expand the diagnosis card / ask AI with the failure attached / dismiss
`Ctrl`+`+` / `Ctrl`+`−`	font size up / down
`Ctrl`+`Shift`+`T` / `W`	new tab (label follows your cwd) / close tab
`Ctrl`+`Shift`+`C` / `V`	copy / paste

DEGRADED MODE

Without the claude CLI installed and logged in, SPLICE is still a complete terminal: tabs, scrollback, OSC7 cwd tab labels, the local typo rescue — and in v1.3 the rescue strip, doctors, guardrails, explain, durable tabs, and the editor lifeline — all work at full strength. The ask bar states it plainly — claude CLI not found — install/login first — and stays out of your way.

SPLICE-AI — THE ENGINE CLI
COMMAND	DOES
suggest "<cmdline>"	corrected full cmdline on stdout, or rc 1 — the rescue pipeline, scriptable
ask "<english>"	one shell command for a task, context attached
chat "<question>"	concise answer, no preamble, context attached
explain "<cmdline>"	one-paragraph explanation of a command
rescue 1.3	failed command + stderr in → ONLY the corrected command + one-line why; haiku tier, cached
classify 1.3	command on stdin → JSON verdict: read-only / mutating / destructive (the sentry’s gate)

SPLICE-CTX — THE CONTEXT CLI
COMMAND	DOES
scan	discover memory cards + project MEMORY.md files; pins survive rescans
list [--json]	every card: checkbox, ~tokens, set_by, title
enable / disable --by user\|ai	flip cards — `--by ai` bounces off user pins
release <id>	un-pin without changing the checkbox
add <path>	register any file as a pinned context
blob [--max-tokens N]	print the exact blob an ask would send, trimmed to budget
auto [--cwd DIR]	one cheap call picks relevant cards — titles only