FastCtx: an MCP runtime that replaces shell command construction for coding agents

The problem FastCtx targets: shell mechanics eating agent context

The README frames the problem in terms of what a model has to track at once. When an agent accesses a repository by assembling shell commands on the fly, it has to handle quotes, escaping, paths, and platform differences, then extract the useful information from terminal output. A single file read or symbol search can take several tool calls just to confirm the command was correct and the result complete. FastCtx's stated goal is to move that work out of the model and into a Rust runtime that handles command construction, directory traversal, encoding, pagination, and output boundaries. The intended user is not a human typing commands. It is a coding agent running under an MCP host, and by extension the engineer who configures that host. The README says FastCtx provides first-class setup for ChatGPT App and Codex CLI, and that any MCP client can register fastctx serve directly. That last sentence matters more than the first two: it means the project is not tied to one vendor's agent, even though the polished onboarding path points at OpenAI's tooling.

The tool surface: five operations and a job manager

The README lists the tools by name, which is the most concrete part of the documentation. inspect_local_file reads text, images, PDFs, and raw bytes. grep searches file contents, glob finds files, and replace performs mechanical batch replacement. Bash execution is split across run, run_background, job_output, job_kill, and job_list, which together manage persistent long-running jobs. The split between run and run_background is the interesting design choice here. A long-running process does not block the tool call; it becomes a job with an output cursor that the model can poll and terminate. The README states that each MCP connection keeps its own background-output cursor, so two sessions attached to the same control center do not share job output position. What the README does not give is the JSON schema for any of these tools, the parameter names beyond a passing mention of path, pattern, range, and mode, or the output format. If you are evaluating FastCtx for a custom MCP client, that is the first thing you will have to read out of the repository rather than the README.

Architecture: one control center, many stdio proxies

This is where FastCtx differs from a typical single-binary MCP server. The README describes each fastctx serve process as a thin stdio proxy. Proxies belonging to the same user and the same FastCtx build share one private local control center, including its search executor and global admission limits. Per-connection state stays separate: working directory, native environment, cancellation state, and the background-output cursor. The failure semantics are spelled out. An MCP session ends when its host ends it, never because the shared runtime had a problem. If the control center becomes unreachable, the proxy answers calls it can no longer complete with an explicit error, reconnects to a replacement (starting one, or running the engine inside the proxy itself), and continues over the same stdio transport. Side-effecting calls are never replayed. The control center stays resident while any host process that used it is still running, and exits ten minutes after the last one is gone, provided there is no connection, no active request, and no running background job. Two consequences follow. First, the shared search executor means grep and glob concurrency is a per-user resource, which is why the control terminal exposes an automatic CPU parallelism mode and an explicit core limit. Second, the build-isolation of the control center is why the README tells you to restart Codex after an update: existing sessions are attached to the old build's center.

Install and connect: npm, the TUI, and the stable binary path

The documented install is two commands. npm install --global fastctx requires Node.js 18 or later, and then running fastctx opens the control terminal. From there you review proposed changes, select Connect to Codex, and start a new ChatGPT / Codex session. Connecting copies the current binary to ~/.fastctx/bin/ and points the host configuration at that stable path, so the setup survives npm cache cleanup or upgrades. The TUI exposes a defined set of actions: output tier and provider-aware output protection, grep/glob parallelism, an optional Bash terminal, background-job storage and concurrency plus AI list page limits, a Jobs screen for inspecting and stopping running jobs across sessions, a factory reset, and a review screen for host configuration changes. For a non-Codex MCP client, the documented entry point is registering fastctx serve directly. cargo install is mentioned as a build path, with the caveat that cargo install builds and the internal ~/.fastctx/bin/ runtime are not self-updated. If you want the startup update check gone, the README gives FASTCTX_DISABLE_UPDATE_CHECK=1.

Update machinery and the 404 that follows a release

FastCtx checks its launch channel for updates before the main menu opens, and the wait is bounded: if the check cannot finish because of being offline, a timeout, or rate limiting, it enters silently. Successful results are cached for 24 hours in machine-private storage outside ~/.fastctx. npm launches query the exact launcher package through a fresh isolated cache with --prefer-online; direct GitHub Release executables read the stable tag from GitHub's releases/latest web redirect. The two paths have different rollback stories. An accepted npm update installs the exact version with lifecycle scripts disabled, and a failed npm update restores the exact previous package version. A GitHub Release update downloads the platform archive and aggregate SHA256SUMS, verifies the archive, extracts the binary, probes the downloaded version, replaces the executable atomically, and rolls back when restart health fails. The README also documents a failure mode you will hit if you install through a mirror registry: mirror registries copy new releases on a delay, so right after a release an install can fail with 404 Not Found, most often on the platform package, which npm installs as an optional dependency. FastCtx shows a propagation screen in that case, and Retry uses another isolated cache rather than clearing your normal npm cache.

Where FastCtx is the wrong tool

The shared control center is the design's main liability as well as its main feature. One resident process per user means admission limits and the search executor are shared across every MCP session that user runs. A runaway grep in one agent session consumes from the same budget as another, and the README's answer to that is a manual core limit in the TUI rather than per-session quotas. The second limitation is platform shape. The install path assumes Node.js 18 or later for the npm route, and the README's own framing of the problem leans on Windows-specific symptoms such as PowerShell syntax and mojibake, which suggests the tool-mechanics problem it solves is worst on Windows. Nothing in the supplied material describes behavior on other platforms beyond the existence of platform packages and platform archives. Third, if your agent loop is code you control, FastCtx is the wrong shape: it is a server plus a terminal UI, not a library you call in-process. You would be adding a process boundary and an MCP transport to solve a problem you could solve with a typed file API. Fourth, the README does not document the tool schemas, so an implementer writing a custom MCP client is working from the repository, not the documentation.

Alternatives and how the approach differs

The obvious alternative is the status quo the README describes: let the agent assemble shell commands itself, using whatever shell tool the host already provides. That approach has no resident process, no shared admission limits, and no install step, but it pays the cost FastCtx is trying to remove, because the model must get quoting, escaping, paths, and platform syntax right before it learns anything about the code. A second alternative is a general-purpose MCP filesystem server, which typically exposes read, write, and list operations over a path allowlist. The difference is scope and state. A filesystem server gives you primitives; FastCtx bundles search, structured file reading across text, images, PDFs and raw bytes, batch replacement, and a job manager with persistent output cursors. The job manager is the part with no clean equivalent in a plain filesystem server, since long-running Bash processes there would either block or be left to the host. A third option is writing a small in-process tool layer in your own agent, which gives you exact control over schemas and output budgets at the cost of building the traversal, encoding, pagination, and boundary handling that FastCtx already implements. None of these is strictly better. They differ on where the complexity sits: in the model's prompt, in your agent code, or in a resident Rust process.

Licence, maintenance, and what to verify before adopting

FastCtx is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; the usual obligations around notices and attribution apply, and none of this is legal advice. Maintenance signals visible in the supplied material are a release cadence of v0.2.4, v0.2.5, and v0.2.6 between early August and late August 2026, and a last push in September 2026. The version numbers are still in 0.x, and the README describes behavior that reads like active hardening: rollback on failed restart health, propagation screens for mirror lag, silent entry on update-check failure. The upgrade cost is asymmetric depending on how you installed. npm and GitHub Release installs self-update and synchronize the owned ~/.fastctx/bin/ copy, leaving externally changed copies untouched. cargo install builds do not self-update, so you rebuild and reinstall yourself. After any update you must restart Codex so existing sessions and their build-isolated control center are replaced. Removal stops FastCtx process images running from the managed bin directory, removes the configuration FastCtx manages, and deletes its managed data, while preserving shared settings the user changed after connecting. Before adopting, verify three things: that your MCP host speaks stdio, that your Node.js is 18 or later if you take the npm route, and whether your registry is a mirror that lags the official one, since that determines whether your first install 404s on the platform package.

Editorial conclusion

Adopt FastCtx if you drive ChatGPT App or Codex CLI against repositories and want repository operations expressed as typed parameters rather than assembled shell strings. Do not adopt it if you need a library you can embed in your own agent loop, since the documented surface is an MCP server plus a TUI, or if you cannot run a resident process per user. Before connecting, verify that your host speaks MCP over stdio, check the Node.js 18 floor for the npm path, and confirm whether you want the managed ~/.fastctx/bin copy or a cargo install, because only the npm and GitHub Release paths self-update.

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. yc-duan/fastctx on GitHub