{"id":47245950,"url":"https://github.com/bilalimamoglu/sift","last_synced_at":"2026-04-01T20:46:18.330Z","repository":{"id":343232226,"uuid":"1176844695","full_name":"bilalimamoglu/sift","owner":"bilalimamoglu","description":"Turn noisy command output into a short, actionable first pass for coding agents.","archived":false,"fork":false,"pushed_at":"2026-03-23T23:37:54.000Z","size":1725,"stargazers_count":45,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-24T22:34:17.932Z","etag":null,"topics":["ai-agents","cli","coding-agents","command-line","debugging","developer-tools","heuristics","jest","llm","log-analysis","pytest","terminal","testing","vitest"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@bilalimamoglu/sift","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bilalimamoglu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-09T12:43:19.000Z","updated_at":"2026-03-24T15:34:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bilalimamoglu/sift","commit_stats":null,"previous_names":["bilalimamoglu/sift"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/bilalimamoglu/sift","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bilalimamoglu%2Fsift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bilalimamoglu%2Fsift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bilalimamoglu%2Fsift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bilalimamoglu%2Fsift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bilalimamoglu","download_url":"https://codeload.github.com/bilalimamoglu/sift/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bilalimamoglu%2Fsift/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291797,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","cli","coding-agents","command-line","debugging","developer-tools","heuristics","jest","llm","log-analysis","pytest","terminal","testing","vitest"],"created_at":"2026-03-14T06:08:40.084Z","updated_at":"2026-04-01T20:46:18.315Z","avatar_url":"https://github.com/bilalimamoglu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/brand/sift-logo-minimal-teal-default.svg\" alt=\"sift logo\" width=\"220\" /\u003e\n\n# sift\n\n### Turn noisy command output into a short, actionable first pass for your coding agent\n\n**Local heuristics first. Group repeated failures into likely root causes and next steps before your agent reads the full log.**\n\n[![npm version](https://img.shields.io/npm/v/@bilalimamoglu/sift)](https://www.npmjs.com/package/@bilalimamoglu/sift)\n[![license](https://img.shields.io/github/license/bilalimamoglu/sift)](LICENSE)\n[![CI](https://img.shields.io/github/actions/workflow/status/bilalimamoglu/sift/ci.yml?branch=main\u0026label=CI)](https://github.com/bilalimamoglu/sift/actions/workflows/ci.yml)\n[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)\n\n\u003cbr /\u003e\n\n### Get Started\n\n```bash\nnpm install -g @bilalimamoglu/sift\n```\n\n\u003csub\u003eBest today on noisy pytest, vitest, jest, `tsc`, ESLint, common build failures, `npm audit`, and `terraform plan` output.\u003c/sub\u003e\n\n\u003c/div\u003e\n\n---\n\n## Why Sift?\n\nWhen an agent hits noisy output, it can eventually make sense of the log wall, but it wastes time and tokens getting there.\n\n`sift` narrows that output locally first. It groups repeated failures, surfaces likely root causes, and points to the next useful step so your agent starts from signal instead of raw noise.\n\nIt is not a generic repo summarizer, not a shell telemetry product, and not a benchmark dashboard. It is a local-first triage layer for noisy command output in coding-agent workflows.\n\nTurn 13,000 lines of test output into 2 root causes.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/readme/test-status-demo.gif\" alt=\"sift turning a pytest failure wall into a short, actionable first pass\" width=\"960\" /\u003e\n\u003c/p\u003e\n\nWith `sift`, the same run becomes:\n\n```text\n- Tests did not pass.\n- 3 tests failed. 125 errors occurred.\n- Shared blocker: 125 errors share the same root cause - a missing test environment variable.\n  Anchor: tests/conftest.py\n  Fix: Set the required env var before rerunning DB-isolated tests.\n- Contract drift: 3 snapshot tests are out of sync with the current API or model state.\n  Anchor: tests/contracts/test_feature_manifest_freeze.py\n  Fix: Regenerate the snapshots if the changes are intentional.\n- Decision: stop and act.\n```\n\nIn one large `test-status` benchmark fixture, `sift` compressed 198,026 raw output tokens to 129. That is scoped proof for a noisy test-debugging case, not a promise that every preset behaves the same way.\n\n---\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g @bilalimamoglu/sift\n```\n\nRequires Node.js 20+.\n\n### 2. Try the main workflow\n\nIf you are new, start here and ignore hook beta and native surfaces for now:\n\n```bash\nsift exec --preset test-status -- pytest -q\n```\n\nOther common entry points:\n\n```bash\nsift exec --preset test-status -- npx vitest run\nsift exec --preset test-status -- npx jest\nsift exec \"what changed?\" -- git diff\n```\n\n### 3. Zoom only if needed\n\nThink of the workflow like this:\n\n- `standard` = map\n- `focused` = zoom\n- raw traceback = last resort\n\n```bash\nsift rerun\nsift rerun --remaining --detail focused\n```\n\nIf `standard` already gives you the likely root cause, anchor, and fix, stop there and act.\n\n---\n\n## Benchmark Results\n\nThe output reduction above measures a single command's raw output. The table below measures one replayed end-to-end debug loop: how many tokens, tool calls, and seconds the agent spent to reach the same outcome in that benchmarked scenario.\n\nReal debug loop on a 640-test Python backend with 124 repeated setup errors, 3 contract failures, and 511 passing tests:\n\n| Metric | Without sift | With sift | Reduction |\n|--------|-------------:|----------:|----------:|\n| Tokens | 52,944 | 20,049 | 62% fewer |\n| Tool calls | 40.8 | 12 | 71% fewer |\n| Wall-clock time | 244s | 85s | 65% faster |\n| Commands | 15.5 | 6 | 61% fewer |\n| Outcome | Same | Same | Same outcome |\n\nSame outcome, less agent thrash.\n\nMethodology and caveats: [BENCHMARK_NOTES.md](BENCHMARK_NOTES.md)\n\n---\n\n## How It Works\n\n`sift` keeps the explanation simple:\n\n1. **Capture output.** Run the noisy command or accept already-existing piped output.\n2. **Run local heuristics.** Detect known failure shapes first so common cases stay cheap and deterministic.\n3. **Return a useful first pass.** When heuristics are confident, `sift` gives the agent grouped failures, likely root causes, and the next step.\n4. **Fall back only when needed.** If heuristics are not enough, `sift` uses a cheaper model instead of spending your main agent budget.\n\nYour agent spends tokens fixing, not reading.\n\n---\n\n## Key Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### Test Failure Guidance\nCollapse repeated pytest, vitest, and jest failures into grouped issues with likely root causes, anchors, and fix hints.\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### Typecheck and Lint Guidance\nGroup noisy `tsc` and ESLint output into the few issues that actually matter instead of dumping the whole log back into the model.\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### Build Failure Extraction\nPull out the first concrete error from webpack, esbuild/Vite, Cargo, Go, GCC/Clang, and similar build output.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### Audit and Infra Risk\nSurface high-impact `npm audit` findings and destructive `terraform plan` signals without making the agent read everything.\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### Heuristic-First by Default\nEvery built-in preset tries local parsing first. When the heuristic handles the output, no provider call is needed.\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\n### Agent and Automation Friendly\nUse `sift` in Codex, Claude, CI, hooks, or shell scripts when you want downstream tooling to receive a short first pass instead of the raw log wall.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Presets\n\n| Preset | What it does | Needs provider? |\n|--------|--------------|:---------------:|\n| `test-status` | Groups pytest, vitest, and jest failures into root-cause buckets with anchors and fix suggestions. | No |\n| `typecheck-summary` | Parses `tsc` output and groups issues by error code. | No |\n| `lint-failures` | Parses ESLint output and groups failures by rule. | No |\n| `build-failure` | Extracts the first concrete build error from common toolchains. | Fallback only |\n| `contract-drift` | Detects explicit snapshot, golden, OpenAPI, manifest, or generated-artifact drift without broadening into generic repo analysis. | Fallback only |\n| `audit-critical` | Pulls high and critical `npm audit` findings. | No |\n| `infra-risk` | Detects destructive signals in `terraform plan`. | No |\n| `diff-summary` | Summarizes change sets and likely risks in diff output. | Yes |\n| `log-errors` | Extracts the strongest error signals from noisy logs. | Fallback only |\n\nWhen output already exists in a pipeline, use pipe mode instead of `exec`:\n\n```bash\npytest -q 2\u003e\u00261 | sift preset test-status\nnpm audit 2\u003e\u00261 | sift preset audit-critical\n```\n\n---\n\n## Setup and Agent Integration\n\nIf you want deeper integration after the first successful `sift exec` run, start with:\n\n```bash\nsift install\n```\n\nMost built-in presets run entirely on local heuristics with no API key required. If you want deeper fallback for ambiguous cases, `sift` also supports OpenAI-compatible and OpenRouter-compatible endpoints.\n\nDuring install, pick the mode that matches reality:\n- `agent-escalation`: `sift` gives the first answer, then your agent keeps going\n- `provider-assisted`: `sift` itself can ask a cheap fallback model when needed\n- `local-only`: keep everything local\n\nRuntime-native files are small guidance surfaces, not a second execution system:\n- Codex: managed `AGENTS.md` block plus a generated `SKILL.md`\n- Claude: managed `CLAUDE.md` block plus a generated `.claude/commands/sift/` command pack\n- Cursor: optional `.cursor/skills/sift/SKILL.md` path when you want an explicit native Cursor skill\n\nDefault rule:\n- use `sift exec` for the normal first pass\n- use `sift hook` only as an optional beta shortcut for a tiny known-command set\n\nOptional local evidence surfaces:\n\n```bash\nsift gain\nsift discover\n```\n\n- `gain` shows local, metadata-only first-pass history\n- `discover` stays quiet unless your own local history is strong enough to justify a concrete suggestion\n\nIf you want the full install, ownership, and touched-files details, see [docs/cli-reference.md](docs/cli-reference.md). The short version: `sift` does **not** write shell rc files, PATH entries, git hooks, or arbitrary repo files during install.\n\nIf you want this repo's tracked pre-push verification hook to actually run on your machine, you still need to activate it once:\n\n```bash\nnpm run setup:hooks\n```\n\n---\n\n## Test Debugging Workflow\n\nFor noisy test failures, start with the `test-status` preset and let `standard` be the default stop point.\n\n```bash\nsift exec --preset test-status -- \u003ctest command\u003e\nsift rerun\nsift rerun --remaining --detail focused\nsift rerun --remaining --detail verbose --show-raw\n```\n\nUseful rules of thumb:\n\n- If `standard` ends with `Decision: stop and act`, go read source and fix the issue.\n- Use `sift rerun` after a change to refresh the same test command at `standard`.\n- Use `sift rerun --remaining` to zoom into what still fails after the first pass.\n- Treat raw traceback as the last resort, not the starting point.\n\nFor machine branching or automation, `test-status` also supports diagnose JSON:\n\n```bash\nsift exec --preset test-status --goal diagnose --format json -- pytest -q\nsift rerun --goal diagnose --format json\n```\n\nDiagnose JSON is summary-first on purpose. If `read_targets.anchor_kind=traceback` and `read_targets.context_hint.kind=exact_window`, read that narrow range first. If the read target is lower-confidence or `search_only`, treat it as a representative hint rather than exact root-cause proof.\n\n---\n\n## Limitations\n\n- sift adds the most value when output is long, repetitive, and shaped by a small number of root causes. For short, obvious failures it may not save much.\n- The deepest local heuristic coverage is in test debugging (pytest, vitest, jest). Other presets have solid heuristics but less depth.\n- sift does not help with interactive or TUI-based commands.\n- sift is not a generic repo summarizer or broad mismatch detector. It works best when the command output itself carries strong failure or drift evidence.\n- When heuristics cannot explain the output confidently, sift either falls back to a provider or returns the strongest local first pass it can, depending on how you choose to use it.\n\n---\n\n## Docs\n\n- CLI reference: [docs/cli-reference.md](docs/cli-reference.md)\n- Worked examples: [docs/examples](docs/examples)\n- Benchmark methodology: [BENCHMARK_NOTES.md](BENCHMARK_NOTES.md)\n- Contributing and development notes: [CONTRIBUTING.md](CONTRIBUTING.md)\n- Release notes: [release-notes](release-notes)\n\n---\n\n## License\n\nMIT\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nLocal-first output guidance for coding agents.\n\n[Report Bug](https://github.com/bilalimamoglu/sift/issues) | [Request Feature](https://github.com/bilalimamoglu/sift/issues)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbilalimamoglu%2Fsift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbilalimamoglu%2Fsift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbilalimamoglu%2Fsift/lists"}