# FastCtx: Structured MCP Repository Tools for AI Coding Agents > FastCtx is an Apache-2.0 Rust tool that exposes file reading, content search, file discovery, batch replacement, and Bash command execution through the Model Context Protocol (MCP). It reduces the number of tool calls a coding agent needs to gather context from a codebase by providing structured input and output instead of raw shell commands. **yc-duan/fastctx** — Fast, context-efficient repository tools for AI agents (MCP) - Repository: https://github.com/yc-duan/fastctx - Stars: 1,441 · Forks: 55 - Language: Rust - License: Apache-2.0 - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/yc-duan-fastctx ## The Problem FastCtx Solves for Coding Agents AI coding agents that access a repository through a shell often spend a significant part of each task on mechanics: constructing the right command syntax, quoting paths correctly for the operating system, handling encoding differences, and extracting useful information from raw terminal output. The README describes the cost clearly: more tool overhead leaves less room for the repository itself. A common example is a file read. Without a structured tool, an agent might issue a cat command, check that the path escaped correctly, verify the encoding produced readable output, and handle the case where the terminal truncated a long file. Each step is a separate tool call or requires the agent to reason about platform-specific details rather than the code. FastCtx removes those steps. The agent provides structured parameters (a path, a pattern, a line range), and FastCtx's Rust runtime handles command construction, encoding, pagination, and output boundaries. The model receives clean output and spends its context window on understanding the code. ## The Tool Set: Read, Search, Glob, Replace, and Bash FastCtx exposes nine MCP tools. The README describes each: - inspect_local_file: reads text files, images, PDFs, and raw bytes. - grep: searches file contents using the grep-regex crate (a Rust ripgrep-compatible search engine). - glob: finds files by pattern. - replace: performs mechanical batch text replacement. - run: executes a Bash command synchronously. - run_background: starts a long-running Bash command as a background job. - job_output: retrieves output from a background job. - job_kill: terminates a background job. - job_list: lists all running background jobs. These tools cover the main phases of a coding task: discovering the codebase structure with glob, reading files with inspect_local_file, finding symbols with grep, making mechanical changes with replace, and running the build or tests with run. ## Installing FastCtx and Connecting to Codex FastCtx installs through npm as a global package. Node.js 18 or later is required: ```console npm install --global fastctx fastctx ``` The first launch opens a full-screen control terminal. From that terminal, you configure output settings, set CPU parallelism for grep and glob, enable the Bash terminal if needed, and connect to the AI host. For ChatGPT and Codex CLI, the Connect to Codex screen in the terminal applies the host configuration change and asks you to restart the Codex session after confirming. Connecting copies the current FastCtx binary to ~/.fastctx/bin/ and points the host configuration at that stable path. This means the connection persists through npm cache cleanups and version upgrades. The README also documents a cargo install path for engineers who want to build from the Rust source. The self-update system that FastCtx uses for npm installations does not apply to cargo-built binaries: those must be updated manually. ## The Control Center Architecture FastCtx uses a persistent control center process shared across all instances of the same user and build. Each fastctx serve process that an MCP client starts is a thin stdio proxy that connects to this shared control center. The control center owns the search executor and enforces global admission limits. This design has a specific reliability property: if the control center crashes or becomes unreachable, the proxy answers calls it can no longer complete with an explicit error, reconnects to a replacement control center (starting one if needed or running the engine inside the proxy itself), and continues on the same stdio transport. Side-effecting calls are never replayed automatically. The control center stays running as long as any host process that used it is still active. It exits ten minutes after the last such process finishes, with no active connections, requests, or background jobs remaining. Each MCP connection maintains its own working directory, environment, cancellation state, and background-output cursor. Multiple Codex sessions can run concurrently against the same repository without interfering with each other's file views. ## Update Mechanism and Version Management The control terminal that opens on launch includes an automatic update check. On each launch, FastCtx queries its update channel for a newer version. The check is strictly bounded: if it cannot complete due to a network issue, rate limiting, or a timeout, FastCtx enters the main menu silently. Results are cached for 24 hours in machine-private storage, so most launches skip the network check entirely. When a new version is available, the update screen offers Update and restart or Continue. A successful npm update installs the exact version with lifecycle scripts disabled. A failed npm update restores the previous package version. GitHub Release updates download a platform archive, verify it against a published SHA256 checksum file, extract the binary atomically, and roll back if the restarted version fails a health check. The build from cargo install and the internal binary at ~/.fastctx/bin/ are not self-updated. Set FASTCTX_DISABLE_UPDATE_CHECK=1 to disable the startup check entirely. ## Limitations and When FastCtx Does Not Help FastCtx is only useful inside an MCP-capable client. If your coding workflow does not use Codex CLI, a Claude Code MCP setup, or another MCP host, FastCtx adds nothing. The Bash terminal is disabled by default and must be enabled explicitly in the control terminal. The README does not explain the exact security model behind that default, but the implication is that shell execution is gated intentionally. The README notes a potential 404 error on install if you are using a mirror npm registry: mirrors copy new releases from the official registry with a delay, and a fresh version may not be available through a mirror immediately after release. The workaround is to install directly from the official registry. FastCtx provides no GUI, no syntax highlighting, and no diff viewer. It is a tool server for an AI agent, not a developer tool for humans. The tool is specific to local repository access. It does not provide tools for querying remote APIs, interacting with web interfaces, or accessing databases. An agent that needs to call a REST API or inspect a running container would still need to compose those operations through the run tool, which means the same shell-mechanics problem recurs for operations outside the filesystem. ## Maintenance Status and Licence The last push to the repository was on 2026-09-05, and the project is not archived. The current version is v0.2.6, released 2026-08-23. Prior releases include v0.2.5 in August 2026 and v0.2.4 in August 2026. All three releases within the past two months indicate active iteration at the time of writing. The Cargo.toml lists the minimum supported Rust version as 1.88. The crate is published to crates.io (documented at docs.rs/fastctx) and to npm under the fastctx package name. Both distribution channels are updated with each release. The project is licensed under Apache-2.0, which permits use, modification, and redistribution with standard attribution requirements and no commercial restrictions. The repository includes a THIRD_PARTY_LICENSES.md and THIRD_PARTY_LICENSES_RUST.md listing the licences of all bundled dependencies. ## Conclusion FastCtx is the right tool for engineers who run AI coding agents (particularly ChatGPT Codex or any MCP-compatible client) and want to reduce the overhead those agents spend on shell command construction and output parsing. It is not useful as a standalone CLI tool for humans and is not a replacement for a full development environment. Before connecting it, run fastctx to review the output tier and provider-aware output limits in the control terminal, since defaults affect how much content the agent receives per call. The Apache-2.0 licence permits commercial use with attribution. ## FAQ ### What is FastCtx? FastCtx is a Rust MCP server that provides AI coding agents with structured tools for reading files, searching content, finding files by pattern, making batch text replacements, and running Bash commands. It eliminates the need for agents to construct and parse raw shell commands. ### How do I install FastCtx? Run npm install --global fastctx with Node.js 18 or later. Then run fastctx to open the control terminal, where you can configure settings and connect it to ChatGPT or Codex CLI. ### Which AI hosts does FastCtx support? The README describes first-class setup for ChatGPT App and Codex CLI. Any MCP client can also register fastctx serve directly as an MCP server. ## Sources - [Issues](https://github.com/yc-duan/fastctx/issues) - [License: Apache-2.0](https://github.com/yc-duan/fastctx/blob/main/LICENSE) - [README](https://github.com/yc-duan/fastctx/blob/main/README.md) - [Releases](https://github.com/yc-duan/fastctx/releases) - [yc-duan/fastctx on GitHub](https://github.com/yc-duan/fastctx) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yc-duan-fastctx