Skip to content
Back to search

vulcan-code

Open-source AI coding workbench in Rust: desktop app (GUI) + terminal TUI. Multi-session agents, plan and goal modes, built-in terminal and browser, diff review and Git commits, MCP client and server, skills, knowledge base and long-term memory. Works with OpenAI, Anthropic, Gemini, DeepSeek and more.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 18 Nov 2026.

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

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/OpenVulcan/vulcan-code with scanskillsafety

Or from a terminal, clone it and run it:

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

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openvulcan--vulcan-code/badge.svg)](/listings/openvulcan--vulcan-code)

HTML

<a href="/listings/openvulcan--vulcan-code"><img src="/api/listings/openvulcan--vulcan-code/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

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

> Full verification has been done on **Windows x86_64**. Linux and macOS have a matching `make.sh` script but have not been fully run end to end yet — help verifying is welcome.

Requirements

- `make` - [Rustup](https://rustup.rs/): the toolchain version is pinned by `rust-toolchain.toml` and installed automatically - PowerShell 7 - Node.js and pnpm

Build and run

make init-system   # First time: install Rust tools, host dependencies and managed Node/pnpm
make sync          # Sync config, system skills, plugins and browser runtime into output/
make build         # Build Core, WebUI and the Electron desktop shell
make run           # Launch the desktop app

You can also use `make br` to build and run in one step; `make bt` does a full build, starts Core and opens the TUI, without the desktop app or Vite. Use `make release` for release builds.

See [`docs/contracts/development-environment.md`](docs/contracts/development-environment.md) for detailed environment notes.

Day-to-day development

The Vite dev server, the Core service and the Electron shell are independent and can be started and restarted separately:

make vite start      # Start the WebUI Vite dev server (also supports status / stop)
make service         # Start only the background Core, without the desktop window
make core-restart    # Rust Core changes only: incremental build and hot-swap the Core (Windows Debug)
make sync            # Re-sync after changing resources, config, skills or plugins

- For WebUI-only changes, keep Vite and the desktop shell running to get hot reload - In debug mode, `make run` / `make br` make sure Vite is running - Do not edit `output/` directly; authoritative resources live in `crates/vulcan-runtime-assets/resources/`

What was scanned

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

README.md · README · 249 lines
  1. <div align="center">
  2. <img src="apps/vulcan-code-web/public/vulcan-logo.png" alt="Vulcan Code" width="120" />
  3. # Vulcan Code
  4. **An open-source AI Coding workbench: GUI desktop app + terminal TUI**
  5. Rust Core · Electron desktop shell · React WebUI · ratatui TUI
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  7. [![Issues](https://img.shields.io/github/issues/OpenVulcan/vulcan-code)](https://github.com/OpenVulcan/vulcan-code/issues)
  8. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/OpenVulcan/vulcan-code/pulls)
  9. **English** | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Español](README.es.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Русский](README.ru.md) | [Português](README.pt-BR.md)
  10. </div>
  11. > This is a translation of the [Simplified Chinese README](README.zh-CN.md). If the two differ, the Chinese version is authoritative. Translation fixes are welcome via PR.
  12. ---
  13. ## About
  14. Vulcan Code is an **AI Coding application** with two clients: a GUI desktop app and a terminal TUI. It brings projects, sessions, terminals, a browser, code review and Git commits into a single workbench, so AI can understand your code, move tasks forward, and deliver results you can inspect.
  15. The project has been developed and debugged internally for a long time and is now open source under the **MIT License**. We want it to be more than one team's product — a tool the community shapes together:
  16. - 🐛 Found a problem or have an idea? Open an [Issue](https://github.com/OpenVulcan/vulcan-code/issues)
  17. - 🔧 Fixed a bug or built a feature? Send a [Pull Request](https://github.com/OpenVulcan/vulcan-code/pulls)
  18. - 🤝 Users and developers alike are welcome to join in and help build an AI Coding tool everyone loves
  19. ## Highlights
  20. ### 🧭 Desktop workbench
  21. - Multiple projects and sessions, with freely combined panels for files, review, memory and sub-agents
  22. - Built-in project terminal with tabs; AI can hold long-running or interactive command sessions
  23. - Streaming answers with Markdown, code blocks, Mermaid/SVG diagrams and tool-call cards rendered inline
  24. - Edit a past prompt to regenerate, or fork a new session from any completed turn
  25. - Chinese and English UI, light and dark themes
  26. ### 💻 Terminal client (TUI)
  27. - The same workbench in your terminal: projects and sessions, conversation and thinking, tool calls, questions, Git changes and commits, plus memory, knowledge base, skills, agents, plugin management and system settings
  28. - Shares the same service interface as the WebUI and connects to the same Core
  29. - Full mouse support: click, double-click, context menu and wheel; command palette, slash commands and shortcuts
  30. - Open it from the tray menu, or build and start it with `make bt`; see the [TUI guide](apps/vulcan-code-tui/README.md)
  31. ### 🎯 Getting tasks done
  32. - **Goal mode**: set a goal and a token budget; AI keeps working turn by turn, and you can pause, resume or clear it
  33. - **Plan mode**: explore and draft a plan first, execute after you confirm
  34. - **Steering while running**: add instructions or queue follow-up requests while a task is running
  35. - **Sub-agents**: built-in roles such as Explore and Plan, plus 260+ role templates from [agency-agents](https://github.com/msitarzewski/agency-agents) (off by default, enable as needed)
  36. - **Structured questions**: when AI needs a decision from you, it asks with option cards
  37. ### 🧠 Understanding code and retaining experience
  38. - **CodeKit code navigation**: structure lookup, text search, function body extraction and whole-function replacement directly on the live working tree; there is no prebuilt index, so nothing goes stale. Connect an external MCP service when you need semantic code search
  39. - **AI-managed knowledge base**: AI organizes, reads and searches long-term material with dedicated tools, with BM25, vector and hybrid search; history is kept permanently and can be restored; grant access per project and select per session
  40. - **MemoryMesh long-term memory**: distills experience after each turn and recalls it before the next; memories can be viewed, corrected and deleted, with a recycle bin and source tracing
  41. ### 🔍 Results you can inspect
  42. - **Diff review**: unified/split views, word-level diffs, full-text search, stage and revert
  43. - **Git commits**: AI-generated commit messages, commit to the current or a new branch, and push directly
  44. - **AI browser**: AI navigates, clicks, takes screenshots and reads the console in a real Chromium page; you can take over control at any time
  45. ### 🧩 Extensible
  46. - **Prompt skills** (`SKILL.md`): capture how your team works and reuse it next time
  47. - **LuaSkills**: package common actions into configurable, installable programmatic capability packs
  48. - **MCP**: local-process and HTTP MCP servers, with connection diagnostics and tool schema inspection
  49. - **MCP service**: Vulcan is an MCP server too. Other AI tools such as Claude Code and Codex can, as granted, list projects and sessions, send a message and wait for the reply, start sessions, stop runs and answer questions, and call separately granted image and video models; each tool gets its own token, and permission approvals always stay in Vulcan
  50. - **Plugin system**: plugins can provide tools and mount their own UI. Built-in plugins: Context7 docs lookup, AI browser, usage statistics, CDP/DAP debugging tools
  51. ### ⚙️ Models and providers
  52. - Supports the OpenAI, Anthropic, Gemini and Cohere protocol families, with built-in configurations for OpenAI, Anthropic, Google, DeepSeek, Kimi, MiniMax, Alibaba, OpenRouter and more; custom providers can be added
  53. - Chat, memory retrieval, knowledge-base vectors and media generation can each use a different model
  54. - Extended capabilities: web search and fetch, image/video/audio understanding, image and video generation, speech synthesis and transcription
  55. - Layered context-window policies, with automatic or manual (`/compact`) context compaction
  56. - **RTK command-output compression**: RTK is integrated natively in the host, compressing command output and Git commit context to cut token use; toggle it in settings and view savings statistics
  57. - Token usage, latency and reference cost statistics
  58. ## Roadmap
  59. The **GUI desktop app** and the **terminal TUI** are available today. Next up:
  60. - [ ] **Remote mobile connection**: view and control sessions running on your desktop from your phone
  61. - [ ] **Linux / macOS verification**: build scripts are in place, full verification on each platform is still needed
  62. If any of these interest you, or you have new ideas, let's discuss in the Issues.
  63. ## Architecture
  64. ```mermaid
  65. flowchart LR
  66. subgraph Desktop["Electron desktop shell (window / tray / host)"]
  67. WebUI["React WebUI"]
  68. end
  69. TUI["TUI terminal client (ratatui)"]
  70. Core["Rust Core (vulcan-code-service)<br/>session kernel · agent runtime · tools<br/>provider protocols · MCP · LuaSkills<br/>knowledge base · MemoryMesh · RTK<br/>terminal host · browser host · plugins"]
  71. WebUI <-->|"RPC / events"| Core
  72. TUI <-->|"same RPC / events"| Core
  73. ```
  74. The Core service can run on its own in the background (system tray); closing the desktop window or quitting the TUI does not interrupt running tasks. The desktop app, the WebUI in a browser and the TUI all connect to the same Core.
  75. | Directory | Description |
  76. | --- | --- |
  77. | `apps/vulcan-code-service` | Core service host: session kernel, agent runtime and WebUI RPC/streaming services |
  78. | `apps/vulcan-code-desktop` | Electron desktop shell: window and tray; starts the local Core and loads the WebUI |
  79. | `apps/vulcan-code-web` | React/Vite WebUI: workbench, settings, sessions, diff, skills and more |
  80. | `apps/vulcan-code-tui` | TUI terminal client (ratatui), calling the same service interface with the WebUI's functions and parameters |
  81. | `crates/vulcan-agent-runtime` | Shared agent runtime: providers, tools, LuaSkills, MCP, streaming execution |
  82. | `crates/vulcan-service-*` | Backend service API, core service kernel and runtime adapters |
  83. | `crates/vulcan-memorymesh-*` | MemoryMesh long-term memory |
  84. | `crates/vulcan-runtime-assets` | Authoritative resources: system prompts, provider manifests, sub-agent templates |
  85. | `plugins/` | Built-in plugins |
  86. | `docs/contracts/` | Development contract documents |
  87. ## Getting started
  88. > Full verification has been done on **Windows x86_64**. Linux and macOS have a matching `make.sh` script but have not been fully run end to end yet — help verifying is welcome.
  89. ### Requirements
  90. - `make`
  91. - [Rustup](https://rustup.rs/): the toolchain version is pinned by `rust-toolchain.toml` and installed automatically
  92. - PowerShell 7
  93. - Node.js and pnpm
  94. ### Build and run
  95. ```bash
  96. make init-system # First time: install Rust tools, host dependencies and managed Node/pnpm
  97. make sync # Sync config, system skills, plugins and browser runtime into output/
  98. make build # Build Core, WebUI and the Electron desktop shell
  99. make run # Launch the desktop app
  100. ```
  101. You can also use `make br` to build and run in one step; `make bt` does a full build, starts Core and opens the TUI, without the desktop app or Vite. Use `make release` for release builds.
  102. See [`docs/contracts/development-environment.md`](docs/contracts/development-environment.md) for detailed environment notes.
  103. ### Day-to-day development
  104. The Vite dev server, the Core service and the Electron shell are independent and can be started and restarted separately:
  105. ```bash
  106. make vite start # Start the WebUI Vite dev server (also supports status / stop)
  107. make service # Start only the background Core, without the desktop window
  108. make core-restart # Rust Core changes only: incremental build and hot-swap the Core (Windows Debug)
  109. make sync # Re-sync after changing resources, config, skills or plugins
  110. ```
  111. - For WebUI-only changes, keep Vite and the desktop shell running to get hot reload
  112. - In debug mode, `make run` / `make br` make sure Vite is running
  113. - Do not edit `output/` directly; authoritative resources live in `crates/vulcan-runtime-assets/resources/`
  114. ## Contributing
  115. All kinds of contributions are welcome: bug reports, docs, UX improvements, new platforms, new providers, plugins and skills…
  116. **Opening an Issue**
  117. - Bugs: include your OS, reproduction steps, expected vs. actual behavior, and relevant logs or screenshots
  118. - Feature requests: describe the use case and the problem you want to solve
  119. **Opening a PR**
  120. 1. Fork the repository and create a branch from `main`
  121. 2. Read [`AGENTS.md`](AGENTS.md) before making changes. It records the repository's long-term conventions; for specific areas, also read the matching documents in [`docs/contracts/`](docs/contracts/)
  122. 3. Verify locally before submitting:
  123. ```bash
  124. # Rust: prefer targeted checks on the crates you changed
  125. cargo check -p <crate> --all-targets
  126. cargo nextest run -p <crate>
  127. # WebUI
  128. pnpm --dir apps/vulcan-code-web run lint
  129. pnpm --dir apps/vulcan-code-web run test
  130. pnpm --dir apps/vulcan-code-web run build
  131. ```
  132. 4. In the PR description, explain what changed, why, and how you verified it
  133. A few conventions:
  134. - AI-facing tool names, descriptions and schemas are written in English; user-facing UI text is localized
  135. - Build and test concurrency is limited to 4 by default; please don't remove this limit in verification commands
  136. - Keep each PR focused on one thing to make review easier
  137. ## Acknowledgments
  138. Vulcan Code is built on many excellent open-source projects. Thanks to their authors and communities.
  139. **Bundled components and tools**
  140. - [RTK](https://github.com/rtk-ai/rtk): command-output compression to save tokens (integrated natively in the host)
  141. - [Context7](https://github.com/upstash/context7): up-to-date, version-aware library docs (Context7 plugin)
  142. - [Playwright](https://github.com/microsoft/playwright) / [Playwright MCP](https://github.com/microsoft/playwright-mcp): driver and tools for the AI browser
  143. - [LuaSkills](https://github.com/LuaSkills/luaskills): LuaSkills runtime
  144. - [ripgrep](https://github.com/BurntSushi/ripgrep) and [ast-grep](https://github.com/ast-grep/ast-grep): bundled text and syntax-tree search tools
  145. **Desktop and UI**
  146. - [Electron](https://www.electronjs.org/): desktop shell
  147. - [React](https://react.dev/) and [Vite](https://vite.dev/): WebUI framework and build tool
  148. - [shadcn/ui](https://ui.shadcn.com/), [Radix UI](https://www.radix-ui.com/), [Tailwind CSS](https://tailwindcss.com/): components and styling
  149. - [xterm.js](https://xtermjs.org/): terminal rendering
  150. - [Shiki](https://shiki.style/): code and diff syntax highlighting
  151. - [Mermaid](https://mermaid.js.org/): diagram rendering
  152. - [Lucide](https://lucide.dev/), [Iconify](https://iconify.design/): icons
  153. **Terminal client**
  154. - [Ratatui](https://ratatui.rs/): TUI rendering framework
  155. **Rust Core**
  156. - [Tokio](https://tokio.rs/) and [Axum](https://github.com/tokio-rs/axum): async runtime and service framework
  157. - [rmcp](https://github.com/modelcontextprotocol/rust-sdk): the official MCP Rust SDK
  158. - [LanceDB](https://github.com/lancedb/lancedb) and [Apache Arrow](https://arrow.apache.org/): vector index and columnar data
  159. - [SQLite](https://sqlite.org/) ([rusqlite](https://github.com/rusqlite/rusqlite)): local data storage
  160. - [jieba-rs](https://github.com/messense/jieba-rs): Chinese word segmentation for knowledge-base full-text search
  161. - [portable-pty](https://github.com/wezterm/wezterm) (WezTerm): cross-platform pseudo-terminal
  162. **Design and implementation references**
  163. - [OpenAI Codex](https://github.com/openai/codex): reference for Responses protocol transport, retries and context compaction; the Apply Patch grammar and streaming parser are adapted from Codex
  164. - [cc-switch](https://github.com/farion1231/cc-switch): reference for multi-protocol conversion, streaming tool calls and model pricing data
  165. - [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI): reference for the Gemini protocol and compatibility conversion
  166. - [OpenCode](https://github.com/anomalyco/opencode): reference for provider catalogs and system prompts
  167. - [agency-agents](https://github.com/msitarzewski/agency-agents): source of the sub-agent role templates
  168. - [Answer me with HTML](https://github.com/QingYunA/answer-me-with-html): design inspiration for answer components (findings, comparisons, flows and other structured blocks); our component syntax and native in-conversation rendering are implemented independently, without its CLI
  169. **Community**
  170. - [LINUX DO](https://linux.do/): thanks to the LINUX DO community for its support and discussions
  171. For the full list of third-party dependencies and licenses, see [`THIRD_PARTY_NOTICES.md`](crates/vulcan-runtime-assets/resources/licenses/THIRD_PARTY_NOTICES.md), or browse them in the app under **Settings → About and licenses**.
  172. ## License
  173. [MIT](LICENSE) © 2026 OpenVulcan

Ratings and comments

Sign in to rate this skill.

Sign in

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