Repository navigation
Releases
Keyfit 0.1.1
Fixes from a review of 0.1.0. After upgrading, run keyfit setup once to rewrite your shims.
Removed
keyfit add linear --readonly. It was recorded in the registry, but nothing read it: no MCP server Keyfit
sets up uses Linear's read-only endpoint, and the docs never offered it. Areadonly = truealready in the
registry is ignored.
Fixed
- The AWS check skips Superset's agent wrappers too. It ran the first
awson PATH after
Keyfit's shims, so anawsin~/.superset/binwould have answered it; like every other check,
it now runs the first one after Superset's wrappers as well, as the security page says. - A tool started in a folder that no longer exists (a removed worktree) says so and doesn't start, instead
ofinternal error (FileNotFoundError …), or a Python traceback when.ornode_modules/.binis on
PATH.KEYFIT_DISABLE=1still starts it. - AWS: an SSO or
aws logincache time without a zone is read as UTC instead of ending ininternal error (TypeError …). Sections written[profile acme]or[profile "acme"](andsso-sessionsections
written that way) are found, as the AWS CLI reads them, instead of "no profile 'acme'".$VARIABLESin
AWS_CONFIG_FILEandAWS_SHARED_CREDENTIALS_FILEare expanded, as the AWS CLI does, andkeyfit add awskeeps the expanded file. - A relative
CLOUDSDK_CONFIGno longer crasheskeyfit add google,keyfit add gcloud,keyfit add firebaseandkeyfit init; it is taken from the current folder, as gcloud does. - With Claude Code older than 2.1.268, whose
claude auth status --jsondoesn't name its config folder,
every check failed ("Claude used config directory None"). The organisation alone decides then. - A shim whose Python is gone (for example, Homebrew removed the Python that pipx's Keyfit ran on) says so and
names the fix,pipx reinstall keyfit(orbrew reinstall keyfit), thenkeyfit setup, instead of only
keyfit setup, which can't run either.KEYFIT_DISABLE=1now runs the tool when Keyfit can't start, too. Run
keyfit setuponce to rewrite your shims. - Setup edge cases.
keyfit setup --rcon a startup file that isn't UTF-8, on a folder or with aZDOTDIR
that doesn't exist printed a traceback after writing the shims; it now keeps every byte of such a file, or says
which line to add by hand.--removesaid "No Keyfit line" in a file that isn't UTF-8 and deleted the PATH file
that line loads, so every new zsh printed an error; it now takes the line out. A commented-out Keyfit line no
longer counts as active.--remove --purgewith~/.config/keyfita symbolic link stops before changing
anything instead of half-way. An unwritable config folder is said in one line instead of a traceback. - Ctrl-C during online checks (
keyfit status, the end ofkeyfit init) stops at once with exit status 130,
instead of waiting for the slowest check (up to 40 seconds) and then printing a traceback. - Hand edits.
roots = ["."]is refused: a relative root made every folder the project. A number or a date
where Keyfit writes text (config_dir = 5,token = 5,login = 5) fails that account's check, and stops its
sign-in commands, instead of an internal error. A check cache of another shape ([],null) counts as empty
instead of stopping every tool until it was deleted. - The tests no longer depend on the Mac that runs them. They never read your home folder, git
identity, Keychain or the tokens of a Keyfit session they run in, and their guard against the
network now covers the requests Keyfit actually makes. Their fake tools run on the Python that
runs the tests, so a Mac without the Command Line Tools runs them too. New tests cover
keyfit run, every online check's request, and paths that had none.
Security
- The firebase CLI Keyfit runs to renew a sign-in and at
Sign in now?is looked for innode_modules/.bin
no higher than the repository's top (outside a repository, the nearestpackage.json) or your home
folder. For a project outside your home folder the search went up to/, so a
node_modules/.bin/firebaseanother local user created in/private/tmpor/Users/Sharedcould run. - The project's own wrangler, which Keyfit runs for its Cloudflare check,
keyfit add cloudflare,Sign in now?andBind this folder now?, is looked for the same way: for a project outside your home folder the
search fornode_modules/.bin/wranglerwent up to/too. - Only a Google API key goes to Google.
keyfit add gemini --keysent any printable value to the
Gemini API and stored it, so a typo such as--key env:GITHUB_TOKENshipped a GitHub token to Google.
Now only a value shaped like a Google API key (AIza…) is sent, there and in the Gemini check. - A key typed where a name belongs is never repeated. argparse echoed it (
keyfit add linear lin_api_…without--key:unrecognized arguments: lin_api_…), and so did the messages about
--profile,--login,--emailand--workspace. It is now shown as<a key, not shown>, and those
options refuse a key before anything runs. - A key written into the registry by hand (
linear = "lin_api_…") is named, not shown, in
keyfit status,keyfit which -vand every failed start. - AWS errors show account IDs as their last four digits. The error Keyfit passes on from
aws sts get-caller-identity(an AccessDenied with an ARN, say) showed them in full. vercel --api URLis refused inside a project: every request carries the login's token. Vercel's
own API may still be named.- Control characters can't lock the registry or drive the terminal. Written as they were, a control character
in a project name, or in an AWS profile imported from a repository's.envrconkeyfit init, made
registry.tomlunreadable, so everykeyfitcommand and all thirteen tools stopped, in every folder. The registry
now escapes them, project names refuse them and.envrcprofiles with them are not imported. Supabase
organization names,.firebasercproject IDs, Google Workspace server names and the emails in their login files,
and the Claude status line show them escaped. - Folder names can't run commands through the generated shell code. The shims, the PATH files and the
startup-file line put paths in double quotes, so a$, backtick or quote in the install or config folder's name
made every tool exit 127, and a backtick ran its command at every launch. Such paths are now single-quoted;
others are written as before. Runkeyfit setuponce to rewrite them.
Keyfit 0.1.0
First published version. macOS only; Python 3.11 or newer, no other dependencies.
The Changed, Fixed and Security entries record what changed during development and three pre-launch
reviews, before anything was published.
Added
-
Shims for
claude,codex,aws,ghandvercel.keyfit setupwrites them and a small shell
file that puts them on PATH in new terminals (right after Superset's agent wrapper when it is
there, so its hooks keep working). You keep typing the commands as usual. -
zsh and bash.
keyfit setupwrites a PATH file for each;keyfit setup --rcadds the
line to~/.zshrc, or for bash to the login profile (and~/.bashrcwhen the profile sources
it).--shell zsh|bashoverrides$SHELL,--rc PATHpicks another file,--zshrc PATH
still works. On other systems than macOS,keyfit setupsays so and stops. -
Install with pip, pipx or Homebrew. Keyfit is a self-contained package (
pip install keyfit, a Homebrew formula for a tap); the shims and the Claude status line run the
installed package with the Python that rankeyfit setup.keyfit --versionprints the
version. -
claude-swap and codex-multi-auth on the first setup. In a terminal, the first
keyfit setup
asks whether to install each of these login switchers whose agent is installed and which isn't
yet (uv tool install claude-swaporpipx install claude-swap;npm install -g codex-multi-auth). Enter skips; running setup again asks nothing. -
Guided first run. In a terminal,
keyfit initregisters the repository, then offers what
it finds on this Mac one at a time: an AWS profile from~/.aws/config(orAWS_CONFIG_FILE),
a GitHub accountghis signed in to, the current Claude, Codex and Vercel logins, and a Linear key
(hidden input, stored in the Keychain). Enter skips; anything already set is left alone; it
ends withkeyfit status.--yes, or no terminal, registers without asking. -
keyfit setup --removeundoes setup: it deletes the shims and both PATH files and takes
Keyfit's line out of~/.zshrc,~/.bash_profile,~/.bash_login,~/.profileand
~/.bashrc(or only--rc PATH), leaving every other line as it was. The registry stays;
--purgealso deletes~/.config/keyfit, with the Claude and Vercel login folders Keyfit made, after
asking (--yesto skip the question).
Keychain items are never deleted. -
keyfit doctorchecks the installation with a ✔/✘ line each and the fix under every ✘:
macOS, Python, the shims, their place on PATH (before every real tool, right after Superset's
wrapper), the realclaude,codex,aws,ghandvercel, the registry, the Keychain and the
current folder's project. It never reads a secret. -
Projects recognised by folder.
keyfit initregisters a repository. Every subfolder and
every git worktree of it, wherever it lives on disk (Superset's included), belongs to that
project, and so do worktrees of repositories nested inside a project folder.keyfit which
tells you which project a folder belongs to and why;keyfit projectslists them all. In a
folder that is not registered, every tool runs exactly as before. -
Verified accounts per project. Before a tool starts, Keyfit hands it only the project's
accounts, removes conflicting credentials inherited from your shell, and checks each account.
When one is wrong or expired, the tool does not start and you see the command that fixes it.- AWS: a named profile and the account it must resolve to (
keyfit add aws, or imported
from ause awsline in.envrconkeyfit init); a profile found throughAWS_CONFIG_FILE
keeps that file.aws --profile <another project's profile>is refused inside a project. - Linear: one API key per project, read from an environment variable or the macOS Keychain,
checked against the expected workspace (keyfit add linear). - GitHub: the project's account from
gh's stored logins, checked against the expected login;
a different git author email or SSH host shows as a warning (keyfit add github). - Claude Code: the project's login, checked to be a claude.ai subscription in the expected
organisation, never down to one login (keyfit add claude,--newfor another account). - Codex: the project's ChatGPT login, never down to one account (
keyfit add codex). - Vercel: the project's login (the CLI's global config folder) and team, checked with Vercel's API
against the expected username and team membership (keyfit add vercel,--newfor another
login).vercelgets the folder (--global-config) and the team (--scope); inside a project,
--scopeor--global-configof another team or folder and--tokenare refused, and so is a
repository linked (.vercel/project.json,.vercel/repo.json) to another team. Inherited
VERCEL_ORG_ID,VERCEL_PROJECT_ID,VERCEL_TEAM_IDandVERCEL_TOKENare removed.
- AWS: a named profile and the account it must resolve to (
-
Sign-in always works.
aws sso login,claude auth login,codex login,gh auth …and
vercel login(alsologout,switch,whoami,teams) run even when a check fails, with the
project's environment (and forvercel, the project's login folder), so they fix the right account. -
MCP servers per project. In a project, Claude and Codex see only that project's Linear
server and never a server another project owns. Your servers keep their names. -
keyfit add mcp NAME…marks MCP servers (names or patterns such as'globex_cloud_*') as
belonging to the current project; every other project stops seeing them. -
Status line. Claude Code sessions started through Keyfit show the project and its
accounts, unless you configured a status line of your own. -
keyfit statuschecks every connection of the current project (--offlinefor local
checks only). -
Fast, forgiving checks. Successful remote checks are cached for 30 minutes. A network
blip is retried once, then a success from the last 24 hours is accepted with a warning; a
wrong account never is. -
Switches.
KEYFIT_DRY_RUN=1 <tool>shows what would run and which environment variables
would change (names only, never values).KEYFIT_DISABLE=1 <tool>skips Keyfit once.
Removing the shell line turns Keyfit off. -
Keys stored for you.
keyfit add linearwithout--keyasks for the key with hidden
input (or reads one line from stdin in scripts), checks it with Linear, then stores it in the
macOS Keychain.keyfit secret set NAMEstores any key the same way and prints its
keychain:keyfit/NAMEreference;keyfit secret listshows the names. Values never appear
in output or process arguments. -
The registry (
~/.config/keyfit/registry.toml) stores where secrets live, never their values. -
Documentation. A README for first-time users,
docs/security.md(everything Keyfit
reads, stores and sends, and its limits) anddocs/troubleshooting.md. -
Gmail, Drive and Calendar MCP servers on the project's Google account.
keyfit add google-mcp --server NAMEgives a project a Google Workspace MCP server that runs on the Mac with a login of its
own, signed in as the project's Google account (the work or the personal email ofkeyfit add google); servers of one Google account are shared by its projects ([accounts.google-mcp.NAME]).
Four servers are known by the package they run, with where each keeps its login: Google Workspace MCP
(workspace-mcp, a folder of<email>.json), Gmail AutoAuth (@gongrzhe/server-gmail-autoauth-mcp),
Google Calendar MCP (@cocal/google-calendar-mcp) and Google Drive MCP
(@piotr-agier/google-drive-mcp); any other server works with--login PATH. The login path comes
from the server's own definition (env) in the five agents' configs, else the server's default.
Before an agent starts, every definition of the server (yours and the folder's, in every agent) must
read that login, and every account in it must be the project's Google account (by the email it names:
the file's name,cached_email,emailor anid_token). Google must name that account too
(tokeninfo, Gmail's profile or the primary calendar), asked with the saved token while it is valid,
else with one renewed the way the server does: the login's refresh token and the server's own OAuth
client (from the Workspace server's login,GMAIL_OAUTH_PATHor~/.gmail-mcp/gcp-oauth.keys.json,
GOOGLE_OAUTH_CREDENTIALS,GOOGLE_DRIVE_OAUTH_CREDENTIALSor the Drive server's config folder) go
to Google's token endpoint, pinned, and the fresh token answers once and is dropped; nothing is
written to the login. This is the one place Keyfit uses a refresh token, so Gmail AutoAuth, whose
login names no account, is confirmed at every check, hours after its sign-in; a signed-out or revoked
sign-in fails with the server's own sign-in as the fix. Without a refresh token or OAuth client the
local check decides, and a login that names no account is a warning,account not confirmed, at
every agent start; a server not signed in yet is a warning too. Another account blocks the start,
with a fix that gives the server a login of its own (Keyfit never removes the other one). The servers
join the project's MCP ownership: every other project's sessions don't see them, in all five agents,
and a project with Google Workspace servers doesn't see any other Gmail, Drive or Calendar server
(Google's own remote servers included;keyfit add mcpstill gives one to a project). Sessions start
without inheritedGMAIL_CREDENTIALS_PATH,WORKSPACE_MCP_CREDENTIALS_DIR,
GOOGLE_MCP_CREDENTIALS_DIR,GOOGLE_CALENDAR_MCP_TOKEN_PATH,GOOGLE_DRIVE_MCP_TOKEN_PATHand
USER_GOOGLE_EMAIL, so each server reads the login Keyfit checked.keyfit initoffers the servers
signed in as the project's account;doctorshows each server, its login and the account it names.
cl...