Approvable, local-first AI coding agent for regulated teams: policy controls, governed MCP, evidence packs, audit trails, secure remediation, and any OpenAI-compatible model.
English Β· δΈζ Β· π dvalincode.dev
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 trusttrust 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| π¨οΈ Chat mode | Read-only Q&A with one-click prompt templates β explain a codebase, find TODOs, review changes, write tests. The agent can read files and search, but never writes. |
| π₯ Cowork mode | Plan-then-execute. The agent drafts a numbered plan, you click Proceed, and every file write asks for explicit approval β with an inline red/green diff before you say yes. |
| β‘ Code mode | Autonomous agent with full tool access. Run tests, type-check, build, lint β one click via the Routines panel. macOS shell calls run inside a sandbox-exec profile with network denied. |
| π¦ Regulated teams | 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. |
| π‘οΈ Secure remediation | Run a local security 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 and PR-ready reporting. Workflow β |
| π Skills | 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. Format β |
| π‘οΈ Audit trail | 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; dvalincode report verify proves the chain is intact. Threat model β |
π Org policy & trust | A company β not the developer β bounds the agent. A dvalin.policy.json constrains modes, shell commands, file paths, tools, and models; a repo policy can only ever narrow the machine-level one, never widen it. Each run records the governing policy's hash. dvalincode trust prints the install's live security posture β active policy + hashes, audit status, runtime β so a reviewer can verify it directly. Policy reference β Β· Approvability plan β |
| ποΈ Governance evidence | OpenSSF Scorecard, CodeQL, Dependabot, pinned GitHub Actions, CODEOWNERS, and ISO/IEC 42001 AIMS alignment docs are maintained as reviewable project evidence. Scorecard map β Β· ISO 42001 alignment β |
| π₯οΈ First-class GUI | Modern web UI with code highlighting, file @-references, / slash commands, Git branch indicator, live token + cost counter, multi-profile LLM config, and a dark / light / system theme switcher. |
| π₯οΈ Terminal or web β one binary | Run it bare for an interactive terminal agent with streaming output, inline approvals, and red/green diffs, or dvalincode serve to host the web GUI for browser/remote use. Both frontends drive the same agent core. |
| πͺΆ Zero-dependency binary | Single ~25MB executable per platform. No Node, no Python, no Docker. |
| π Local-first | Sessions, config, profiles, and audit logs live in ~/.dvalincode/. .dvalincodeignore blocks the agent from reading sensitive files. AGENTS.md in your repo becomes persistent project instructions. |
| πΎ Portable & exportable | Export all 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 Markdown transcript. |
π― 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 trustmakes 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 β
β 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
dvalin/remediate/... worktree; then send a focused repair prompt with
source context and verification instructions.
- Skills as governed operating procedures β upload, download, and inspect
- Model freedom without policy drift β use DeepSeek, OpenAI, Claude via
- Security evidence, not just security claims β OpenSSF Scorecard support,
- Local-first by default β sessions, config, profiles, memory, and audit
~/.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
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,
- ISO/IEC 42001 alignment β an AI management system scope, AI policy, role
- AI change impact assessment β a reusable template for changes that affect
- Regulated-use posture β local-first data handling, policy-controlled
- Secure remediation workflow β local scan and SARIF import turn built-in,
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
- π Skills β upload, download, inspect, and reuse local skill bundles.
- π CodeQL path hardening β user-controlled workspace, remediation, and
- π¨ App icons β dark and light theme application icons now ship with the web
v0.8.0 β π Governance: controllable Β· transparent Β· auditable
- π Org policy β a
dvalin.policy.jsonlets 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 policyplus apolicyviolationaudit event. Policy reference β - π
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.--jsonfor tooling. dvalincode policy checkβ validatesdvalin.policy.jsonagainst 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 β- π§Ύ 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. - π Approvability plan β the through-line is documented in docs/APPROVABILITY-PLAN.md: make DvalinCode trivially approvable by any company β controllable, transparent, auditable.
v0.7.0 β π§ͺ Desktop app (beta)
- π§ 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. - π 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>, orGET /api/sessions/:id/markdown. - π₯οΈ Native desktop app β a real application window (not a browser tab) over the same engine:
DvalinCode.appon macOS, plus Windows/Linux builds. Built with webview-bun using the OS-native webview (WKWebView / WebView2 / WebKitGTK) β no Electron, stays a small self-contained binary. - 𧩠A third frontend, one core β the desktop app, terminal UI, and web GUI all drive the same shared turn-runner. The current
dvalincodebinary is now positioned purely as the CLI (terminal +serve). - Status: the desktop binaries are experimental / unverified β grab them from the latest pre-release and please report how the window behaves on your OS.
v0.6.0 β terminal agent Β·
serve Β· shared turn-runner
- π₯οΈ Terminal agent β run
dvalincodebare 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. - π
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. - 𧩠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.
v0.5.0 β security-grade audit trail Β· Run Report Β· theme switcher
- π‘οΈ Security-grade audit trail β every Cowork/Code run writes a tamper-evident, hash-chained JSONL log to
~/.dvalincode/audit/(runstart, everytoolcall/file*/shellexec/approval,runend). The hash chain makes any after-the-fact edit detectable. No local coding agent ships verifiable behavior logs. Format + threat model β - π Run Report +
dvalincode reportCLI β 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:
dvalincode report --last # render the most recent run
dvalincode report <run-id> --format json
dvalincode report verify <run-id> # β chain intact / β broken at seq N- π¨ Theme switcher β choose dark / light / system in Settings.
systemfollows your OS live; the choice persists across sessions.
v0.4.0 β
/compact Β· dvalin.json team playbook Β· self-contained binaries
/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%).dvalin.jsonteam 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 todvalin.jsonin one click.- Self-contained binaries β single ~25 MB executable per platform; no Node, no Python, no Docker. Auto-opens your browser on launch. Built with
bun --compileso the web UI is bundled alongside the server binary.
v0.3.0 β Mode-aware sidebar Β· one-line installer Β· multi-profile LLM config
- 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. - One-line installer β
curl β¦ | bashauto-detects your OS + arch, drops the binary into~/.dvalincode/, and patches yourPATH. No package manager dependencies. - 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.
πΈ 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.
dvalincode policy check β validate dvalin.policy.json in CI: schema check, the resolved policy after machine-layer narrowing, and its canonical hash.
Tamper-evident audit β every agent run is a hash-chained, minimized report you can verify offline:
Evidence Pack β one command bundles policy, posture, and audit proofs into a single file a reviewer can verify fully offline:
Project intelligence β dvalincode scan maps the workspace before the agent touches it:
π When to choose DvalinCode
| If you needβ¦ | DvalinCode's answer | |---|---| | 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. | | 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. | | A safer alternative to generic autonomous coding agents | The product thesis is controllable / transparent / auditable, not only "the model can edit files". | | 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. | | 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. | | 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. | | 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. |
π Quick Install
macOS / Linux (one-liner)
curl -fsSL https://raw.githubusercontent.com/arthurpanhku/dvalincode/main/scripts/install.sh | bashDetects 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 useWindows
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:
| 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).
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 latestIt 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.
π¬ 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:
- The server starts on
http://localhost:3000and your browser opens automatically. - Click LLM Configuration in the sidebar (bottom-left).
- Pick a provider, paste your API key, choose a model, hit Save.
- Optional: save the current config as a named profile (e.g.
fast,cheap,local-ollama) to switch quickly later.
~/.dvalincode/.
β¨ Features
| Category | Feature | Notes | |---|---|---| | Modes | Chat / Cowork / Code | Each with a distinct sidebar (Templates / Projects / Routines) and tool-access policy | | 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 | | 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 | | 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/ | | Secure remediation | Local scan / SARIF import / case queue / remediation worktree | Code mode can scan common local risks, import SARIF findings, persist local cases, and create isolated dvalin/remediate/... worktrees with repair prompts | | Skills | Upload / download / built-in security skills | Skills live under ~/.dvalincode/skills; built-ins guide security scanning and remediation with dedicated agent tools. Format β | | Composer | @ file references | Type @ for a fuzzy file search; selected files get inlined into the prompt | | | / slash commands | /clear /compact /git /plan /undo /help | | | Multiline + interrupt | Shift+Enter for newline, stop button to abort mid-stream | | Tool UI | Inline diffs | editfile and writefile results render as red/green unified diff, default folded | | | Approval dialog with diff | Cowork mode shows the diff before the change is applied | | | Live tool counter + token + cost | Topbar shows session totals in real time | | Agent | LLM-based context compaction | /compact summarises into Goal / Completed / Decisions / Pending | | | Persistent undo stack | /undo [N] reverses the last N tool calls | | | Run Report | Markdown summary per run (files, commands, decisions, test result) β GUI card + dvalincode report | | | Git awareness | Branch name in topbar; git_status tool; git context auto-injected into prompt | | | AGENTS.md project memory | Per-repo persistent instructions, auto-loaded each turn | | Security | Tamper-evident audit trail | Hash-chained JSONL per run in ~/.dvalincode/audit/; dvalincode report verify detects edits | | | macOS shell sandbox | sandbox-exec denies network; allows writes only inside cwd + /tmp | | | .dvalincodeignore | gitignore-style exclusion; blocks readfile / listfiles / search_text | | | Per-action approval | Approve/deny each write / delete / shell call in Cowork mode | | Appearance | Theme switcher | Dark / light / system, persisted; system follows the OS live | | Providers | OpenAI-compatible endpoints | DeepSeek Β· OpenAI Β· Groq Β· OpenRouter Β· Ollama Β· custom | | | Multi-profile config | Save and switch between named (provider, model, API key) sets | | Sessions | Auto-save + restore | All sessions persisted to ~/.dvalincode/sessions/ as JSON | | | LLM summary memory | Cross-session summary keeps the agent oriented after restart | | Memory | Local user/project memory | Searchable facts, preferences, and decisions in ~/.dvalincode/memory/; import from Claude/Hermes/Markdown | | Data portability | Export / import all data | One bundle of memory + sessions + config + audit β dvalincode export / import, or GUI Settings β Export / Import | | | Markdown transcript | Download any conversation as Markdown β sidebar download icon, dvalincode session md <id>, or /api/sessions/:id/markdown |
β¨οΈ Slash Commands
| Command | Description | |---|---| | /clear | Clear the current conversation (client-side, starts a fresh session) | | /compact | LLM-based context compaction β replaces history with a structured summary | | /undo [N] | Reverse the last N tool calls (default 1) | | /git | Run git_status and show branch, recent commits, changed files | | /plan <task> | Ask the agent to plan the task step-by-step without executing | | /help | Show all available 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 β
β runstart / runend β AuditSink (hash-chained JSONL) β
ββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ
β run()
ββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββ
β ToolRegistry β Zod schemas + permission gating β
β + audit taps: toolcall Β· file* Β· shell_exec β
β readfile Β· listfiles Β· searchtext Β· gitstatus Β· β
β writefile Β· editfile Β· delete_file Β· shell β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββAgent Loop β 8 States
RESTORE β COMPACT β COMMAND β BUILD β RUN β SAVE β RESPOND β DONE- RESTORE β Load session from
~/.dvalincode/sessions/ - COMPACT β If context near the limit, compress history (LLM summary)
- COMMAND β Handle built-in slash commands
- BUILD β Assemble system prompt (mode prompt + project + git + AGENTS.md)
- RUN β Delegate to
AgentRunnerfor the LLM tool-calling loop - SAVE β Persist session
- RESPOND β Generate cross-session summary memory
- DONE
π§ͺ Tests
npm test229 tests Β· 40 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 onlyBefore 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:
| Provider | Cheapest model | Input / Output | Notes | |---|---|---|---| | Groq | llama-3.1-8b-instant | Free tier | Fastest open models β Llama 3.3 70B, Mixtral | | Ollama | qwen2.5-coder | $0 (local) | No API key needed, runs on your machine | | DeepSeek | deepseek-chat | $0.14 / $0.28 per 1M | Cheap and strong; v3 nearly matches GPT-4 quality | | OpenRouter | google/gemini-2.0-flash-001 | $0.10 / $0.40 per 1M | 200+ models including Claude, Gemini, Llama | | OpenAI | gpt-4o-mini | $0.15 / $0.60 per 1M | Reliable; o1 available for deep reasoning | | Custom | β | depends | Any OpenAI-compatible base URL |
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
Does it send my code to a third party?
Only what the agent sends to the LLM you configured. Sessions, configs, and profiles all live on your machine in ~/.dvalincode/. To exclude sensitive files from the agent's view, drop a .dvalincodeignore in your repo root (gitignore-style patterns).
Can I run this without an API key?
Yes β use Ollama. Pull a model (ollama pull qwen2.5-coder), then in the LLM Configuration modal pick the Ollama provider. No key, no internet, no per-token cost.
Why three modes? Can't I just use one?
Each mode has different tool access and safety defaults: Chat is read-only, Cowork requires approval per write, Code is full-auto. Each also has a different sidebar (Templates / Projects / Routines) optimized for that workflow. You can switch any time β the conversation continues.
Is the shell tool sandboxed?
On macOS, yes β every shell tool invocation is wrapped in sandbox-exec with a profile that denies network access and allows file writes only inside cwd, /tmp, and /var. Linux and Windows sandboxing is planned.
How do I see what the agent actually did β and is the log trustworthy?
Every run writes a JSONL audit log to ~/.dvalincode/audit/run-<timestamp>-<id>.jsonl. Render it with dvalincode report --last (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 β dvalincode report verify <run-id> reports β chain intact or the exact position of a break. It's tamper-evident, not tamper-proof: a local attacker who can rewrite the whole file could recompute the chain. The value is forensic/accountability. See docs/AUDIT-TRAIL.md for the full threat model.
Will it overwrite my files without asking?
Depends on the mode. Chat never writes. Cowork requires approval per file (with inline red/green diff before you click Allow). Code is full-auto β use it for trusted tasks or in a feature branch.
The macOS binary won't open β "unverified developer"
The binary is unsigned. Run this once to clear the quarantine flag:
Or right-click the binary in Finder β Open β confirm once. xattr -dr com.apple.quarantine ~/.dvalincode
How do I save a routine in Code mode?
Switch to Code mode, click the + next to "ROUTINES" in the sidebar. Enter a name (e.g. "Deploy preview") and a prompt or slash command (e.g. "/git" or "Build the project and deploy to staging"). Routines persist in your browser's localStorage.
Does
AGENTS.md get sent every turn?
Yes β DvalinCode reads AGENTS.md from the project root before each turn and injects it under === PROJECT INSTRUCTIONS === in the system prompt. Keep it focused β it counts toward your token budget.
π€ 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 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
TurnState flow.
- The ReAct paper (Yao et al., 2022)
- OpenAI's
tool_callsmessage format, along with the broader
- OpenAI Codex / Codex CLI, Claude Code, Aider, opencode, Cursor, Cline, and
- The
AGENTS.mdproject-instruction convention, common in coding-agent tools,
- CodeQL, GitHub Code Scanning, Semgrep, SARIF, OpenSSF Scorecard, and ISO/IEC
- Git worktree, MCP, and local-first developer tooling patterns influenced the
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
