[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93570":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":16,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":9,"trendingCount":15,"starSnapshotCount":15,"syncStatus":14,"lastSyncTime":26,"discoverSource":27},93570,"fastctx","yc-duan\u002Ffastctx","yc-duan","Fast, context-efficient repository tools for AI agents (MCP)",null,"Rust",309,9,124,2,0,93,279,92.01,"Apache License 2.0",false,"main",true,[],"2026-07-22 04:02:09","# FastCtx\n\n**English** | [简体中文](.\u002FREADME.zh-CN.md)\n\n### Fast, context-efficient repository tools for AI agents.\n\nFastCtx is a local Rust tool runtime. It provides file reading, content search, file discovery, batch replacement, and Bash command execution through MCP.\n\nRepository 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.\n\n```console\nnpm install --global fastctx\nfastctx\n```\n\nThe `fastctx` command opens the control terminal. Review the proposed changes, select **Apply**, then start a new ChatGPT \u002F Codex session.\n\nFastCtx currently provides first-class setup for ChatGPT App and Codex CLI. Any MCP client can also register `fastctx serve` directly.\n\n## What FastCtx solves\n\nCoding 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.\n\nThis 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.\n\nFastCtx 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.\n\nThe tools cover the main parts of a coding task:\n\n- `read` reads text, images, PDFs, and raw bytes;\n- `grep` searches file contents;\n- `glob` finds files;\n- `replace` performs mechanical batch replacement;\n- `run`, `run_background`, `job_output`, `job_kill`, and `job_list` execute Bash commands and manage persistent long-running jobs.\n\nThis 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.\n\n## Installation\n\n### Install with npm\n\nRequires Node.js 18 or later:\n\n```console\nnpm install --global fastctx\nfastctx\n```\n\nThe first launch opens the full-screen control terminal. The interface supports 17 languages and provides these main actions:\n\n1. Adjust the output tier;\n2. Enable **Bash terminal** when needed;\n3. Set current-user background-job storage, concurrency, and AI list page limits;\n4. Inspect every currently running job across FastCtx sessions, follow its output, and stop it on the **Jobs** screen;\n5. Review every configuration change on the Apply screen;\n6. Apply the changes and restart the ChatGPT \u002F Codex session.\n\nApply copies the current binary to `~\u002F.fastctx\u002Fbin\u002F` and points the host configuration at that stable path. The applied setup keeps working after npm cache cleanup or upgrades.\n\nThe full-screen terminal opens immediately while FastCtx checks its launch channel in a background thread. Successful results are cached for 24 hours in machine-private storage outside `~\u002F.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\u002Flatest` web redirect. Available updates remain visible from the main menu and open a dedicated screen with **Update & restart** and **Continue**.\n\nIf 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, an owned `~\u002F.fastctx\u002Fbin\u002F` Apply copy is synchronized; externally changed copies are left untouched.\n\n`cargo install` builds and the internal `~\u002F.fastctx\u002Fbin\u002F` runtime are not self-updated. Set `FASTCTX_DISABLE_UPDATE_CHECK=1` to disable the TUI startup check.\n\n**Unapply** 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 Apply are preserved.\n\n### If the install returns 404\n\nMirror 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.\n\nInstall once from the official registry:\n\n```console\nnpm install --global fastctx --registry=https:\u002F\u002Fregistry.npmjs.org\u002F\n```\n\nThe flag applies to this command only and leaves the npm configuration unchanged. To use the official registry permanently:\n\n```console\nnpm config set registry https:\u002F\u002Fregistry.npmjs.org\u002F --location=user\n```\n\nAfter 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.\n\n### One-off run\n\n```console\nnpx fastctx\n```\n\n`npx` opens the same control terminal without a global installation. Apply still copies the binary to `~\u002F.fastctx\u002Fbin\u002F`, so the applied setup keeps working after the npx cache is cleaned; only the `fastctx` command itself requires the global installation.\n\n### Non-interactive use\n\n```console\nfastctx apply --tier standard --yes\nfastctx status\nfastctx jobs\nfastctx jobs kill j-a1b2c3\nfastctx unapply --yes\n```\n\n- `apply`: install FastCtx and write the configuration;\n- `status`: check the configuration, binary, and MCP handshake;\n- `jobs`: list running background jobs;\n- `jobs kill \u003Cjob_id>`: stop one background job and its full process tree;\n- `unapply`: remove the content managed by FastCtx;\n- `lang \u003Ccode>`: set the control terminal language.\n\n`status` uses three states: `[PASS]`, `[INFO]`, and `[FAIL]`. A `[FAIL]` result returns a non-zero exit code.\n\n### Other distribution channels\n\n```console\ncargo install fastctx --locked\n```\n\nGitHub Releases provides a zip archive for Windows x64 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`.\n\n## Tools\n\nFastCtx provides nine MCP tools:\n\n| Tool | Purpose |\n|---|---|\n| `read` | Read text, images, PDFs, and raw bytes from any file |\n| `grep` | Search contents in a file or repository tree |\n| `glob` | Find files by path pattern |\n| `replace` | Apply mechanical batch replacements to files or a repository tree |\n| `run` | Run a Bash command in the foreground |\n| `run_background` | Start a background Bash job |\n| `job_output` | Read new output from a background job |\n| `job_kill` | Stop the full process tree of a background job |\n| `job_list` | Rediscover running and retained finished jobs |\n\n`read`, `grep`, `glob`, and `replace` are published by default. The other five tools are enabled with the **Bash terminal** setting in the control terminal. Once enabled, they share the same `mcp__fastctx__*` namespace as the file tools.\n\n### `read`\n\n`read` returns 1-based line numbers for text and supports paging:\n\n```json\n{\n  \"file_path\": \"V:\u002Frepo\u002Fsrc\u002Fmain.rs\",\n  \"offset\": 120,\n  \"limit\": 40\n}\n```\n\n```text\n120\tfn main() {\n121\t    ...\n159\t}\n\n(Partial: lines 120-159 of 512 shown. Continue with offset=160.)\n```\n\nThe continuation parameters in the final status line can be used directly in the next call. In this example, pass `offset=160` to read the next section.\n\n`read` also supports:\n\n- PNG, JPG, GIF, WebP, and BMP images;\n- PDF text layers and rendered page images;\n- a paged hex view for any file;\n- UTF-8, BOM-based encodings, and common legacy encodings.\n\nAutomatic encoding detection accepts results with sufficient evidence. When the encoding is ambiguous, the error lists candidates and retry options. Pass `encoding` to select one explicitly:\n\n```json\n{\n  \"file_path\": \"V:\u002Frepo\u002Fdocs\u002Flegacy.txt\",\n  \"encoding\": \"gbk\"\n}\n```\n\nUse the hex view for binary files:\n\n```json\n{\n  \"file_path\": \"V:\u002Frepo\u002Fdata\u002Fcache.bin\",\n  \"view\": \"hex\"\n}\n```\n\n### `grep`\n\n`grep` uses the Rust regex engine from the ripgrep family:\n\n```json\n{\n  \"pattern\": \"fn \\\\w+_lock\",\n  \"path\": \"V:\u002Frepo\u002Fsrc\",\n  \"output_mode\": \"content\",\n  \"context\": 1\n}\n```\n\n```text\nV:\u002Frepo\u002Fsrc\u002Fedit\u002Flocks.rs\n62-\u002F\u002F\u002F Cross-process lock keyed by file identity.\n63:pub fn acquire_path_lock(identity: &PathIdentity) -> LockGuard {\n64-    ...\n\n(Complete: all 1 result shown.)\n```\n\n`output_mode` has four values:\n\n- `files_with_matches`: return matching files;\n- `content`: show matches grouped by file;\n- `count`: return the occurrence count for each file;\n- `summary`: scan the full target and return global totals.\n\nSearches respect `.gitignore` and `.ignore` by default, include hidden files, and exclude `.git` and binary files. Common filters include `glob`, `type`, `case_insensitive`, `multiline`, and `context`. Page through results with `head_limit` and `offset`.\n\nFiles with uncertain encodings appear in a skip report with their path, reason, and resolution parameters. Use `encoding` for a single file and `fallback_encoding` for a directory search.\n\n### `glob`\n\n`glob` finds files with a pattern relative to the search root:\n\n```json\n{\n  \"pattern\": \"**\u002F*.toml\",\n  \"path\": \"V:\u002Frepo\",\n  \"sort\": \"modified\"\n}\n```\n\n```text\nV:\u002Frepo\u002Fcrates\u002Fcore\u002FCargo.toml\nV:\u002Frepo\u002FCargo.toml\n\n(Complete: all 2 files shown.)\n```\n\nMain parameters:\n\n- `filter_mode: \"project\"`: apply ignore rules, exclude `.git`, and keep hidden files visible;\n- `filter_mode: \"all\"`: list every file;\n- `sort: \"path\"`: use a stable path order;\n- `sort: \"modified\"`: order files from newest to oldest;\n- `offset` \u002F `limit`: page through the result set.\n\n### `replace`\n\n`replace` handles mechanical, deterministic batch changes such as symbol renames, import rewrites, configuration key migrations, and fixed-pattern deletion. Generated code changes and per-location semantic edits are handled by the host's `apply_patch` tool.\n\n```json\n{\n  \"pattern\": \"old_name\\\\(\",\n  \"replacement\": \"new_name(\",\n  \"path\": \"V:\u002Frepo\u002Fsrc\",\n  \"glob\": \"**\u002F*.rs\",\n  \"dry_run\": true\n}\n```\n\n```text\n...\n\n(Complete: dry run — 12 matches in 3 files; nothing written.)\n```\n\n`replace` freezes the candidate set and counts every match before the first write. Use `dry_run` for preview and `max_replacements` to cap the change scope.\n\nEach file is checked again before commit. Writes use atomic replacement in the same directory and preserve the original encoding, BOM, line endings, trailing newline, Unix mode, and untouched bytes. Concurrent changes move the affected file into the failure report while the remaining files continue.\n\n### `run`\n\n`run` executes a Bash command in the foreground and returns merged stdout, stderr, and the exit code. It uses Git Bash on Windows and the system Bash on macOS and Linux.\n\n```json\n{\n  \"command\": \"cargo test --quiet 2>&1 | tail -n 40\",\n  \"timeout_ms\": 180000\n}\n```\n\nCommands run in a non-interactive environment. Installation, confirmation, and editor commands need flags such as `-y` and `--no-edit`. Non-zero exit codes are returned as execution results.\n\nOn Windows, every FastCtx-owned non-interactive child process is created without allocating a console window, including Bash discovery, foreground\u002Fbackground Bash, detached supervisors, and doctor probes. There is no hidden-window parameter to remember. A command that explicitly launches a GUI or a new terminal still has that visible effect.\n\nOutput uses bounded memory. When output exceeds the response capacity, the final status line reports the truncated range and gives a path to the complete result: redirect the command output to a file, then page through it with `read`.\n\n### `run_background`\n\n`run_background` starts a background Bash job and returns a job id immediately. It is useful for builds, tests, development servers, and other long-running commands.\n\nEach job is owned by a detached supervisor rather than by the MCP server. It keeps running across server exits, ChatGPT \u002F Codex restarts, and session changes until the command exits or `job_kill` stops it. There is no background timeout parameter.\n\nOutput and exit status are stored under `~\u002F.fastctx\u002Fjobs\u002F`, so another FastCtx server can resume the same job by id. Each job keeps an 8 MiB rolling output window; redirect the command to a file when a complete log is required.\n\n### `job_output`\n\n`job_output` reads new output from a background job, including jobs started in earlier sessions, and reports `running`, `exited`, or `interrupted`. `wait_ms` enables long polling. `after_seq` re-anchors the read position and keeps paging stable when a call is retried.\n\nKeep calling it until the final line says `Complete`. When the ring buffer evicts output, the response reports the number of lost lines and recommends redirecting command output to a file for a complete log.\n\n### `job_kill`\n\n`job_kill` stops the selected background job and its full process tree. If the job has already exited, the call returns the existing exit status.\n\n### `job_list`\n\n`job_list` defaults to `status=\"running\"`. Use `status=\"finished\"` to inspect retained exited or interrupted records, and `status=\"all\"` only when both lifecycles are needed. Results are newest first within each lifecycle. `offset` continues a page; `limit` overrides the saved page size for one call.\n\nFinished records have no time-to-live. FastCtx retains them until the current user's `fastshell.job_storage_limit_mib` limit requires eviction of the oldest finished records. The default is 1024 MiB. Running jobs and their records are never evicted; `fastshell.max_running_jobs` limits concurrent jobs across all FastCtx sessions for that user and defaults to 128. `fastshell.job_list_limit` is the default page size (20, valid range 1–100). All three settings take effect immediately when saved and do not require Apply; the TUI presets for page size are 10 \u002F 20 \u002F 50 \u002F 100.\n\nThe TUI **Jobs** dashboard scans this same current-user registry but shows only jobs that are currently running, aggregated from every FastCtx server and TUI instance. A finished job disappears with a short notice that its retained output remains available to the agent through `job_output`. Jobs are grouped by an honest source-session tag with workspace, server PID, and parent-process context. Fixed list columns keep relative age and job ids aligned, while long ASCII or CJK commands end with an ellipsis at one shared edge. The detail panel shows the exact UTC start time to the second and a live `HH:MM:SS` elapsed time. Horizontal and vertical output navigation remains available; one width-aware footer row keeps the essential keys visible and adds `←\u002F→ output`, `PgUp\u002FPgDn scroll`, and `F follow` when space permits. ChatGPT \u002F Codex does not expose conversation titles or ids to the MCP server, so FastCtx does not invent one.\n\n## Security and privacy\n\nThe FastCtx MCP server inherits the local permissions of the host process.\n\n| Capability | Default state | Access scope |\n|---|---|---|\n| `read` \u002F `grep` \u002F `glob` | Enabled | Local files readable by the host process |\n| `replace` | Enabled | Local file writes with dry-run, CAS, and atomic replacement safeguards |\n| Bash tools | Disabled | Bash command execution after the user enables them |\n| TUI update check | Enabled for npm and GitHub Release launches | Version metadata from `registry.npmjs.org` and GitHub's `releases\u002Flatest` web redirect; downloads require explicit confirmation |\n| MCP runtime network requests | None | `serve` and tool calls perform no telemetry or update traffic |\n\nThe startup check sends the FastCtx version, normal HTTPS request metadata, and npm's standard registry request; it never sends repository paths, job data, or file contents. Background jobs persist their command, working directory, rolling stdout\u002Fstderr, and exit status only in the current user's private `~\u002F.fastctx\u002Fjobs\u002F` directory. FastCtx does not upload this data. Bash commands can access the network according to the command itself. Prebuilt binaries include the PDF engine.\n\nThe MCP server runs outside the host filesystem sandbox. Use an approval mode when every write and command execution should be reviewed:\n\n```toml\n[mcp_servers.fastctx]\ndefault_tools_approval_mode = \"writes\"\n```\n\n- `writes`: review `replace` and shell execution tools;\n- `prompt`: review every tool call.\n\n`replace` is published with the default file tools. The host's read-only mode covers the host's own tools. MCP writes still run with the server process permissions. Set `writes` or `prompt` when the workflow depends on a read-only boundary.\n\n## Codex configuration\n\nCodex code mode places regular MCP tools inside an execution container. Aggregated results from multiple calls can be truncated in the middle by the host. This setting keeps FastCtx as a direct top-level namespace:\n\n```toml\n[features.code_mode]\ndirect_only_tool_namespaces = [\"mcp__fastctx\"]\n```\n\nApply maintains this setting automatically and writes a guidance block with explicit markers to `~\u002F.codex\u002FAGENTS.md` so the model prefers the FastCtx tools.\n\nFastCtx uses an internal output budget of 8,500 tokens by default, around 85% of Codex's default tool output limit. The control terminal provides three tiers:\n\n- `Standard`: the default tier;\n- `High`: raises the global Codex tool output limit;\n- `Extra High`: provides the largest per-call output space.\n\nHigher output tiers allow larger results per call and consume context faster. Choose a tier according to the task.\n\n\u003Cdetails>\n\u003Csummary>Manual MCP registration\u003C\u002Fsummary>\n\n```toml\n[mcp_servers.fastctx]\ncommand = \"C:\u002Fabsolute\u002Fpath\u002Fto\u002Ffastctx.exe\"\nargs = [\"serve\"]\nstartup_timeout_sec = 120\n\n[features.code_mode]\ndirect_only_tool_namespaces = [\"mcp__fastctx\"]\n```\n\nEnable the Bash tools with:\n\n```toml\nargs = [\"serve\", \"--enable-shell\"]\n```\n\nWhen the binary is on PATH, `command` can be set to `fastctx`. The compatibility npm package `codex-fastctx` installs the same `fastctx` command.\n\n\u003C\u002Fdetails>\n\n## What FastCtx changes\n\nFastCtx uses or manages these paths and settings:\n\n- `~\u002F.fastctx\u002Fbin\u002Ffastctx(.exe)`: the stable self-installed binary;\n- `~\u002F.fastctx\u002Fconfig.toml`: control terminal settings and the Apply receipt;\n- `~\u002F.fastctx\u002Fjobs\u002F`: persistent background-job records and rolling output, created on demand by `run_background`;\n- `[mcp_servers.fastctx]` in `~\u002F.codex\u002Fconfig.toml`;\n- the `mcp__fastctx` entry in `direct_only_tool_namespaces`;\n- the marker-delimited FastCtx block in `~\u002F.codex\u002FAGENTS.md`;\n- the selected `tool_output_token_limit` value after user confirmation.\n\nFastCtx edits existing TOML with `toml_edit`, preserving comments, formatting, and unrelated configuration. Unapply removes entries according to write ownership and preserves later user changes. It stops running background jobs before removing `~\u002F.fastctx\u002F`.\n\n## License\n\nFastCtx is dual-licensed under MIT OR Apache-2.0. Redistributions must retain the [`NOTICE`](.\u002FNOTICE) file. Third-party notices for the bundled Pdfium build are listed in [`THIRD_PARTY_LICENSES.md`](.\u002FTHIRD_PARTY_LICENSES.md).\n\n## Contact\n\nFastCtx is created and maintained by [yc-duan](https:\u002F\u002Fgithub.com\u002Fyc-duan). For integration, redistribution, partnership, or anything else, feel free to reach out: dy2958830371@gmail.com.\n\n## Acknowledgements\n\nThanks to the [linuxdo](https:\u002F\u002Flinux.do\u002F) community for discussion, sharing, and feedback.\n","2026-07-21 02:30:03","CREATED_QUERY"]