Dvalincode

English · 中文 · 🌐 dvalincode.dev

Find the security holes in your repo, fix them, and prove the fix — in one command.
Every fix is diffed, tested, re-scanned, and recorded in a tamper-evident audit log before it can become a PR.

⏱️ 30 seconds, no install, no API key

npx dvalincode dvalin .

That is the whole thing. It runs the built-in rules for injection, hardcoded secrets, XSS, eval, and unsafe shell use against the current directory and prints what it found. No account, no model, no config, no code leaves your machine. Add --scanners builtin,semgrep,trivy,osv-scanner to pull in whichever of those engines you already have on PATH.

Or put it on every pull request — nothing to install at all

# .github/workflows/security.yml
permissions:
  contents: read
  security-events: write
steps:
  - uses: actions/checkout@v5
  - uses: arthurpanhku/dvalincode@v0.17.0
    with:
      fail-on: high

Findings land inline on the pull request diff and in your Security tab. No API key, no secrets, no model — the scan is deterministic and local to the runner. Full example →

Or let your agent call it

If an agent is writing the code, something other than that agent has to check it. DvalinCode is an MCP server, so any agent that speaks MCP can:

claude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .

dvalin_scan is read-only and deterministic — no model runs, no credentials are needed, no files are touched — so an agent can call it after every edit. A real call against a vulnerable fixture returns in ~170ms with a ~600 byte payload. The same server also exposes dvalin_run_task for delegating a whole governed task, plus the session and audit-evidence tools.

Verified end to end with both Claude Code and Codex driving a real tool call against the published package, not only completing a handshake. Agent integrations →

Then let it fix what it found

dvalincode dvalin . --fix --verify --draft-pr

This step does use a model — your model, any OpenAI-compatible endpoint. It prepares focused repairs in an isolated worktree, runs your tests, and requires a clean re-scan before anything can proceed to a draft PR. It never auto-merges, and a clean scan is never treated as proof that the code is safe.

This animation is made from the real application, not a mock. The input is an Apache-2.0-licensed example adapted from OWASP NodeGoat, whose contribution route evaluated user-controlled text.

🛡️ What that run actually did

Dvalin turns open-source scanner evidence into a controlled scan → fix → test → re-scan → draft-PR workflow. Here is the run in the animation above, measured:

The scanning and hardening control plane uses open-source components:

• Semgrep CE and its community rules for semantic SAST.
• Trivy for filesystem vulnerabilities, secrets, and misconfiguration.
• OSV-Scanner with the open OSV database for dependency vulnerabilities.
• DvalinCode's MIT-licensed built-in rules, remediation orchestration, test and re-scan gates, plus SARIF 2.1 import for other compatible scanners.

The scanners find and rank evidence. The configured model proposes source changes; DvalinCode constrains that work, records the diff, runs project tests, re-scans the changed tree, and keeps PR publication explicit. It does not auto-merge and it does not claim that a clean scan proves the absence of bugs. Choose an open-weight model through Ollama if the repair-proposal step must also stay fully local and open; hosted model licensing depends on the provider.

You can still prove what the agent did after the fact:

dvalincode report verify    # re-derive the hash chain of the last run's audit log

🏛️ And it survives a security review

That last command is the part that matters once more than one person depends on this. DvalinCode is a full coding agent — terminal, web GUI, and desktop app — built so that an organization, not the developer, bounds what it may do: a policy file constrains modes, commands, paths, tools, and models; every run is hash-chained into a tamper-evident audit log; nothing reaches a provider that the egress guard did not allow. A repo policy can only ever narrow the machine-level one.

If you are the person who has to approve this class of tool, start at APPROVABILITY-PLAN.md and the Evidence Pack that every release ships of itself.

🎯 Core Goal

Make AI coding approvable for regulated and security-sensitive teams.

DvalinCode is built as an approvable agent runtime, not just another coding agent app. The core product is not only "AI writes code"; it is the evidence a security, compliance, or platform team needs to safely allow AI coding in financial services, healthcare, internal enterprise platforms, and other confidential codebases.

• 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.
• Safe by default — three-tier approvals with diff preview, an undo stack, and sandboxed shell execution. An agent you can trust on full-auto.
• 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.
• 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.
• 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 →

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.

✅ Why Teams Pick DvalinCode

DvalinCode is differentiated by approvability. It is built for teams that need AI coding to pass security, compliance, and data-governance review before it can touch production repositories.

• Closed-loop secure remediation — scan locally or import SARIF from CodeQL, GitHub Code Scanning, Semgrep, or compatible scanners; persist findings as local remediation cases; create an isolated dvalin/remediate/... worktree; then send a focused repair prompt with source context and verification instructions.
• Skills as governed operating procedures — upload, download, and inspect local skill bundles. Built-in secure scanning and remediation skills tell agents which tools to use and keep workflows portable across machines.
• Model freedom without policy drift — use DeepSeek, OpenAI, Claude via OpenRouter, Groq, Ollama, or any OpenAI-compatible endpoint while keeping tool permissions, audit, and workspace policy consistent.
• Security evidence, not just security claims — OpenSSF Scorecard support, CodeQL, Dependabot, pinned Actions, CODEOWNERS, ISO/IEC 42001 alignment docs, AI change-impact records, and hash-chained run logs are part of the project.
• Local-first by default — sessions, config, profiles, memory, and audit logs stay under ~/.dvalincode/; .dvalincodeignore and policy controls bound what the agent can read, write, or execute.

🛡️ Security & Governance

DvalinCode maintains project-level governance evidence for open-source and enterprise review. This is the differentiator for teams where AI coding must pass security approval before it can reach production repositories:

• Threat model — the full attack surface of an agentic coding runtime (malicious AGENTS.md, poisoned MCP servers, prompt-injection escalation, egress, audit tampering, supply chain, sandbox escape), each mapped to the control that defends it and the honest residual gap. Threat model →
• OpenSSF Scorecard support — scheduled Scorecard workflow, SARIF upload, CodeQL, Dependabot, CODEOWNERS, least-privilege workflow permissions, and SHA-pinned GitHub Actions. Control map →
• ISO/IEC 42001 alignment — an AI management system scope, AI policy, role map, risk register, AI change classification, required records, and review cadence. AIMS alignment →
• AI change impact assessment — a reusable template for changes that affect model/provider behavior, prompts, permissions, tools, audit logs, or release security. Template →
• Regulated-use posture — local-first data handling, policy-controlled autonomy, minimized audit records, and release supply-chain evidence for finance, healthcare, security-sensitive SaaS, and internal enterprise use.
• Dvalin security engineering — the dedicated Dvalin workspace combines the built-in scanner with installed Semgrep CE, Trivy, and OSV-Scanner, normalizes SARIF findings, drives isolated test-backed fixes, and explicitly prepares a reviewable draft PR without auto-merging it. Workflow →

These documents are implementation evidence and operating procedures; they do not claim third-party ISO certification.

⭐ What's New in v0.14.0 — Dvalin security engineering

• Home unifies Chat and Cowork — the GUI now has a single Home workspace with read-only Ask and approval-gated Collaborate intents, while keeping the same project and conversation context.
• Code is focused again — the old Security and Routines panels have been removed from Code so its sidebar is dedicated to projects and autonomous implementation.
• Dvalin is a first-class workspace — orchestrate the built-in scanner plus installed Semgrep CE, Trivy, and OSV-Scanner; import SARIF; score and triage findings; persist remediation cases; and create isolated repair worktrees.
• One flow from evidence to draft PR — selected findings can launch an evidence-backed Agent fix, run focused tests/typecheck/build and a fresh scan, review the diff, and explicitly publish a draft PR without automatic merge.
• Agent loops converge sooner and cost less — investigation-before-edit and stall detection reduce repeated failed actions, general tool output is bounded, prompts remain append-only for cache reuse, and provider usage now accounts for cache hits/misses.
• Provider and evaluation upgrades — native Anthropic prompt caching and cache accounting are supported, and the SWE-bench Docker harness reports official scores, policy violations, stalls, and token/cache metrics.

⭐ What's New in v0.12.4 — finish the task before stopping

• Process narration no longer ends a task — responses such as “let me verify the file” are recognized as pending work, and the agent immediately continues with the promised action instead of treating them as a final answer.
• Truncated responses automatically recover — provider finish reasons are preserved, so output cut off by a token limit triggers another model step.
• Normal coding turns get room to finish — the per-turn action limit is now an emergency 100-action guard rather than a routine 15-action stopping point; stricter organization policy limits still take precedence.
• Completion is explicit — Code mode is instructed to return a tool-free answer only after the requested work and focused validation are complete.

⭐ What's New in v0.12.3 — resilient long-running Code mode

• Long coding turns keep going — Code mode now compacts context during an active tool loop, accounts for the full provider request when estimating tokens, and raises the default iteration checkpoint from 10 to 40.
• Interruptions are resumable — completed tool state is persisted when a turn is interrupted or its connection closes, so a follow-up continue resumes from the actual workspace progress.
• Visible, quieter agent activity — running sessions show a sidebar loading state, each response reports elapsed work time, and its Action timeline is available on click while raw Tool Calls stay collapsed by default.
• GitHub workflows from Code mode — network-aware git and GitHub CLI (gh) operations now support pull, push, PR creation, and Actions/repository commands through the governed shell approval path.
• Safer releases — package and CLI versions are synchronized, and prepublishOnly runs the build, typecheck, and test suite before publishing.
• Simple tasks stay simple — the Action budget is enforced across the whole turn instead of resetting on every model iteration, and Code mode is prompted to take the shortest direct path and stop when focused validation passes.

⭐ What's New in v0.12.2 — 🖥️ Desktop app milestone: it just works

• 🖥️ The native desktop app now works out of the box on macOS — DvalinCode.app opens a real dock window (WKWebView, no Electron) over the embedded engine. Two threading bugs that shipped in every earlier desktop build are fixed: the blocking webview loop no longer starves the embedded server (blank window), and the webview runs on the main thread as macOS requires (no window at all) — the server now lives in a child process of the same binary.
• 📦 The one-line installer installs the app — on macOS, curl … install.sh | bash now also puts DvalinCode.app (with the DvalinCode icon) into /Applications, so the desktop window launches straight from Launchpad after a CLI install. Opt out with DVALINCODE_NO_APP=1; pin with DVALINCODE_GUI_VERSION.
• ✅ Desktop is no longer "experimental" on macOS — the window and the embedded server are verified working; Windows and Linux desktop builds are cross-compiled and remain a preview.

📸 Preview

A real Dvalin scan of vulnerable code — Security health 22/100 · F, with the 10 findings the engines actually reported, located to the line:

The verified result — the three eval call sites replaced by a constrained numeric parser, one new injection regression test, all four open-source engines complete, 0 findings, 100/100 · A:

Home → Code → Dvalin — the current workspaces:

The scan images above are unedited captures of a real run against the documented NodeGoat-derived case: the scanners were run, the model repaired the source, the project's tests were run, and the tree was re-scanned. Nothing is staged, and a 100/A means the configured engines found nothing — not that the code is proven safe.

🆚 When to choose DvalinCode

🚀 Quick Install

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 for cron, CI, and external-agent examples.

Windows

Download dvalincode-v*-windows-x64.zip from Releases, unzip, then double-click start.bat.

Manual download

Grab the archive for your platform from the Releases page:

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 →

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 swapping anything in, then replaces ~/.dvalincode/ in place. npm installs are updated via npm i -g, and source checkouts are pointed at git pull. Add -y to skip the prompt, --prerelease to track pre-releases, or --json for scripting.

The macOS desktop app checks the separate gui-v* release track when it starts. When a newer GUI is available, it asks before downloading, verifies the archive against SHA256SUMS-gui.txt, validates the app version, then replaces and restarts DvalinCode.app. A failed replacement rolls back to the previous app.

🎬 First-time setup

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 grouped under Home.

Web GUI: run dvalincode serve and:

1. The server starts on http://localhost:3000 and your browser opens automatically.
2. Click LLM Configuration in the sidebar (bottom-left).
3. Pick a provider, paste your API key, choose a model, hit Save.
4. Optional: save the current config as a named profile (e.g. fast, cheap, local-ollama) to switch quickly later.

Both share the same config and sessions in ~/.dvalincode/.

✨ Features

⌨️ Slash Commands

🛠️ Architecture

┌───────────────────────────┐   ┌─────────────────────────┐
│  Terminal UI (readline)   │   │  Browser GUI (React/Vite)│
│  streaming · approvals    │   │  ChatThread · DiffViewer │
└─────────────┬─────────────┘   └────────────┬────────────┘
              │ in-process          HTTP / WebSocket
              │                ┌───────────────▼─────────────┐
              │                │  Express + ws server         │
              │                │  /api/* · `dvalincode serve` │
              │                └───────────────┬─────────────┘
              └──────────────┬─────────────────┘
┌────────────────────────────▼────────────────────────────┐
│  runAgentTurn — shared turn-runner (src/agent/session)   │
│  provider · prompt (mode · git · AGENTS.md) · session    │
└────────────────────────────┬────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────┐
│                    Agent Engine                          │
│  AgentLoop (8-state machine) → AgentRunner              │
│  Streaming · Interrupt · Undo stack · LLM compaction    │
│  run_start / run_end → AuditSink (hash-chained JSONL)   │
└──────────────────────────┬──────────────────────────────┘
                           │ run()
┌──────────────────────────▼──────────────────────────────┐
│  ToolRegistry — Zod schemas + permission gating         │
│  + audit taps: tool_call · file_* · shell_exec          │
│  read_file · list_files · search_text · git_status ·    │
│  write_file · edit_file · delete_file · shell           │
└─────────────────────────────────────────────────────────┘

Agent Loop — 8 States

RESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE

1. RESTORE — Load session from ~/.dvalincode/sessions/
2. COMPACT — If context near the limit, compress history (LLM summary)
3. COMMAND — Handle built-in slash commands
4. BUILD — Assemble system prompt (mode prompt + project + git + AGENTS.md)
5. RUN — Delegate to AgentRunner for the LLM tool-calling loop
6. SAVE — Persist session
7. RESPOND — Generate cross-session summary memory
8. DONE

🧪 Tests

npm test

357 tests · 52 files · all green.

🏗️ Build from source

Requires Bun (curl -fsSL https://bun.sh/install | bash).

git clone https://github.com/arthurpanhku/dvalincode
cd dvalincode
npm install
npm run dev:all                 # start backend (3001) + Vite (5173)

Build release binaries for every platform:

bash scripts/build-release.sh   # → release/ with tar.gz / zip + SHA256SUMS.txt
bash scripts/build-release.sh darwin    # macOS only
bash scripts/build-release.sh windows   # Windows only

Before publishing a release:

(cd release && shasum -a 256 -c SHA256SUMS.txt)
unzip -l release/dvalincode-v*-windows-x64.zip | grep 'web/dist/index.html'
tar tzf release/dvalincode-v*-macos-arm64.tar.gz | grep 'DvalinCode.app/Contents/Resources/AppIcon.icns'

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.

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.

🌐 Providers

DvalinCode supports any OpenAI-compatible endpoint. Built-in presets, sorted by cost:

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.

❓ FAQ

xattr -dr com.apple.quarantine ~/.dvalincode

🤝 Contributing

Contributions welcome. The codebase is intentionally small and surgical — see CONTRIBUTING.md.

git clone https://github.com/arthurpanhku/dvalincode
cd dvalincode && npm install
npm test                # 357/357 ✅
npm run typecheck

📄 License

MIT — see LICENSE.

🔗 Independence & Attribution

DvalinCode is an independent implementation. It is not affiliated with, sponsored by, or endorsed by Anthropic, Claude, Claude Code, OpenAI, OpenAI Codex, GitHub, Cursor, Aider, opencode, Cline, HKUDS/nanobot, or any other project or vendor named here.

We gratefully acknowledge that DvalinCode's product direction and architecture were informed by public research, open-source projects, published papers, standards, release notes, and common workflow patterns across the agentic coding ecosystem:

• HKUDS/nanobot (MIT) helped validate the explicit turn-state approach used in DvalinCode's TurnState flow.
• The ReAct paper (Yao et al., 2022) provides the widely used "reason, act, observe" loop that informs many modern tool-using agents.
• OpenAI's tool_calls message format, along with the broader OpenAI-compatible provider ecosystem, gives DvalinCode a portable interface for model/tool interaction.
• OpenAI Codex / Codex CLI, Claude Code, Aider, opencode, Cursor, Cline, and similar coding agents clarified user expectations around terminal agents, plan/build modes, permission prompts, project-local context, sandboxing, session lifecycle, MCP integration, and diff-first editing workflows.
• The AGENTS.md project-instruction convention, common in coding-agent tools, informed DvalinCode's project-local instruction loading behavior.
• CodeQL, GitHub Code Scanning, Semgrep, SARIF, OpenSSF Scorecard, and ISO/IEC 42001 informed DvalinCode's security-remediation and approvability posture.
• Git worktree, MCP, and local-first developer tooling patterns influenced the product direction for isolated remediation, governed tool access, and auditable execution.

These references shaped our understanding of what users expect from coding agents. DvalinCode's source code, prompts, UI text, tool schemas, module layout, and product implementation remain original unless explicitly noted. No source code, prompts, or UI text from the projects above was copied.

Full source references: docs/REFERENCES.md

⭐ Star Growth

💛 Thanks to Our Contributors

Every issue, idea, documentation improvement, test, and code contribution helps make DvalinCode better.

_{Want to join them? Read the contribution guide and send your first pull request.}