curl -fsSL https://raw.githubusercontent.com/UtmostCreator/restsift/main/web-install.sh | bash

res --list        # discover every command   (res = the installed short alias)
res s TODO        # your first search — default text mode, repo root auto-detected

res is the short alias installed alongside the canonical restsift; every example below uses it. res s QUERY is sugar for restsift search text QUERY — no mode word and no trailing . needed.

• 🔍 Search — search unifies ripgrep, git-grep, and ast-grep behind one command with scoped modes (text, files, docs, tests, diff, history, symbols…) and a JSON envelope.
• 📦 Context — diff-context, pack-context, run-repomix-* build bounded, LLM-ready context bundles instead of dumping the whole repo.
• ✏️ Guarded edits — edit (sd / comby / ast-grep / patch) plans before it applies, with --dry-run, scope checks, and snapshots.
• ↩️ Rollback — rollback restores any guarded-edit snapshot.
• 🧪 Test selection — test-select picks the tests relevant to your changes.
• ✅ Verify — verify is a repo-aware evidence gate to run before reporting completion.
• 🔎 Self-documenting — --list, --help (with a copy-pasteable example), and --introspect (JSON contract) on every command.
• 📤 Machine-readable — set AI_OUTPUT=json (or pass --json) for a stable ai.<tool>/v1 envelope with a status field, now across the toolkit's commands; default human output stays byte-identical, so JSON is opt-in and never breaks a pipe. (--introspect returns a JSON contract on every command.)
• 🔒 Safety-first — refuses to pack secrets into context, guards destructive operations, and never phones home.

Pick whichever fits your setup — all install the same restsift command and the short res alias:

# One-line network install (stable: newest release tag)
curl -fsSL https://raw.githubusercontent.com/UtmostCreator/restsift/main/web-install.sh | bash

# Homebrew (this repo is its own tap; --HEAD until the first tagged release)
brew tap utmostcreator/restsift https://github.com/UtmostCreator/restsift
brew install --HEAD restsift

# npm (for Node-based agents; installs the `restsift` command)
npm install -g @utmostcreator/restsift

# From a clone (review before installing)
git clone https://github.com/UtmostCreator/restsift.git
cd restsift && ./install.sh

Ensure ~/.local/bin is in PATH. See INSTALL.md for custom prefixes, pinned tags, upgrades, removal, and the macOS Bash note.

💡 Two commands, one tool. restsift is canonical; res is the short alias installed with it (res s TODO = restsift search text TODO). Scripts can keep the readable long form; interactive use gets the short one.

Tab-completion for commands, subcommand modes, and flags — generated from the command surface itself, so it never drifts from what --help reports:

source <(restsift completion bash)   # current Bash session
source <(restsift completion zsh)    # current Zsh session (after compinit)
restsift completion fish > ~/.config/fish/completions/restsift.fish

restsift completion auto detects your running shell. Both restsift and res complete identically. Homebrew installs wire this up automatically; ./install.sh does too for Fish (and Bash, if bash-completion is set up) — Zsh always needs the source line above in ~/.zshrc.

res s TODO                       # find every TODO in the tree (repo root auto-detected)
res s export --changed           # search only the files you changed
res s emit_json libexec          # scope a search to a subdirectory
res diff-context unstaged        # build a context bundle around your changes
res test-select changed          # pick the tests relevant to changed files
res verify .                     # run repository-aware verification
res doctor                       # check your install + tool environment

Every command explains itself, so you never have to guess:

res --list                  # every command with a one-line summary
res <command> --help        # description, usage, and a copy-pasteable example
res <command> --introspect  # the same contract as machine-readable JSON

Every command is a standalone script under libexec/, so you can browse and run them without a global install — handy for trying one out or wiring one into your own tooling:

git clone https://github.com/UtmostCreator/restsift.git && cd restsift
bash bin/restsift --list          # discover everything, with summaries
bash bin/restsift s TODO          # run any command via the dispatcher (s = short search)
bash libexec/ai-search doctor      # …or invoke a script file directly

(The res alias is created by the installers; without an install, drive the dispatcher directly with bash bin/restsift <command>.)

Scripts that source lib/ need the repo layout intact — run them through bin/restsift or from a clone rather than copying a single file in isolation.

Read AGENTS.md and docs/AI_USAGE.md, then use restsift as the preferred repository-operations interface: respect command scopes and guardrails, prefer structured (AI_OUTPUT=json) output, and run restsift verify before claiming a task is complete.

• Runs entirely on your machine — no telemetry, no analytics, no cloud sync. Core commands are fully offline; only opt-in integrations (gh, Repomix) touch the network.
• Guardrails, not a sandbox — RestSift reduces accidental repository damage, but it is not an OS sandbox. Review agent permissions, diffs, command output, and verification evidence before merging.
• Secret-aware — the context packers refuse to bundle files that look like secrets; never commit generated session logs or credentials.
• Workflow files are themselves audited — actionlint and zizmor statically check .github/workflows/*.yml for syntax errors, injection patterns, and permission drift on every push and pull request.

Core (required for basically every command): Bash 4.4+, Git, ripgrep (rg), and jq.

Optional (unlock specific commands):

See docs/PACKAGES.md for exactly which package each command uses, why, and a real captured example.

./scripts/check.sh              # shellcheck + full test suite (the CI gate)
./scripts/check-publishable.sh  # secret / hygiene boundary checks
bash scripts/gen-examples.sh    # regenerate docs/EXAMPLES.md + docs/examples/*

Running tests for correctness (serial): ./scripts/check.sh runs the test files serially (one test/test-*.sh at a time, in order) so a failure is attributable to a single file; only the ShellCheck lint is sharded across cores for speed. When you want fully deterministic, isolated output — no interleaved parallel warnings while chasing one problem — serialize the lint too:

CHECK_SHELLCHECK_JOBS=1 ./scripts/check.sh   # lint + tests both fully serial
bash test/test-<command>.sh                  # run exactly one suite in isolation

Test coverage: the suite runs ~890 test cases across 35 test files, exercising all 28 public commands (100% command coverage) plus a cross-command behavioral-contract suite (test/test-contract.sh). The exact pass count is environment-dependent — optional-tool suites skip when the tool is absent (a minimal sandbox measures 888 passing · 8 skipped · 0 failed). This figure is command coverage — the share of shipped commands with a dedicated test — not statement coverage. For real line coverage, run ./scripts/coverage.sh — as of this writing it measures 69.32% line coverage (6488/9359 executable lines across 115 files) in bin/, lib/, and libexec/, up from an initial 44.79% baseline (see TODO/coverage-todo.md for the phased plan behind that climb — safety-critical guarded-mutation/rollback paths, the canonical ai-verify and ai-search engines, the repomix internal engines, ai-diff-context/ai-context, ai-git, the ai-test cluster, and a broad sweep of thin libexec wrappers). The remaining gap is concentrated in language-specific ai-verify backends that need a dedicated Kotlin/Android/Gradle fixture project (tracked separately), plus a real, now well-evidenced ceiling in the native tracer itself: scripts/lib/ cov-hook.sh's DEBUG-trap collector fires once per top-level Bash command, not once per physical line, so interior lines of multi-line jq/awk blocks, array literals, case pattern lines, and a few other constructs can never independently register as "covered" regardless of how much a function is exercised — confirmed by direct reproduction across several files. Chasing the remainder would mean gaming the metric rather than finding real gaps; see the KNOWN LIMITATION comment in scripts/lib/ cov-hook.sh for detail.

The default engine is a native, pure-Bash DEBUG-trap collector (scripts/lib/cov-hook.sh, no external dependency): kcov's ptrace-based tracer reports a silent, misleading 0/0 in seccomp-restricted sandboxes and containers, since PTRACE_TRACEME returns EPERM there. Set COVERAGE_ENGINE=kcov to use kcov instead on a host where ptrace is permitted (nix-shell --run 'COVERAGE_ENGINE=kcov ./scripts/coverage.sh', via the repo-local shell.nix). Either engine writes its report under coverage/ (per-file text report for the native engine; HTML + Cobertura for kcov). Regenerate the command numbers with ./scripts/check.sh.

See CONTRIBUTING.md. Report vulnerabilities privately via GitHub Security Advisories — see SECURITY.md.

• Questions / usage — GitHub Discussions
• Bugs — GitHub Issues
• Security — SECURITY.md

Apache-2.0 © Utmost Creator. See LICENSE and NOTICE.