| name | commit-gpg-tmux |
| description | Runs GPG-signed git commits inside a tmux session so the user can attach and enter their passphrase. Use when committing in a no-TTY environment, when GPG fails with "signing failed: No such file or directory" or "not a tty", or when the user asks to commit with GPG, use tmux for signing, or send-keys. |
Commit GPG Tmux
Runs the commit in a tmux session so the user gets a real TTY for the GPG passphrase. The agent sends the commit via tmux send-keys; the user attaches, enters the passphrase, and detaches.
Quick Start
- Ensure pre-commit passes on staged files (if the repo uses it).
- Create or reuse a tmux session; send
export GPG_TTY=$(tty) then git commit -m "..." with tmux send-keys.
- Tell the user to run
tmux attach -t <session>, enter passphrase, then Ctrl-b d.
- Verify with
tmux capture-pane -pt <session> and/or git log -1.
When to Use
- User wants to commit with GPG signing and the current shell has no TTY (e.g. agent, CI).
git commit fails with gpg: signing failed: No such file or directory or not a tty.- User says "commit with GPG", "use tmux for signing", or "send-keys" for the commit.
Instructions
Prerequisites
If the repo uses pre-commit: run pre-commit run on staged files and fix any failures before sending the commit to tmux. Avoid mixed staged/unstaged changes on the same files so pre-commit stash restore does not conflict.
Workflow
Task progress:
Create session (if needed):
Check for existing session: tmux list-sessions. If compose-gpg (or your session name) is listed, skip creation and send keys to it.
tmux new-session -d -s compose-gpg 'cd /path/to/repo && exec $SHELL'
Use a stable session name (e.g. compose-gpg).
Send commit: set GPG_TTY then run git commit in the same pane. C-m is Enter.
tmux send-keys -t compose-gpg 'export GPG_TTY=$(tty)' C-m \
'git commit -m "type(scope): short description"' C-m
With a body:
tmux send-keys -t compose-gpg 'export GPG_TTY=$(tty)' C-m \
'git commit -m "type(scope): short description" -m "Optional body."' C-m
User: tmux attach -t compose-gpg → enter passphrase → Ctrl-b d.
Verify:
tmux capture-pane -pt compose-gpg
git log -1 --oneline
git show --name-only -1 --oneline
Use tmux capture-pane to read the pane (errors or success) without the user pasting.
Examples
Example 1: Single commit with conventional message
Repo at /path/to/repo; staged: .gitignore, AGENTS.md, README.md, .python-version, pyproject.toml, uv.lock; .vscode/settings.json deleted.
tmux new-session -d -s compose-gpg 'cd /path/to/repo && exec $SHELL'
tmux send-keys -t compose-gpg 'export GPG_TTY=$(tty)' C-m \
'git commit -m "chore(root): add python tooling and commit conventions" -m "Track python version and tooling (pyproject/uv.lock), tighten .gitignore, document Conventional Commits in AGENTS.md, remove obsolete VS Code settings."' C-m
User: tmux attach -t compose-gpg → passphrase → Ctrl-b d. Agent: git log -1 --oneline.
Example 2: Read pane after commit (success or failure)
To see why the commit failed or to confirm the user approved:
tmux capture-pane -pt compose-gpg
Summary
| Step | Who | Action |
|---|
| 1 | Agent | Pre-commit passes; create session if needed: tmux new-session -d -s <name> 'cd <repo> && exec $SHELL' |
| 2 | Agent | tmux send-keys -t <name> 'export GPG_TTY=$(tty)' C-m 'git commit -m "..."' C-m |
| 3 | User | tmux attach -t <name>, enter passphrase, Ctrl-b d |
| 4 | Agent | tmux capture-pane -pt <name> and/or git log -1 |
Additional Resources
- Session already exists, multiple commits, session naming, skipping GPG: see reference.md.
