{"id":49416313,"url":"https://github.com/parthalon025/senex","last_synced_at":"2026-04-29T03:08:42.211Z","repository":{"id":354089274,"uuid":"1222105134","full_name":"parthalon025/senex","owner":"parthalon025","description":"Local-LLM code audit tool: file-by-file repository audits using LM Studio with GitNexus graph awareness, integrated TUI, and Claude Code handoff","archived":false,"fork":false,"pushed_at":"2026-04-27T04:58:18.000Z","size":159,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T05:26:27.796Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parthalon025.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-27T03:38:24.000Z","updated_at":"2026-04-27T04:58:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/parthalon025/senex","commit_stats":null,"previous_names":["parthalon025/senex"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/parthalon025/senex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parthalon025%2Fsenex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parthalon025%2Fsenex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parthalon025%2Fsenex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parthalon025%2Fsenex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parthalon025","download_url":"https://codeload.github.com/parthalon025/senex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parthalon025%2Fsenex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32408504,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T02:37:21.628Z","status":"ssl_error","status_checked_at":"2026-04-29T02:36:50.947Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":[],"created_at":"2026-04-29T03:08:41.534Z","updated_at":"2026-04-29T03:08:42.206Z","avatar_url":"https://github.com/parthalon025.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# senex\n\nLocal-LLM repository audit tool. Audits a target repository file by file using a thinking-MoE\nmodel running in LM Studio, with GitNexus as background graph awareness. Produces per-file\nMarkdown reports, a combined run report, a `findings.json` machine index, and a Claude Code\nhandoff artifact.\n\nsenex is a local-first tool: source code never leaves the machine, no telemetry, secret\nredaction is applied to every persisted artifact. See \"Security\" below.\n\n---\n\n## Overview\n\nsenex pairs a small local thinking model (default: `google/gemma-4-26b-a4b` in LM Studio)\nwith a 6-tool framework (`gitnexus_query`, `gitnexus_context`, `gitnexus_impact`, `read_file`,\n`grep`, `search_code`), context compaction safety, and a streaming Textual TUI. Each file\nin the audited repo gets one model turn (with optional tool calls). Findings are aggregated\ninto a stable `findings.json` and a human-readable `combined.md`; a final `claude-handoff.md`\nsummarizes hot spots for downstream work in Claude Code.\n\n## Prerequisites\n\n- **Windows 10/11** (Linux/macOS supported but the scheduled-task scripts are Windows-only).\n- **Python 3.11+** (3.13 supported and recommended).\n- **LM Studio** — download from \u003chttps://lmstudio.ai\u003e. Load `google/gemma-4-26b-a4b`\n  before running the audit (or set `[lmstudio.lifecycle].auto_load = true` for senex\n  to load it for you).\n- **GitNexus** (optional but strongly recommended) — provides the graph context block\n  prepended to every per-file prompt. Install with `npx gitnexus init` in the audited\n  repo. Without it, senex still runs but with degraded context.\n- **`gh`** (optional) — for the v1.0.0 release flow only.\n\n## Install\n\n### Windows (one-liner)\n\n```powershell\ngit clone https://github.com/parthalon025/senex.git\ncd senex\n.\\scripts\\setup.ps1\n```\n\n`setup.ps1` creates `.venv`, runs `pip install -e .`, verifies `senex --version`, and\nprints next steps.\n\n### Manual (any platform)\n\n```bash\ngit clone https://github.com/parthalon025/senex.git\ncd senex\npython -m venv .venv\n.venv\\Scripts\\activate     # PowerShell: . .\\.venv\\Scripts\\Activate.ps1\npython -m pip install --upgrade pip\npython -m pip install -e .\nsenex --version\n```\n\n## Configure\n\nCopy the example to the working file and edit:\n\n```powershell\ncopy senex.config.toml.example senex.config.toml\nnotepad senex.config.toml\n```\n\nMinimum edits to ship:\n\n1. **`[lmstudio].base_url`** — leave at `http://localhost:1234/v1` unless you bind LM\n   Studio elsewhere.\n2. **`[lmstudio].model`** — the loaded model id (default: `google/gemma-4-26b-a4b`).\n3. **`[[repos]]`** — at least one `name` + absolute `path` entry. `senex audit --nightly`\n   iterates every entry; ad-hoc runs target a single repo by argument.\n\n## LM Studio setup\n\nsenex talks to LM Studio's local OpenAI-compat API. Two things must be done in the\nLM Studio UI before every audit (they persist across restarts once configured):\n\n### 1. Enable the local server\n\nOpen LM Studio → click the **server icon** in the left sidebar (or go to the\n**Developer** tab) → click **Start Server**. The default address is\n`http://localhost:1234`; leave it unless you also change `[lmstudio].base_url`.\n\n\u003e If the server is not running, `senex doctor` reports `lmstudio_reachable: fail`\n\u003e and the audit exits with code 3.\n\n### 2. Load the model\n\nIn LM Studio, search for and load the model whose **identifier matches exactly**\nwhat you have in `[lmstudio].model` (default: `google/gemma-4-26b-a4b`). The\nidentifier must match byte-for-byte; senex compares it against `/v1/models` at\npreflight.\n\nIf you set `[lmstudio.lifecycle].auto_load = true`, senex will load/unload the\nmodel automatically via the `lmstudio` Python SDK or the `lms` CLI — whichever\nis available. The `lmstudio` SDK ships with the Python package; the `lms` CLI\nrequires a separate install from lmstudio.ai.\n\n\u003e Model not loaded + `auto_load = false` → `model_loaded: fail`, exit code 3.\n\n### 3. Set context length before the first run (required)\n\nLM Studio's default context window is **262 144 tokens**. At that size the\nKV cache alone consumes ~24 GB of VRAM on gemma-4-26b and the model will fail\nto load on most hardware. **Change it to 16384 or 32768** in the model's\nload settings before starting the server.\n\nTo change it: in LM Studio, open the loaded model's settings panel →\n**Context Length** → type `16384` → reload the model.\n\nAlso set this in `senex.config.toml` so the two values stay in sync:\n\n```toml\n[lmstudio]\ncontext_window = 16384   # must match what you set in LM Studio\n```\n\n### 4. Recommended one-time settings\n\n| LM Studio setting | Recommended value | Why |\n|---|---|---|\n| **Context Length** | 16384 or 32768 | Reduces KV-cache VRAM from ~24 GB to ~2–4 GB |\n| **Parallel requests** | 1 | Each slot reserves KV cache headroom; use 4 only if VRAM allows |\n| **Flash Attention v2** | On | KV cache compression; enable if your model supports it |\n| **Speculative decoding** | On | 1.5–3× speedup; enable if available for your model |\n| **GPU offload** | Max layers that fit | Any layer offloaded to CPU degrades throughput |\n\nThese settings persist per-model in LM Studio and do not need to be changed on\nsubsequent runs unless you switch models.\n\n---\n\n## Run\n\n```powershell\nsenex audit                                 # interactive launcher wizard\nsenex audit C:\\path\\to\\your\\repo            # direct TUI launch\nsenex audit C:\\path\\to\\your\\repo --no-tui   # headless (stdout progress)\nsenex audit --nightly                       # iterate every [[repos]]\nsenex audit C:\\path\\to\\your\\repo --resume   # continue an interrupted run\nsenex audit --no-wizard                     # error: requires a positional path\n```\n\nRun `senex audit` with no path to launch the interactive wizard. The wizard\nwalks you through repo selection (from `[[repos]]`, on-disk discovery, or a\ncustom path), model selection (probed live from `GET /v1/models`), and a\nhandful of yes/no prompts before handing off to the TUI or headless flow.\nPass `--no-wizard` to disable it (a positional path is then required) — useful\nfor scripts and CI.\n\nInside the TUI Launcher screen, the **Scan disk for repos** button performs\nthe same on-disk discovery without leaving the UI — found repos are appended\nto the configured-repos dropdown, deduplicated against any already-listed\npaths. Tune the scan via `[ui].scan_root` (defaults to your home directory)\nand `[ui].scan_max_depth` (default 6) in `senex.config.toml`.\n\nScheduled-task entrypoint for Windows Task Scheduler: `scripts\\run_senex.bat`. It\nactivates the venv and runs `python -m senex audit --nightly`.\n\n## View results\n\n```powershell\nsenex view                                 # latest audit (auto-detect)\nsenex view \u003caudit-dir\u003e                     # specific run\nsenex view \u003caudit-dir\u003e --speed 10.0        # 10x replay\n```\n\nThe replay does not call LM Studio; it reads `events.jsonl` from the audit dir and\nre-renders the Monitor screen offline.\n\n## Diagnostics\n\n```powershell\nsenex doctor                               # check every [[repos]] entry\nsenex doctor C:\\path\\to\\your\\repo          # single repo\nsenex doctor --json                        # CI-friendly output\nsenex lifecycle status                     # loaded models + runlock holders\nsenex lifecycle clear-locks                # prune stale-PID holders\nsenex config show C:\\path\\to\\your\\repo     # resolved config (TOML)\nsenex aggregate \u003caudit-dir\u003e                # re-run Phase 5 after a crash\n```\n\nRun `senex doctor` once after install. Every check should return `pass` or `warn`;\n`fail` exits non-zero and prints the failing check's diagnostic.\n\n## Performance tuning\n\nsenex's per-file audit time is dominated by model thinking. With\n`google/gemma-4-26b-a4b` at default settings, expect **~7-8 minutes per file**\non `effort=high`. Two axes to tune.\n\n### LM Studio (GUI knobs — frees GPU VRAM)\n\n| Knob | Default | Recommended start | Effect |\n|------|---------|-------------------|--------|\n| **Context length** | 262144 | **16384** or **32768** | Largest single VRAM win — KV cache scales with context; senex prompts are \u003c16K tokens |\n| **GPU offload** | All layers | All if you have headroom | Off-loaded layers run on CPU (slower but frees VRAM) |\n| **Concurrent requests (`parallel`)** | 4 | **1** if VRAM-constrained, **4** if you want to enable senex's future parallel-files feature | Each parallel slot reserves KV cache headroom |\n| **Speculative decoding** | varies | enable if available | 1.5-3× speedup with negligible quality loss |\n| **Flash Attention v2** | varies | enable | KV cache compression |\n\n### senex (config knobs — shapes what senex requests)\n\n```toml\n# senex.config.toml\n[lmstudio]\n# Should match (or be slightly under) LM Studio's context length.\ncontext_window = 16384\n# Set true ONLY for OpenAI/Together/Groq backends that honor strict json_schema\n# reliably. False (default) routes through json_object + post-hoc Pydantic\n# validation, which is what gemma-class models actually return correctly.\nstrict_json_schema = false\n\n[lmstudio.sampling]\nmax_tokens = 4096   # output cap; lower = faster, less KV growth\n\n[lmstudio.thinking]\n# \"high\" -\u003e deep reasoning, ~7-8 min/file\n# \"medium\" -\u003e balanced, ~3-4 min/file\n# \"low\" -\u003e shallow, ~1-2 min/file (fine for first-pass triage)\neffort = \"high\"\nmax_thinking_tokens = 8192   # cap on reasoning phase\n```\n\n### Estimated audit time by configuration\n\n| Config | Per-file | 50-file project | 500-file project |\n|--------|---------:|----------------:|-----------------:|\n| Default (`effort=high`, 8K thinking, 4K output) | ~7-8 min | 6.5 hr | 64 hr |\n| `effort=low`, 2K thinking | ~1-2 min | 1 hr | 11 hr |\n\nFor nightly Windows scheduled-task usage on real repos, `effort=low` + small\nthinking budget is usually the right tradeoff. For spot audits of critical\nfiles, run with `effort=high` directly.\n\n## Where reports go\n\n```\nE:\\senex-audits\\\u003crepo-name\u003e\\\u003cDATE\u003e-\u003crun_id_short\u003e\\\n├── combined.md                # human-readable run report\n├── findings.json              # stable machine index (schema-validated)\n├── claude-handoff.md          # downstream summary for Claude Code\n├── events.jsonl               # canonical event stream (replay source)\n├── checkpoint.json            # resume state machine\n├── audit.log                  # human-readable log\n├── config.snapshot.toml       # resolved config (TOCTOU defense)\n├── findings.partial.jsonl     # streaming append (input to Phase 5)\n└── \u003crelpath\u003e.md               # per-file report (one per audited file)\n└── \u003crelpath\u003e.thinking.md      # per-file thinking trace (when enabled)\n```\n\nThe output root is configurable via `[output].root` (default: `E:\\senex-audits`).\n\n## Security\n\n- **Source stays local.** senex's only outbound network calls are to `localhost`\n  (LM Studio HTTP) and local subprocesses (`npx gitnexus`, `lms`). No telemetry,\n  no third-party APIs.\n- **Loopback-only by default.** Non-loopback `[lmstudio].base_url` requires explicit\n  `[lmstudio].allow_non_loopback = true`.\n- **Secret redaction is on by default.** Every persisted artifact (`\u003cfile\u003e.md`,\n  `combined.md`, `claude-handoff.md`, `events.jsonl`, `audit.log`, `config.snapshot.toml`)\n  passes through the SecretRedactor: PEM blocks, JWTs, AWS access keys, GitHub PATs,\n  `sk-...` style LLM keys, and generic `KEY=value` env-style secrets are masked.\n  Disable only for transient debugging via `[output].redact_secrets = false`.\n- **Trust boundaries.** Audited source is wrapped in `\u003cUNTRUSTED_FILE_CONTENT\u003e...\n  \u003c/UNTRUSTED_FILE_CONTENT\u003e` before LLM ingestion; the system prompt instructs the\n  model to disregard directives within. Tool-call inputs are path-validated and\n  regex-capped per spec section 5.11.4.\n- **Checkpoint integrity.** `checkpoint.json` carries an HMAC over the resume hash\n  bundle (`config_hash`, `prompt_hash`, `model_fingerprint`, `tool_pack_hash`,\n  `lens_version`). Resume is refused on hash drift unless `--allow-mixed-resume`\n  is set.\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| `doctor` reports `lmstudio_reachable: fail` | LM Studio not running | Launch LM Studio and load the configured model. |\n| `doctor` reports `model_loaded: fail` | Wrong model id | Update `[lmstudio].model` in `senex.config.toml`. |\n| `doctor` reports `gitnexus_index: warn` | Repo not indexed | `cd \u003crepo\u003e \u0026\u0026 npx gitnexus analyze`. Audit still runs without it. |\n| Audit aborts immediately | Bad config / repo path | Run `senex doctor` first; fix the failing checks. |\n| Resume rejected: hash mismatch | Config or prompts changed since the original run | Use `--allow-mixed-resume` (advanced) or start a fresh run. |\n| Stale runlock blocks startup | Prior crash left a holder | `senex lifecycle clear-locks` (use `--force` only for live PIDs). |\n| `combined.md` missing after run | Aggregation phase crashed | `senex aggregate \u003caudit-dir\u003e` to retry. |\n\n## License \u0026 contribution\n\nLicense: TBD (see `LICENSE` at repo root once added). Contributions: please open\nan issue or PR; conventions live in `docs/superpowers/conventions.md`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparthalon025%2Fsenex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparthalon025%2Fsenex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparthalon025%2Fsenex/lists"}