@arsh342/athena 0.4.2 → 0.4.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -6
- package/dist/index.cjs +833 -463
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -7,11 +7,13 @@ Find out what AI wrote in your repository, and whether it is safe to ship. Athen
|
|
|
7
7
|
Requires Node.js 18 or newer. The optional ESLint scanner needs Node 20.19 or newer; on older Node it is skipped and Athena's own engine does the work.
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
npm
|
|
10
|
+
npm i -g @arsh342/athena@latest
|
|
11
11
|
# or run without installing
|
|
12
12
|
npx @arsh342/athena scan .
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
+
Run the same command again to update. `athena --version` shows what you have.
|
|
16
|
+
|
|
15
17
|
## Quick start
|
|
16
18
|
|
|
17
19
|
```bash
|
|
@@ -23,7 +25,15 @@ athena init # install the pre-commit hook (athena uninstall r
|
|
|
23
25
|
athena doctor # check Node, npm, git and ESLint
|
|
24
26
|
```
|
|
25
27
|
|
|
26
|
-
Running `athena` with no arguments opens an interactive menu.
|
|
28
|
+
Running `athena` with no arguments opens an interactive menu, so you can pick what to do instead of typing commands and flags. Move with the arrow keys (or press a number), Enter selects, Esc goes back. Each screen shows the command it is equivalent to.
|
|
29
|
+
|
|
30
|
+
- **Scan:** this folder offline, with the AI check (pick a service, mode, model and spend cap), a different folder, or custom options (what blocks, the output format, dependency checks).
|
|
31
|
+
- **Review my changes:** what is staged, everything uncommitted, everything since a branch, or a commit range, with the AI check if you want it.
|
|
32
|
+
- **AI keys:** add, see or remove a key for Anthropic, OpenAI, Google, Groq, OpenRouter, DeepSeek, Mistral, xAI or Together. The key is typed hidden and saved privately on your machine.
|
|
33
|
+
- **Git hooks:** install the commit gate (and the push gate) or remove them.
|
|
34
|
+
- **Vulnerability data, Explain a finding, Skills and provenance, Project settings** (what blocks a commit, saved to `athena.config.json`), **Doctor** and **All commands**.
|
|
35
|
+
|
|
36
|
+
Without a terminal (CI, a pipe) it prints the command help instead.
|
|
27
37
|
|
|
28
38
|
## Commands
|
|
29
39
|
|
|
@@ -38,7 +48,7 @@ Running `athena` with no arguments opens an interactive menu.
|
|
|
38
48
|
| `models reset [--repo]` | Forget what Athena learned from labels and marks (this repository with `--repo`, otherwise all). |
|
|
39
49
|
| `variants <id> [--save]` | Turn a confirmed finding into a rule and find its look-alikes. |
|
|
40
50
|
| `skills list\|show\|new\|test\|add\|remove` | Work with skills (see below). |
|
|
41
|
-
| `keys set\|status\|remove <provider>` | Manage API keys for the optional AI layer. |
|
|
51
|
+
| `keys set\|status\|remove <provider>` | Manage API keys for the optional AI layer. The provider is `anthropic`, `openai`, `google`, `openai-compatible`, or a hosted service such as `groq`, `openrouter`, `deepseek`, `mistral`, `xai` or `together`. |
|
|
42
52
|
| `mcp` | Serve Athena's tools to MCP clients over stdio. |
|
|
43
53
|
| `update` | Refresh advisory data and signed rule packs (`--rollback` restores the previous pack). |
|
|
44
54
|
| `alerts` | New vulnerabilities since your last scan (exit 1 if any). |
|
|
@@ -93,9 +103,16 @@ Off unless you pass `--ai`. It only checks what the offline analyzers were unsur
|
|
|
93
103
|
athena keys set anthropic
|
|
94
104
|
athena scan . --ai verify
|
|
95
105
|
athena scan . --ai deep --budget 1 --suggest-fixes
|
|
106
|
+
|
|
107
|
+
# a free hosted model, for example Groq's gpt-oss
|
|
108
|
+
athena keys set groq
|
|
109
|
+
athena scan . --ai --provider openai-compatible --preset groq --model openai/gpt-oss-120b
|
|
110
|
+
|
|
111
|
+
# AI-check only the lines a change touched; a real flaw the change did not introduce is listed as an existing issue
|
|
112
|
+
athena review --ai
|
|
96
113
|
```
|
|
97
114
|
|
|
98
|
-
Keys come from the environment, then `~/.athena/credentials.json` (mode 0600), and are never printed or logged. Athena reserves the worst-case cost before every call and stops when the next call could exceed a cap; the report lists what was not checked. The first time in a repository it shows exactly what is sent and asks. Secrets and dependency findings are never sent, and repository text is treated as data, never as instructions. Local models (Ollama, LM Studio) cost nothing and send nothing off your machine.
|
|
115
|
+
Keys come from the environment, then `~/.athena/credentials.json` (mode 0600), and are never printed or logged. Athena reserves the worst-case cost before every call and stops when the next call could exceed a cap; the report lists what was not checked. The first time in a repository it shows exactly what is sent and asks. Secrets and dependency findings are never sent, and repository text is treated as data, never as instructions. Local models (Ollama, LM Studio) cost nothing and send nothing off your machine. On the repository's 14-snippet verification benchmark, Groq's `openai/gpt-oss-120b` and `openai/gpt-oss-20b` both scored 100% precision and recall and resisted the planted prompt injections ([results](https://github.com/arsh342/athena/blob/main/docs/athena-bench/AI-VERIFY.md)); that is a small sample, not a guarantee.
|
|
99
116
|
|
|
100
117
|
The Anthropic and OpenAI SDKs are built in. Google's is large, so it is not installed by default: for `--provider google`, run `npm install -g @google/genai` once.
|
|
101
118
|
|
|
@@ -103,7 +120,7 @@ The Anthropic and OpenAI SDKs are built in. Google's is large, so it is not inst
|
|
|
103
120
|
|
|
104
121
|
Athena can tune its AI-code estimate to a repository, locally, from trusted labels only: lines git credits to AI-assisted commits (AI), code whose every line was last changed before 2021-06-01 (human), and your own `athena provenance mark` entries. It activates at 30 labels with at least 10 of each class, shifts an estimate by at most 0.25, and is adopted only if it lowers log-loss on a held-out 20% of the labels and does not reduce AI recall or raise the human false-positive rate by more than one point on a bundled check set. State is in `~/.athena/learning/` (mode 0600) and holds hashes and style numbers, never code. A mark applies only while the code is unchanged. The report line reads `learning: tuned with N labels from this repo (changed X of Y units)` or `learning: global model`.
|
|
105
122
|
|
|
106
|
-
The trained detector is enabled only for JavaScript so far; every other language uses the style heuristic, which rarely scores near the decision boundary, so tuning there seldom changes a result. The report shows how many units tuning changed.
|
|
123
|
+
The trained detector is enabled only for JavaScript and TypeScript so far; every other language uses the style heuristic, which rarely scores near the decision boundary, so tuning there seldom changes a result. The report shows how many units tuning changed.
|
|
107
124
|
|
|
108
125
|
## What Athena checks
|
|
109
126
|
|
|
@@ -137,7 +154,7 @@ Skills are data only and contain no code. Regular expressions are checked before
|
|
|
137
154
|
|
|
138
155
|
- **Hooks.** `athena init` installs a pre-commit hook (`athena check --staged`, about a second on a typical commit); `--hooks pre-commit,pre-push` adds a pre-push review of `@{u}..HEAD`. Husky, lefthook and the pre-commit framework are detected and a snippet is printed instead of changing files. `ATHENA_SKIP=1 git commit` skips the hooks.
|
|
139
156
|
- **MCP server.** `claude mcp add athena -- npx -y @arsh342/athena mcp`. Other clients: [MCP client setup](https://github.com/arsh342/athena/blob/main/docs/agents/mcp-clients.md). No AI model is called and no key is needed.
|
|
140
|
-
- **Claude Code plugin.**
|
|
157
|
+
- **Claude Code plugin.** `claude plugin marketplace add arsh342/athena` then `claude plugin install athena@athena` (or, from a clone, `claude plugin install ./plugins/athena`) for `/athena-scan`, `/athena-review`, the `athena-security` skill, a researcher and a verifier agent, and hooks. Other agents: `npx skills add arsh342/athena`.
|
|
141
158
|
|
|
142
159
|
## Staying current
|
|
143
160
|
|