fastctx

FastCtx

English | 简体中文

Fast, context-efficient repository tools for AI agents.

FastCtx is a local Rust tool runtime. It provides file reading, content search, file discovery, batch replacement, and Bash command execution through MCP.

Repository operations run in a persistent process with stable input schemas and output formats. The model can gather the context it needs in fewer steps and spend more attention on understanding code, planning changes, and verifying results.

Each fastctx serve process is a thin stdio proxy. Proxies for the same user and FastCtx build share one private local control center, including its search executor and global admission limits, while every MCP connection keeps its own working directory, native environment, cancellation state, and background-output cursor.

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 the 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 carries on over the same stdio transport. Side-effecting calls are never replayed. The control center itself stays resident while any host process that used it is still running, and exits ten minutes after the last of them is gone, with no connection, no active request, and no running background job.

npm install --global fastctx
fastctx

The fastctx command opens the control terminal. Review the proposed changes, select Connect to Codex, then start a new ChatGPT / Codex session.

FastCtx currently provides first-class setup for ChatGPT App and Codex CLI. Any MCP client can also register fastctx serve directly.

What FastCtx solves

Coding agents often assemble shell commands on the fly when they access a repository. They have to handle quotes, escaping, paths, and platform differences, then extract the useful information from terminal output. A simple file read or symbol search can take several tool calls just to confirm that the command is correct and the result is complete.

This work consumes context and reasoning. The model tracks the code problem and the tool mechanics at the same time: whether the PowerShell syntax is correct, whether a path was escaped correctly, whether the encoding produced mojibake, and whether the host truncated a long result. More tool overhead leaves less room for the repository itself.

FastCtx turns common repository operations into structured input and output. The model provides parameters such as a path, pattern, range, and mode. The Rust runtime handles command construction, directory traversal, encoding, pagination, and output boundaries.

The tools cover the main parts of a coding task:

• inspect_local_file reads text, images, PDFs, and raw bytes;
• grep searches file contents;
• glob finds files;
• replace performs mechanical batch replacement;
• run, run_background, job_output, job_kill, and job_list execute Bash commands and manage persistent long-running jobs.

This greatly reduces the attention the model spends on tool mechanics, such as checking whether a PowerShell command is correct. It improves context efficiency and helps tasks finish faster with better results.

Installation

Install with npm

Requires Node.js 18 or later:

npm install --global fastctx
fastctx

The first launch opens the full-screen control terminal. The interface supports 17 languages and provides these main actions:

1. Adjust the output tier and provider-aware output protection;
2. Keep grep/glob on automatic CPU parallelism or set an explicit core limit;
3. Enable Bash terminal when needed;
4. Set current-user background-job storage, concurrency, and AI list page limits;
5. Inspect every currently running job across FastCtx sessions, follow its output, and stop it on the Jobs screen;
6. Reset all user preferences to factory defaults through a confirmation screen;
7. Review every host configuration change on the Connect to Codex screen, confirm it, and restart the ChatGPT / Codex session.

Connecting copies the current binary to ~/.fastctx/bin/ and points the host configuration at that stable path. The connected setup keeps working after npm cache cleanup or upgrades.

On launch, FastCtx checks its launch channel for updates before the main menu opens. A brief checking screen appears and the wait is strictly bounded: if the check cannot finish — offline, timeout, rate limiting — FastCtx enters silently, and the dedicated Update screen still offers a manual check at any time. When a newer version is installable, the update screen opens directly and asks whether to Update & restart or Continue into the current version. Successful results are cached for 24 hours in machine-private storage outside ~/.fastctx, so most launches skip the network entirely. 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.

If GitHub has published a release but npm has not exposed the matching version yet, FastCtx shows a propagation screen instead of trusting stale metadata. Retry always uses another isolated cache; it never clears or mutates the user's normal npm cache. Transient network or rate-limit failures stay quiet and are recorded under Status; malformed publication metadata produces one warning. Status also offers a manual check that bypasses the 24-hour TTL. An accepted npm update installs the exact version with lifecycle scripts disabled. A GitHub Release update downloads this repository's platform archive and aggregate SHA256SUMS, verifies the archive before safely extracting the binary, probes the downloaded version, replaces the executable atomically, and rolls back when restart health fails. A failed npm update restores the exact previous package version; every failed update reopens the previous TUI with a warning. After a successful restart, the owned ~/.fastctx/bin/ copy is synchronized; externally changed copies are left untouched. Restart Codex after an update so existing sessions and their build-isolated control center are replaced by the new build.

cargo install builds and the internal ~/.fastctx/bin/ runtime are not self-updated. Set FASTCTX_DISABLE_UPDATE_CHECK=1 to disable the TUI startup check.

Removal stops FastCtx process images running from the managed bin directory, removes the configuration managed by FastCtx, and deletes its managed data. Shared settings changed by the user after connecting are preserved.

If the install returns 404

Mirror registries copy new releases from the official registry on a delay. Right after a release, an install through a mirror can fail with 404 Not Found — most often on the platform package, which npm installs as an optional dependency and skips silently, leaving fastctx installed but unable to start.

Install once from the official registry:

npm install --global fastctx --registry=https://registry.npmjs.org/

The flag applies to this command only and leaves the npm configuration unchanged. To use the official registry permanently:

npm config set registry https://registry.npmjs.org/ --location=user

After installation, the Update screen probes the npm registry configured on this machine, the official registry, and registry.npmmirror.com, then installs from the first source that carries both the launcher and the matching platform package. Version numbers always come from the official registry and GitHub, so a mirror can never announce a version the official source has not published.

One-off run

npx fastctx

npx opens the same control terminal without a global installation. Connecting still copies the binary to ~/.fastctx/bin/, so the connected setup keeps working after the npx cache is cleaned; only the fastctx command itself requires the global installation.

Non-interactive use

fastctx apply --tier standard --yes
fastctx status
fastctx jobs
fastctx jobs kill j-a1b2c3
fastctx unapply --yes

• apply: install FastCtx and write the configuration;
• status: check the configuration, binary, and MCP handshake;
• jobs: list running background jobs;
• jobs kill : stop one background job and its full process tree;
• unapply: remove the content managed by FastCtx;
• lang : set the control terminal language.

status uses three states: [PASS], [INFO], and [FAIL]. It also reports the detected search CPU ceiling and the configured/effective parallelism. A [FAIL] result returns a non-zero exit code.

Tool limits and settings reset

grep/glob uses automatic parallelism by default: the operating system's available parallelism, capped at 16. In Config → Search, choose a preset with ←/→ or press Enter and type auto or any integer in the displayed 1..=maximum range. The setting is loaded when the shared control center starts and takes effect after that control center restarts, which happens once every Codex process using it has exited. Reconnecting is not required.

The same setting can be written manually in ~/.fastctx/config.toml:

[search]
max_cpu_cores = 4

Omitting the key keeps the previous automatic behavior. Invalid types, empty values, zero, negative numbers, and values above the engine's displayed ceiling prevent a session from starting and produce a diagnostic without rewriting the file. The limit sets one request's effective search parallelism to its base lane plus shared extra workers, at most N. Across every session in the per-user control center, concurrent requests retain independent base lanes but share one pool of at most N−1 extra lanes, so the upper bound for R concurrent requests is R+N−1. This is not CPU affinity or a strict system-wide governor.

replace accepts files and replacement results up to 256 MiB by default. In Config → Editing, choose a coarse 64 MiB–4 GiB preset with ←/→. Saving takes effect on the next replace request, including requests from an already-open Codex session, and does not require reconnecting. Larger limits allow replace to use more memory; values set too high may cause an out-of-memory failure.

The same limit can be written manually; 64 MiB is the minimum and 4096 MiB is the maximum:

[replace]
max_file_size_mib = 512

Config → Reset → Reset all settings opens with No selected. Confirming restores every user preference, including language, output budgets, Bash/job limits, search CPU limit, replace file limit, and update settings. It preserves the connection receipt, installed binary, host configuration, and running jobs. Restoring the default 1024 MiB job-history quota may immediately evict the oldest finished records above that quota.

Other distribution channels

cargo install fastctx --locked

GitHub Releases provides zip archives for Windows x64 and Windows arm64, and executable-preserving tar.gz archives for Linux x64, macOS x64, and macOS arm64. Every archive includes the binary and license notices; verify it with the release's aggregate SHA256SUMS.

Tools

FastCtx provides nine MCP tools:

inspect_local_file, grep,