hydra-nano 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rahul05ranjan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rahul05ranjan/hydra/main/assets/hydra-banner.svg" alt="Hydra: small local models that take the noisy work off your coding agent" width="100%">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.npmjs.com/package/hydra-nano"><img src="https://img.shields.io/npm/v/hydra-nano?color=7c5cff&label=npm" alt="npm version"></a>
+  <a href="https://huggingface.co/rahul05ranjan/hydra-nano-git"><img src="https://img.shields.io/badge/model-Hydra%20Nano%20v2-22d3ee" alt="Hydra Nano v2 on Hugging Face"></a>
+  <img src="https://img.shields.io/badge/runs-100%25%20local-5eead4" alt="Runs 100% local">
+  <img src="https://img.shields.io/badge/node-%E2%89%A518-3c873a" alt="Node 18 or later">
+  <a href="https://github.com/rahul05ranjan/hydra/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <b>Your coding agent reads every line of every test log, git diff and process list it runs.<br>Hydra reads them on your machine and hands back only the lines that matter.</b>
+</p>
+
+---
+
+## Why Hydra
+
+Frontier coding agents pay for every token of tool output: a failing test suite, a long `git log`, a `ps` dump. Most of it is noise, and all of it fills the context window.
+
+Hydra puts small specialist models on your own machine between the agent and that output:
+
+- **Less context, same answer.** A `pnpm test` run that printed ~13,807 tokens reached the agent as ~57: the failing test, the assertion diff and the source line.
+- **Nothing leaves your machine.** The model runs locally on llama.cpp. Hydra's telemetry stays in `~/.hydra/ledger.jsonl`.
+- **Read-only by design.** The model never writes a shell command. It picks from fixed, read-only menus; code builds and runs the command.
+- **Verbatim, not paraphrased.** Hydra returns the command's own lines, so the agent sees evidence, not a summary.
+
+## Quick start
+
+```bash
+npx hydra-nano
+```
+
+One command installs everything: a pinned llama.cpp runtime, the ~812 MB Hydra Nano model (SHA-256 checked), the Hydra skill, and the integration for each coding tool it finds.
+
+Want the `hydra` command in your own terminal too?
+
+```bash
+npm install -g hydra-nano
+hydra doctor
+```
+
+Requires Node 18+. Runtime packages for macOS, Linux and Windows on x64 and arm64; verified live on macOS and Windows. Prefer GitHub? `npx github:rahul05ranjan/hydra` installs the same thing.
+
+## Works with your coding tools
+
+| Tool | How Hydra joins | Status |
+|---|---|---|
+| **Claude Code** | Skill + hooks that route test/build runs and git questions | Tested |
+| **Codex** | Skill + MCP server + `PreToolUse` hook | MCP listed by Codex; trust the hook with `/hooks` |
+| **OpenCode** | MCP server + plugin | MCP connects |
+| **Cursor** | MCP server + `beforeShellExecution` hook | Preview |
+| **Gemini CLI** | MCP server + `BeforeTool` hook | Preview |
+| **Antigravity** | Skill + MCP server | Preview |
+
+Any other tool that speaks MCP can use Hydra too: point it at `hydra mcp` (stdio).
+
+Hydra never overwrites your settings. Every file it edits is backed up once as `<file>.before-hydra`, only Hydra's own entries change, and `hydra agents remove` takes them out again.
+
+## What it does
+
+| Head | Ask it | It returns |
+|---|---|---|
+| **git** | "what changed in the last commit?", "who last touched `billing.js`?" | The matching commits, diff hunks or blame lines |
+| **test** | `hydra run -- npm test` (pytest, cargo, go, tsc, gradle, ...) | Failing test names, assertion diffs and source locations, with the original exit code |
+| **os** | "what is listening on port 3000?" | The matching ports, processes or disk lines, with secrets blocked |
+| **read** | `hydra read src/server.ts handleRequest` | One symbol, a line range or an outline |
+| **files** | `hydra search parseConfig` | Definition-ranked matches |
+
+Through MCP, Hydra offers the three where it pays most: `hydra_git`, `hydra_run` and `hydra_os`.
+
+## Benchmarks
+
+**Hydra Nano v2**: a full-parameter fine-tune of a 0.8B model, one set of weights for every head, run as a Q8_0 GGUF.
+
+| Set | Tasks | Solved |
+|---|---|---|
+| Git (sealed test set, never used for training) | 1,000 | **96.3%** |
+| Files (held out) | 1,000 | **98.0%** |
+| Read (held out) | 1,000 | **96.1%** |
+| Test logs (second held-out set) | 1,000 | **97.5%** |
+| OS (held out, synthetic probe outputs) | 1,000 | **100%** |
+| Test-log benchmark across 8 frameworks | 20 | **19/20**, 47% fewer tokens |
+
+Receipts: [model card](https://huggingface.co/rahul05ranjan/hydra-nano-git) and [`evals/results`](https://github.com/rahul05ranjan/hydra/tree/main/evals/results).
+
+**Where Hydra does not help, measured.** In a controlled trial of 36 Claude Code sessions extracting functions from real source code, forcing that work through Hydra used **72% more tokens** than the agent's own tools. So Hydra leaves source reading and search to the agent, and routes only the noisy work: test and build logs, git history, system inspection. Full method and numbers in [evaluations](https://github.com/rahul05ranjan/hydra/blob/main/docs/evaluations.md).
+
+## Commands
+
+```bash
+hydra ask "which branch am I on and what changed?"   # git, files or os, routed by the question
+hydra run -- pytest -q                               # a test or build run, digested
+hydra os "what is using port 8080?"                  # read-only system inspection
+hydra read src/app.py create_app                     # one symbol, a line range or an outline
+hydra stats                                          # tokens kept out of context
+hydra improve --since 2026-10-17                     # what the local telemetry says to improve
+hydra agents status                                  # Hydra in each coding tool
+hydra doctor                                         # is the local model ready?
+```
+
+Need the raw log for one run? Prefix it with `HYDRA_RAW=1` and the hook lets it through.
+
+## Privacy and control
+
+- **Local only.** The model, the runtime and the telemetry live in `~/.hydra`. Nothing is sent anywhere.
+- **Turn telemetry off** with `HYDRA_TELEMETRY=0`.
+- **Skip parts of the install** with `--no-agents` (no other tools), `--no-hooks` (no hooks) or `--runtime-only` (no skill).
+- **Uninstall cleanly.** `hydra agents remove` and `hydra hooks remove` undo every integration and restore your settings; `hydra stop` stops the local server; deleting `~/.hydra` removes the runtime, the model and the telemetry.
+
+## Learn more
+
+- [How Hydra works](https://github.com/rahul05ranjan/hydra/blob/main/docs/how-it-works.md): heads, backends (llama.cpp or Ollama), telemetry, every install path and the code layout.
+- [Evaluations and trials](https://github.com/rahul05ranjan/hydra/blob/main/docs/evaluations.md): how each number above was measured.
+- [What real use teaches](https://github.com/rahul05ranjan/hydra/blob/main/IMPROVEMENTS.md): the open and fixed findings from Hydra's own telemetry.
+- [Hydra Nano on Hugging Face](https://huggingface.co/rahul05ranjan/hydra-nano-git).
+
+## License
+
+MIT. See [LICENSE](https://github.com/rahul05ranjan/hydra/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "hydra-nano",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Small local models that take the noisy work off your coding agent: git history, test and build digests and OS inspection run on your machine, and only the lines that matter reach Claude Code, Codex, Cursor, OpenCode, Gemini CLI or Antigravity. Skill, MCP server and hooks.",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "cursor",
+    "opencode",
+    "gemini-cli",
+    "antigravity",
+    "mcp",
+    "mcp-server",
+    "agent-skill",
+    "ai-agents",
+    "coding-agent",
+    "local-llm",
+    "llama.cpp",
+    "token-saving",
+    "context-window",
+    "git",
+    "test-runner",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "author": "rahul05ranjan",
+  "homepage": "https://github.com/rahul05ranjan/hydra#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rahul05ranjan/hydra.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rahul05ranjan/hydra/issues"
+  },
+  "type": "module",
+  "bin": {
+    "hydra-nano": "skills/hydra/scripts/install.mjs",
+    "hydra": "skills/hydra/scripts/hydra.mjs",
+    "hydra-install": "skills/hydra/scripts/install.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "eval": "node evals/run.mjs",
+    "eval:build": "node evals/git1/build.mjs",
+    "eval:test": "node evals/test_logs/run.mjs",
+    "eval:test:build": "node evals/test_logs/build.mjs",
+    "eval:read": "node evals/read/run.mjs",
+    "eval:read:build": "node evals/read/build.mjs",
+    "eval:files": "node evals/files/run.mjs",
+    "eval:strict": "node evals/trial/strict_trial.mjs",
+    "eval:frontier:prepare": "node evals/trial/frontier_trial.mjs",
+    "eval:frontier": "node evals/trial/frontier_trial.mjs --run",
+    "eval:real:prepare": "node evals/trial/real_repo_trial.mjs",
+    "eval:real": "node evals/trial/real_repo_trial.mjs --run",
+    "dashboard": "node dashboard/server.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "skills/hydra"
+  ]
+}

package/skills/hydra/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: hydra
+description: Hand a read-only git question (repo state, history, blame), a where-is-it code search, targeted file slicing instead of whole-file reads, test/build failure digests, or system/OS inspections (ports, processes, disk) to hydra locally. Use before running git status, log, diff, show, blame, broad searches, whole file reads, ps/lsof dumps, or test/build commands where noisy output would flood your context.
+---
+
+# Hydra
+
+`hydra` runs read-only commands for repo questions, file slicing, test/build runs, and system inspections on a small local model and prints the lines that answer it. The raw output stays on this machine instead of entering your context.
+
+## Call it
+
+From the repository the question is about, naming the head that fits:
+
+```
+node scripts/hydra.mjs ask --head git "<question>"
+node scripts/hydra.mjs ask --head files "<question>"
+node scripts/hydra.mjs ask --head read "<question>"
+node scripts/hydra.mjs ask --head test "<question>"
+node scripts/hydra.mjs ask --head os "<question>"
+node scripts/hydra.mjs search <term...>
+node scripts/hydra.mjs read <file> [symbol|--lines <start-end>|--outline]
+node scripts/hydra.mjs run -- <command...>
+node scripts/hydra.mjs os [question...]
+```
+
+`scripts/` is in this skill's directory. Ask one full question per call and name the file, branch, commit or author when you know it: the model may only use a path, revision or name that appears in your question.
+- For finding definitions & files: use `hydra search <term>` to get definition-ranked matches without noise or raw grep dumps.
+- For reading code: use `hydra read <file> [symbol|--lines]` instead of reading multi-thousand-line files. It returns the exact symbol or slice, or a structural outline of symbols.
+- For tests and builds: run `hydra run -- <command...>` to execute the command locally and get the failure evidence with its exit code.
+- For system and environment: use `hydra os` or `--head os` to inspect listening ports, top processes, disk space, and system info without dumping 500 lines of terminal output into context.
+
+## What it answers
+
+- **git**: current branch and sync state, uncommitted and staged changes, commit history, what this branch adds over a base branch, one commit's patch, blame, branches, worktrees, remotes, stashes, tags.
+- **files**: where a name is defined or used, and which files are named like it.
+- **read**: extracts symbol definitions (functions, classes, methods), line ranges (`--lines 10-50`), or structural definition outlines across TypeScript, JavaScript, Python, Rust, and Go without dumping whole files into context.
+- **test**: runs and parses test and build outputs (`npm test`, `pytest`, `cargo test`, `tsc`). If tests fail, extracts the failing test name, assertion diff, and exact user file:line location, stripping node_modules and framework traces.
+- **os**: inspects listening ports (`lsof`), running processes / CPU consumers (`ps`), disk space (`df -h`), and system info (`uptime`, `uname`) while strictly guarding against printing secrets.
+
+Changes to the repository, and questions that need reasoning about what code does, stay with you.
+
+## Read the result
+
+- Lines under each `$ command` are the command's own output, copied verbatim. Build on these.
+- `Selected evidence:` introduces verbatim lines chosen by the local model. Interpret these lines yourself; Hydra does not generate a factual lead.
+- Git lists (status, commits, branches, stashes, tags, remotes, worktrees) are returned whole. Put an explicit count in commit-history questions; the supported maximum is 50.
+- `(N more lines not shown)` means output was withheld. When the lines shown do not settle the question, run that one command yourself.
+
+## When it cannot run
+
+Exit code 2 with `hydra unavailable` means the configured model is not ready. Run `node scripts/hydra.mjs doctor` to check it. For the default llama.cpp backend, run the installed `scripts/install.mjs --runtime-only` to download the pinned runtime and GGUF after telling the user the download size and that a background server will stay running. The managed config is in `~/.hydra`; Hydra starts its server when needed and `node scripts/hydra.mjs stop` stops it. The initial bootstrap shares one Git model across heads. For an external server, set `HYDRA_LLAMA_URL` to its root (without `/v1`) and `HYDRA_MODEL` to its alias. For Ollama, set `HYDRA_BACKEND=ollama`; its `setup` downloads models, so tell the user before starting it. `npx skills add` installs skill/CLI files only; `npx github:rahul05ranjan/hydra` performs the full bootstrap. If the runtime cannot be made available, do the task directly and report the limitation.

package/skills/hydra/scripts/hooks/route-tests.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Shell-command hook: a test or build run goes through `hydra run --` (or the hydra_run MCP tool),
+// whose digest keeps failing test names, assertion diffs and source locations and drops the rest.
+// Prefix a command with HYDRA_RAW=1 when the raw log is really needed.
+// --format picks the tool's hook protocol:
+//   claude, codex  PreToolUse; command at tool_input.command; deny via hookSpecificOutput.
+//   gemini         BeforeTool on run_shell_command; deny via {"decision": "deny", "reason"}.
+//   cursor         beforeShellExecution; command at command; must always answer with a permission.
+// Each decision goes to the local ledger with the hook's own time, for `hydra improve`; a command
+// that simply passes is recorded without its text.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { rawBypass, testRun } from '../lib/claude_hooks.mjs';
+import { record } from '../lib/ledger.mjs';
+
+const hydra = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'hydra.mjs');
+const flag = process.argv.indexOf('--format');
+const format = flag >= 0 ? process.argv[flag + 1] : 'claude';
+
+const answers = {
+  claude: { pass: null, deny: reason => ({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason } }) },
+  gemini: { pass: { decision: 'allow' }, deny: reason => ({ decision: 'deny', reason }) },
+  cursor: { pass: { permission: 'allow' }, deny: reason => ({ permission: 'deny', agent_message: reason,
+    user_message: 'Hydra sent this test/build run through hydra run to keep the full log out of context.' }) },
+};
+answers.codex = answers.claude;
+const answer = answers[format] ?? answers.claude;
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; }).on('end', () => {
+  let parsed;
+  try { parsed = JSON.parse(input) ?? {}; } catch {
+    if (answer.pass) process.stdout.write(JSON.stringify(answer.pass));
+    return;
+  }
+  const command = String((format === 'cursor' ? parsed.command : parsed.tool_input?.command) ?? '');
+  const session = parsed.session_id ?? parsed.conversation_id;
+  const event = (decision, withCommand = true) => ({ ts: new Date().toISOString(), kind: 'hook', hook: 'route-tests',
+    ...(format === 'claude' ? {} : { agent: format }), decision, ...(withCommand ? { command: command.slice(0, 300) } : {}),
+    ...(session ? { session } : {}), hookMs: Math.round(process.uptime() * 1000) });
+  const run = testRun(command);
+  if (!run) {
+    record(rawBypass(command) ? event('raw') : event('pass', false));
+    if (answer.pass) process.stdout.write(JSON.stringify(answer.pass));
+    return;
+  }
+  record({ ...event('deny'), run });
+  process.stdout.write(JSON.stringify(answer.deny(`Test/build runs go through Hydra so the full log stays out of context. Run it as:\n` +
+    `  node "${hydra}" run -- ${run}\n${format === 'claude' ? '' : 'or call the hydra_run tool with that command. '}` +
+    `(Keep any cd or env prefix before it.) Hydra returns the failing tests, assertion diffs and source locations ` +
+    `verbatim, or a short pass summary. If you truly need the raw log, prefix the original command with HYDRA_RAW=1.`)));
+});

package/skills/hydra/scripts/hooks/session-guide.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Session-start hook: tells the agent where Hydra pays off, so it uses it without being asked.
+// --format claude or codex answers with hookSpecificOutput; cursor with additional_context.
+// The session start goes to the local ledger, so `hydra improve` can tell how many sessions used Hydra.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { record } from '../lib/ledger.mjs';
+
+const hydra = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'hydra.mjs');
+const flag = process.argv.indexOf('--format');
+const format = flag >= 0 ? process.argv[flag + 1] : 'claude';
+const mcp = format === 'claude' ? '' : ' (or the hydra_git / hydra_run MCP tools)';
+const guide = `Hydra is installed: it runs noisy read-only commands on a small local model and returns only the lines that matter.\n` +
+  `- For git history, diff, blame or "what changed" questions, first run: node "${hydra}" ask --head git "<question>"${mcp} ` +
+  `from the repository, instead of reading git log, git diff or git show output yourself. Use plain git for writes ` +
+  `and for short checks such as git status --short.\n` +
+  `- A hook sends test and build runs through: node "${hydra}" run -- <command>\n` +
+  `- Keep using your own file reading and search for source files; Hydra does not save tokens there.`;
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; }).on('end', () => {
+  let start = {};
+  try { start = JSON.parse(input) ?? {}; } catch { /* The tool always sends JSON; record what there is. */ }
+  const session = start.session_id ?? start.conversation_id;
+  record({ ts: new Date().toISOString(), kind: 'session', ...(format === 'claude' ? {} : { agent: format }),
+    ...(session ? { session } : {}), ...(start.source ? { source: start.source } : {}) });
+  process.stdout.write(JSON.stringify(format === 'cursor' ? { additional_context: guide }
+    : { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: guide } }));
+});