{"id":50325299,"url":"https://github.com/testy-cool/ai-cli-utils","last_synced_at":"2026-05-29T05:30:59.124Z","repository":{"id":351040636,"uuid":"1209300821","full_name":"testy-cool/ai-cli-utils","owner":"testy-cool","description":"Shell tools augmented with LLM inference. Find relevant files, diagnose errors, summarize diffs — deterministic-first, LLM-second.","archived":false,"fork":false,"pushed_at":"2026-04-13T10:10:16.000Z","size":18,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T11:34:47.007Z","etag":null,"topics":["ai","bash","cli","coreutils","developer-tools","devtools","gemini","llm","openai","shell"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/testy-cool.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-13T09:36:56.000Z","updated_at":"2026-04-13T10:10:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/testy-cool/ai-cli-utils","commit_stats":null,"previous_names":["testy-cool/ai-cli-utils"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/testy-cool/ai-cli-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Fai-cli-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Fai-cli-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Fai-cli-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Fai-cli-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/testy-cool","download_url":"https://codeload.github.com/testy-cool/ai-cli-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testy-cool%2Fai-cli-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33639050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","bash","cli","coreutils","developer-tools","devtools","gemini","llm","openai","shell"],"created_at":"2026-05-29T05:30:58.494Z","updated_at":"2026-05-29T05:30:59.118Z","avatar_url":"https://github.com/testy-cool.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ai-cli-utils\n\n\u003e **7 Unix tools, augmented with LLM inference.** Find relevant files, diagnose errors, summarize diffs, understand codebases, compress logs, inspect running processes — in 1-3 seconds.\n\n```bash\nrelevant \"fix the login bug\"           # → ranked list of files to look at\nnpm install 2\u003e\u00261 | why                 # → root cause + exact fix command\ndiffsummary                            # → structured change summary + commit titles\ndigest src/ \"how does billing work\"    # → targeted answer from codebase\njournalctl --since \"1h ago\" | sumlog   # → anomalies + pattern summary\nwtf :3000                             # → what's on port 3000\n```\n\n**No agents. No loops. No conversations.** Each tool gathers facts with standard shell commands, pipes them to a cheap LLM, and prints a structured result.\n\n---\n\n## Tools\n\n### `relevant` — find files relevant to a task\n\n```bash\n$ relevant \"fix the login bug\" ./src\nsrc/auth/login.ts — handles credential exchange\nsrc/middleware/session.ts — validates session tokens\ntests/auth/login.test.ts — existing login test coverage\nprisma/schema.prisma — user/session model definitions\n```\n\nHow it works: runs `tree` + `find` (filename matching) + `rg` (content grep) + recently modified files, then asks the LLM to rank by relevance. Only returns files it actually found — never hallucinates paths.\n\n### `why` — diagnose errors\n\n```bash\n$ python3 app.py 2\u003e\u00261 | why\n[dependency] The pandas library is not installed in the current environment.\nConfidence: high\nFix: Install the missing dependency.\nRun: pip install pandas\n```\n\nClassifies errors (dependency, typecheck, permission, port conflict, etc.), extracts the root cause (not the last noisy line), and gives you the exact next command to run.\n\n### `diffsummary` — structured diff analysis\n\n```bash\n$ diffsummary HEAD~3\nFILES CHANGED:\n- auth.py: Replaced hardcoded login with hash-based credential check\n\nBEHAVIOR CHANGES:\n- Login now returns a token instead of a boolean\n\nAPI CHANGES:\n- login(): return type changed from bool to dict\n\nRISK AREAS:\n- Existing callers expecting bool from login() will break\n\nCOMMIT TITLE:\n- Upgrade authentication to use hashed credentials\n```\n\nWorks with: `diffsummary` (unstaged), `diffsummary HEAD~N` (commit range), `git diff branch | diffsummary` (piped).\n\n### `lt` — tree with per-directory limits\n\n```bash\n$ lt /var/log\n├── nginx/\n│   ├── access.log\n│   ├── error.log\n│   └── ... +12 more\n├── syslog\n└── auth.log\n```\n\nLike `tree` but caps each directory at 30 entries. No LLM — pure Python.\n\n### `digest` — understand large files or directories via LLM\n\n```bash\n$ digest app.py\nPURPOSE: Flask web app serving a REST API for user management\nSTACK: Python 3.11, Flask, SQLAlchemy, PostgreSQL\nENTRYPOINTS: app.py (gunicorn), cli.py (management commands)\nKEY COMPONENTS:\n- routes/users.py — CRUD endpoints for /api/users\n- models/user.py — User model with role-based permissions\n- middleware/auth.py — JWT validation on protected routes\n\n$ digest app.py \"where's the auth\"\nAuth is handled in middleware/auth.py. Every route decorated with\n@require_auth calls validate_jwt(), which checks the Authorization\nheader against the HMAC secret in config.py. Token expiry is 24h.\n\n$ digest src/ \"how does billing work\"\nBilling flows through three files: routes/billing.py receives\nStripe webhooks, services/subscription.py manages plan changes,\nand models/invoice.py tracks payment history. Monthly charges\nare triggered by a cron job in tasks/billing_cycle.py.\n```\n\nUses proxy-flash (larger context model) since it handles big inputs.\n\n### `sumlog` — compress logs and surface anomalies\n\n```bash\n$ sumlog /var/log/syslog\nTOP ANOMALIES:\n1. [URGENT] OOM killer invoked 3 times (PIDs 4821, 4833, 4901) — system under memory pressure\n2. [WARN] nginx worker crashed and respawned 12 times in 30min — check upstream timeouts\n3. [INFO] 847 repeated cron entries collapsed — normal but noisy\n\nPATTERN SUMMARY:\n- 1,204 lines → 38 unique patterns\n- 96% routine (cron, dhclient renewals, systemd slice management)\n- 4% anomalous (OOM, nginx crashes, disk I/O errors)\n\n$ journalctl --since \"1h ago\" | sumlog\nTOP ANOMALIES:\n1. [WARN] docker healthcheck failing for container redis-cache — 8 consecutive failures\n2. [INFO] USB device disconnect/reconnect cycle on bus 002 — possibly loose cable\n\n$ sumlog -n 500 /var/log/syslog\n(analyzes last 500 lines only)\n```\n\nDeduplicates and pattern-collapses BEFORE the LLM call. Surfaces top 3-5 anomalies and flags urgent items.\n\n### `wtf` — runtime inspector\n\n```bash\n$ wtf :3000\nPORT 3000: node /home/user/app/server.js (PID 14229, user: deploy)\nListening on 0.0.0.0:3000 (TCP, LISTEN)\nStarted: 2 days ago — 142MB RSS, 0.3% CPU\nThis is a Node.js HTTP server. It's bound to all interfaces,\nso it's accessible from the network, not just localhost.\n\n$ wtf pid 1234\nPROCESS 1234: postgres: writer process (PID 1234, user: postgres)\nPart of PostgreSQL cluster, responsible for writing dirty buffers\nto disk. Parent PID 1200 (postmaster). Running since boot, normal.\n\n$ wtf service postgres\nSERVICE postgresql.service: active (running) since 3 days ago\nMain PID: 1200, 14 child processes (workers, writer, checkpointer)\nListening on: 127.0.0.1:5432\nMemory: 248MB — healthy, no recent restarts or failures.\n\n$ wtf path ./tmp/socket\nPATH ./tmp/socket: Unix domain socket, type=STREAM\nOwned by PID 8821 (gunicorn: master [app:create_app()])\n3 connected peers — this is the gunicorn worker socket.\n```\n\nAuto-detects query type (bare number = pid, starts with `:` = port, file path = path, otherwise tries service). Gathers facts from ss/lsof/ps/systemctl first, then the LLM explains.\n\n---\n\n## Install\n\n```bash\ngit clone https://github.com/testy-cool/ai-cli-utils.git\ncd ai-cli-utils\n\n# Symlink into your PATH\nfor tool in relevant why diffsummary digest sumlog wtf; do\n  ln -sf \"$(pwd)/$tool\" ~/.local/bin/$tool\ndone\nln -sf \"$(pwd)/lt.py\" ~/.local/bin/lt.py\n```\n\n### Requirements\n\n- [llm](https://github.com/simonw/llm) CLI with any model configured\n- `tree`, `rg` (ripgrep) — for `relevant`\n- `git` — for `diffsummary`\n- `ss`, `lsof`, `ps`, `systemctl` — for `wtf`\n- Python 3 — for `lt`\n\n### LLM setup\n\nThese tools call `llm` with whatever default model you've configured. Any backend works:\n\n```bash\n# Gemini (recommended — cheapest)\nllm install llm-gemini \u0026\u0026 llm keys set gemini \u0026\u0026 llm models default gemini-2.0-flash-lite\n\n# OpenAI\nllm keys set openai \u0026\u0026 llm models default gpt-4o-mini\n\n# Local via Ollama\nllm install llm-ollama \u0026\u0026 llm models default llama3\n\n# Any OpenAI-compatible proxy (LiteLLM, vLLM, etc.)\n# See: https://llm.datasette.io/en/stable/other-models.html\n```\n\nA fast, cheap model is recommended. These tools don't need frontier intelligence — they need speed.\n\n---\n\n## Design\n\n```\nshell commands (tree, rg, find, git diff)\n        │\n        ▼\n   deterministic facts (file lists, grep matches, diff text)\n        │\n        ▼\n   LLM inference (rank, diagnose, summarize)\n        │\n        ▼\n   structured output\n```\n\n**Deterministic-first, LLM-second.** The LLM never sees data it didn't get from shell commands, so it can't hallucinate file paths or invent errors. Each tool is a single `llm` call — no agents, no retries, no conversation state.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftesty-cool%2Fai-cli-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftesty-cool%2Fai-cli-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftesty-cool%2Fai-cli-utils/lists"}