Kernel Seeds { News/Updates }

When I rewrote Keychain for its 25th anniversary, I wanted to make it work better in the environments we actually use today. We open several terminals at once. We reconnect to development environments through Visual Studio Code. Some of us work inside WSL, with Linux startup happening underneath a Windows desktop. Getting an ssh-add passphrase prompt into the right terminal has become a more interesting problem.

Keychain 3 added some fairly advanced features to handle this. The last two releases, 3.0.5 and 3.0.6, have been about making those features more robust, and refining their design based on what people actually experienced when using them.

Listening to Gentoo

Feedback from Gentoo raised useful questions about the Python rewrite, distribution packaging, and the new startup behavior.

The single-file Python zipapp is convenient for downloading and installing Keychain directly. But distributions already have infrastructure for installing Python packages, selecting interpreters, and compiling bytecode. They should be able to use it. In 3.0.5, we documented and tested conventional Python installation, cleaned up unused bytecode in the portable zipapp, and added a precompiled build for installations using a specific Python interpreter.

The feedback also brought up a more immediately visible change: why was Keychain now asking people to press Enter?

The idea behind that step is simple. If five terminals start together, I don't want whichever terminal happens to start first to decide where you have to enter your passphrase. Pressing Enter tells Keychain, "I'm over here. Prompt me in this terminal." It's the foundation of Keychain 3's multi-terminal coordination.

While it's technically much more capable, it is a change from Keychain 2, and some users and distribution maintainers felt that the previous behavior should be the default, which can be enabled with --immediate or now set at build time.

But before settling the question of which startup behavior people preferred, we had a more fundamental problem to solve: some users couldn't get past startup at all.

Two Problems That Looked the Same

Real-world reports, including issue #260, exposed several corner cases in multi-terminal coordination, including startup hangs after interrupted key loading. In 3.0.5, we tightened up those behaviors, audited the design, and expanded unit and end-to-end tests to verify recovery with real agents and multiple terminals.

Then came another report: startup was still hanging, but for a different reason. This time, an ssh-add process really was running and waiting for a passphrase in a terminal the user couldn't see. Keychain in the visible terminal was waiting for that request to finish. The explanation lay in how WSL starts user sessions when systemd integration is enabled.

With WSL's systemd integration, distro startup creates a hidden login shell to start user services even before you open a visible terminal. That shell is technically interactive and runs shell startup scripts, potentially including Keychain. With --immediate, it will start a Keychain that immediately starts ssh-add -- prompting you on a terminal that you will never see.

This wasn't a blocker -- Keychain could recover if you typed takeover in your regular WSL terminal, but that still left an extra step between you and your work, and disrupted the standard Keychain ritual a user performs when entering their Linux environment.

A Consistent Login Ritual

It became clear that while the new takeover functionality was technically capable and functioning properly, the user experience was lacking. Why ask users to type takeover just to enter their passphrases, when they have no apparent reason to expect a recovery step? That's an unnecessary complication.

In 3.0.6, significant work has been done to provide that consistent ritual at Keychain startup: whether you use --immediate or the more modern and recommended Enter activation, you can complete passphrase entry in the terminal you are using the same way, every time. There is no special case to recognize and no takeover command to remember.

The feedback also showed that Enter's purpose wasn't clear enough, which encouraged users to try to work around it rather than give it a chance. For someone accustomed to Keychain 2, it could look like an unnecessary step, with --immediate providing a way to bypass it. So now, the prompt has been rewritten to make the purpose explicit:

 ▸ Press Enter to run ssh-add in this terminal

With --immediate, terminals now prompt independently, and redundant requests are canceled once the needed keys are loaded, which is sort of a "Keychain 2 with minimal downsides" behavior. I still recommend the default non-immediate activation because it lets you choose where prompting begins, but if you prefer --immediate, it should give you a robust experience as well.

But there were still other reasons users may want to use --immediate, for reasons that weren't purely technical -- issues I needed to fix.

The Small Details Matter Too

Earlier versions of Keychain had a little boo-boo -- they used a Unicode "key" emoji for the terminal activation prompt that looked fantastic for me but many Linux terminal fonts couldn't display. Many saw an ugly blob instead, providing even more motivation to use --immediate to bypass the multi-terminal coordination prompt.

To address this, the "key" emoji is now gone in 3.0.6. It has been replaced with a small, well-supported animation to bring attention to the need for interaction. You can disable the animation with animate = false under [output] in ~/.keychainrc.

3.0.6 also adds --debug-log FILE to record detailed diagnostics without capturing passphrases or private-key contents.

I appreciate everyone's bug reports and feedback. I have tried to be responsive, and when necessary read between the lines and try to understand the underlying design or technical challenges contributing to the user experience, and address them. The Gentoo feedback, WSL reports, and packaging discussions are necessary to ensure that Keychain 3 does all the little things right, too.

Keychain 3.0.6 is available on GitHub. You can also visit the Keychain project page or report an issue. Please keep the feedback coming.