{ "markdown": "

\n \"DvalinCode\"\n

\n\n

\n English · 中文 · 🌐 dvalincode.dev\n

\n\n

\n \"Release\"\n \"Downloads\"\n \"Tests\"\n \"License\"\n \"OpenSSF\n \"Platforms\"\n \"LLM\n \"English\n

\n\n

\n Open security engineering for code written by humans and AI agents.
\n Every repair carries its own proof.\n

\n\nWhen an agent fixes a security finding, someone has to decide whether the fix\nworked. Almost every tool asks the model that wrote it — which is the one\nquestion a model cannot answer against its own interest.\n\n**Dvalin decides instead, and hands you the proof.** It re-scans, runs your\nproject's own tests itself, and reads the exit codes from processes it started.\nWho wrote the repair — our agent, Claude Code, Codex, Copilot, a person — is\nrecorded and never consulted. The result is a **Verified Fix Record**: a small\nJSON file anyone can re-check offline, on a laptop with no network and no\nDvalin state.\n\n```sh\ndvalin verify-fix fix-record.json\n```\n```\nFix record 2c9d71ac03e0 · VERIFIED · scan-and-checks\n executor: claude-code (recorded, not consulted)\n targets: 1 before · 0 remaining\n coverage: complete → complete\n introduced: 0 (gate high/new)\n outcome: verified\n ✓ test: npm run test (exit 0)\n audit: run verify-36509f42 @ 414644c75af0\n```\n\nThat record says something narrow on purpose: *these findings were gone, and\nthese checks were observed to pass.* It is not a claim that your code is safe,\nand Dvalin will not let it be read as one — every record carries what the scan\nactually covered, and a repair no check could confirm does not pass.\n[The open profile →](docs/spec/FIX-VERIFICATION.md)\n\nA repair is a change, and a change can add as well as remove. So the record also\ncarries what the re-scan saw that the first scan did not, and the gate threshold\nthe verdict was reached under: a fix that removes an `eval` and introduces an SQL\ninjection is recorded as `regressed` and does not verify. Neither does a record\nwhose issuer never looked — `introduced: not determined` fails, because a\nverifier that skips the question must not score better than one that asks it and\nfinds something.\n\nDvalin is the independent security runtime between code generation and merge.\nHumans, coding agents, and CI call the same versioned contract for discovery,\nremediation, and verification. It runs independently, or interoperates with\nspecialist systems such as Codex Security through portable SARIF. Its built-in\ncoding capability is a remediation executor — not the trust boundary, and not an\nattempt to compete with every general-purpose coding agent. See the\n[security-agent strategy](docs/SECURITY-AGENT-STRATEGY.md).\n\n---\n\n## ⏱️ 30 seconds, no install, no API key\n\n```sh\nnpx dvalincode security scan .\n# After installing the package: dvalin scan .\n```\n\nThat is the whole thing. It runs the built-in rules for injection, hardcoded\nsecrets, XSS, `eval`, and unsafe shell use against the current directory and\nprints what it found. No account, no model, no config, no code leaves your\nmachine. The default policy runs only Dvalin Built-in, so the first scan always\nworks. Add optional engines explicitly, or inspect their fixed install commands:\n\n```sh\ndvalin scanners list\ndvalin scanners install semgrep # review the command\ndvalin scanners install semgrep --yes # execute it under Dvalin policy\n```\n\nFor an incremental “no new high-risk findings” gate, commit the policy and\nbaseline with the repository:\n\n```sh\ndvalin init\ndvalin baseline\ndvalin scan\n```\n\nThis creates `dvalin.security.json` and `.dvalin/baseline.json`. Suppressions\nrequire a reason and may have an owner and expiry date. Scan output is a\nversioned envelope with a deterministic gate result and a resumable workflow ID.\n\n### Or put it on every pull request — nothing to install at all\n\n```yaml\n# .github/workflows/security.yml\npermissions:\n contents: read\n security-events: write\nsteps:\n - uses: actions/checkout@v5\n with:\n fetch-depth: 0 # so the scan can reach the base commit\n - uses: arthurpanhku/dvalincode@v0.18.0\n with:\n fail-on: high\n diff: true # only report on what this PR changed\n```\n\nFindings land inline on the pull request diff and in your Security tab.\nNo API key, no secrets, no model — the scan is deterministic and local to the\nrunner. [Full example →](docs/examples/dvalin-scan.yml)\n\n`diff: true` reports only on lines the pull request changed, so the gate blocks\nwhat this change *adds* instead of everything the repository already carried.\nThat is what makes the check adoptable on a codebase that was not clean to\nbegin with. Drop it to scan the whole repository.\n\nEvery comment states what the scan **covered** — `complete`, `partial`, or\n`unknown` — beside the result, because \"no findings\" from a run where half the\nengines were missing is not the same answer as \"no findings\" from a complete one.\n\n### And publish the proof next to the diff\n\nIf your pipeline produced a fix record, hand it to the same action:\n\n```yaml\n - uses: arthurpanhku/dvalincode@v0.18.0\n with:\n fix-record: fix-record.json\n```\n\nThe runner re-derives the record from the file alone — recomputing its hash and\nre-deriving its verdict from its own evidence — and posts the result on the pull\nrequest. A record that was edited after it was issued fails here, and fails the\njob. The reviewer does not have to trust the pipeline that produced it, or us.\n\n```\n🔏 Verified Fix Record\n✅ ce504a995395 · VERIFIED · scan-and-checks\n- repaired by claude-code — recorded, and not consulted for this verdict\n- targets: 1 before → 0 remaining\n- coverage: complete → complete\n- introduced: none (gate high/new)\n- outcome: verified\n- ✓ test: `npm run test` (exit 0)\n- audit chain: verify-eeb1bae7 @ 80881867270d\n```\n\nA repair that regressed says so in the same place, and fails the job with it:\n\n```\n❌ 916e2eeaf065 · NOT VERIFIED · scan-and-checks\n- introduced: 1 finding(s) the first scan did not report (gate high/new)\n - critical dvalin/sql-injection — src/db.ts:31\n- outcome: regressed\n```\n\n### Or let your agent call it\n\nIf an agent is writing the code, something other than that agent has to check\nit. DvalinCode is an MCP server, so any agent that speaks MCP can:\n\n```sh\nclaude mcp add dvalin -- npx -y dvalincode mcp-serve --workspace .\n```\n\nOne command configures the editor you actually use:\n\n```sh\nnpx dvalincode mcp-install cursor # .cursor/mcp.json\nnpx dvalincode mcp-install vscode # .vscode/mcp.json\nnpx dvalincode mcp-install claude-code # .mcp.json\n```\n\nThe formats differ in a way that fails silently — VS Code keys its servers under\n`servers`, Cursor under `mcpServers` — so the command writes the right one and\nmerges into whatever is already there. [Editors and MCP →](integrations/mcp/)\n\n`dvalin_scan` accepts `diff: \"uncommitted\"`, which reports only on what the\nagent just wrote rather than everything the repository already carried — the\ndifference between a usable answer and a wall of pre-existing findings. It never\nruns a model, edits the target workspace, or persists Dvalin state, so clients\ncan allow the preview by default. When a finding will be repaired, the agent\nexplicitly calls `dvalin_begin_verification` to record a small local workflow;\nit can then retrieve the finding by fingerprint and request an independent\nre-scan through `dvalin_get_finding` and `dvalin_verify_findings`.\n\nThat last one is the point: an agent that has just written a repair can ask for\nan independent verdict on it. Dvalin re-scans, runs the project's own checks\nitself, and returns a **Verified Fix Record** — what was targeted, what remains,\nwhat the repair introduced that was not there before, the gate the verdict was\nreached under, which commands ran and the exit codes Dvalin observed, and how\nmuch of the codebase was actually covered. Whoever wrote the repair is recorded\nand never consulted. `dvalin_verify_fix` re-derives such a record offline, so the reviewer\nreceiving it does not have to trust the tool that issued it.\n[FVP-1 →](docs/spec/FIX-VERIFICATION.md) Responses include MCP `structuredContent`; scanner\nreadiness is available through `dvalin_list_scanners`. The same server exposes\n`dvalin_run_task` as an optional implementation helper, plus session and audit\nevidence tools.\n\nEvery client below has been driven to a real tool call rather than only a\nhandshake — which client, which version, and on what date is a table rather\nthan a sentence, because hand-written version numbers go stale quietly.\n[Integration support ↓](#-integration-support) · [Agent integrations →](integrations/)\n\nThe repository also contains one [dual Codex/Claude plugin payload](integrations/dvalin-security/)\nwith both native manifests, the shared security-gate skill, and the local MCP\nserver configuration. Installing it makes the gate discoverable from task\ncontext instead of requiring every developer to remember a scan prompt.\nCodex honors the scan's read-only MCP annotation. Claude Code requires one\nexplicit MCP permission by design; the plugin documents the exact scan-only\nallow rule instead of asking users to bypass all permissions.\n\n### Wherever you already work\n\nOne server, reached the way each tool expects:\n\n| Harness | How Dvalin reaches it |\n|---|---|\n| **Claude Code** | [dual plugin](integrations/dvalin-security/) or `claude mcp add` · [standalone skill](integrations/claude-code/) |\n| **Codex** | [dual plugin](integrations/dvalin-security/) or `codex mcp add` · [SARIF interop](integrations/codex-security/) with Codex Security |\n| **Cursor** | `dvalincode mcp-install cursor` |\n| **VS Code** | `dvalincode mcp-install vscode` · [extension](editors/vscode/) for Problems, coverage/gate status, and offline VFR verification — *built, not yet published* |\n| **Windsurf · Zed** | stdio MCP through their own settings — [server command](integrations/mcp/) |\n| **Any MCP client** | [MCP registry](https://registry.modelcontextprotocol.io/): `io.github.arthurpanhku/dvalincode` |\n| **GitHub Actions** | [Marketplace action](https://github.com/marketplace/actions/dvalin-security-scan) — findings inline on the pull request diff |\n| **Any CI** | `dvalin scan . --fail-on high`, SARIF out for code scanning |\n\nThe MCP config formats are not interchangeable — VS Code keys its servers under\n`servers`, Cursor under `mcpServers`, and the wrong one fails silently — so\n`mcp-install` writes the right shape and merges into whatever is already there.\n[Editors and MCP →](integrations/mcp/)\n\n### Or interoperate with Codex Security\n\n[Codex Security](https://github.com/openai/codex-security) can export a completed,\nsealed scan as SARIF. Import that portable projection without coupling Dvalin to\nCodex Security's private state directory:\n\n```sh\nDVALIN_CODEX_SCAN_DIR=/tmp/codex-security-results\nnpx @openai/codex-security scan . --output-dir \"$DVALIN_CODEX_SCAN_DIR\"\nnpx @openai/codex-security export \"$DVALIN_CODEX_SCAN_DIR\" \\\n --export-format sarif --source-root \"$PWD\" --output /tmp/codex-security.sarif\n\ndvalin import /tmp/codex-security.sarif .\ndvalin scan . --fail-on high\n```\n\nThe import creates stable Dvalin remediation cases; `--no-persist` validates the\nhandoff without changing the backlog. Keep Codex Security's original manifest,\nfindings, and coverage artifacts together—Dvalin imports the SARIF finding\nprojection but does not rewrite its sealed bundle or reinterpret its coverage.\n[Integration guide →](integrations/codex-security/)\n\n### Then let it fix what it found\n\n```sh\ndvalincode dvalin . --fix --verify --draft-pr\n```\n\nThis step *does* use a model — your model, any OpenAI-compatible endpoint. It\nprepares focused repairs in an isolated worktree, runs your tests, and requires\na clean re-scan before anything can proceed to a draft PR. It never auto-merges,\nand a clean scan is never treated as proof that the code is safe.\n\n

\n \"Dvalin\n

\n\nThis animation is made from the real application, not a mock. The input is an\nApache-2.0-licensed example adapted from\n[OWASP NodeGoat](https://github.com/OWASP/NodeGoat/tree/c5cb68a7084e4ae7dcc60e6a98768720a81841e8/app/routes),\nwhose contribution route evaluated user-controlled text.\n\n## 🛡️ What that run actually did\n\nDvalin turns open-source scanner evidence into a controlled scan → fix → test →\nre-scan → draft-PR workflow. Here is the run in the animation above, measured:\n\n| Real NodeGoat-derived run | Before | After Dvalin remediation |\n|---|---:|---:|\n| Security health (triage heuristic) | 22 / 100 · F | 100 / 100 · A |\n| Findings | 10 (`eval` across 3 rules, 2 engines) | 0 |\n| Tests | 2 passing | 3 passing, including an injection regression test |\n| Scanner fleet | 4 / 4 completed | 4 / 4 completed |\n\nThe scanning and hardening **control plane** uses open-source components:\n\n- [Semgrep CE](https://github.com/semgrep/semgrep) and its community rules for\n semantic SAST.\n- [Trivy](https://github.com/aquasecurity/trivy) for filesystem vulnerabilities,\n secrets, and misconfiguration.\n- [OSV-Scanner](https://github.com/google/osv-scanner) with the open\n [OSV database](https://osv.dev/) for dependency vulnerabilities.\n- DvalinCode's MIT-licensed built-in rules, remediation orchestration, test and\n re-scan gates, plus [SARIF 2.1](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html)\n import for other compatible scanners.\n\nThe scanners find and rank evidence. The configured model proposes source\nchanges; DvalinCode constrains that work, records the diff, runs project tests,\nre-scans the changed tree, and keeps PR publication explicit. It does not\nauto-merge and it does not claim that a clean scan proves the absence of bugs.\nChoose an open-weight model through Ollama if the repair-proposal step must also\nstay fully local and open; hosted model licensing depends on the provider.\n\nYou can still prove what the agent did after the fact:\n\n```sh\ndvalincode report verify # re-derive the hash chain of the last run's audit log\n```\n\n---\n\n## 🧩 Integration support\n\nCode written with an AI assistant passes through four sets of hands before it\nmerges: the agent that writes it, the editor the developer reads it back in, the\npull request that gates it, and the reviewer who has to believe the result. A\nsecurity answer that exists in only one of those places is not a gate — it is a\nsuggestion the next stage is free to ignore.\n\nDvalin is one MCP server and one deterministic scan behind all four, so the\nanswer does not change depending on who asks it.\n\n| Stage of the loop | Where you are | How Dvalin gets there | Status |\n|---|---|---|---|\n| **Writing the code** | Claude Code | [dual plugin](integrations/dvalin-security/) · `claude mcp add` · `mcp-install claude-code` | ✅ session verified |\n| | Codex | [dual plugin](integrations/dvalin-security/) · `codex mcp add` · [SARIF interop](integrations/codex-security/) | ✅ session verified · capture pending |\n| | Cursor | `dvalincode mcp-install cursor` | ⚙️ config verified |\n| | Windsurf · Zed | stdio MCP through their own settings | ⚙️ documented, unverified |\n| | Any MCP client | registry `io.github.arthurpanhku/dvalincode` | ⚙️ published |\n| **Reading it back** | VS Code | `mcp-install vscode` · [extension](editors/vscode/) for Problems, coverage and gate status | ✅ editor verified |\n| **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 |\n| | Any CI | `dvalin scan . --fail-on high`, SARIF out for code scanning | ✅ the exit code is the contract |\n| **Believing the result** | anyone, offline | `dvalin verify-fix record.json` | ✅ no workspace, no network, no Dvalin state |\n\n**✅** means a real client was driven end to end and the tool call was observed.\n**⚙️** means the configuration is generated and its shape is tested, but no\nsession has been captured. The difference is not smoothed over here, because a\nconfig file that loads is not evidence that a tool was ever called.\n\n### What each claim rests on\n\n| Client | Version | Checked | How |\n|---|---|---|---|\n| 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 |\n| 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 |\n| Codex | CLI 0.149.1 | 2026-09-03 | by hand on macOS: scan called under `approval=never` in a read-only sandbox, no workflow state written |\n| 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 |\n| 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 |\n| Cursor | — | 2026-09-04 | `mcp-install cursor` writes `.cursor/mcp.json` under `mcpServers`; no session has been captured |\n\nThat weekly workflow exists because an earlier version of this claim named two\nCLI versions by hand, both went stale within weeks, and nothing said so. It now\nre-checks against whatever those tools shipped that week, so the dates above\neither move on their own or stop moving in public.\n\n### The same finding, in each place\n\n**Claude Code** — one read-only tool allow-listed, and the MCP call itself:\n\n![A Claude Code session calling the Dvalin MCP server](docs/screenshots/10-claude-code-session.png)\n\n**Codex** — capture pending.\n\n\n\n**VS Code** — the same scanner contract, as squiggles and a status bar:\n\n![A Dvalin finding and its coverage status inside VS Code](docs/screenshots/09-vscode-dvalin-integration.png)\n\n---\n\n## 🏛️ And it survives a security review\n\nThat last command is the part that matters once more than one person depends on\nthis. DvalinCode is a full coding agent — terminal, web GUI, and desktop app —\nbuilt so that an organization, not the developer, bounds what it may do: a\npolicy file constrains modes, commands, paths, tools, and models; every run is\nhash-chained into a tamper-evident audit log; nothing reaches a provider that\nthe egress guard did not allow. A repo policy can only ever *narrow* the\nmachine-level one.\n\nIf you are the person who has to approve this class of tool, start at\n[APPROVABILITY-PLAN.md](docs/APPROVABILITY-PLAN.md) and the\n[Evidence Pack](docs/EVIDENCE-PACK.md) that every release ships of itself.\n\n---\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
🏠 HomeOne place for read-only Ask and approval-gated Collaborate workflows. Switch intent without leaving the project or conversation.
⚡ CodeFocused 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.
🛡️ DvalinDedicated 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. Dvalin guide →
🏦 Regulated teamsDesigned 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 remediationRun 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. Workflow →
📚 SkillsUpload, 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 trailEvery 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 & trustA 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 evidenceOpenSSF 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. Scorecard map → · ISO 42001 alignment → · Release evidence →
📐 Open specsPCP-1 — 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. Provider Conformance Profile →
🖥️ First-class GUIModern 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 binaryRun 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.
🖥️ Native desktop appDvalinCode.app — a real dock application (OS-native webview, no Electron) over the same engine. On macOS the one-line installer puts it in /Applications automatically; launch it straight from Launchpad.
🪶 Zero-dependency binarySingle ~25MB executable per platform. No Node, no Python, no Docker.
🔐 Local-firstSessions, 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 & exportableExport 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.
\n\n---\n\n## 🎯 Core Goal\n\n> **Make every code-producing human or agent pass the same independent security gate.**\n\nDvalinCode is built as an **agent-compatible security runtime**, not another\ngeneral coding-agent benchmark entry. The core product is scan evidence,\npolicy, baseline, deterministic verification, and portable interfaces that a\nhuman developer, an external agent, or CI can all call. The bundled coding agent\nstays capable enough to implement and test focused remediations reliably; its\nmodel prose never decides whether the security gate passed.\n\n- **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.\n- **Safe by default** — three-tier approvals with diff preview, an undo stack, and sandboxed shell execution. An agent you can trust on full-auto.\n- **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.\n- **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.\n- **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)\n\nThe bundled **web GUI is the runtime's reference implementation and showcase** — the first consumer of that public API, demonstrating everything the runtime can do.\n\n---\n\n## ✅ Why Teams Pick DvalinCode\n\nDvalinCode is differentiated by **approvability**. It is built for teams that\nneed AI coding to pass security, compliance, and data-governance review before\nit can touch production repositories.\n\n- **Closed-loop secure remediation** — scan locally or import SARIF from\n CodeQL, GitHub Code Scanning, Semgrep, or compatible scanners; persist\n findings as local remediation cases; create an isolated\n `dvalin/remediate/...` worktree; then send a focused repair prompt with\n source context and verification instructions.\n- **Skills as governed operating procedures** — upload, download, and inspect\n local skill bundles. Built-in secure scanning and remediation skills tell\n agents which tools to use and keep workflows portable across machines.\n- **Model freedom without policy drift** — use DeepSeek, OpenAI, Claude via\n OpenRouter, Groq, Ollama, or any OpenAI-compatible endpoint while keeping\n tool permissions, audit, and workspace policy consistent.\n- **Security evidence, not just security claims** — OpenSSF Scorecard support,\n CodeQL, Dependabot, pinned Actions, CODEOWNERS, ISO/IEC 42001 alignment docs,\n AI change-impact records, and hash-chained run logs are part of the project.\n- **Local-first by default** — sessions, config, profiles, memory, and audit\n logs stay under `~/.dvalincode/`; `.dvalincodeignore` and policy controls\n bound what the agent can read, write, or execute.\n\n---\n\n## 🛡️ Security & Governance\n\n

\n \"ISO/IEC\n \"Compliance\n \"DevSecOps\n

\n\nDvalinCode maintains project-level governance evidence for open-source and\nenterprise review. This is the differentiator for teams where AI coding must\npass security approval before it can reach production repositories:\n\n- **Threat model** — the full attack surface of an agentic coding runtime\n (malicious `AGENTS.md`, poisoned MCP servers, prompt-injection escalation,\n egress, audit tampering, supply chain, sandbox escape), each mapped to the\n control that defends it and the honest residual gap. [Threat model →](docs/THREAT-MODEL.md)\n- **OpenSSF Scorecard support** — scheduled Scorecard workflow, SARIF upload,\n CodeQL, Dependabot, CODEOWNERS, least-privilege workflow permissions, and\n SHA-pinned GitHub Actions. [Control map →](docs/security/OPENSSF-SCORECARD.md)\n- **ISO/IEC 42001 alignment** — an AI management system scope, AI policy, role\n map, risk register, AI change classification, required records, and review\n cadence. [AIMS alignment →](docs/governance/ISO-42001-AIMS.md)\n- **AI change impact assessment** — a reusable template for changes that affect\n model/provider behavior, prompts, permissions, tools, audit logs, or release\n security. [Template →](docs/governance/AI-CHANGE-IMPACT-ASSESSMENT.md)\n- **Regulated-use posture** — local-first data handling, policy-controlled\n autonomy, minimized audit records, and release supply-chain evidence for\n finance, healthcare, security-sensitive SaaS, and internal enterprise use.\n- **Dvalin security engineering** — the dedicated Dvalin workspace combines the\n built-in scanner with installed Semgrep CE, Trivy, and OSV-Scanner, normalizes\n SARIF findings, drives isolated test-backed fixes, and explicitly prepares a\n reviewable draft PR without auto-merging it.\n [Workflow →](docs/SECURE-REMEDIATION.md)\n\nThese documents are implementation evidence and operating procedures; they do\nnot claim third-party ISO certification.\n\n---\n\n## ⭐ What's New in v0.14.0 — Dvalin security engineering\n\n- **Home unifies Chat and Cowork** — the GUI now has a single Home workspace\n with read-only Ask and approval-gated Collaborate intents, while keeping the\n same project and conversation context.\n- **Code is focused again** — the old Security and Routines panels have been\n removed from Code so its sidebar is dedicated to projects and autonomous\n implementation.\n- **Dvalin is a first-class workspace** — orchestrate the built-in scanner plus\n installed Semgrep CE, Trivy, and OSV-Scanner; import SARIF; score and triage\n findings; persist remediation cases; and create isolated repair worktrees.\n- **One flow from evidence to draft PR** — selected findings can launch an\n evidence-backed Agent fix, run focused tests/typecheck/build and a fresh scan,\n review the diff, and explicitly publish a draft PR without automatic merge.\n- **Agent loops converge sooner and cost less** — investigation-before-edit and\n stall detection reduce repeated failed actions, general tool output is\n bounded, prompts remain append-only for cache reuse, and provider usage now\n accounts for cache hits/misses.\n- **Provider and evaluation upgrades** — native Anthropic prompt caching and\n cache accounting are supported, and the SWE-bench Docker harness reports\n official scores, policy violations, stalls, and token/cache metrics.\n\n---\n\n## ⭐ What's New in v0.12.4 — finish the task before stopping\n\n- **Process narration no longer ends a task** — responses such as “let me\n verify the file” are recognized as pending work, and the agent immediately\n continues with the promised action instead of treating them as a final answer.\n- **Truncated responses automatically recover** — provider finish reasons are\n preserved, so output cut off by a token limit triggers another model step.\n- **Normal coding turns get room to finish** — the per-turn action limit is now\n an emergency 100-action guard rather than a routine 15-action stopping point;\n stricter organization policy limits still take precedence.\n- **Completion is explicit** — Code mode is instructed to return a tool-free\n answer only after the requested work and focused validation are complete.\n\n---\n\n## ⭐ What's New in v0.12.3 — resilient long-running Code mode\n\n- **Long coding turns keep going** — Code mode now compacts context during an\n active tool loop, accounts for the full provider request when estimating\n tokens, and raises the default iteration checkpoint from 10 to 40.\n- **Interruptions are resumable** — completed tool state is persisted when a\n turn is interrupted or its connection closes, so a follow-up `continue`\n resumes from the actual workspace progress.\n- **Visible, quieter agent activity** — running sessions show a sidebar loading\n state, each response reports elapsed work time, and its Action timeline is\n available on click while raw Tool Calls stay collapsed by default.\n- **GitHub workflows from Code mode** — network-aware `git` and GitHub CLI\n (`gh`) operations now support pull, push, PR creation, and Actions/repository\n commands through the governed shell approval path.\n- **Safer releases** — package and CLI versions are synchronized, and\n `prepublishOnly` runs the build, typecheck, and test suite before publishing.\n- **Simple tasks stay simple** — the Action budget is enforced across the whole\n turn instead of resetting on every model iteration, and Code mode is prompted\n to take the shortest direct path and stop when focused validation passes.\n\n---\n\n## ⭐ What's New in v0.12.2 — 🖥️ Desktop app milestone: it just works\n\n- **🖥️ The native desktop app now works out of the box on macOS** — `DvalinCode.app`\n opens a real dock window (WKWebView, no Electron) over the embedded engine.\n Two threading bugs that shipped in every earlier desktop build are fixed:\n the blocking webview loop no longer starves the embedded server (blank\n window), and the webview runs on the main thread as macOS requires (no\n window at all) — the server now lives in a child process of the same binary.\n- **📦 The one-line installer installs the app** — on macOS,\n `curl … install.sh | bash` now also puts `DvalinCode.app` (with the\n DvalinCode icon) into `/Applications`, so the desktop window launches\n straight from Launchpad after a CLI install. Opt out with\n `DVALINCODE_NO_APP=1`; pin with `DVALINCODE_GUI_VERSION`.\n- **✅ Desktop is no longer \"experimental\" on macOS** — the window and the\n embedded server are verified working; Windows and Linux desktop builds are\n cross-compiled and remain a preview.\n\n
\nv0.9.0 — 🛡️ Secure remediation · Skills · CodeQL hardening\n\n- **🛡️ Secure remediation workflow** — run a built-in local scan or import SARIF\n from CodeQL, GitHub Code Scanning, Semgrep, and compatible scanners; findings\n become local remediation cases with source context, verification guidance, and\n isolated worktree repair tasks.\n- **📚 Skills** — upload, download, inspect, and reuse local skill bundles.\n DvalinCode now ships built-in secure-code-scan and secure-code-remediation\n skills, plus agent tools for listing skills, reading instructions, scanning,\n listing remediation cases, and preparing remediation worktrees.\n- **🔐 CodeQL path hardening** — user-controlled workspace, remediation, and\n skill paths now go through explicit root-containment checks, with regression\n tests covering traversal-safe resolution and skill import boundaries.\n- **🎨 App icons** — dark and light theme application icons now ship with the web\n bundle and desktop build inputs.\n\n
\n\n
\nv0.8.0 — 🔒 Governance: controllable · transparent · auditable\n\n- **🔒 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)\n- **🔎 `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.\n- **`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)\n- **🧾 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.\n- **📐 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.\n\n
\n\n
\nv0.7.0 — 🧪 Desktop app (beta)\n\n- **🧠 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.\n- **📝 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 `, or `GET /api/sessions/:id/markdown`.\n- **🖥️ 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.\n- **🧩 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`).\n- **Status:** the desktop binaries are **experimental / unverified** — grab them from the latest **pre-release** and please report how the window behaves on your OS.\n\n
\n\n
\nv0.6.0 — terminal agent · serve · shared turn-runner\n\n- **🖥️ 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.\n- **🌐 `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`.\n- **🧩 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.\n\n
\n\n
\nv0.5.0 — security-grade audit trail · Run Report · theme switcher\n\n- **🛡️ 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)\n- **📋 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:\n ```sh\n dvalincode report --last # render the most recent run\n dvalincode report --format json\n dvalincode report verify # ✓ chain intact / ✗ broken at seq N\n ```\n- **🎨 Theme switcher** — choose **dark / light / system** in Settings. `system` follows your OS live; the choice persists across sessions.\n\n
\n\n
\nv0.4.0 — /compact · dvalin.json team playbook · self-contained binaries\n\n- **`/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%`).\n- **`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.\n- **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.\n\n
\n\n
\nv0.3.0 — Mode-aware sidebar · one-line installer · multi-profile LLM config\n\n- **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`.\n- **One-line installer** — `curl … | bash` auto-detects your OS + arch, drops the binary into `~/.dvalincode/`, and patches your `PATH`. No package manager dependencies.\n- **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.\n\n
\n\n---\n\n## 📸 Preview\n\n**A real Dvalin scan of vulnerable code — Security health 22/100 · F, with the\n10 findings the engines actually reported, located to the line:**\n\n

\n \"Dvalin\n

\n\n**The verified result — a real model-driven Verify turn inspected the repair,\nran the regression tests and all four open-source engines, then the deterministic\nserver re-scan reported complete coverage, a passing gate, 0 findings, 100/100 · A:**\n\n

\n \"A\n

\n\n**Home → Code → Dvalin — the current workspaces:**\n\n

\n \"DvalinCode\n

\n\nThe scan images above are unedited captures of a real run against the documented\nNodeGoat-derived case: the scanners were run, the model repaired the source, the\nproject's tests were run, and the tree was re-scanned. Nothing is staged, and a\n100/A means the configured engines found nothing — not that the code is proven\nsafe.\n\n---\n\n## 🆚 When to choose DvalinCode\n\n| If you need… | DvalinCode's answer |\n|---|---|\n| **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. |\n| **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. |\n| **A safer alternative to generic autonomous coding agents** | The product thesis is controllable / transparent / auditable, not only \"the model can edit files\". |\n| **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`. |\n| **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. |\n| **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. |\n| **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. |\n\n---\n\n## 🚀 Quick Install\n\n### Homebrew (macOS / Linux)\n\n```sh\nbrew tap arthurpanhku/dvalincode https://github.com/arthurpanhku/dvalincode\nbrew install arthurpanhku/dvalincode/dvalincode\n```\n\nInstalls the same signed-by-checksum release archive the one-liner does, and\n`brew upgrade` keeps it current. Homebrew never applies the macOS quarantine\nattribute, so this path is not subject to Gatekeeper.\n\n### macOS / Linux (one-liner)\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/arthurpanhku/dvalincode/main/scripts/install.sh | bash\n```\n\nDetects 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:\n\n```sh\nsource ~/.zshrc # or ~/.bashrc\ndvalincode # interactive terminal agent\ndvalincode dvalin . # white-box security scan (GUI-independent)\ndvalincode serve # start the web GUI, open the browser\ndvalincode serve --host 0.0.0.0 --no-open # host it on a server for remote/browser use\necho \"inspect src and summarize\" | dvalincode run - --output-format stream-json\ndvalincode mcp-serve # task-level stdio MCP server for external agents\n```\n\nHeadless `run` and `mcp-serve` keep the same policy and audit chokepoint as\nthe interactive clients. See the [unattended recipes](docs/RECIPES-UNATTENDED.md)\nfor cron, CI, and external-agent examples.\n\nA run that scanned or filed a fix record also carries a `verification` envelope\nbeside its answer — in `json`, in `stream-json`, and in the MCP `dvalin_run_task`\nresult. `coverageStatus` is the *weakest* coverage the run has evidence of, so\none complete scan cannot speak for a partial one, and any record it produced is\nlisted by path for offline re-derivation. A CI gate can read it directly:\n\n```sh\njq -e '.verification.coverageStatus == \"complete\"' run.json || exit 1\n```\n\nThat is the same rule the pull-request comment applies, on the surface with no\nhuman watching. [Harness mode →](docs/HARNESS-MODE.md)\n\n### Windows\n\nDownload `dvalincode-v*-windows-x64.zip` from [Releases](https://github.com/arthurpanhku/dvalincode/releases/latest), unzip, then double-click `start.bat`.\n\n### Manual download\n\nGrab the archive for your platform from the [Releases page](https://github.com/arthurpanhku/dvalincode/releases/latest):\n\n| Platform | Archive |\n|---|---|\n| macOS Apple Silicon (M1/M2/M3) | `dvalincode-v*-macos-arm64.tar.gz` |\n| macOS Intel | `dvalincode-v*-macos-x64.tar.gz` |\n| Windows x64 | `dvalincode-v*-windows-x64.zip` |\n| Linux ARM64 | `dvalincode-v*-linux-arm64.tar.gz` |\n| Linux x64 | `dvalincode-v*-linux-x64.tar.gz` |\n\nVerify against `SHA256SUMS.txt` (included in each release).\n\nEach release also ships **`dvalincode-v*-evidence.json`** — an Evidence Pack the\nshipped binary produced of itself on the build machine: two real governed runs,\none allowed and one blocked by policy, with their hash chains. You can check the\nclaims on this page before installing anything:\n\n```sh\ndvalincode evidence verify dvalincode-v0.14.0-evidence.json # offline, reads only the file\n```\n\nThe pack's checksum is inside `SHA256SUMS.txt`, which is the subject of the\nrelease's build-provenance attestation. [How it is produced →](docs/RELEASE-EVIDENCE.md)\n\n> **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.\n\n### Staying up to date\n\nDvalinCode updates itself — no need to re-run the installer:\n\n```sh\ndvalincode update --check # is a newer release out? (read-only)\ndvalincode update # download, verify, and install the latest\n```\n\nIt finds the newest release on GitHub, and for a binary install downloads the\nmatching archive, **verifies it against the release's `SHA256SUMS.txt` before\nswapping anything in**, then replaces `~/.dvalincode/` in place. npm installs are\nupdated via `npm i -g`, and source checkouts are pointed at `git pull`. Add\n`-y` to skip the prompt, `--prerelease` to track pre-releases, or `--json` for\nscripting.\n\nThe macOS desktop app checks the separate `gui-v*` release track when it starts.\nWhen a newer GUI is available, it asks before downloading, verifies the archive\nagainst `SHA256SUMS-gui.txt`, validates the app version, then replaces and\nrestarts `DvalinCode.app`. A failed replacement rolls back to the previous app.\n\n---\n\n## 🎬 First-time setup\n\n**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**.\n\n**Web GUI:** run `dvalincode serve` and:\n\n1. The server starts on `http://localhost:3000` and your browser opens automatically.\n2. Click **LLM Configuration** in the sidebar (bottom-left).\n3. Pick a provider, paste your API key, choose a model, hit **Save**.\n4. Optional: save the current config as a named profile (e.g. `fast`, `cheap`, `local-ollama`) to switch quickly later.\n\nBoth share the same config and sessions in `~/.dvalincode/`.\n\n---\n\n## ✨ Features\n\n| Category | Feature | Notes |\n|---|---|---|\n| **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 |\n| **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 |\n| **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 |\n| **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/` |\n| **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 |\n| **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) |\n| **Composer** | `@` file references | Type `@` for a fuzzy file search; selected files get inlined into the prompt |\n| | `/` slash commands | `/clear` `/compact` `/git` `/plan` `/undo` `/help` |\n| | Multiline + interrupt | Shift+Enter for newline, stop button to abort mid-stream |\n| **Tool UI** | Inline diffs | `edit_file` and `write_file` results render as red/green unified diff, default folded |\n| | Approval dialog with diff | Cowork mode shows the diff *before* the change is applied |\n| | Live tool counter + token + cost | Topbar shows session totals in real time |\n| **Agent** | LLM-based context compaction | `/compact` summarises into Goal / Completed / Decisions / Pending |\n| | Persistent undo stack | `/undo [N]` reverses the last N tool calls |\n| | Run Report | Markdown summary per run (files, commands, decisions, test result) — GUI card + `dvalincode report` |\n| | Git awareness | Branch name in topbar; `git_status` tool; git context auto-injected into prompt |\n| | `AGENTS.md` project memory | Per-repo persistent instructions, auto-loaded each turn |\n| **Security** | Tamper-evident audit trail | Hash-chained JSONL per run in `~/.dvalincode/audit/`; `dvalincode report verify` detects edits |\n| | macOS shell sandbox | `sandbox-exec` denies network; allows writes only inside cwd + `/tmp` |\n| | `.dvalincodeignore` | gitignore-style exclusion; blocks `read_file` / `list_files` / `search_text` |\n| | Per-action approval | Approve/deny each write / delete / shell call in Cowork mode |\n| **Appearance** | Theme switcher | Dark / light / system, persisted; `system` follows the OS live |\n| **Providers** | OpenAI-compatible endpoints | DeepSeek · OpenAI · Groq · OpenRouter · Ollama · custom |\n| | Multi-profile config | Save and switch between named (provider, model, API key) sets |\n| **Sessions** | Auto-save + restore | All sessions persisted to `~/.dvalincode/sessions/` as JSON |\n| | LLM summary memory | Cross-session summary keeps the agent oriented after restart |\n| **Memory** | Local user/project memory | Searchable facts, preferences, and decisions in `~/.dvalincode/memory/`; import from Claude/Hermes/Markdown |\n| **Data portability** | Export / import all data | One bundle of memory + sessions + config + audit — `dvalincode export` / `import`, or GUI Settings → Export / Import |\n| | Markdown transcript | Download any conversation as Markdown — sidebar download icon, `dvalincode session md `, or `/api/sessions/:id/markdown` |\n\n---\n\n## ⌨️ Slash Commands\n\n| Command | Description |\n|---|---|\n| `/clear` | Clear the current conversation (client-side, starts a fresh session) |\n| `/compact` | LLM-based context compaction — replaces history with a structured summary |\n| `/undo [N]` | Reverse the last N tool calls (default 1) |\n| `/git` | Run `git_status` and show branch, recent commits, changed files |\n| `/plan ` | Ask the agent to plan the task step-by-step *without* executing |\n| `/help` | Show all available slash commands |\n\n---\n\n## 🛠️ Architecture\n\n```\n┌───────────────────────────┐ ┌─────────────────────────┐\n│ Terminal UI (readline) │ │ Browser GUI (React/Vite)│\n│ streaming · approvals │ │ ChatThread · DiffViewer │\n└─────────────┬─────────────┘ └────────────┬────────────┘\n │ in-process HTTP / WebSocket\n │ ┌───────────────▼─────────────┐\n │ │ Express + ws server │\n │ │ /api/* · `dvalincode serve` │\n │ └───────────────┬─────────────┘\n └──────────────┬─────────────────┘\n┌────────────────────────────▼────────────────────────────┐\n│ runAgentTurn — shared turn-runner (src/agent/session) │\n│ provider · prompt (mode · git · AGENTS.md) · session │\n└────────────────────────────┬────────────────────────────┘\n │\n┌────────────────────────────▼────────────────────────────┐\n│ Agent Engine │\n│ AgentLoop (8-state machine) → AgentRunner │\n│ Streaming · Interrupt · Undo stack · LLM compaction │\n│ run_start / run_end → AuditSink (hash-chained JSONL) │\n└──────────────────────────┬──────────────────────────────┘\n │ run()\n┌──────────────────────────▼──────────────────────────────┐\n│ ToolRegistry — Zod schemas + permission gating │\n│ + audit taps: tool_call · file_* · shell_exec │\n│ read_file · list_files · search_text · git_status · │\n│ write_file · edit_file · delete_file · shell │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Agent Loop — 8 States\n\n```\nRESTORE → COMPACT → COMMAND → BUILD → RUN → SAVE → RESPOND → DONE\n```\n\n1. **RESTORE** — Load session from `~/.dvalincode/sessions/`\n2. **COMPACT** — If context near the limit, compress history (LLM summary)\n3. **COMMAND** — Handle built-in slash commands\n4. **BUILD** — Assemble system prompt (mode prompt + project + git + AGENTS.md)\n5. **RUN** — Delegate to `AgentRunner` for the LLM tool-calling loop\n6. **SAVE** — Persist session\n7. **RESPOND** — Generate cross-session summary memory\n8. **DONE**\n\n---\n\n## 🧪 Tests\n\n```sh\nnpm test\n```\n\n**584 core tests · 74 files · all green.** The VS Code extension has a separate\n37-test suite plus one opt-in published-package integration test.\n\n---\n\n## 🏗️ Build from source\n\nRequires [Bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`).\n\n```sh\ngit clone https://github.com/arthurpanhku/dvalincode\ncd dvalincode\nnpm install\nnpm run dev:all # start backend (3001) + Vite (5173)\n```\n\nBuild release binaries for every platform:\n\n```sh\nbash scripts/build-release.sh # → release/ with tar.gz / zip + SHA256SUMS.txt\nbash scripts/build-release.sh darwin # macOS only\nbash scripts/build-release.sh windows # Windows only\n```\n\nBefore publishing a release:\n\n```sh\n(cd release && shasum -a 256 -c SHA256SUMS.txt)\nunzip -l release/dvalincode-v*-windows-x64.zip | grep 'web/dist/index.html'\ntar tzf release/dvalincode-v*-macos-arm64.tar.gz | grep 'DvalinCode.app/Contents/Resources/AppIcon.icns'\n```\n\nWindows 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 `w", "bytes": 60000, "sha": "ca22e4bbb7e036f2ef87946f479bc8ed81ee04cb90f882bc5400930ccbbb5503", "repo_slug": "arthurpanhku/dvalincode", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_arthurpanhku_dvalincode_9d8621ed/readme" }