holdfast MCP server
Commit Nov 11, 2026Provides AI agents with persistent, PTY-backed shell sessions that allow human observation and takeover via a terminal.
Also known as Sertelegger/holdfast
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 11, 2026
- License
- MIT
What is holdfast MCP?
holdfast provides AI agents with persistent, PTY-backed shell sessions that allow human observation and takeover via a terminal.
Summary generated from the project's README
About holdfast MCP server
Providing AI agents with persistent, PTY-backed shell sessions that humans can monitor or take over is what holdfast enables. It allows developers to maintain long-lived terminal environments that survive even if the MCP client or a tool like Claude Code restarts. On Linux, macOS, and WSL, the server runs as a background daemon to manage these sessions, while Windows users run it in-process via stdio.
Users interact with the server through twelve specialized tools, including start_session, send_input, and read_output. The system prioritizes security by stripping ANSI sequences and redacting secrets by default, ensuring sensitive data like passwords does not reach the agent. Humans can use the attach command to turn their own terminal into an interactive session with full color and TUI support, or use the watch command for a redacted, read-only view. This setup is ideal for developers who need to supervise autonomous agent actions or intervene manually when a process requires human input.
What you can do with it
- 1Human takeover of agent sessionsA developer can use the attach command to jump into a live shell being used by an AI to provide manual input.
- 2Secure password handlingAn agent can request a password from a human without the agent ever seeing the actual secret value.
- 3Monitoring full-screen terminal applicationsDevelopers can track the visual state of complex terminal interfaces like text editors or installers.
- 4Resilient agent workflowsLong-running shell tasks continue to execute even if the developer restarts their AI client.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
CLAUDE_CONFIG_DIR
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesertelegger/holdfast is public and reachablegithub.com/sertelegger/holdfast ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/sertelegger/holdfast ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubHOLDFAST — Human-Observable Long-lived Daemon For Agent Shell Terminals
An MCP server that gives AI agents persistent, PTY-backed shell sessions.
The Human-Observable in that name is a shipped property from 0.0.6:
holdfast attach and holdfast watch let a human look at — and take
over — a live session from any terminal. The web UI is still to come; see
ROADMAP.md.
Status:
v0.0.8is the newest tag — early development. Its release is a draft that has not been promoted, so no release serves a binary and the plugin cannot download one yet (see below). Twelve tools, hybrid mode on Linux/macOS/WSL. Sessions live in a background daemon and survive the MCP client, so a Claude Code restart no longer takes them with it. On Windows there is no daemon:holdfast mcpserves stdio in-process and sessions end with it — see the platform-support table below for what is verified there. Output is ANSI-stripped and secret-redacted by default. Not yet suitable for real use; see ROADMAP.md for what is and is not there.
What works today (on main)
This list describes main, which is ahead of the newest tag; CHANGELOG.md's
[Unreleased] section says by how much. It used to carry the tag's version in
this heading while describing main, which is a claim about v0.0.7 that
v0.0.7 does not keep.
start_session— spawn a shell or program on a real PTYsend_input— type into itrequest_secret_input— ask for a password without ever holding one. The value is typed by an attached human or resolved by a configured provider and goes straight to the PTY; the agent gets back a status and a byte count, never the secret. That is true of the tool's result, not of the session's output: if the program prints the value, or a shell's line editor draws it because it arrived while the shell sat at its prompt, only the pattern rules stand between it and the agent (G3 in SECURITY.md)read_output— read what it printed, using a cursor you carry between calls; escape sequences stripped and secrets replaced with[REDACTED:<kind>]markers by defaultwait_for_pattern— block until the session stops executing, or until a regex matches new output, instead of polling;send_input(wait_for:)does the same after a write. The pattern is optional, and for "has the command finished?" you want it omitted: a regex for the shell's prompt is a guess about the operator's$PS1, and against a customised one it never matches, so the call reports a timeout for a command that finished long ago. Supply a pattern for a program's prompt —Password:,(gdb),>>>— which is text no detector knows aboutterminate— stop it, killing the whole process groupstatus— what one session is doing right nowlist_sessions— every session this server knows about, live or exitedget_command_history— per-command exit codes and output spans, for integrated shellsget_screen_state— read the rendered terminal grid of a full-screen program, withdiff_fromfor incremental updates. VT100 emulation is adaptive: it is off for ordinary line-oriented sessions and turns on only when something needs the rendered screenresize— change a session's terminal dimensions. The child getsSIGWINCH, and the tracked grid reflows so the rendered screen is not still clipped at the old widthinterrupt— send Ctrl+C to the foreground process group, stopping the command that is running without killing the shell hosting itholdfast daemon start|stop|status|run— manage the background daemonholdfast list/holdfast logs <session> [--tail N] [--raw]— inspect sessions from any terminalholdfast attach <session> [--allow-echo] [--keep-size]— your terminal becomes the session. Full colour, full TUIs, full keyboard. Detach with Ctrl-B then d; the session keeps running. That works at a password prompt too, and Ctrl+C there abandons the prompt rather than answering it.--allow-echosubmits secrets even to a program that has not turned terminal echo off — see the password note below for what that costs.--keep-sizenever sends your terminal's size, so attaching from a smaller pane, such as a tmux split beside the agent, does not shrink the session for everyone else; long lines wrap in your view instead.holdfast watch <session>— the same view, read-only and redacted. Detach with Ctrl+C.
Multiple clients can attach at once: output goes to all of them, and input from
any of them reaches the PTY. One terminal hosts one interactive client per
session, though — a second holdfast attach from a terminal that already has
one is refused with terminal_busy, because two processes reading one keyboard
are handed alternate keystrokes by the kernel and neither reliably sees a
detach. Attach from another window instead. The session's size is the smallest
attached writer's, so another client's window can narrow what a program sees,
unless that client attached with --keep-size, which makes no claim on it.
When a program asks for a password, every attached
client is told and any of them can answer — without the value ever reaching the
agent, provided the program turned terminal echo off, as sudo, ssh and
gpg do. If it did not, the terminal echoes what it is given straight into the
session's output, where the agent reads it; so Holdfast refuses that write and
tells you why rather than delivering it. holdfast attach --allow-echo sends it
anyway, for the programs that ask for a code or an API key without ever clearing
echo — the value is still masked on your own terminal, and it will still appear
in the session's output. Echo off is not proof of a password prompt, though: a
shell's line editor turns echo off too and draws what it is given. So Holdfast
also refuses a secret while the session's shell sits at its own prompt, which
it knows from the shell's OSC 133 markers, and --allow-echo does not change
that. A REPL, or a shell without those markers, still passes the echo test at
its prompt and would draw, run and record the value (G3 in SECURITY.md). A
daemon started from 0.0.7 and still running after an upgrade has neither
check: against one, holdfast attach says so under the prompt, and the MCP
server refuses request_secret_input until the daemon is restarted.
request_secret_input, the tool an agent calls to ask for that
password, ships in 0.0.7 and is one of the twelve above.
Sessions outlive the MCP client: holdfast mcp auto-spawns a daemon on
first use and reconnects to it afterwards. holdfast mcp --no-daemon runs
everything in-process instead.
Sessions report what the program is doing, not a guess:
interaction_mode:AtPrompt|Executing|AwaitingSecret|Fullscreen|Exiteddetection_tier:semantic(OSC 133) |terminal_mode(bracketed paste / alternate screen / termiosECHO) |heuristic(output quiescence × the stronger of prompt patterns and cursor position)
detection_tier is there so an agent can tell a measurement from a
guess. Every tool also ships an outputSchema, so a client can validate
what it gets back.
Full-screen programs
VT100 emulation is adaptive, and off is the ordinary case: a
line-oriented bash session reports screen_tracking: "off" from start
to exit and pays nothing for a screen nobody is rendering. It turns on
when the child does something that only makes sense against a rendered
screen — the alternate screen buffer, cursor addressing — and
get_screen_state then answers with the grid, the cursor, alt_screen
and the window title. Pass diff_from: <screen_revision> and the reply
is the escape sequence that turns the screen you last saw into the
current one, instead of the whole grid again.
Tracking is also where the heuristic tier gets its third signal: where the cursor is sitting relative to a prompt character on the rendered line. The cursor term is 0 whenever tracking is off, so it can only add recall, never take it away.
Holdfast answers exactly one terminal query — Primary Device Attributes,
replying \x1b[?6c with no optional parameter, so it claims no
capability it does not have. A PTY master is not a terminal, so a shell
that waits on a query stalls until its own timeout: measured, fish
takes 10.04 s to reach its first prompt with no reply and 0.02 s with
this one answered. The reply is rate-limited, is never recorded as a
send_input, and deliberately does not count as session activity —
otherwise a child querying in a loop would be immortal. Pass
terminal_queries: false to start_session to write nothing at all
into the child and accept the stall.
Shell integration
When the session command is bash, zsh or fish, Holdfast types a
one-line OSC 133 snippet into the session as it spawns, so the shell marks
its own prompt, command and exit-code boundaries and detection runs at the
semantic tier. The terminal holds the line until the shell first reads
input, which is normally at its first prompt, after your rc files have run.
The snippet wraps whatever PS1 the shell ended up with instead of
replacing it, does nothing when your configuration already emits OSC 133,
and is not exported. It is typed once, into the shell the session starts:
a shell started inside the session, or with exec, gets no markers unless
its own configuration emits them, so detection there falls back to the
lower tiers and a secret is not refused at its prompt (G3 in SECURITY.md).
Pass shell_integration: false to start_session to skip it.
It is typed into the session, never installed: there is nothing to add
to an rc file, and crates/holdfast-core/src/detect/shell.rs holds the only
copy of each snippet. bash's snippet is longer than macOS lets a line typed
at start-up be, and zsh's nearly as long, so for both Holdfast types a short
line that runs the snippet from HOLDFAST_BASH_INTEGRATION or
HOLDFAST_ZSH_INTEGRATION, which the session starts with and that line
unsets. Anything else — dash, sh, a REPL, a plain
program — degrades silently to terminal_mode or heuristic, with no
configuration and no error.
Anything an rc file reads from the terminal at start-up reads that line
instead. A read in .bashrc or .zshrc, zsh's new-user menu in a home
with no .zshrc, or oh-my-zsh's update question [Y/n] takes the line, or
its first characters, as its answer, and the session can start without
integration and degrade the same way. Measured with a read in the rc
file, bash and zsh both started at terminal_mode with no command history.
Switch such a question off for the shells Holdfast starts; oh-my-zsh's is
zstyle ':omz:update' mode auto (or disabled).
Output is ANSI-stripped and secret-redacted by default: secrets are
replaced with [REDACTED:<kind>] markers, and read_output with
redact: false returns the raw bytes and is recorded in the audit log.
status and list_sessions redact command, args and
prompt.last_line on the way out, and every string written to the audit
log goes through the redactor first — so a session's own trail cannot
carry the secret whose disclosure it is recording.
The rendered screen is held to the same rule, and is masked rather
than truncated: while the redactor is withholding bytes that may turn
out to be the start of a secret, the cells those bytes would have
written read [REDACTED:unresolved] and the response carries
held_back: true. The exemption that lets a tail read see those bytes
is licensed by read_output's own tail_lines / tail_bytes argument
— a per-call opt-in get_screen_state does not have, and neither does
holdfast logs --tail, which asks for the tail inside the holdback.
Shell history
A session's shell writes nothing to the history files under $HOME (GH
#252), however the session ends: exit, EOF, terminate, holdfast daemon stop or a daemon crash. Every session starts with
HISTFILE=/dev/null, an empty fish_history and a zsh HISTORY_IGNORE
matching the line Holdfast types. The integration snippet, which begins with a
space, sets HISTFILE=/dev/null again in bash and zsh after your rc files
have run, and zsh's SAVEHIST=0, so zsh does not try to lock and save
/dev/null as it exits. fish is started with an init command (-C) that
keeps its history in memory whatever config.fish sets or erases, and keeps
any fish started inside the session from saving one. tcsh and csh are
never hung up, because a hung-up tcsh saves its history; they wait out
terminate's grace instead.
The REPLs and database clients that keep history files of their own start
with them switched off: PYTHON_HISTORY, NODE_REPL_HISTORY,
TS_NODE_HISTORY, PSQL_HISTORY, MYSQL_HISTFILE, MARIADB_HISTFILE and
SQLITE_HISTORY, plus SHELL_SESSIONS_DISABLE=1 for macOS Terminal's
per-window zsh history, which has not been measured on a Mac. A call's own
env overrides any of these, HISTFILE included. A non-empty
fish_history in it starts fish without the init command, so a
config.fish that sets fish_history overrides the call's value too.
Except:
- a shell that sets
HISTFILEitself after the snippet has run: re-sourcing an rc that hard-sets it,exec bashor a nested bash under such an rc, any nested zsh under an unconditional one (macOS's/etc/zshrcsets one for every zsh), aPROMPT_COMMANDthat assigns it, or areadonly HISTFILEthe snippet cannot change; - mksh under an rc that sets
HISTFILE; - tcsh and csh on
exit, EOF or a daemon crash, which save~/.historywhen an rc setssavehist; - a fish started inside a bash or zsh session, or through a wrapper such
as
env fish, whose config.fish setsfish_history; - a zsh
HISTORY_IGNOREof your own, which lets the line Holdfast types — not the agent's commands — into a history file your rc names; - as root, a zsh started inside a session or by
exec zsh, under an rc that setsSAVEHISTand unsetsappend_historywithout settingHISTFILE: it replaces/dev/nullwith a file of its commands; - a login bash in macOS Terminal, whose per-window history under
~/.bash_sessions/only a~/.bash_sessions_disablefile turns off; - a history recorder your rc installs as a hook — atuin, zsh-histdb, mcfly or a bash-preexec logger — which records every command in a store of its own;
- an rc that reads the terminal at start-up, which takes the integration line (see Shell integration above), so a zsh whose rc names a history file saves to it;
- Python 3.12 and older, which ignore
PYTHON_HISTORYand write~/.python_history, a.psqlrcthat setsHISTFILE, and any other program with a history file of its own, PowerShell's PSReadLine among them.
Reading is covered only in zsh. bash and zsh load the history file your
rc names as they start, and in zsh the snippet then cuts that list, so the
agent cannot list your history with fc -l or recall it with up-arrow.
It leaves the list whole under a zsh rc that turns off append_history,
inc_append_history and share_history, where a later save would rewrite
your file from the cut list, and under a readonly HISTFILE. bash keeps
the list your rc loaded, and the agent can list and recall it: emptied, it
is what a bash rc that runs history -w, sourced again, would write over
your file (SECURITY.md's H1 and H10). A bash or zsh started inside the
session loads its rc's file again, and the session runs as you, so cat ~/.bash_history works either way. Nothing is cut with
shell_integration: false, under an rc that takes the integration line,
or in a zsh that HOLDFAST_ZSH_INTEGRATION does not reach, such as one an
rc re-execs through env -i. A fish started inside a fish session reads
the file its config.fish names.
If your rc's PROMPT_COMMAND re-reads the history file at every prompt
(history -a; history -c; history -r), HISTFILE=/dev/null also empties
the session's in-memory history: up-arrow and !! recall nothing. On bash
4.3 and older, macOS's /bin/bash among them, an rc that syncs with
history -n; history -w; history -c; history -r and is sourced again in
the session rewrites your history file without its oldest entry, or
without any entry when source was the session's first command
(SECURITY.md's H1).
To keep a record of what an agent ran instead, set
[terminal]
shell_history_file = "per_session"
Each bash and zsh session then gets
~/.holdfast/logs/history/<session_id>.history
($HOLDFAST_RUNTIME_DIR/logs/history/ for an explicit instance): 0600
files in a 0700 directory, kept after their sessions end and never
rotated or deleted by Holdfast. bash appends each command as it finishes
and zsh as it is entered, so a forced terminate still leaves the record,
and the snippet lifts bash's HISTFILESIZE and zsh's SAVEHIST so neither
trims it. The files hold what the shell saw, unredacted. Any other session
is pointed at the same path and gets a file only if a shell it starts
saves one; fish sessions get none.
It is a convenience record, not an audit trail. A call's own env can
point HISTFILE somewhere else, your rc's history options still apply —
Debian's HISTCONTROL=ignoreboth drops commands that begin with a space,
and without it each bash file begins with the line Holdfast typed, and holds
your own history too if your rc runs history -w — an rc sourced again
that sets HISTFILESIZE, or one that makes it
readonly, truncates the file when bash exits, and anything in the list
above that re-points HISTFILE takes the rest of the session's commands
with it.
With shell_integration: false only the environment applies: an rc file
that sets HISTFILE itself decides where bash and zsh save history — and
macOS's /etc/zshrc sets one for every zsh — and a per-session file is
written only when the shell saves its history on its own, at exit or on a
hangup. fish's init command is applied either way.
Build and try it
From a checkout, which is the only way in today — the paragraph after the lifecycle notes says why:
cargo install --locked --path crates/holdfast # -> ~/.cargo/bin/holdfast
./scripts/mcp-smoke.sh "$HOME/.cargo/bin/holdfast" # raw JSON-RPC smoke test (needs jq)
claude mcp add --scope user holdfast -- "$HOME/.cargo/bin/holdfast" mcp
claude mcp list # holdfast: ... ✔ Connected
Install it; do not register target/. This section used to register
target/debug/holdfast. That works, and the debug build is not slow, but it
ties every Claude Code session on the machine to your build directory:
cargo clean breaks them all at once, and every rebuild swaps the binary out
from under a daemon that is still running the old one. cargo install --path
copies the binary out of target/, so neither happens and an upgrade is a
step you take on purpose. The holdfast CLI below needs ~/.cargo/bin on your
PATH.
The daemon outlives Claude Code, and it runs the binary it was started
from. The first MCP call starts a background holdfast daemon. It owns the
sessions, every Claude Code session on the machine shares it, and closing
Claude Code does not stop it. So a rebuild changes nothing until the daemon
restarts:
cargo install --locked --path crates/holdfast
holdfast daemon stop # ends every session it holds
(cd ~ && holdfast daemon start) # from ~, not from this checkout
daemon stop is the only way to put new code into the daemon, and it ends
every live session, so choose the moment. Start the new one yourself, and
from ~. Each half answers a defect, and costs nothing on a build that has
the fix. Without GH #231's fix, a Claude Code session whose holdfast mcp is
already running does not start a daemon when its daemon goes away: its tools
answer daemon_unreachable until one exists, and then reconnect (measured).
Without GH #229's fix, a session started with no cwd begins in the daemon's
working directory, with the daemon's environment — and cargo install --path
runs in this checkout, so a daemon started from the same shell would point
every such session, in every project, at the Holdfast repository. Those
holdfast mcp processes are still the old binary until each Claude Code
session restarts. A different protocol minor between them and the daemon is
allowed for every call that means the same to both. A call that does not is
refused, with a message saying which side to restart; start_session above
all, which would start in the daemon's directory. A different major is refused
outright. holdfast daemon status shows what is running, and says on stderr
when the daemon is older than the CLI.
One registration per Claude Code config directory. claude mcp add --scope user writes to the config directory in effect — ~/.claude.json, or
.claude.json inside $CLAUDE_CONFIG_DIR — so a machine with several (one
per account, say) needs the line once for each:
CLAUDE_CONFIG_DIR=/path/to/that/config claude mcp add --scope user holdfast -- "$HOME/.cargo/bin/holdfast" mcp
They all share the one daemon. And register it one way, not two: the
plugin below and claude mcp add are two servers exposing the same tools
under two names.
Why a checkout. cargo install holdfast resolves the 0.0.0 name
reservation on crates.io and errors with "there is nothing to install", and
the shipped GitHub Releases carry no binary assets. (cargo install --locked --git https://github.com/Sertelegger/holdfast holdfast builds main without
a checkout, and --tag vX.Y.Z builds a release.) Publishing either is this
project's first external distribution — a decision it has not taken, and
one that changes what several in-tree escapes are allowed to do (see
CONTRIBUTING.md).
When it is taken, releases are the channel and crates.io the source-build
fallback beside it.
holdfast MCP questions
Can a human interact with the agent's shell session?
Yes, humans can use 'holdfast attach' to take over a live session or 'holdfast watch' for a redacted read-only view.
Do sessions end if the MCP client restarts?
No, sessions live in a background daemon and survive the MCP client, meaning a restart like Claude Code won't kill them.
How does the server handle sensitive information like passwords?
The server uses a request_secret_input tool that allows humans to provide secrets directly to the PTY without the agent ever seeing the value.