README.md

English · 中文

The approvable coding agent for regulated teams.
Built for finance, healthcare, and security-sensitive engineering where AI coding must be controllable, transparent, and auditable.

🔑 Any model · local-first · policy-bound · audit-ready — the agent your security team can actually approve.

Bring your own model — DeepSeek, OpenAI, Claude (via OpenRouter), Groq, Ollama, or any OpenAI-compatible endpoint. Switch with one click, no code changes, no lock-in.

⏱️ 60 seconds to proof

Don't take the claims on trust — verify them on your own machine:

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

trust prints this install's live security posture: the resolved org policy and its hash, per-boundary network enforcement (provider · shell · MCP), and the tamper-evident audit status — the exact evidence a security reviewer needs, straight from the tool itself.

Then let the agent work, and prove what it did after the fact:

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

🎯 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.
• Secure remediation workflow — local scan and SARIF import turn built-in, CodeQL, GitHub Code Scanning, Semgrep, and compatible scanner findings into local remediation cases and isolated worktree repair tasks with source context and verification/reporting instructions. Workflow →

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

⭐ What's New in v0.9.0 — 🛡️ Secure remediation · Skills · CodeQL hardening

• 🛡️ Secure remediation workflow — run a built-in local scan or import SARIF from CodeQL, GitHub Code Scanning, Semgrep, and compatible scanners; findings become local remediation cases with source context, verification guidance, and isolated worktree repair tasks.
• 📚 Skills — upload, download, inspect, and reuse local skill bundles. DvalinCode now ships built-in secure-code-scan and secure-code-remediation skills, plus agent tools for listing skills, reading instructions, scanning, listing remediation cases, and preparing remediation worktrees.
• 🔐 CodeQL path hardening — user-controlled workspace, remediation, and skill paths now go through explicit root-containment checks, with regression tests covering traversal-safe resolution and skill import boundaries.
• 🎨 App icons — dark and light theme application icons now ship with the web bundle and desktop build inputs.

📸 Preview

Switching modes — each mode has its own sidebar:

Slash commands & file references in the composer:

🔒 Governance, from the command line

dvalincode trust — the install's live security posture (resolved policy, per-boundary enforcement, audit status) that a security review can read directly. Field semantics and copy-paste recipes: docs/POLICY-REFERENCE.md.

Tamper-evident audit — every agent run is a hash-chained, minimized report you can verify offline:

Project intelligence — dvalincode scan maps the workspace before the agent touches it:

🆚 When to choose DvalinCode

🚀 Quick Install

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. After reload:

source ~/.zshrc    # or ~/.bashrc
dvalincode                       # interactive terminal agent
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

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).

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.

🎬 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, /help for commands.

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

162 tests · 30 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                # 65/65 ✅
npm run typecheck

📄 License

MIT — see LICENSE.

🔗 Independence & Attribution

DvalinCode is not affiliated with Anthropic, Claude, Claude Code, OpenAI, GitHub, Cursor, Aider, OpenCode, HKUDS/nanobot, or any other vendor or project named here.

We are grateful to the projects, papers, tools, and standards that shaped the public vocabulary around agentic coding:

• 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.
• Claude Code, Aider, OpenCode, Cursor, Cline, and similar coding agents clarified user expectations around terminal agents, plan/build modes, permission prompts, project-local context, and diff-first editing workflows.
• 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.

DvalinCode's implementation, UI, tool schemas, prompts, module layout, and documentation are 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