Skip to content
Back to search

dvalincode

Independent security verification for code written by humans and AI agents. Scan, repair, then prove it — Dvalin runs your project's own checks and issues a Verified Fix Record anyone can re-derive offline. Local-first, policy-bound, MIT.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/arthurpanhku/dvalincode with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/arthurpanhku/dvalincode'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/arthurpanhku--dvalincode/badge.svg)](/listings/arthurpanhku--dvalincode)

HTML

<a href="/listings/arthurpanhku--dvalincode"><img src="/api/listings/arthurpanhku--dvalincode/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Homebrew (macOS / Linux)

brew tap arthurpanhku/dvalincode https://github.com/arthurpanhku/dvalincode
brew install arthurpanhku/dvalincode/dvalincode

Installs the same signed-by-checksum release archive the one-liner does, and `brew upgrade` keeps it current. Homebrew never applies the macOS quarantine attribute, so this path is not subject to Gatekeeper.

macOS / Linux (one-liner)

curl -fsSL https://raw.githubusercontent.com/arthurpanhku/dvalincode/main/scripts/install.sh | bash

Detects your OS + arch, downloads the right binary, installs to `~/.dvalincode/`, and adds it to your `PATH`. On macOS it also installs the native **DvalinCode.app** into `/Applications` (skip with `DVALINCODE_NO_APP=1`), so the desktop window launches straight from Launchpad. After reload:

source ~/.zshrc    # or ~/.bashrc
dvalincode                       # interactive terminal agent
dvalincode dvalin .              # white-box security scan (GUI-independent)
dvalincode serve                 # start the web GUI, open the browser
dvalincode serve --host 0.0.0.0 --no-open   # host it on a server for remote/browser use
echo "inspect src and summarize" | dvalincode run - --output-format stream-json
dvalincode mcp-serve             # task-level stdio MCP server for external agents

Headless `run` and `mcp-serve` keep the same policy and audit chokepoint as the interactive clients. See the [unattended recipes](docs/RECIPES-UNATTENDED.md) for cron, CI, and external-agent examples.

A run that scanned or filed a fix record also carries a `verification` envelope beside its answer — in `json`, in `stream-json`, and in the MCP `dvalin_run_task` result. `coverageStatus` is the *weakest* coverage the run has evidence of, so one complete scan cannot speak for a partial one, and any record it produced is listed by path for offline re-derivation. A CI gate can read it directly:

jq -e '.verification.coverageStatus == "complete"' run.json || exit 1

That is the same rule the pull-request comment applies, on the surface with no human watching. [Harness mode →](docs/HARNESS-MODE.md)

Windows

Download `dvalincode-v*-windows-x64.zip` from [Releases](https://github.com/arthurpanhku/dvalincode/releases/latest), unzip, then double-click `start.bat`.

Manual download

Grab the archive for your platform from the [Releases page](https://github.com/arthurpanhku/dvalincode/releases/latest):

| Platform | Archive | |---|---| | macOS Apple Silicon (M1/M2/M3) | `dvalincode-v*-macos-arm64.tar.gz` | | macOS Intel | `dvalincode-v*-macos-x64.tar.gz` | | Windows x64 | `dvalincode-v*-windows-x64.zip` | | Linux ARM64 | `dvalincode-v*-linux-arm64.tar.gz` | | Linux x64 | `dvalincode-v*-linux-x64.tar.gz` |

Verify against `SHA256SUMS.txt` (included in each release).

Each release also ships **`dvalincode-v*-evidence.json`** — an Evidence Pack the shipped binary produced of itself on the build machine: two real governed runs, one allowed and one blocked by policy, with their hash chains. You can check the claims on this page before installing anything:

dvalincode evidence verify dvalincode-v0.14.0-evidence.json   # offline, reads only the file

The pack's checksum is inside `SHA256SUMS.txt`, which is the subject of the release's build-provenance attestation. [How it is produced →](docs/RELEASE-EVIDENCE.md)

> **macOS Gatekeeper:** binaries are unsigned. On first run, either clear the quarantine flag with `xattr -dr com.apple.quarantine ~/.dvalincode`, or right-click the binary in Finder → Open → confirm.

Staying up to date

DvalinCode updates itself — no need to re-run the installer:

dvalincode update --check   # is a newer release out? (read-only)
dvalincode update           # download, verify, and install the latest

It finds the newest release on GitHub, and for a binary install downloads the matching archive, **verifies it against the release's `SHA256SUMS.txt` before

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,483 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/logo.png" alt="DvalinCode" width="480">
  3. </p>
  4. <p align="center">
  5. <b>English</b> · <a href="README.zh-CN.md">中文</a> · <a href="https://dvalincode.dev">🌐 dvalincode.dev</a>
  6. </p>
  7. <p align="center">
  8. <a href="https://github.com/arthurpanhku/dvalincode/releases/latest"><img src="https://img.shields.io/github/v/release/arthurpanhku/dvalincode?style=for-the-badge&color=818cf8&label=Release" alt="Release"></a>
  9. <a href="https://github.com/arthurpanhku/dvalincode/releases"><img src="https://img.shields.io/github/downloads/arthurpanhku/dvalincode/total?style=for-the-badge&color=blue&label=Downloads" alt="Downloads"></a>
  10. <a href="#-tests"><img src="https://img.shields.io/badge/Tests-819%20%2F%20819%20%E2%9C%93-success?style=for-the-badge" alt="Tests"></a>
  11. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License"></a>
  12. <a href="https://scorecard.dev/viewer/?uri=github.com/arthurpanhku/dvalincode"><img src="https://api.scorecard.dev/projects/github.com/arthurpanhku/dvalincode/badge" alt="OpenSSF Scorecard"></a>
  13. <a href="#-quick-install"><img src="https://img.shields.io/badge/Platforms-macOS%20·%20Windows%20·%20Linux-blue?style=for-the-badge" alt="Platforms"></a>
  14. <a href="#-providers"><img src="https://img.shields.io/badge/LLM-OpenAI%20·%20Claude%20·%20DeepSeek%20·%20Ollama%20·%20Groq-7C3AED?style=for-the-badge" alt="LLM Support"></a>
  15. <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/i18n-EN%20·%20中文-orange?style=for-the-badge" alt="English / 中文"></a>
  16. </p>
  17. <p align="center">
  18. <b>Open security engineering for code written by humans and AI agents.</b><br>
  19. <b>Every repair carries its own proof.</b>
  20. </p>
  21. When an agent fixes a security finding, someone has to decide whether the fix
  22. worked. Almost every tool asks the model that wrote it — which is the one
  23. question a model cannot answer against its own interest.
  24. **Dvalin decides instead, and hands you the proof.** It re-scans, runs your
  25. project's own tests itself, and reads the exit codes from processes it started.
  26. Who wrote the repair — our agent, Claude Code, Codex, Copilot, a person — is
  27. recorded and never consulted. The result is a **Verified Fix Record**: a small
  28. JSON file anyone can re-check offline, on a laptop with no network and no
  29. Dvalin state.
  30. ```sh
  31. dvalin verify-fix fix-record.json
  32. ```
  33. ```
  34. Fix record 2c9d71ac03e0 · VERIFIED · scan-and-checks
  35. executor: claude-code (recorded, not consulted)
  36. targets: 1 before · 0 remaining
  37. coverage: complete → complete
  38. introduced: 0 (gate high/new)
  39. outcome: verified
  40. ✓ test: npm run test (exit 0)
  41. audit: run verify-36509f42 @ 414644c75af0
  42. ```
  43. That record says something narrow on purpose: *these findings were gone, and
  44. these checks were observed to pass.* It is not a claim that your code is safe,
  45. and Dvalin will not let it be read as one — every record carries what the scan
  46. actually covered, and a repair no check could confirm does not pass.
  47. [The open profile →](docs/spec/FIX-VERIFICATION.md)
  48. A repair is a change, and a change can add as well as remove. So the record also
  49. carries what the re-scan saw that the first scan did not, and the gate threshold
  50. the verdict was reached under: a fix that removes an `eval` and introduces an SQL
  51. injection is recorded as `regressed` and does not verify. Neither does a record
  52. whose issuer never looked — `introduced: not determined` fails, because a
  53. verifier that skips the question must not score better than one that asks it and
  54. finds something.
  55. Dvalin is the independent security runtime between code generation and merge.
  56. Humans, coding agents, and CI call the same versioned contract for discovery,
  57. remediation, and verification. It runs independently, or interoperates with
  58. specialist systems such as Codex Security through sealed scan artifacts or portable SARIF. Its built-in
  59. coding capability is a remediation executor — not the trust boundary, and not an
  60. attempt to compete with every general-purpose coding agent. See the
  61. [security-agent strategy](docs/SECURITY-AGENT-STRATEGY.md).
  62. ---
  63. ## ⏱️ 30 seconds, no install, no API key
  64. ```sh
  65. npx dvalincode security scan .
  66. # After installing the package: dvalin scan .
  67. ```
  68. That is the whole thing. It runs the built-in rules for injection, hardcoded
  69. secrets, XSS, `eval`, and unsafe shell use against the current directory and
  70. prints what it found. No account, no model, no config, no code leaves your
  71. machine. The default policy runs only Dvalin Built-in, so the first scan always
  72. works. Add optional engines explicitly, or inspect their fixed install commands:
  73. ```sh
  74. dvalin scanners list
  75. dvalin scanners install semgrep # review the command
  76. dvalin scanners install semgrep --yes # execute it under Dvalin policy
  77. ```
  78. ### Make it the gate in one step
  79. ```sh
  80. dvalin init
  81. ```
  82. `init` writes `dvalin.security.json` (fail on *new* findings at high or above),
  83. names the checks your project actually has (`test`, `typecheck`, `build`,
  84. `lint`) as what Dvalin runs before it calls a fix verified, records today's
  85. findings as the accepted backlog in `.dvalin/baseline.json`, and writes a CI
  86. gate for GitHub (`.github/workflows/dvalin.yml`) or GitLab
  87. (`.gitlab/dvalin-security.yml`, with a Code Quality report for the merge
  88. request widget). It never overwrites a file that is already there unless you
  89. pass `--force`. Commit what it wrote, and the backlog stops blocking anyone:
  90. only what a change adds fails.
  91. To gate every commit locally too, add the [pre-commit](https://pre-commit.com) hook:
  92. ```yaml
  93. # .pre-commit-config.yaml
  94. repos:
  95. - repo: https://github.com/arthurpanhku/dvalincode
  96. rev: v0.24.0 # the hook ships in v0.22.0 and later
  97. hooks:
  98. - id: dvalin-scan # or dvalin-scan-installed, to use the CLI you installed
  99. ```
  100. ### Measure with the scanner your CI gate uses
  101. If Snyk is what blocks your merges, verify against Snyk. A fix judged "clean"
  102. by a different engine is a fix the gate can still reject, and that mismatch is
  103. what turns one agent repair into several rounds of push, fail, and rebase.
  104. ```sh
  105. npm install -g snyk && snyk auth # or set SNYK_TOKEN
  106. dvalin scan . --scanners builtin,snyk-code,snyk-oss
  107. ```
  108. `snyk-code` (SAST) and `snyk-oss` (dependencies) are engines like any other:
  109. their findings carry the same fingerprints, coverage and gate, and a failed
  110. login is reported as an engine error, which makes the scan `partial`, never
  111. clean. They run only when named, because Snyk Code uploads source to Snyk.
  112. Name them in `dvalin.security.json` to make them part of the policy, and
  113. `reverify` will judge every fix with them.
  114. If GitHub code scanning is the gate, use CodeQL the same way:
  115. ```sh
  116. dvalin scan . --scanners builtin,codeql
  117. ```
  118. `codeql` builds one database per language outside the workspace and runs that
  119. language's default code-scanning queries, so its findings are the ones the gate
  120. reports. JavaScript/TypeScript, Python, Ruby, Java and C# are analysed without a
  121. build; Go uses CodeQL's autobuild. Kotlin, C/C++ and Swift need the project's own
  122. build, so when they are in the tree the run says so and the scan is `partial`,
  123. not clean. It runs only when named — a database takes minutes, not seconds, and
  124. the CodeQL CLI's license covers open-source code and GitHub Advanced Security
  125. customers.
  126. Ignores Snyk itself reports as accepted are honored and listed as coverage
  127. exclusions. Ignores **the change under review adds** are not: when a fix is
  128. judged, `.snyk`, `.semgrepignore`, `.trivyignore` and `.dvalincodeignore` are
  129. restored to the base commit's version and new inline markers (`deepcode
  130. ignore`, `nosemgrep`, `nosec`, `NOSONAR`, …) are blanked, so a finding that was
  131. silenced rather than fixed still fails the fix. A suppression is a risk
  132. decision a person makes in its own change, never a repair.
  133. The same judgement applies wherever Dvalin says "verified": the fix loop,
  134. `dvalin verify`, the MCP `dvalin_verify_findings` tool, single-round
  135. `--fix --verify`, and CI `reverify`. Those records are `dvalin-fix-record/v3`,
  136. which also fails a repair that hid a finding instead of fixing it — a sibling
  137. sink, a deleted vulnerable file, deleted tests or assertions. Outside a git
  138. repository, where the change cannot be determined, records stay v2 and say
  139. that evasion was not evaluated.
  140. ### Let it loop until the gate would pass
  141. ```sh
  142. dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean --max-rounds 3 --executor codex
  143. ```
  144. `--until-clean` turns one fix attempt into a bounded loop. The executor edits;
  145. Dvalin re-scans with the same engines and runs the project's checks itself;
  146. the executor is sent **only what is still wrong** — targets still present,
  147. findings its change introduced, failing checks with their last lines of
  148. output, suppressions it added — and fixes again. Dependency findings go first.
  149. The loop stops, and says which, when every target is gone with nothing
  150. blocking introduced and every check passing (`verified`), when the round
  151. budget runs out, when a round leaves the same problems open or the open set
  152. stops shrinking (`stalled`), when the targets need a person — a dependency
  153. with no fixed version (`not-auto-fixable`) — or when the engines or checks
  154. cannot run (`unverifiable`). Suppressions the executor adds are undone before
  155. each scan and stay open problems until removed. Every outcome issues a fix
  156. record, and every round is logged under `~/.dvalincode/security/fix-loops/`;
  157. `dvalin loop-stats` summarizes those logs — how often loops reach `verified`,
  158. the median and p90 rounds to green, which stop rule fired, and what was still
  159. open when a loop stalled (`--json`, `--since`, `--executor` to slice it).
  160. Rounds are kept short without changing what decides them. The engines run side
  161. by side, so a scan costs the slowest engine rather than the sum. Between rounds,
  162. the engines that analyse one file at a time (Dvalin Built-in, Semgrep) rescan
  163. only the files the change touched and the files the targets are in; the others
  164. always scan the whole tree. That narrowed scan only steers the executor: any
  165. round that would stop the loop is re-judged on a full scan of the same tree, and
  166. only the full scan decides the outcome and goes into the record.
  167. `--full-rescan` scans everything every round, and `loop-stats` reports scan time
  168. per round and how often a full scan changed the decision.
  169. For **code** findings the loop first asks for a reproduction: tests only, which
  170. Dvalin runs on the unfixed code and requires to fail — by a failing assertion,
  171. not a missing runner or a not-yet-written import. The tests are hashed; the
  172. fix must then make them pass **unchanged**, and that run is a check in the
  173. record. A finding no test could demonstrate stops the loop as
  174. `not-reproduced` before anything is fixed: it may be a false positive, and a
  175. person triages it. The runner is inferred (vitest, jest, mocha, `node --test`,
  176. pytest, `go test`) or set with `--repro-command 'npx vitest run {files}'` or
  177. `reproduce` in `dvalin.security.json` — never chosen by the executor.
  178. Each fix round also rejects the evasions an agent reaches for when the goal is
  179. "the scanner went quiet": moving the sink to a sibling (`eval` →
  180. `new Function`, `exec` → `spawn` with `shell: true`), deleting the vulnerable
  181. file, deleting tests, removing assertions. In practice the scanner alone is
  182. fooled by the first one — the rule stops matching — and the reproduction test
  183. and the evasion check are what catch it.
  184. ### Keep it on today's main, and close it in CI
  185. ```sh
  186. dvalincode dvalin . --scanners builtin,snyk-code,snyk-oss --until-clean \
  187. --rebase-onto origin/main --executor codex --draft-pr --sign-key ci.key
  188. ```
  189. With `--rebase-onto` the loop fetches and rebases the fix onto upstream before
  190. it starts and after every round, then judges it there. Conflicts go to the
  191. executor — the conflicted files only, with "do not run git" — and Dvalin
  192. continues the rebase itself; markers left in a file are a conflict not
  193. resolved. If they cannot be resolved the rebase is aborted, the tree is left as
  194. it was, and the loop stops as `rebase-conflict`. After each rebase the baseline
  195. is re-scanned on the new base, so a finding a teammate landed on main is not
  196. blamed on the fix.
  197. `--draft-pr` commits the record at `.dvalin/fix-record.json`, and
  198. [`docs/examples/dvalin-fix-loop.yml`](docs/examples/dvalin-fix-loop.yml)
  199. re-executes it on the pull request with `reverify: true`: base and head
  200. re-scanned, checks re-run, and the reproduction re-run with the fix reverted in
  201. place (it must fail) and restored (it must pass) — then signed with the CI key.
  202. For an incremental “no new high-risk findings” gate, commit the policy and
  203. baseline with the repository:
  204. ```sh
  205. dvalin init
  206. dvalin baseline
  207. dvalin scan
  208. ```
  209. This creates `dvalin.security.json` and `.dvalin/baseline.json`. Suppressions
  210. require a reason and may have an owner and expiry date. Scan output is a
  211. versioned envelope with a deterministic gate result and a resumable workflow ID.
  212. ### Or put it on every pull request — nothing to install at all
  213. ```yaml
  214. # .github/workflows/security.yml
  215. permissions:
  216. contents: read
  217. security-events: write
  218. steps:
  219. - uses: actions/checkout@v5
  220. with:
  221. fetch-depth: 0 # so the scan can reach the base commit
  222. - uses: arthurpanhku/dvalincode@v0.24.0
  223. with:
  224. fail-on: high
  225. diff: true # only report on what this PR changed
  226. ```
  227. Findings land inline on the pull request diff and in your Security tab.
  228. No API key, no secrets, no model — the scan is deterministic and local to the
  229. runner. [Full example →](docs/examples/dvalin-scan.yml)
  230. `diff: true` reports only on lines the pull request changed, so the gate blocks
  231. what this change *adds* instead of everything the repository already carried.
  232. That is what makes the check adoptable on a codebase that was not clean to
  233. begin with. Drop it to scan the whole repository.
  234. Every comment states what the scan **covered** — `complete`, `partial`, or
  235. `unknown` — beside the result, because "no findings" from a run where half the
  236. engines were missing is not the same answer as "no findings" from a complete one.
  237. ### And publish the proof next to the diff
  238. If your pipeline produced a fix record, hand it to the same action:
  239. ```yaml
  240. - uses: arthurpanhku/dvalincode@v0.24.0
  241. with:
  242. fix-record: fix-record.json
  243. ```
  244. The runner re-derives the record from the file alone — recomputing its hash and
  245. re-deriving its verdict from its own evidence — and posts the result on the pull
  246. request. A record that was edited after it was issued fails here, and fails the
  247. job.
  248. Re-derivation proves the record is *self-consistent*. It cannot prove the record
  249. was issued by anyone who actually ran anything: every field in it, the exit
  250. codes included, is something a forger could write, and a self-consistent
  251. forgery re-derives. Two things close that gap — re-execute the claim on the
  252. runner, and sign what the runner observed.
  253. ```
  254. 🔏 Verified Fix Record
  255. ✅ ce504a995395 · VERIFIED · scan-and-checks
  256. - repaired by claude-code — recorded, and not consulted for this verdict
  257. - targets: 1 before → 0 remaining
  258. - coverage: complete → complete
  259. - introduced: none (gate high/new)
  260. - outcome: verified
  261. - ✓ test: `npm run test` (exit 0)
  262. - audit chain: verify-eeb1bae7 @ 80881867270d
  263. ```
  264. A repair that regressed says so in the same place, and fails the job with it:
  265. ```
  266. ❌ 916e2eeaf065 · NOT VERIFIED · scan-and-checks
  267. - introduced: 1 finding(s) the first scan did not report (gate high/new)
  268. - critical dvalin/sql-injection — src/db.ts:31
  269. - outcome: regressed
  270. ```
  271. ### Re-execute it on the runner, and sign what you saw
  272. ```yaml
  273. - uses: actions/checkout@v5
  274. with:
  275. fetch-depth: 0 # the base commit has to be reachable
  276. - run: npm ci # the project's checks run on the runner
  277. - uses: arthurpanhku/dvalincode@v0.24.0 # reverify needs v0.22.0 or later
  278. with:
  279. fix-record: fix-record.json
  280. reverify: true
  281. signing-key: ${{ secrets.DVALIN_SIGNING_KEY }} # optional
  282. ```
  283. With `reverify: true` the claimed record contributes only *which targets* it
  284. says it fixed and *who* the executor was. Everything else is observed again:
  285. - the **base** commit is checked out and scanned, so each claimed target must
  286. actually have existed there — a record cannot take credit for removing a
  287. finding nobody had;
  288. - the **head** is scanned, so "gone" is observed on the runner;
  289. - the project's checks are run on the runner, with the checks, gate and
  290. scanners read from the **base** commit's `dvalin.security.json` — a pull
  291. request that relaxes its own gate or deletes its own checks is judged under
  292. the rules it is trying to change;
  293. - a fresh record is issued from those observations, and the job fails unless it
  294. verifies.
  295. With `signing-key` the fresh record is signed (Ed25519, over its hash). The key
  296. is taken into memory and removed from the environment before the project's
  297. checks run, so the code under review cannot read it. Downstream — a release
  298. job, another repository, an auditor — can then require that signature:
  299. ```sh
  300. dvalin keygen --out ci # once; store ci.key as a secret, publish ci.pub
  301. dvalin verify-fix record.json --trusted-key ci.pub
  302. ```
  303. A record that is unsigned, or signed only by a key you did not name, fails
  304. under `--trusted-key`. A valid signature says *which key vouched for this
  305. record*; whether that key deserves trust is your decision, and the reason to
  306. trust a CI key is that the CI job re-executed the verification rather than
  307. copying it. Locally, `dvalin reverify <record> --base origin/main` runs the same
  308. re-execution, and `dvalin sign-fix` signs a record that re-derives.
  309. [FVP-1 §4a, §5a →](docs/spec/FIX-VERIFICATION.md)
  310. ### Or let your agent call it
  311. If an agent is writing the code, something other than that agent has to check
  312. it. DvalinCode is an MCP server, so any agent that speaks MCP can:
  313. ```sh
  314. claude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .
  315. ```
  316. One command configures the editor you actually use:
  317. ```sh
  318. npx dvalincode mcp-install codex # ~/.codex/config.toml, via `codex mcp add`
  319. npx dvalincode mcp-install cursor # .cursor/mcp.json
  320. npx dvalincode mcp-install vscode # .vscode/mcp.json
  321. npx dvalincode mcp-install claude-code # .mcp.json
  322. npx dvalincode mcp-install gemini # .gemini/settings.json
  323. npx dvalincode mcp-install opencode # opencode.json
  324. ```
  325. For Codex, Dvalin delegates to the official `codex mcp add` command, so it safely
  326. updates TOML without hand-editing user configuration. The other formats differ
  327. in a way that fails silently — VS Code keys its servers under
  328. `servers`, Cursor under `mcpServers` — so the command writes the right one and
  329. merges into whatever is already there. [Editors and MCP →](integrations/mcp/)
  330. Or let Dvalin find them. `agents` lists the coding agents on this machine and
  331. where Dvalin is already connected; `agents connect` plans the rest, and writes
  332. nothing until you add `--yes`:
  333. ```sh
  334. npx dvalincode agents # which agents are here, and which have Dvalin
  335. npx dvalincode agents connect # the plan: what each agent gets
  336. npx dvalincode agents connect --yes # apply it
  337. ```
  338. If you manage MCP servers with [CC Switch](https://github.com/farion1231/cc-switch),
  339. `agents connect cc-switch --yes` hands Dvalin to it instead. CC Switch shows the
  340. import, asks first, then syncs Dvalin into Claude Code, Codex, Gemini CLI and
  341. OpenCode.
  342. `dvalin_scan` accepts `diff: "uncommitted"`, which reports only on what the
  343. agent just wrote rather than everything the repository already carried — the
  344. difference between a usable answer and a wall of pre-existing findings. It never
  345. runs a model, edits the target workspace, or persists Dvalin state, so clients
  346. can allow the preview by default. When a finding will be repaired, the agent
  347. explicitly calls `dvalin_begin_verification` to record a small local workflow;
  348. it can then retrieve the finding by fingerprint and request an independent
  349. re-scan through `dvalin_get_finding` and `dvalin_verify_findings`.
  350. That last one is the point: an agent that has just written a repair can ask for
  351. an independent verdict on it. Dvalin re-scans, runs the project's own checks
  352. itself, and returns a **Verified Fix Record** — what was targeted, what remains,
  353. what the repair introduced that was not there before, the gate the verdict was
  354. reached under, which commands ran and the exit codes Dvalin observed, and how
  355. much of the codebase was actually covered. Whoever wrote the repair is recorded
  356. and never consulted. `dvalin_verify_fix` re-derives such a record offline, so the reviewer
  357. receiving it does not have to trust the tool that issued it.
  358. [FVP-1 →](docs/spec/FIX-VERIFICATION.md) Responses include MCP `structuredContent`; scanner
  359. readiness is available through `dvalin_list_scanners`. The same server exposes
  360. `dvalin_run_task` as an optional implementation helper, plus session and audit
  361. evidence tools.
  362. Every client below has been driven to a real tool call rather than only a
  363. handshake — which client, which version, and on what date is a table rather
  364. than a sentence, because hand-written version numbers go stale quietly.
  365. [Integration support ↓](#-integration-support) · [Agent integrations →](integrations/)
  366. The repository also contains one [portable Codex/Claude plugin payload](integrations/dvalin-security/)
  367. with the current root Agent Plugins manifest, compatibility manifests, the
  368. shared security-gate skill, and a Claude-compatible MCP configuration. A repo-local
  369. marketplace makes it discoverable in Codex desktop; installing it lets task
  370. context trigger the gate instead of requiring every developer to remember a scan prompt.
  371. For Codex, `mcp-install codex` separately binds the server to the active project;
  372. the plugin does not risk scanning its own installed cache directory.
  373. Codex honors the scan's read-only MCP annotation. Claude Code requires one
  374. explicit MCP permission by design; the plugin documents the exact scan-only
  375. allow rule instead of asking users to bypass all permissions.
  376. ### Wherever you already work
  377. One server, reached the way each tool expects:
  378. | Harness | How Dvalin reaches it |
  379. |---|---|
  380. | **Claude Code** | [portable plugin](integrations/dvalin-security/) or `claude mcp add` · [standalone skill](integrations/claude-code/) |
  381. | **Codex** | `dvalincode mcp-install codex` · [portable plugin](integrations/dvalin-security/) · [sealed scan + SARIF interop](integrations/codex-security/) with Codex Security |
  382. | **Cursor** | `dvalincode mcp-install cursor` |
  383. | **VS Code** | `dvalincode mcp-install vscode` · [extension](editors/vscode/) for Problems, coverage/gate status, and offline VFR verification — *built, not yet published* |
  384. | **Gemini CLI** | `dvalincode mcp-install gemini` |
  385. | **OpenCode** | `dvalincode mcp-install opencode` |
  386. | **CC Switch** | `dvalin agents connect cc-switch` — one import, synced into each agent CC Switch manages |
  387. | **Windsurf · Zed** | stdio MCP through their own settings — [server command](integrations/mcp/) |
  388. | **Any MCP client** | [MCP registry](https://registry.modelcontextprotocol.io/): `io.github.arthurpanhku/dvalincode` |
  389. | **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings inline on the pull request diff |
  390. | **GitLab CI** | `dvalin init --ci gitlab` — new findings gate the merge request, shown in its Code Quality widget |
  391. | **pre-commit** | [`dvalin-scan` hook](.pre-commit-hooks.yaml) — the same policy gate before every commit |
  392. | **Any CI** | `dvalin scan . --fail-on high`, SARIF out for code scanning |
  393. The MCP config formats are not interchangeable — Codex uses TOML through its own
  394. CLI, VS Code keys its servers under
  395. `servers`, Cursor under `mcpServers`, OpenCode under `mcp` with the command line
  396. in one array, and the wrong one fails silently — so
  397. `mcp-install` writes the right shape and merges into whatever is already there.
  398. [Editors and MCP →](integrations/mcp/)
  399. ### Or interoperate with Codex Security
  400. [Codex Security](https://github.com/openai/codex-security) writes completed,
  401. sealed scans with a manifest, structured findings, and coverage. Import those
  402. portable artifacts without coupling Dvalin to its private application state:
  403. ```sh
  404. DVALIN_CODEX_SCAN_DIR=/tmp/codex-security-results
  405. npx @openai/codex-security scan . --output-dir "$DVALIN_CODEX_SCAN_DIR"
  406. dvalin import "$DVALIN_CODEX_SCAN_DIR" .
  407. dvalin scan . --fail-on high
  408. ```
  409. The import verifies manifest-recorded artifact hashes, creates stable Dvalin
  410. remediation cases, and reports exclusions and deferred work as explicit
  411. complete, partial, or unknown coverage. `--no-persist` validates the handoff
  412. without changing the backlog. SARIF remains the findings-only fallback.
  413. [Integration guide →](integrations/codex-security/)
  414. ### Then let it fix what it found
  415. ```sh
  416. dvalincode dvalin . --fix --verify --draft-pr
  417. ```
  418. This step *does* use a model — your model, any OpenAI-compatible endpoint. It
  419. prepares focused repairs in an isolated worktree, runs your tests, and requires
  420. a clean re-scan before anything can proceed to a draft PR. It never auto-merges,
  421. and a clean scan is never treated as proof that the code is safe.
  422. <p align="center">
  423. <img src="assets/dvalin-remediation.gif" alt="Dvalin scanning a vulnerable OWASP NodeGoat example at 22/100 F with 10 findings, then showing a clean verified re-scan at 100/100 A" width="100%">
  424. </p>
  425. This animation is made from the real application, not a mock. The input is an
  426. Apache-2.0-licensed example adapted from
  427. [OWASP NodeGoat](https://github.com/OWASP/NodeGoat/tree/c5cb68a7084e4ae7dcc60e6a98768720a81841e8/app/routes),
  428. whose contribution route evaluated user-controlled text.
  429. ## 🛡️ What that run actually did
  430. Dvalin turns open-source scanner evidence into a controlled scan → fix → test →
  431. re-scan → draft-PR workflow. Here is the run in the animation above, measured:
  432. | Real NodeGoat-derived run | Before | After Dvalin remediation |
  433. |---|---:|---:|
  434. | Security health (triage heuristic) | 22 / 100 · F | 100 / 100 · A |
  435. | Findings | 10 (`eval` across 3 rules, 2 engines) | 0 |
  436. | Tests | 2 passing | 3 passing, including an injection regression test |
  437. | Scanner fleet | 4 / 4 completed | 4 / 4 completed |
  438. The scanning and hardening **control plane** uses open-source components:
  439. - [Semgrep CE](https://github.com/semgrep/semgrep) and its community rules for
  440. semantic SAST.
  441. - [Trivy](https://github.com/aquasecurity/trivy) for filesystem vulnerabilities,
  442. secrets, and misconfiguration.
  443. - [OSV-Scanner](https://github.com/google/osv-scanner) with the open
  444. [OSV database](https://osv.dev/) for dependency vulnerabilities.
  445. - DvalinCode's MIT-licensed built-in rules, remediation orchestration, test and
  446. re-scan gates, plus [SARIF 2.1](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)
  447. import for other compatible scanners.
  448. The scanners find and rank evidence. The configured model proposes source
  449. changes; DvalinCode constrains that work, records the diff, runs project tests,
  450. re-scans the changed tree, and keeps PR publication explicit. It does not
  451. auto-merge and it does not claim that a clean scan proves the absence of bugs.
  452. Choose an open-weight model through Ollama if the repair-proposal step must also
  453. stay fully local and open; hosted model licensing depends on the provider.
  454. You can still prove what the agent did after the fact:
  455. ```sh
  456. dvalincode report verify # re-derive the hash chain of the last run's audit log
  457. ```
  458. ---
  459. ## 🧩 Integration support
  460. Code written with an AI assistant passes through four sets of hands before it
  461. merges: the agent that writes it, the editor the developer reads it back in, the
  462. pull request that gates it, and the reviewer who has to believe the result. A
  463. security answer that exists in only one of those places is not a gate — it is a
  464. suggestion the next stage is free to ignore.
  465. Dvalin is one MCP server and one deterministic scan behind all four, so the
  466. answer does not change depending on who asks it.
  467. | Stage of the loop | Where you are | How Dvalin gets there | Status |
  468. |---|---|---|---|
  469. | **Writing the code** | Claude Code | [portable plugin](integrations/dvalin-security/) · `claude mcp add` · `mcp-install claude-code` | ✅ session verified |
  470. | | Codex | `mcp-install codex` · [portable plugin](integrations/dvalin-security/) · [sealed scan + SARIF interop](integrations/codex-security/) | ✅ session verified · capture below |
  471. | | Cursor | `dvalincode mcp-install cursor` | ⚙️ config verified |
  472. | | Gemini CLI · OpenCode | `mcp-install gemini\|opencode` · `dvalin agents connect` | ⚙️ config verified |
  473. | | CC Switch | `dvalin agents connect cc-switch` | ⚙️ link format tested, not yet imported |
  474. | | Windsurf · Zed | stdio MCP through their own settings | ⚙️ documented, unverified |
  475. | | Any MCP client | registry `io.github.arthurpanhku/dvalincode` | ⚙️ published |
  476. | **Reading it back** | VS Code | `mcp-install vscode` · [extension](editors/vscode/) for Problems, coverage and gate status | ✅ editor verified |
  477. | **Gating the merge** | GitHub Actions | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings on the diff, fix records re-derived on the runner | ✅ runs on this repository's own CI |
  478. | | Any CI | `dvalin scan . --fail-on high`, SARIF out for code scanning | ✅ the exit code is the contract |
  479. | **Believing the result** | anyone, offline | `dvalin verify-fix record.json --trusted-key ci.pub` | ✅ no workspace, no network, no Dvalin state |
  480. | | the merge gate | `reverify: true` — base and head re-scanned, checks re-run on the runner, fresh record signed | ✅ covered by the test suite |
  481. **✅** means a real client was driven end to end and the tool call was observed.
  482. **⚙️** means the configuration is generated and its shape is tested, but no
  483. session has been captured. The difference is not smoothed over here, because a
  484. config file that loads is not evidence that a tool was ever called.
  485. ### What each claim rests on
  486. | Client | Version | Checked | How |
  487. |---|---|---|---|
  488. | Claude Code | CLI 2.1.260 | 2026-09-04 | server connected, `dvalin_scan` called with only that tool allow-listed, three findings returned — capture below |
  489. | Claude Code | CLI 2.1.251 | 2026-08-31 | weekly [`harness-interop`](.github/workflows/harness-interop.yml) — a real handshake against the built binary, which needs no credentials |
  490. | Codex | CLI 0.153.2 | 2026-09-18 | real `dvalin_scan` call in an ephemeral read-only sandbox; the completed MCP event was recorded as JSONL and returned one `dvalin/eval` finding — capture below |
  491. | Codex | CLI 0.151.0 | 2026-08-31 | weekly `harness-interop` — the server spec is accepted and stored as stdio. **Not a handshake**: the tool-call step stays skipped until `CODEX_API_KEY` is set |
  492. | VS Code | 1.134.0 · extension 0.18.0 | 2026-09-03 | packaged VSIX in a clean profile; finding, gate and coverage rendered in the editor — capture below |
  493. | Cursor | — | 2026-09-04 | `mcp-install cursor` writes `.cursor/mcp.json` under `mcpServers`; no session has been captured |
  494. | Gemini CLI · OpenCode | — | 2026-11-11 | `mcp-install` writes the shapes their own docs specify (Gemini: `mcpServers` in `settings.json`; OpenCode: the V1 `mcp` entry, which V2 still reads); no session has been captured |
  495. | CC Switch | — | 2026-11-11 | the `ccswitch://` link follows CC Switch's deep-link guide and importer source; not yet opened in a running CC Switch |
  496. That weekly workflow exists because an earlier version of this claim named two
  497. CLI versions by hand, both went stale within weeks, and nothing said so. It now
  498. re-checks against whatever those tools shipped that week, so the dates above
  499. either move on their own or stop moving in public.
  500. ### The same finding, in each place
  501. **Claude Code** — one read-only tool allow-listed, and the MCP call itself:
  502. ![A Claude Code session calling the Dvalin MCP server](docs/screenshots/10-claude-code-session.png)
  503. **Codex** — one read-only MCP call, with the completed JSONL tool event shown separately:
  504. ![A Codex session calling the Dvalin MCP server](docs/screenshots/11-codex-session.png)
  505. **VS Code** — the same scanner contract, as squiggles and a status bar:
  506. ![A Dvalin finding and its coverage status inside VS Code](docs/screenshots/09-vscode-dvalin-integration.png)
  507. ---
  508. ## 🏛️ And it survives a security review
  509. That last command is the part that matters once more than one person depends on
  510. this. DvalinCode is a full coding agent — terminal, web GUI, and desktop app —
  511. built so that an organization, not the developer, bounds what it may do: a
  512. policy file constrains modes, commands, paths, tools, and models; every run is
  513. hash-chained into a tamper-evident audit log; nothing reaches a provider that
  514. the egress guard did not allow. A repo policy can only ever *narrow* the
  515. machine-level one.
  516. If you are the person who has to approve this class of tool, start at
  517. [APPROVABILITY-PLAN.md](docs/APPROVABILITY-PLAN.md) and the
  518. [Evidence Pack](docs/EVIDENCE-PACK.md) that every release ships of itself.
  519. ---
  520. <table>
  521. <tr><td><b>🏠 Home</b></td><td>One place for read-only <b>Ask</b> and approval-gated <b>Collaborate</b> workflows. Switch intent without leaving the project or conversation.</td></tr>
  522. <tr><td><b>⚡ Code</b></td><td>Focused autonomous coding with full tool access and Ask / Plan / Auto / Bypass permission levels. Security and browser routines no longer compete with the core coding workflow.</td></tr>
  523. <tr><td><b>🛡️ Dvalin</b></td><td>Dedicated white-box security engineering: orchestrate the built-in scanner plus installed Semgrep CE, Trivy, and OSV-Scanner; triage findings; create isolated fixes; run tests and re-scan; then explicitly publish a reviewable draft PR. <a href="docs/DVALIN.md">Dvalin guide →</a></td></tr>
  524. <tr><td><b>🏦 Regulated teams</b></td><td>Designed for finance, healthcare, security-sensitive SaaS, and internal platform teams that need AI coding under policy, audit, data minimization, and supply-chain review — not just developer convenience.</td></tr>
  525. <tr><td><b>🛡️ Secure remediation</b></td><td>Run a multi-engine scan or import SARIF from CodeQL, GitHub Code Scanning, Semgrep, or compatible scanners, then create an isolated remediation worktree and turn findings into focused repair tasks with source context, verification evidence, and PR-ready reporting. <a href="docs/SECURE-REMEDIATION.md">Workflow →</a></td></tr>
  526. <tr><td><b>📚 Skills</b></td><td>Upload, download, and inspect local skill bundles. DvalinCode ships built-in secure-code-scan and secure-code-remediation skills, plus agent tools for listing skills, reading skill instructions, scanning, listing cases, and preparing remediation worktrees. <a href="docs/SKILLS.md">Format →</a></td></tr>
  527. <tr><td><b>🛡️ Audit trail</b></td><td>Every run emits a tamper-evident, hash-chained JSONL log — every file read/written, every command, every approval. A Run Report renders it as Markdown; <code>dvalincode report verify</code> proves the chain is intact. <a href="docs/AUDIT-TRAIL.md">Threat model →</a></td></tr>
  528. <tr><td><b>🔒 Org policy &amp; <code>trust</code></b></td><td>A company — not the developer — bounds the agent. A <code>dvalin.policy.json</code> constrains modes, shell commands, file paths, tools, and models; a repo policy can only ever <i>narrow</i> the machine-level one, never widen it. Each run records the governing policy's hash. <code>dvalincode trust</code> prints the install's live security posture — active policy + hashes, audit status, runtime — so a reviewer can verify it directly. <a href="docs/POLICY-REFERENCE.md">Policy reference →</a> · <a href="docs/APPROVABILITY-PLAN.md">Approvability plan →</a></td></tr>
  529. <tr><td><b>🏛️ Governance evidence</b></td><td>OpenSSF Scorecard, CodeQL, Dependabot, pinned GitHub Actions, CODEOWNERS, and ISO/IEC 42001 AIMS alignment docs are maintained as reviewable project evidence, and every release ships an Evidence Pack the binary produced of itself. <a href="docs/security/OPENSSF-SCORECARD.md">Scorecard map →</a> · <a href="docs/governance/ISO-42001-AIMS.md">ISO 42001 alignment →</a> · <a href="docs/RELEASE-EVIDENCE.md">Release evidence →</a></td></tr>
  530. <tr><td><b>📐 Open specs</b></td><td><b>PCP-1</b> — the provider-boundary contract (egress containment, credential containment, audit, policy binding) written as a vendor-neutral profile with test procedures, so any agent runtime can run it against its own adapters and publish the result. Not a DvalinCode test file; a checklist anyone can hold us to as well. <a href="docs/spec/PROVIDER-CONFORMANCE.md">Provider Conformance Profile →</a></td></tr>
  531. <tr><td><b>🖥️ First-class GUI</b></td><td>Modern web UI with code highlighting, file <code>@</code>-references, <code>/</code> slash commands, Git branch indicator, live token + cost counter, multi-profile LLM config, and a dark / light / system theme switcher.</td></tr>
  532. <tr><td><b>🖥️ Terminal or web — one binary</b></td><td>Run it bare for an interactive <b>terminal agent</b> with streaming output, inline approvals, and red/green diffs, or <code>dvalincode serve</code> to host the <b>web GUI</b> for browser/remote use. Both frontends drive the same agent core.</td></tr>
  533. <tr><td><b>🖥️ Native desktop app</b></td><td><code>DvalinCode.app</code> — a real dock application (OS-native webview, no Electron) over the same engine. On macOS the one-line installer puts it in <code>/Applications</code> automatically; launch it straight from Launchpad.</td></tr>
  534. <tr><td><b>🪶 Zero-dependency binary</b></td><td>Single ~25MB executable per platform. No Node, no Python, no Docker.</td></tr>
  535. <tr><td><b>🔐 Local-first</b></td><td>Sessions, config, profiles, and audit logs live in <code>~/.dvalincode/</code>. <code>.dvalincodeignore</code> blocks the agent from reading sensitive files. <code>AGENTS.md</code> in your repo becomes persistent project instructions.</td></tr>
  536. <tr><td><b>💾 Portable & exportable</b></td><td>Export <b>all</b> local data (memory, sessions, config, audit) to one file and import it on another machine — your setup moves with you. Any conversation downloads as a clean <b>Markdown</b> transcript.</td></tr>
  537. </table>
  538. ---
  539. ## 🎯 Core Goal
  540. > **Make every code-producing human or agent pass the same independent security gate.**
  541. DvalinCode is built as an **agent-compatible security runtime**, not another
  542. general coding-agent benchmark entry. The core product is scan evidence,
  543. policy, baseline, deterministic verification, and portable interfaces that a
  544. human developer, an external agent, or CI can all call. The bundled coding agent
  545. stays capable enough to implement and test focused remediations reliably; its
  546. model prose never decides whether the security gate passed.
  547. - **Any model** — every OpenAI-compatible endpoint is a first-class citizen, local models included. Your workflow should never be hostage to one vendor's pricing, rate limits, or quality swings.
  548. - **Safe by default** — three-tier approvals with diff preview, an undo stack, and sandboxed shell execution. An agent you can trust on full-auto.
  549. - **Small enough to audit** — one ~25MB binary, a handful of runtime dependencies, a codebase you can read in a weekend. Trust through inspection, not promises. As of v0.5, **every agent run is auditable too**: a tamper-evident, hash-chained log of every action, verifiable after the fact.
  550. - **Open enough to embed** — the agent core speaks a clean REST + WebSocket API, ready to be wired into your own product, CI, or internal tools.
  551. - **Approvable by any company** — governance is built in, not bolted on. An org policy bounds the blast radius (**controllable**), `dvalincode trust` makes the posture self-verifiable (**transparent**), and the hash-chained log proves what every run did (**auditable**). Those three together are exactly what a security review needs to say yes — and what cloud, closed, mutable-log agents structurally struggle to provide. [Approvability plan →](docs/APPROVABILITY-PLAN.md)
  552. The bundled **web GUI is the runtime's reference implementation and showcase** — the first consumer of that public API, demonstrating everything the runtime can do.
  553. ---
  554. ## ✅ Why Teams Pick DvalinCode
  555. DvalinCode is differentiated by **approvability**. It is built for teams that
  556. need AI coding to pass security, compliance, and data-governance review before
  557. it can touch production repositories.
  558. - **Closed-loop secure remediation** — scan locally or import SARIF from
  559. CodeQL, GitHub Code Scanning, Semgrep, or compatible scanners; persist
  560. findings as local remediation cases; create an isolated
  561. `dvalin/remediate/...` worktree; then send a focused repair prompt with
  562. source context and verification instructions.
  563. - **Skills as governed operating procedures** — upload, download, and inspect
  564. local skill bundles. Built-in secure scanning and remediation skills tell
  565. agents which tools to use and keep workflows portable across machines.
  566. - **Model freedom without policy drift** — use DeepSeek, OpenAI, Claude via
  567. OpenRouter, Groq, Ollama, or any OpenAI-compatible endpoint while keeping
  568. tool permissions, audit, and workspace policy consistent.
  569. - **Security evidence, not just security claims** — OpenSSF Scorecard support,
  570. CodeQL, Dependabot, pinned Actions, CODEOWNERS, ISO/IEC 42001 alignment docs,
  571. AI change-impact records, and hash-chained run logs are part of the project.
  572. - **Local-first by default** — sessions, config, profiles, memory, and audit
  573. logs stay under `~/.dvalincode/`; `.dvalincodeignore` and policy controls
  574. bound what the agent can read, write, or execute.
  575. ---
  576. ## 🛡️ Security & Governance
  577. <p align="center">
  578. <a href="docs/governance/ISO-42001-AIMS.md"><img src="https://img.shields.io/badge/ISO%2FIEC%2042001-AIMS%20Aligned-0F766E?style=for-the-badge" alt="ISO/IEC 42001 AIMS aligned"></a>
  579. <a href="docs/EVIDENCE-PACK.md"><img src="https://img.shields.io/badge/Compliance-Evidence%20Pack-2563EB?style=for-the-badge" alt="Compliance evidence pack"></a>
  580. <a href="docs/security/OPENSSF-SCORECARD.md"><img src="https://img.shields.io/badge/DevSecOps-Native-B91C1C?style=for-the-badge" alt="DevSecOps native"></a>
  581. </p>
  582. DvalinCode maintains project-level governance evidence for open-source and
  583. enterprise review. This is the differentiator for teams where AI coding must
  584. pass security approval before it can reach production repositories:
  585. - **Threat model** — the full attack surface of an agentic coding runtime
  586. (malicious `AGENTS.md`, poisoned MCP servers, prompt-injection escalation,
  587. egress, audit tampering, supply chain, sandbox escape), each mapped to the
  588. control that defends it and the honest residual gap. [Threat model →](docs/THREAT-MODEL.md)
  589. - **OpenSSF Scorecard support** — scheduled Scorecard workflow, SARIF upload,
  590. CodeQL, Dependabot, CODEOWNERS, least-privilege workflow permissions, and
  591. SHA-pinned GitHub Actions. [Control map →](docs/security/OPENSSF-SCORECARD.md)
  592. - **ISO/IEC 42001 alignment** — an AI management system scope, AI policy, role
  593. map, risk register, AI change classification, required records, and review
  594. cadence. [AIMS alignment →](docs/governance/ISO-42001-AIMS.md)
  595. - **AI change impact assessment** — a reusable template for changes that affect
  596. model/provider behavior, prompts, permissions, tools, audit logs, or release
  597. security. [Template →](docs/governance/AI-CHANGE-IMPACT-ASSESSMENT.md)
  598. - **Regulated-use posture** — local-first data handling, policy-controlled
  599. autonomy, minimized audit records, and release supply-chain evidence for
  600. finance, healthcare, security-sensitive SaaS, and internal enterprise use.
  601. - **Dvalin security engineering** — the dedicated Dvalin workspace combines the
  602. built-in scanner with installed Semgrep CE, Trivy, and OSV-Scanner, normalizes
  603. SARIF findings, drives isolated test-backed fixes, and explicitly prepares a
  604. reviewable draft PR without auto-merging it.
  605. [Workflow →](docs/SECURE-REMEDIATION.md)
  606. These documents are implementation evidence and operating procedures; they do
  607. not claim third-party ISO certification.
  608. ---
  609. ## ⭐ What's New in v0.24.0 — web access, more governed tools, a leaner GUI
  610. - **The GUI server requires an access token** — `dvalincode serve` now refuses
  611. `/api` and `/ws` without the token it mints at each start, and the desktop
  612. app's embedded server does too from its next build. The printed launch link
  613. carries the token once, and the page trades it for an HttpOnly cookie; scripts
  614. send `Authorization: Bearer`. `DVALINCODE_SERVER_TOKEN` keeps one token across
  615. restarts. A link without it opens an unlock screen.
  616. - **A leaner GUI** — the web GUI (and the desktop app from its next build) has
  617. one sidebar for every workspace: New chat (⌘N), the Chat / Code / Dvalin
  618. switch (Home is now Chat), recent conversations grouped by project, and
  619. Settings at the bottom. Ask and Collaborate move into the composer's mode
  620. menu. Controls that did nothing, like the intensity picker and the sidebar
  621. prompt templates, are gone. Enter no longer sends a message while an input
  622. method is still composing, the connection comes back after sleep, and the
  623. light theme renders code legibly.
  624. - **The agent can search and read the web** — `web_search` uses Tavily, Brave
  625. Search or your own SearXNG endpoint. `web_fetch` reads a public page as text,
  626. asks once per site per turn, and refuses private, loopback and metadata
  627. addresses. Both follow the policy's `network` level and are audited by origin.
  628. - **More governed tools** — read-only Git history (`git_log`, `git_show`,
  629. `git_blame`), regex search, ranged reads, batched `edit_file`, multi-file
  630. `apply_patch`, an `update_plan` checklist, structured `ask_user` questions,
  631. and image attachments in the GUI. Each passes the same policy and approval
  632. checks as every other tool.
  633. - **Secrets stay out of the model** — tool output is filtered for recognizable
  634. credential formats before it is sent, and `write_file`, `edit_file` and
  635. `apply_patch` refuse to write the redaction placeholder back over a real key.
  636. - **Budgets and rollback** — a policy can cap model spend with `maxCostUsd`.
  637. `dvalincode run --checkpoint` snapshots covered files, so
  638. `dvalincode rollback <run-id>` can restore them after a headless run, whether
  639. it succeeded or failed.
  640. - **Stricter headless runs** — one policy snapshot holds for the whole run,
  641. unattended runs refuse a policy they cannot apply, and resumes stay in their
  642. original workspace. `stream-json` consumers should read
  643. `tool_call.inputSummary` instead of `tool_call.input`.
  644. - **Release inventories** — every release now ships CycloneDX SBOMs for the CLI
  645. and the web bundle.
  646. ---
  647. ## ⭐ What's New in v0.23.0 — connect Dvalin to the agents you already use
  648. - **`dvalin agents` finds the coding agents on this machine** — Claude Code,
  649. Codex, Cursor, VS Code, Gemini CLI and OpenCode, and where Dvalin is already
  650. connected to each. It only looks: a command on `PATH`, the folder the agent
  651. creates, or its macOS app. Nothing is run or written.
  652. - **`dvalin agents connect` wires Dvalin in** — it plans the MCP entry for every
  653. agent that lacks one and writes only with `--yes`, through the same writers as
  654. `mcp-install`. That command now also covers Codex (through `codex mcp add`),
  655. Gemini CLI and OpenCode. [Editors and MCP →](integrations/mcp/)
  656. - **CC Switch support** — `dvalin agents connect cc-switch` hands Dvalin to
  657. CC Switch through its own import link, and CC Switch syncs it into every agent
  658. it manages. `provider set cc-switch` now points at CC Switch's local routing,
  659. `127.0.0.1:15721`. It used to point at port 3456, which belongs to
  660. claude-code-router.
  661. - **Import Codex Security scans** — `dvalin import` reads a sealed Codex
  662. Security scan directory, checking its manifest, hashes and coverage, or a
  663. SARIF handoff, into remediation cases. A portable Codex security skill and a
  664. repository-local plugin marketplace ship alongside.
  665. [Codex Security interop →](integrations/codex-security/)
  666. - **MCP clients learn the workflow when they connect** — at initialization the
  667. server tells an agent to scan uncommitted changes, check coverage before
  668. trusting zero findings, then inspect a finding and ask for independent
  669. verification.
  670. - **A failed turn keeps its work** — a turn that fails part-way now saves what it
  671. finished, so its session can resume, and the audit log records its iterations
  672. and tokens.
  673. ---
  674. ## ⭐ What's New in v0.14.0 — Dvalin security engineering
  675. - **Home unifies Chat and Cowork** — the GUI now has a single Home workspace
  676. with read-only Ask and approval-gated Collaborate intents, while keeping the
  677. same project and conversation context.
  678. - **Code is focused again** — the old Security and Routines panels have been
  679. removed from Code so its sidebar is dedicated to projects and autonomous
  680. implementation.
  681. - **Dvalin is a first-class workspace** — orchestrate the built-in scanner plus
  682. installed Semgrep CE, Trivy, and OSV-Scanner; import SARIF; score and triage
  683. findings; persist remediation cases; and create isolated repair worktrees.
  684. - **One flow from evidence to draft PR** — selected findings can launch an
  685. evidence-backed Agent fix, run focused tests/typecheck/build and a fresh scan,
  686. review the diff, and explicitly publish a draft PR without automatic merge.
  687. - **Agent loops converge sooner and cost less** — investigation-before-edit and
  688. stall detection reduce repeated failed actions, general tool output is
  689. bounded, prompts remain append-only for cache reuse, and provider usage now
  690. accounts for cache hits/misses.
  691. - **Provider and evaluation upgrades** — native Anthropic prompt caching and
  692. cache accounting are supported, and the SWE-bench Docker harness reports
  693. official scores, policy violations, stalls, and token/cache metrics.
  694. ---
  695. ## ⭐ What's New in v0.12.4 — finish the task before stopping
  696. - **Process narration no longer ends a task** — responses such as “let me
  697. verify the file” are recognized as pending work, and the agent immediately
  698. continues with the promised action instead of treating them as a final answer.
  699. - **Truncated responses automatically recover** — provider finish reasons are
  700. preserved, so output cut off by a token limit triggers another model step.
  701. - **Normal coding turns get room to finish** — the per-turn action limit is now
  702. an emergency 100-action guard rather than a routine 15-action stopping point;
  703. stricter organization policy limits still take precedence.
  704. - **Completion is explicit** — Code mode is instructed to return a tool-free
  705. answer only after the requested work and focused validation are complete.
  706. ---
  707. ## ⭐ What's New in v0.12.3 — resilient long-running Code mode
  708. - **Long coding turns keep going** — Code mode now compacts context during an
  709. active tool loop, accounts for the full provider request when estimating
  710. tokens, and raises the default iteration checkpoint from 10 to 40.
  711. - **Interruptions are resumable** — completed tool state is persisted when a
  712. turn is interrupted or its connection closes, so a follow-up `continue`
  713. resumes from the actual workspace progress.
  714. - **Visible, quieter agent activity** — running sessions show a sidebar loading
  715. state, each response reports elapsed work time, and its Action timeline is
  716. available on click while raw Tool Calls stay collapsed by default.
  717. - **GitHub workflows from Code mode** — network-aware `git` and GitHub CLI
  718. (`gh`) operations now support pull, push, PR creation, and Actions/repository
  719. commands through the governed shell approval path.
  720. - **Safer releases** — package and CLI versions are synchronized, and
  721. `prepublishOnly` runs the build, typecheck, and test suite before publishing.
  722. - **Simple tasks stay simple** — the Action budget is enforced across the whole
  723. turn instead of resetting on every model iteration, and Code mode is prompted
  724. to take the shortest direct path and stop when focused validation passes.
  725. ---
  726. ## ⭐ What's New in v0.12.2 — 🖥️ Desktop app milestone: it just works
  727. - **🖥️ The native desktop app now works out of the box on macOS** — `DvalinCode.app`
  728. opens a real dock window (WKWebView, no Electron) over the embedded engine.
  729. Two threading bugs that shipped in every earlier desktop build are fixed:
  730. the blocking webview loop no longer starves the embedded server (blank
  731. window), and the webview runs on the main thread as macOS requires (no
  732. window at all) — the server now lives in a child process of the same binary.
  733. - **📦 The one-line installer installs the app** — on macOS,
  734. `curl … install.sh | bash` now also puts `DvalinCode.app` (with the
  735. DvalinCode icon) into `/Applications`, so the desktop window launches
  736. straight from Launchpad after a CLI install. Opt out with
  737. `DVALINCODE_NO_APP=1`; pin with `DVALINCODE_GUI_VERSION`.
  738. - **✅ Desktop is no longer "experimental" on macOS** — the window and the
  739. embedded server are verified working; Windows and Linux desktop builds are
  740. cross-compiled and remain a preview.
  741. <details>
  742. <summary>v0.9.0 — 🛡️ Secure remediation · Skills · CodeQL hardening</summary>
  743. - **🛡️ Secure remediation workflow** — run a built-in local scan or import SARIF
  744. from CodeQL, GitHub Code Scanning, Semgrep, and compatible scanners; findings
  745. become local remediation cases with source context, verification guidance, and
  746. isolated worktree repair tasks.
  747. - **📚 Skills** — upload, download, inspect, and reuse local skill bundles.
  748. DvalinCode now ships built-in secure-code-scan and secure-code-remediation
  749. skills, plus agent tools for listing skills, reading instructions, scanning,
  750. listing remediation cases, and preparing remediation worktrees.
  751. - **🔐 CodeQL path hardening** — user-controlled workspace, remediation, and
  752. skill paths now go through explicit root-containment checks, with regression
  753. tests covering traversal-safe resolution and skill import boundaries.
  754. - **🎨 App icons** — dark and light theme application icons now ship with the web
  755. bundle and desktop build inputs.
  756. </details>
  757. <details>
  758. <summary>v0.8.0 — 🔒 Governance: controllable · transparent · auditable</summary>
  759. - **🔒 Org policy** — a `dvalin.policy.json` lets a *company*, not the developer, bound the agent: which modes, shell commands, file paths, tools, and models are allowed. Two layers (machine `~/.dvalincode/policy.json` + repo) resolve by **narrowing** — a repo policy can only ever make the machine policy stricter, never widen it. With no policy file, behavior is identical to before. Enforced at a single chokepoint; every denial is an inline `⛔ Blocked by policy` plus a `policy_violation` audit event. [Policy reference →](docs/POLICY-REFERENCE.md)
  760. - **🔎 `dvalincode trust`** — prints this install's live security posture in one command — active policy + source hashes, audit status, runtime, dependencies — so a reviewer can verify what the agent may and may not do directly, instead of taking claims on trust. `--json` for tooling.
  761. - **`dvalincode policy check`** — validates `dvalin.policy.json` against the schema, prints the resolved policy + canonical hash (after narrowing with the machine layer), and exits non-zero on failure — for CI and policy authoring. [Policy reference →](docs/POLICY-REFERENCE.md)
  762. - **🧾 Policy-aware audit** — every run records the hash of the governing policy (and which files contributed) in `run_start`, so the tamper-evident log proves *which* rules were in force.
  763. - **📐 Approvability plan** — the through-line is documented in [docs/APPROVABILITY-PLAN.md](docs/APPROVABILITY-PLAN.md): make DvalinCode trivially approvable by any company — controllable, transparent, auditable.
  764. </details>
  765. <details>
  766. <summary>v0.7.0 — 🧪 Desktop app (beta)</summary>
  767. - **🧠 Portable memory & full data export/import** — the upgraded local memory mechanism, plus every session, config, profile, and audit log, can now be bundled into a single file and restored on another machine. Migrate your whole setup in one step: `dvalincode export` / `dvalincode import`, or the **Export / Import** buttons in the GUI Settings panel.
  768. - **📝 Download any AI interaction as Markdown** — every conversation can be saved as a clean Markdown transcript (user turns, assistant replies, tool calls + results, decisions — all inline). Use the download icon on any session in the sidebar, `dvalincode session md <id>`, or `GET /api/sessions/:id/markdown`.
  769. - **🖥️ Native desktop app** — a real application window (not a browser tab) over the same engine: `DvalinCode.app` on macOS, plus Windows/Linux builds. Built with [webview-bun](https://github.com/tr1ckydev/webview-bun) using the OS-native webview (WKWebView / WebView2 / WebKitGTK) — no Electron, stays a small self-contained binary.
  770. - **🧩 A third frontend, one core** — the desktop app, terminal UI, and web GUI all drive the same shared turn-runner. The current `dvalincode` binary is now positioned purely as the **CLI** (terminal + `serve`).
  771. - **Status:** the desktop binaries are **experimental / unverified** — grab them from the latest **pre-release** and please report how the window behaves on your OS.
  772. </details>
  773. <details>
  774. <summary>v0.6.0 — terminal agent · <code>serve</code> · shared turn-runner</summary>
  775. - **🖥️ Terminal agent** — run `dvalincode` bare for an interactive terminal coding agent, Claude-Code-style: streaming responses, inline `[y/N]` write approvals with red/green diffs, `/mode` · `/clear` · `/git` · `/plan` · `/compact` · `/undo` · `/help`, Ctrl-C to interrupt, and a guided first-run provider setup. Defaults to read-only **Chat**, switchable live.
  776. - **🌐 `dvalincode serve`** — the web GUI now lives behind a command, so the *same* binary deploys headless on a server: `dvalincode serve --host 0.0.0.0 --no-open`.
  777. - **🧩 One engine, two frontends** — the terminal UI and web GUI both drive a shared, transport-agnostic turn-runner (`src/agent/session.ts`), keeping them at feature parity.
  778. </details>
  779. <details>
  780. <summary>v0.5.0 — security-grade audit trail · Run Report · theme switcher</summary>
  781. - **🛡️ Security-grade audit trail** — every Cowork/Code run writes a tamper-evident, hash-chained JSONL log to `~/.dvalincode/audit/` (`run_start`, every `tool_call` / `file_*` / `shell_exec` / `approval`, `run_end`). The hash chain makes any after-the-fact edit detectable. No local coding agent ships verifiable behavior logs. [Format + threat model →](docs/AUDIT-TRAIL.md)
  782. - **📋 Run Report + `dvalincode report` CLI** — a Markdown summary of each run (files read/changed, commands, decisions, test result), rendered as a collapsible card in the GUI and from the CLI:
  783. ```sh
  784. dvalincode report --last # render the most recent run
  785. dvalincode report <run-id> --format json
  786. dvalincode report verify <run-id> # ✓ chain intact / ✗ broken at seq N
  787. ```
  788. - **🎨 Theme switcher** — choose **dark / light / system** in Settings. `system` follows your OS live; the choice persists across sessions.
  789. </details>
  790. <details>
  791. <summary>v0.4.0 — <code>/compact</code> · <code>dvalin.json</code> team playbook · self-contained binaries</summary>
  792. - **`/compact`** — LLM-based context compaction: replaces conversation history with a structured five-section summary (Goal / Completed / Decisions / Current State / Pending). A divider in the chat thread shows the token reduction (e.g. `8,412 → 1,203 tokens −85%`).
  793. - **`dvalin.json` team playbook** — commit a shared set of automation prompts to your repo. The sidebar loads them automatically and lets teammates run the same one-click routines without any manual setup. Export button converts your personal routines to `dvalin.json` in one click.
  794. - **Self-contained binaries** — single ~25 MB executable per platform; no Node, no Python, no Docker. Auto-opens your browser on launch. Built with `bun --compile` so the web UI is bundled alongside the server binary.
  795. </details>
  796. <details>
  797. <summary>v0.3.0 — Mode-aware sidebar · one-line installer · multi-profile LLM config</summary>
  798. - **Mode-aware sidebar** — Chat shows quick-prompt **Templates**, Cowork shows a **Projects** folder tree, Code shows custom **Routines** (one-click commands like "Run tests" / "Git status" / "Type check"). Add your own routines from the sidebar — they persist in `localStorage`.
  799. - **One-line installer** — `curl … | bash` auto-detects your OS + arch, drops the binary into `~/.dvalincode/`, and patches your `PATH`. No package manager dependencies.
  800. - **Multi-profile LLM config** — save named (provider, model, API key) sets and switch in one click from the sidebar; live per-session cost counter in the topbar so you can compare providers on the fly.
  801. </details>
  802. ---
  803. ## 📸 Preview
  804. **A real Dvalin scan of vulnerable code — Security health 22/100 · F, with the
  805. 10 findings the engines actually reported, located to the line:**
  806. <p align="center">
  807. <img src="assets/hero.png" alt="Dvalin Security health showing 22/100 F with 4 high and 6 medium findings, and a Findings list locating each eval to a line in the NodeGoat-derived route" width="100%">
  808. </p>
  809. **The verified result — a real model-driven Verify turn inspected the repair,
  810. ran the regression tests and all four open-source engines, then the deterministic
  811. server re-scan reported complete coverage, a passing gate, 0 findings, 100/100 · A:**
  812. <p align="center">
  813. <img src="assets/dvalin-verify-local.jpg" alt="A local Dvalin model-driven Verify run showing its test evidence beside a deterministic 100/100 A re-scan, complete four-engine coverage, and a passing gate" width="100%">
  814. </p>
  815. ### Current Mac mini smoke test
  816. On 2026-09-18, commit `d4bf02b` was built and run as the local app on an
  817. Apple-silicon Mac mini with macOS 27.0. The disposable test project had no API
  818. key or configured model, and selected only the network-independent built-in
  819. scanner. Dvalin located a deliberately vulnerable `eval` at `quantity.js:3`,
  820. reported **1 high finding, 88/100 · B**, recorded complete **1/1** selected-engine
  821. coverage, and blocked the `high` security gate:
  822. <p align="center">
  823. <img src="docs/screenshots/12-mac-mini-local-scan.png" alt="Mac mini local Dvalin scan showing one high eval finding, 88/100 B, complete built-in scanner coverage, and a blocked high-severity gate" width="100%">
  824. </p>
  825. After replacing `eval` with a constrained integer parser and adding an
  826. executable-input regression test, all **3/3** tests passed. The selected engine
  827. then reported **0 findings, 100/100 · A**, complete coverage, and a passing gate:
  828. <p align="center">
  829. <img src="docs/screenshots/13-mac-mini-clean-rescan.png" alt="Mac mini local Dvalin re-scan showing zero findings, 100/100 A, complete built-in scanner coverage, and a passing high-severity gate" width="100%">
  830. </p>
  831. The same CLI workflow ran `npm run test` with exit code 0, issued a
  832. `dvalin-fix-record/v2`, and `dvalin verify-fix` re-derived it offline with
  833. `ok: true`. The clean-scan screenshot was captured before that record was
  834. imported, so it still says **Offline fix record: Not attached**. The Web workspace
  835. can now import the portable JSON record, re-derive its hash and verdict offline,
  836. and display its executor, checks, and exit codes. A clean scan is evidence about
  837. the selected engine, not a claim that the code is proven safe.
  838. **Home → Code → Dvalin — the current workspaces:**
  839. <p align="center">
  840. <img src="assets/modes.gif" alt="DvalinCode switching between Home, Code, and Dvalin" width="100%">
  841. </p>
  842. The scan images above are unedited captures of a real run against the documented
  843. NodeGoat-derived case: the scanners were run, the model repaired the source, the
  844. project's tests were run, and the tree was re-scanned. Nothing is staged, and a
  845. 100/A means the configured engines found nothing — not that the code is proven
  846. safe.
  847. ---
  848. ## 🆚 When to choose DvalinCode
  849. | If you need… | DvalinCode's answer |
  850. |---|---|
  851. | **An agent your security team can approve** | Policy-bound tools, explicit approval modes, `dvalincode trust`, audit logs, OpenSSF evidence, and ISO/IEC 42001 alignment docs. |
  852. | **AI coding for regulated repositories** — finance, healthcare, enterprise data, customer-confidential code | Local-first runtime, bring-your-own-model, `.dvalincodeignore`, governed egress, and minimized audit records. |
  853. | **A safer alternative to generic autonomous coding agents** | The product thesis is controllable / transparent / auditable, not only "the model can edit files". |
  854. | **IDE-centric AI workflows** | Zero-dep binary (~25 MB). Runs anywhere, no IDE required. macOS shell is sandboxed by default — network denied, writes capped to `cwd`. |
  855. | **Terminal-first AI workflows** | CLI start → auto-opens a modern Web UI with code highlighting and red/green diff approval. One install command, nothing else needed. |
  856. | **Cloud-only AI workflows** | Every OpenAI-compatible endpoint is a first-class citizen. Run Ollama with Qwen2.5-Coder: no key, no internet, no per-token cost. |
  857. | **Single-machine AI setup** | `AGENTS.md` committed to the repo ships AI context to every clone. `dvalin.json` ships the team's automation commands the same way — export from the sidebar, commit, done. |
  858. ---
  859. ## 🚀 Quick Install
  860. ### Homebrew (macOS / Linux)
  861. ```sh
  862. brew tap arthurpanhku/dvalincode https://github.com/arthurpanhku/dvalincode
  863. brew install arthurpanhku/dvalincode/dvalincode
  864. ```
  865. Installs the same signed-by-checksum release archive the one-liner does, and
  866. `brew upgrade` keeps it current. Homebrew never applies the macOS quarantine
  867. attribute, so this path is not subject to Gatekeeper.
  868. ### macOS / Linux (one-liner)
  869. ```sh
  870. curl -fsSL https://raw.githubusercontent.com/arthurpanhku/dvalincode/main/scripts/install.sh | bash
  871. ```
  872. Detects your OS + arch, downloads the right binary, installs to `~/.dvalincode/`, and adds it to your `PATH`. On macOS it also installs the native **DvalinCode.app** into `/Applications` (skip with `DVALINCODE_NO_APP=1`), so the desktop window launches straight from Launchpad. After reload:
  873. ```sh
  874. source ~/.zshrc # or ~/.bashrc
  875. dvalincode # interactive terminal agent
  876. dvalincode dvalin . # white-box security scan (GUI-independent)
  877. dvalincode serve # start the web GUI, open the browser
  878. dvalincode serve --host 0.0.0.0 --no-open # host it on a server; open the printed ?token= link
  879. echo "inspect src and summarize" | dvalincode run - --output-format stream-json
  880. dvalincode mcp-serve # task-level stdio MCP server for external agents
  881. ```
  882. Headless `run` and `mcp-serve` keep the same policy and audit chokepoint as
  883. the interactive clients. See the [unattended recipes](docs/RECIPES-UNATTENDED.md)
  884. for cron, CI, and external-agent examples.
  885. A run that scanned or filed a fix record also carries a `verification` envelope
  886. beside its answer — in `json`, in `stream-json`, and in the MCP `dvalin_run_task`
  887. result. `coverageStatus` is the *weakest* coverage the run has evidence of, so
  888. one complete scan cannot speak for a partial one, and any record it produced is
  889. listed by path for offline re-derivation. A CI gate can read it directly:
  890. ```sh
  891. jq -e '.verification.coverageStatus == "complete"' run.json || exit 1
  892. ```
  893. That is the same rule the pull-request comment applies, on the surface with no
  894. human watching. [Harness mode →](docs/HARNESS-MODE.md)
  895. ### Windows
  896. Download `dvalincode-v*-windows-x64.zip` from [Releases](https://github.com/arthurpanhku/dvalincode/releases/latest), unzip, then double-click `start.bat`.
  897. ### Manual download
  898. Grab the archive for your platform from the [Releases page](https://github.com/arthurpanhku/dvalincode/releases/latest):
  899. | Platform | Archive |
  900. |---|---|
  901. | macOS Apple Silicon (M1/M2/M3) | `dvalincode-v*-macos-arm64.tar.gz` |
  902. | macOS Intel | `dvalincode-v*-macos-x64.tar.gz` |
  903. | Windows x64 | `dvalincode-v*-windows-x64.zip` |
  904. | Linux ARM64 | `dvalincode-v*-linux-arm64.tar.gz` |
  905. | Linux x64 | `dvalincode-v*-linux-x64.tar.gz` |
  906. Verify against `SHA256SUMS.txt` (included in each release).
  907. Each release also ships **`dvalincode-v*-evidence.json`** — an Evidence Pack the
  908. shipped binary produced of itself on the build machine: two real governed runs,
  909. one allowed and one blocked by policy, with their hash chains. You can check the
  910. claims on this page before installing anything:
  911. ```sh
  912. dvalincode evidence verify dvalincode-v0.14.0-evidence.json # offline, reads only the file
  913. ```
  914. The pack's checksum is inside `SHA256SUMS.txt`, which is the subject of the
  915. release's build-provenance attestation. [How it is produced →](docs/RELEASE-EVIDENCE.md)
  916. > **macOS Gatekeeper:** binaries are unsigned. On first run, either clear the quarantine flag with `xattr -dr com.apple.quarantine ~/.dvalincode`, or right-click the binary in Finder → Open → confirm.
  917. ### Staying up to date
  918. DvalinCode updates itself — no need to re-run the installer:
  919. ```sh
  920. dvalincode update --check # is a newer release out? (read-only)
  921. dvalincode update # download, verify, and install the latest
  922. ```
  923. It finds the newest release on GitHub, and for a binary install downloads the
  924. matching archive, **verifies it against the release's `SHA256SUMS.txt` before
  925. swapping anything in**, then replaces `~/.dvalincode/` in place. npm installs are
  926. updated via `npm i -g`, and source checkouts are pointed at `git pull`. Add
  927. `-y` to skip the prompt, `--prerelease` to track pre-releases, or `--json` for
  928. scripting.
  929. The macOS desktop app checks the separate `gui-v*` release track when it starts.
  930. When a newer GUI is available, it asks before downloading, verifies the archive
  931. against `SHA256SUMS-gui.txt`, validates the app version, then replaces and
  932. restarts `DvalinCode.app`. A failed replacement rolls back to the previous app.
  933. ---
  934. ## 🎬 First-time setup
  935. **Terminal (default):** run `dvalincode`. On first launch it walks you through a one-time provider setup (pick a provider, paste your API key, choose a model) and saves it to `~/.dvalincode/config.json`. Then you're at the prompt — type to chat, `/mode` to switch between Chat / Cowork / Code / Dvalin, `/help` for commands. In the GUI, Chat and Cowork are the **Chat** workspace, as Ask and Collaborate in the composer's mode menu.
  936. **Web GUI:** run `dvalincode serve` and:
  937. 1. The server starts on `http://localhost:3000` and opens your browser at the link it prints.
  938. 2. Open **Settings** (bottom of the sidebar) → **LLM Providers** → **Configure**.
  939. 3. Pick a provider, paste your API key, choose a model, hit **Save**.
  940. 4. Optional: save the current config as a named profile (e.g. `fast`, `cheap`, `local-ollama`) to switch quickly later.
  941. **Access token:** the server drives an agent that edits files and runs commands, so it refuses `/api` and `/ws` without its access token. A fresh token is minted on every start and printed in the launch link (`http://localhost:3000/?token=…`); the page trades it for an HttpOnly cookie. Keep the link private. A browser without it shows an unlock screen where you can paste the link or the token; scripts send `Authorization: Bearer <token>`. Set `DVALINCODE_SERVER_TOKEN` (16+ characters of `A–Z a–z 0–9 - _`) to keep one token across restarts. The desktop app handles its token on its own. To use the GUI from another machine (`--host 0.0.0.0`), also set `DVALINCODE_ALLOWED_ORIGINS` to the URL you open it at.
  942. Both share the same config and sessions in `~/.dvalincode/`.
  943. ---
  944. ## ✨ Features
  945. | Category | Feature | Notes |
  946. |---|---|---|
  947. | **Modes** | Home / Code / Dvalin | Home contains read-only Ask and approval-gated Collaborate; Code is focused autonomous development; Dvalin is the scan-to-fix security workspace |
  948. | **Code permissions** | Ask Permissions / Plan Mode / Auto Mode / Bypass permissions | Verified behavior: Ask requests approval before writes/commands, Plan is read-only and does not write files, Auto runs operations automatically, Bypass runs without confirmation prompts |
  949. | **Workspaces** | Open folder / Import Git / Add worktree | Cowork and Code can switch to a local folder, clone a Git project, or create a Git worktree from the UI |
  950. | **Governance** | OpenSSF Scorecard / ISO 42001 AIMS alignment | Scorecard, CodeQL, Dependabot, pinned Actions, AI impact assessment, risk register, and review cadence are documented under `docs/security/` and `docs/governance/` |
  951. | **Secure remediation** | Built-in + Semgrep CE + Trivy + OSV-Scanner / SARIF / cases / worktrees / tests / draft PR | Dvalin detects installed engines, normalizes SARIF, scores risk, persists cases, drives evidence-backed fixes, verifies changes, and publishes only after an explicit user action |
  952. | **Agent integrations** | `dvalin agents` / MCP server | Finds Claude Code, Codex, Cursor, VS Code, Gemini CLI and OpenCode on this machine and wires Dvalin's MCP server into each, writing only with `--yes`; or hands it to CC Switch. [Editors and MCP →](integrations/mcp/) |
  953. | **Skills** | Upload / download / built-in security skills | Skills live under `~/.dvalincode/skills`; built-ins guide security scanning and remediation with dedicated agent tools. [Format →](docs/SKILLS.md) |
  954. | **Composer** | `@` file references | Type `@` for a fuzzy file search; selected files get inlined into the prompt |
  955. | | `/` slash commands | `/clear` `/compact` `/git` `/plan` `/undo` `/help` |
  956. | | Multiline + interrupt | <kbd>Shift</kbd>+<kbd>Enter</kbd> for newline, stop button to abort mid-stream |
  957. | **Tool UI** | Inline diffs | `edit_file` and `write_file` results render as red/green unified diff, default folded |
  958. | | Approval dialog with diff | Cowork mode shows the diff *before* the change is applied |
  959. | | Live tool counter + token + cost | Topbar shows session totals in real time |
  960. | **Agent** | LLM-based context compaction | `/compact` summarises into Goal / Completed / Decisions / Pending |
  961. | | Persistent undo stack | `/undo [N]` reverses the last N tool calls |
  962. | | Run Report | Markdown summary per run (files, commands, decisions, test result) — GUI card + `dvalincode report` |
  963. | | Git awareness | Branch name in topbar; git context auto-injected into prompt; read-only `git_status`, `git_diff`, `git_log`, `git_show` and `git_blame` tools, also in Ask and Plan |
  964. | | Code search and edits | `search_text` takes regular expressions, shows context lines, and skips `.gitignore`d paths; `edit_file` makes several edits or a replace-all in one call; `read_file` reads line ranges of files over 256 KB |
  965. | | Task checklist | `update_plan` keeps a step checklist that the desktop app shows as a card; in Code mode the agent is sent back if it stops with steps still open |
  966. | | `AGENTS.md` project memory | Per-repo persistent instructions, auto-loaded each turn |
  967. | | Web search + fetch | `web_search` is free by default: it asks Exa's free tier, which needs no key, and your queries go to Exa. If that search fails, for example at Exa's free rate limit, it falls back automatically to a Tavily, Brave Search or Exa API key: the one saved in Settings → LLM Providers → Web search, then `TAVILY_API_KEY`, `BRAVE_API_KEY`, `EXA_API_KEY`. Your own SearXNG endpoint (`DVALINCODE_SEARXNG_URL`) takes Exa's place. Turn the free step off in Settings, or with `"freeWebSearch": false` in `~/.dvalincode/config.json`, which the CLI reads too. `web_fetch` needs no key and reads public pages as text, asking once per site per turn. Both obey the policy `network` level and are audited by origin only |
  968. | **Security** | Tamper-evident audit trail | Hash-chained JSONL per run in `~/.dvalincode/audit/`; `dvalincode report verify` detects edits |
  969. | | macOS shell sandbox | `sandbox-exec` denies network; allows writes only inside cwd + `/tmp` |
  970. | | `.dvalincodeignore` | gitignore-style exclusion; blocks `read_file` / `list_files` / `search_text` |
  971. | | Per-action approval | Approve/deny each write / delete / shell call in Cowork mode |
  972. | **Appearance** | Theme switcher | Dark / light / system, persisted; `system` follows the OS live |
  973. | **Providers** | OpenAI-compatible endpoints | DeepSeek · OpenAI · Groq · OpenRouter · Ollama · custom |
  974. | | Multi-profile config | Save and switch between named (provider, model, API key) sets |
  975. | **Sessions** | Auto-save + restore | All sessions persisted to `~/.dvalincode/sessions/` as JSON |
  976. | | LLM summary memory | Cross-session summary keeps the agent oriented after restart |
  977. | **Memory** | Local user/project memory | Searchable facts, preferences, and decisions in `~/.dvalincode/memory/`; import from Claude/Hermes/Markdown |
  978. | **Data portability** | Export / import all data | One bundle of memory + sessions + config + audit — `dvalincode export` / `import`, or GUI Settings → Export / Import |
  979. | | Markdown transcript | Download any conversation as Markdown — sidebar download icon, `dvalincode session md <id>`, or `/api/sessions/:id/markdown` |
  980. ---
  981. ## ⌨️ Slash Commands
  982. | Command | Description |
  983. |---|---|
  984. | `/clear` | Clear the current conversation (client-side, starts a fresh session) |
  985. | `/compact` | LLM-based context compaction — replaces history with a structured summary |
  986. | `/undo [N]` | Reverse the last N tool calls (default 1) |
  987. | `/git` | Run `git_status` and show branch, recent commits, changed files |
  988. | `/plan <task>` | Ask the agent to plan the task step-by-step *without* executing |
  989. | `/help` | Show all available slash commands |
  990. ---
  991. ## 🛠️ Architecture
  992. ```
  993. ┌───────────────────────────┐ ┌─────────────────────────┐
  994. │ Terminal UI (readline) │ │ Browser GUI (React/Vite)│
  995. │ streaming · approvals │ │ ChatThread · DiffViewer │
  996. └─────────────┬─────────────┘ └────────────┬────────────┘
  997. │ in-process HTTP / WebSocket
  998. │ ┌───────────────▼─────────────┐
  999. │ │ Express + ws server │
  1000. │ │ /api/* · `dvalincode serve` │
  1001. │ └───────────────┬─────────────┘
  1002. └──────────────┬─────────────────┘
  1003. ┌────────────────────────────▼────────────────────────────┐
  1004. │ runAgentTurn — shared turn-runner (src/agent/session) │
  1005. │ provider · prompt (mode · git · AGENTS.md) · session │
  1006. └────────────────────────────┬────────────────────────────┘
  1007. │
  1008. ┌────────────────────────────▼────────────────────────────┐
  1009. │ Agent Engine │
  1010. │ AgentLoop (8-state machine) → AgentRunner │
  1011. │ Streaming · Interrupt · Undo stack · LLM compaction │
  1012. │ run_start / run_end → AuditSink (hash-chained JSONL) │
  1013. └──────────────────────────┬──────────────────────────────┘
  1014. │ run()
  1015. ┌──────────────────────────▼──────────────────────────────┐
  1016. │ ToolRegistry — Zod schemas + permission gating │
  1017. │ + audit taps: tool_call · file_* · shell_exec │
  1018. │ read_file · list_files · search_text · git_status · │
  1019. │ write_file · edit_file · delete_file · shell │
  1020. │ web_search · web_fetch │
  1021. │ git_log · git_show · git_blame · update_plan │
  1022. └─────────────────────────────────────────────────────────┘
  1023. ```
  1024. ### Agent Loop — 8 States
  1025. ```
  1026. RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE
  1027. ```
  1028. 1. **RESTORE** — Load session from `~/.dvalincode/sessions/`
  1029. 2. **COMPACT** — If context near the limit, compress history (LLM summary)
  1030. 3. **COMMAND** — Handle built-in slash commands
  1031. 4. **BUILD** — Assemble system prompt (mode prompt + project + git + AGENTS.md)
  1032. 5. **RUN** — Delegate to `AgentRunner` for the LLM tool-calling loop
  1033. 6. **SAVE** — Persist session
  1034. 7. **RESPOND** — Generate cross-session summary memory
  1035. 8. **DONE**
  1036. ---
  1037. ## 🧪 Tests
  1038. ```sh
  1039. npm test
  1040. ```
  1041. **819 core tests · 95 files · all green.** The VS Code extension has a separate
  1042. 37-test suite plus one opt-in published-package integration test.
  1043. ---
  1044. ## 🏗️ Build from source
  1045. Requires [Bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`).
  1046. ```sh
  1047. git clone https://github.com/arthurpanhku/dvalincode
  1048. cd dvalincode
  1049. npm install
  1050. npm run dev:all # start backend (3001) + Vite (5173)
  1051. ```
  1052. Build release binaries for every platform:
  1053. ```sh
  1054. bash scripts/build-release.sh # → release/ with tar.gz / zip + SHA256SUMS.txt
  1055. bash scripts/build-release.sh darwin # macOS only
  1056. bash scripts/build-release.sh windows # Windows only
  1057. ```
  1058. Before publishing a release:
  1059. ```sh
  1060. (cd release && shasum -a 256 -c SHA256SUMS.txt)
  1061. unzip -l release/dvalincode-v*-windows-x64.zip | grep 'web/dist/index.html'
  1062. tar tzf release/dvalincode-v*-macos-arm64.tar.gz | grep 'DvalinCode.app/Contents/Resources/AppIcon.icns'
  1063. ```
  1064. Windows smoke test: unzip `dvalincode-v*-windows-x64.zip` on Windows and run `start.bat` from the extracted folder. The server should open `http://localhost:3000`. If it reports an `ENOENT` path under `B:\~BUN\root\web\dist`, the compiled Bun virtual path detection has regressed; the packaged binary must resolve `web/dist` beside the extracted executable.
  1065. Note: Bun only allows Windows `.exe` icon/metadata injection when compiling on Windows. macOS/Linux cross-builds still produce a valid Windows archive, but without an embedded `.exe` icon.
  1066. ---
  1067. ## 🌐 Providers
  1068. DvalinCode supports any OpenAI-compatible endpoint. Built-in presets, sorted by cost:
  1069. | Provider | Cheapest model | Input / Output | Notes |
  1070. |---|---|---|---|
  1071. | **Groq** | `llama-3.1-8b-instant` | Free tier | Fastest open models — Llama 3.3 70B, Mixtral |
  1072. | **Ollama** | `qwen2.5-coder` | $0 (local) | No API key needed, runs on your machine |
  1073. | **DeepSeek** | `deepseek-chat` | $0.14 / $0.28 per 1M | Cheap and strong; v3 nearly matches GPT-4 quality |
  1074. | **OpenRouter** | `google/gemini-2.0-flash-001` | $0.10 / $0.40 per 1M | 200+ models including Claude, Gemini, Llama |
  1075. | **OpenAI** | `gpt-4o-mini` | $0.15 / $0.60 per 1M | Reliable; `o1` available for deep reasoning |
  1076. | **Custom** | — | depends | Any OpenAI-compatible base URL |
  1077. | **CC Switch** | — | depends | `provider set cc-switch`: requests go through CC Switch's local routing (`127.0.0.1:15721`) to whichever provider its Codex app uses; CC Switch holds the key |
  1078. DvalinCode shows the per-session cost live in the topbar — flip between providers in the **LLM Configuration** modal, save named profiles, and compare on the fly.
  1079. ---
  1080. ## ❓ FAQ
  1081. <details>
  1082. <summary><b>Does it send my code to a third party?</b></summary>
  1083. <br>
  1084. Only what the agent sends to the LLM you configured. Sessions, configs, and profiles all live on your machine in <code>~/.dvalincode/</code>. To exclude sensitive files from the agent's view, drop a <code>.dvalincodeignore</code> in your repo root (gitignore-style patterns).
  1085. </details>
  1086. <details>
  1087. <summary><b>Can I run this without an API key?</b></summary>
  1088. <br>
  1089. Yes — use Ollama. Pull a model (<code>ollama pull qwen2.5-coder</code>), then in the LLM Configuration modal pick the <b>Ollama</b> provider. No key, no internet, no per-token cost.
  1090. </details>
  1091. <details>
  1092. <summary><b>Why Home, Code, and Dvalin?</b></summary>
  1093. <br>
  1094. They represent different outcomes and safety defaults. <b>Home</b> groups read-only Ask and approval-gated Collaborate. <b>Code</b> is the focused software-development agent. <b>Dvalin</b> is a security pipeline with scanner evidence, remediation cases, isolated worktrees, verification, and explicit draft-PR publication. You can switch at any time while keeping project context.
  1095. </details>
  1096. <details>
  1097. <summary><b>Is the shell tool sandboxed?</b></summary>
  1098. <br>
  1099. On macOS, commands use <code>sandbox-exec</code>; on Linux, restrictive network policies use Bubblewrap when installed. Windows has no supported subprocess network sandbox yet, so restrictive policies fail closed instead of silently running unrestricted. The native command runner itself works on all three platforms.
  1100. </details>
  1101. <details>
  1102. <summary><b>Which operating-system shells are supported?</b></summary>
  1103. <br>
  1104. Linux and macOS commands run through <code>/bin/sh</code>; Windows commands run through the system <code>ComSpec</code> (<code>cmd.exe</code> by default). Full native command lines support pipes, redirects, and conditional operators. The split <code>command</code> + <code>args</code> form quotes executable paths and arguments for the host shell.
  1105. </details>
  1106. <details>
  1107. <summary><b>How do I see what the agent actually did — and is the log trustworthy?</b></summary>
  1108. <br>
  1109. Every run writes a JSONL audit log to <code>~/.dvalincode/audit/run-&lt;timestamp&gt;-&lt;id&gt;.jsonl</code>. Render it with <code>dvalincode report --last</code> (or see the collapsible Run Report card in the GUI). Each record is chained to the previous one with a SHA-256 hash, so any after-the-fact edit is detectable — <code>dvalincode report verify &lt;run-id&gt;</code> reports <code>✓ chain intact</code> or the exact position of a break. It's tamper-<b>evident</b>, not tamper-<b>proof</b>: a local attacker who can rewrite the whole file could recompute the chain. The value is forensic/accountability. See <a href="docs/AUDIT-TRAIL.md">docs/AUDIT-TRAIL.md</a> for the full threat model.
  1110. </details>
  1111. <details>
  1112. <summary><b>Will it overwrite my files without asking?</b></summary>
  1113. <br>
  1114. Depends on the mode. <b>Home → Ask</b> never writes. <b>Home → Collaborate</b> requires approval per file (with inline red/green diff before you click Allow). <b>Code</b> and <b>Dvalin</b> honor their selected permission level; use Auto only for trusted workspaces or isolated branches.
  1115. </details>
  1116. <details>
  1117. <summary><b>The macOS binary won't open — "unverified developer"</b></summary>
  1118. <br>
  1119. The binary is unsigned. Run this once to clear the quarantine flag:
  1120. <pre><code>xattr -dr com.apple.quarantine ~/.dvalincode</code></pre>
  1121. Or right-click the binary in Finder → Open → confirm once.
  1122. </details>
  1123. <details>
  1124. <summary><b>Does <code>AGENTS.md</code> get sent every turn?</b></summary>
  1125. <br>
  1126. Yes — DvalinCode reads <code>AGENTS.md</code> from the project root before each turn and injects it under <code>=== PROJECT INSTRUCTIONS ===</code> in the system prompt. Keep it focused — it counts toward your token budget.
  1127. </details>
  1128. ---
  1129. ## 🤝 Contributing
  1130. Contributions welcome. The codebase is intentionally small and surgical — see [CONTRIBUTING.md](CONTRIBUTING.md).
  1131. ```sh
  1132. git clone https://github.com/arthurpanhku/dvalincode
  1133. cd dvalincode && npm install
  1134. npm test # 819/819 core tests ✅
  1135. npm run typecheck
  1136. ```
  1137. ---
  1138. ## 📄 License
  1139. MIT — see [LICENSE](LICENSE).
  1140. ---
  1141. ## 🔗 Independence & Attribution
  1142. DvalinCode is an independent implementation. It is not affiliated with,
  1143. sponsored by, or endorsed by Anthropic, Claude, Claude Code, OpenAI, OpenAI
  1144. Codex, GitHub, Cursor, Aider, opencode, Cline, HKUDS/nanobot, or any other
  1145. project or vendor named here.
  1146. We gratefully acknowledge that DvalinCode's product direction and architecture
  1147. were informed by public research, open-source projects, published papers,
  1148. standards, release notes, and common workflow patterns across the agentic coding
  1149. ecosystem:
  1150. - [HKUDS/nanobot](https://github.com/HKUDS/nanobot) (MIT) helped validate the
  1151. explicit turn-state approach used in DvalinCode's `TurnState` flow.
  1152. - The [ReAct paper](https://arxiv.org/abs/2210.03629) (Yao et al., 2022)
  1153. provides the widely used "reason, act, observe" loop that informs many modern
  1154. tool-using agents.
  1155. - OpenAI's `tool_calls` message format, along with the broader
  1156. OpenAI-compatible provider ecosystem, gives DvalinCode a portable interface
  1157. for model/tool interaction.
  1158. - OpenAI Codex / Codex CLI, Claude Code, Aider, opencode, Cursor, Cline, and
  1159. similar coding agents clarified user expectations around terminal agents,
  1160. plan/build modes, permission prompts, project-local context, sandboxing,
  1161. session lifecycle, MCP integration, and diff-first editing workflows.
  1162. - [OpenAI Codex Security](https://github.com/openai/codex-security) and its
  1163. public documentation informed Dvalin's specialist security-agent research and
  1164. portable SARIF handoff. Dvalin remains an independent, competing security
  1165. runtime.
  1166. - The `AGENTS.md` project-instruction convention, common in coding-agent tools,
  1167. informed DvalinCode's project-local instruction loading behavior.
  1168. - CodeQL, GitHub Code Scanning, Semgrep, SARIF, OpenSSF Scorecard, and ISO/IEC
  1169. 42001 informed DvalinCode's security-remediation and approvability posture.
  1170. - Git worktree, MCP, and local-first developer tooling patterns influenced the
  1171. product direction for isolated remediation, governed tool access, and
  1172. auditable execution.
  1173. These references shaped our understanding of what users expect from coding
  1174. agents. DvalinCode's source code, prompts, UI text, tool schemas, module layout,
  1175. and product implementation remain original unless explicitly noted. No source
  1176. code, prompts, or UI text from the projects above was copied.
  1177. Full source references: [docs/REFERENCES.md](docs/REFERENCES.md)
  1178. ---
  1179. ## 💛 Thanks to Our Contributors
  1180. <p align="center">
  1181. Every issue, idea, documentation improvement, test, and code contribution helps make DvalinCode better.
  1182. </p>
  1183. | Contributor | GitHub profile |
  1184. | --- | --- |
  1185. | Arthur Pan | [@arthurpanhku](https://github.com/arthurpanhku) |
  1186. | Shivas | [@shivasb42](https://github.com/shivasb42) |
  1187. | Aditya | [@adity982](https://github.com/adity982) |
  1188. | badhope | [@weed33834](https://github.com/weed33834) |
  1189. | Samran Asif | [@webdevsamran](https://github.com/webdevsamran) |
  1190. | dchaudhari7177 | [@dchaudhari7177](https://github.com/dchaudhari7177) |
  1191. | TayfurYldz | [@TayfurYldz](https://github.com/TayfurYldz) |
  1192. See the [complete contribution history](https://github.com/arthurpanhku/dvalincode/graphs/contributors), including automated dependency and maintenance updates.
  1193. <p align="center">
  1194. <sub>Want to join them? Read the <a href="CONTRIBUTING.md">contribution guide</a> and send your first pull request.</sub>
  1195. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.