{
  "markdown": "# Squire\n\nSquire is a transparent local execution and verification layer for coding\nagents. It keeps common repository reads hot and continuously maintains whether\nthe current declared workspace state is verified.\n\nThe agent keeps using ordinary terminal commands. Before Codex starts a local\nread-only command, Squire checks current state and either replays a proven mmap\nobservation or executes a small bounded operation over hash-verified current\nfile bytes. A valid hit returns the exact stdout, stderr, and exit status.\nEvery miss follows Codex's original native execution path.\n\n## Install\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/reidgoodbar/squire/main/install.sh | bash\n```\n\nThe installer verifies matching Squire and Squire-Codex release archives and\ninstalls the driver, Codex runtime helper, and host-native Squire runtime to\n`~/.local/bin`. It does not change Codex authentication or configuration.\nSupported hosts are macOS and Linux on `amd64` or `arm64`.\n\nCheck the installation:\n\n```sh\nsquire doctor\n```\n\n`doctor` exits nonzero when any required driver, helper, runtime, or ABI\ncomponent is missing.\n\n## Use\n\nStart from any directory:\n\n```sh\nsquire codex\n```\n\nThat is the complete user path. There is no setup command, global shell shim,\nprompt change, MCP tool, preload injection, or VM provisioning step. If Codex\nmoves into a repository later, Squire discovers and prepares that repository\nfrom the command's actual cwd.\n\n`squire-codex` is also installed as a direct convenience command.\n\nInspect the current repository and runtime:\n\n```sh\nsquire status\nsquire status --json\nsquire explain -- git status --short\n```\n\n## Continuous Verification\n\nSquire Green runs declared tests, lint, typechecks, and builds natively in the\nbackground after repository edits settle. Each result is bound to the exact\ndeclared input bytes, check configuration, environment, and executable. A\nlater relevant edit makes that result stale; unrelated edits do not.\n\n```toml\n# .squire/checks.toml\n[[check]]\nname = \"tests\"\ncommand = [\"go\", \"test\", \"./...\"]\ninputs = [\"**/*.go\", \"go.mod\", \"go.sum\"]\ntimeout = \"10m\"\n```\n\nRepository-provided commands never run silently on first use. Review the file\nand trust its exact hash once:\n\n```sh\nsquire green trust\nsquire verify\n```\n\nAny config change revokes trust. `squire codex` then schedules trusted checks\nautomatically; no second daemon or warm command is required. See\n[docs/GREEN.md](docs/GREEN.md) for configuration and proof semantics.\n\n## What It Accelerates\n\nProduction lanes are bounded but cover the common read-only command surface:\n\n- Git metadata: supported `git rev-parse` forms and branch discovery.\n- Repository reads: supported `git status`, `git ls-files`, and `git diff`\n  forms, including path-scoped diffs and `git diff --check`, plus bounded\n  `git log -N --oneline -- <literal paths>` history.\n- File and search reads: bounded `cat`, ordered single- or multi-range `sed -n`,\n  `head`, `tail`, `nl -ba`, `file`, fixed-string `grep`/`rg`, demand-prepared\n  bounded repository `rg` searches, and tight `ls` forms.\n- Environment discovery: supported version probes, `which`/`command -v`, safe\n  `printenv`, `whoami`, `id`, `hostname`, and `uname` forms.\n- Compositions: complete read-only plans over supported sources and filters,\n  including pipes, sequences, redirection to `/dev/null`, `head`, `tail`,\n  bounded `sed -n`, `grep -F`, `wc -l`, and `sort`.\n\nNo operation is removed. Builds, tests, edits, installs, mutating Git commands,\nexpansions, unknown shell syntax, sensitive probes, and unsupported variants\nimmediately follow Codex's unchanged native path. A safe cold miss does the\nsame while requesting exact preparation in the background. `rg --files`\nremains outside the bounded preparation policy and follows the native path.\n\nSupported commands compile into typed bounded plans rather than exact command\ntemplates. Source proof and execution are separate: one proven file snapshot\ncan serve different line selections, filters, and compositions without a cache\nentry for each command string. The same plan representation is implemented by\nthe Go engine and native runtime, keeping future read operators additive while\ndifferential tests enforce parity at the ABI boundary.\n\n## Why Hits Are Current\n\nSquire caches observations, not authority. A foreground replay either\nrecomputes the inputs that can affect that command or reuses a cryptographic\nfingerprint while a complete `kqueue`/`inotify` guard reports no dependency\nchange. The prepared epoch must still match. Proof inputs include the normalized\ncommand and cwd, Git refs/index/config and external behavior files, relevant\nworkspace state, canonical paths, content hashes, command-specific environment\nproof, and executable identity. Guard failure always invalidates the resident\nproof.\n\nFor bounded file reads, an epoch mismatch may instead use the current-file\nlane: Squire retains the exact bytes read while computing the foreground\nSHA-256 proof and applies only its fixed byte grammar to those bytes. This\nrequires no rewarm and does not persist the file or result. The cache may still\ncontain stale records, but they are never replayed after a proof mismatch.\nMissing state, corruption, unsupported syntax, an ABI mismatch, or an\nunprofitable proof all become native fallback.\n\nThe invalidation suite changes file bytes without changing size or mtime,\nmutates the Git index and untracked set, changes same-size diffs, edits Git\nconfig, commits, renames branches, changes loose and packed object namespaces,\nchanges environment inputs, and probes outside-workspace symlinks. Returning\nold bytes or an unsafe hit fails the release.\n\nSee [SQUIRE_CONTRACT.md](SQUIRE_CONTRACT.md) for the complete invariants.\n\n## Current Runtime Check\n\nOn July 16, 2026, a 500-command randomized production-ABI run recorded 421\nexact hits, 79 safe fallbacks, 468 native comparisons, zero mismatches, and\nzero unsafe hits. Hit p50/p95/p99 was `0.315/0.630/0.933ms`; the same commands\nran natively at `8.084/27.692/51.820ms`. A separate 500-query repository-search\ndifferential had 500 exact or order-equivalent hits and zero semantic\nmismatches. Bounded path history was 28/28 exact at `0.333ms` p50 and `0.492ms`\np99 versus `20.060ms` native p50. All 2,048 steady calls were exact with\n`0.433ms` wall p99. Under eight-way load, CPU p99 was `0.334ms`; scheduler-\ncontended wall p99 was `3.242ms`.\n\nFresh live `gpt-5.6-luna` treatments independently replayed 2/3 Express calls\n(`66.7%`), 5/5 Flask calls (`100%`), and 4/5 fmt calls (`80%`). Every treatment\npassed the `50%` all-terminal-call gate with valid accounting and zero\ndiagnostic mismatches. These small live samples validate coverage, not causal\nwhole-task wall time; model trajectories diverged before seeing tool results.\n\nA deterministic 40-pair Codex attribution test held model responses, commands,\nworkspace, and terminal payloads fixed. Six serial calls fell from `374.876ms`\nto `103.600ms`, saving `271.277ms` (`72.4%`, paired 95% interval\n`265.630-276.540ms`). Two parallel batches saved `52.6%`. AB and BA orders both\nremained positive, while interleaved A/A and B/B intervals included zero.\n\nFull methodology and historical tables: [docs/BENCHMARKS.md](docs/BENCHMARKS.md).\n\nArchitecture and backend notes: [docs/ADVANCED.md](docs/ADVANCED.md).\n",
  "bytes": 7339,
  "sha": "b56d9c506720f4643aca51af0c5a89cb608012a4f7a8eadfd3599ae51db95e5e",
  "repo_slug": "reidgoodbar/squire",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_reidgoodbar_squire_5bcd6e26/readme"
}