# VTabs Engine for Obsidianπ
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://obsidian.md)
[](<>)
**VTabs Engine** is a high-performance, tree-structured vertical tab manager for Obsidian. Designed for power users, it replaces standard horizontal tab strips with a clean, responsive vertical sidebar hierarchy featuring group management, custom styling, instant search, and zero-overhead performance.
#### VTabs Engine Main Sidebar Interface
---
## β¨ Key Features
### π² Tree Hierarchy & Tab Grouping
Organize open tabs and custom groups in a collapsible vertical tree structure with item counter badges.
#### Grouped Vertical Tabs View
---
### π¨ Custom Accent Colors & Icons
Assign distinct colors and Lucide icons to individual tab groups for fast visual identification.
#### Color Picker Modal
---
### π οΈ Inline Management Modals
Rename groups and manage workspace organization effortlessly via built-in modals.
#### Rename Group Modal
---
## βοΈ Configuration & Settings
Fine-tune the sidebar interface directly from Obsidian's Plugin Settings tab. Customize ribbon icon style, toggle tab icons, adjust nesting indent size, or enable compact view.
#### VTabs Engine Settings Page
---
### β‘ Additional Core Capabilities
- **Flat-Map Zustand Store**: Reactive state management decoupled from heavy render loops for smooth handling of dozens of tabs.
- **Instant Search**: Real-time filtering across active tabs, groups, and paths using optimized tree algorithms.
- **Native Obsidian Sync**: Seamless handling of workspace active leaf changes, leaf closures, pinned tabs, and vault file rename events.
---
## π Project Structure
```
tab-engine-obsidian/
βββ docs/
β βββ ARCHITECTURE.md
βββ src/
β βββ adapter/
β β βββ obsidian-events.ts # Workspace event listeners β store.syncLeaves()
β βββ engine/
β β βββ icon-engine.ts # Lucide icon auto-detection & overrides
β βββ features/
β β βββ group-workspace-split/ # Self-contained "Focus View" feature module
β β βββ group-split.types.ts
β β βββ group-split.service.ts
β β βββ GroupSplitButton.tsx
β β βββ index.ts
β βββ modals/
β β βββ rename-modal.ts
β β βββ icon-picker-modal.ts
β β βββ color-picker-modal.ts
β β βββ group-picker-modal.ts
β βββ settings/
β β βββ setting-tab.ts
β βββ store/
β β βββ tab-store.ts # Central Zustand store
β βββ types/
β β βββ plugin-settings.ts
β β βββ tree.ts # Discriminated union node types
β βββ ui/
β β βββ components/
β β β βββ ObsidianIcon.tsx
β β β βββ TabGroupNode.tsx
β β β βββ TabItemNode.tsx
β β β βββ VirtualTabList.tsx
β β βββ context/
β β β βββ plugin-context.tsx
β β βββ types/
β β βββ view-container.ts # ItemView β React root bridge
β βββ utils/
β β βββ persistence.ts # Serialize/deserialize/validate the tree
β β βββ tree-utils.ts # Sibling lookup + search filter
β βββ main.ts
βββ esbuild.config.mjs
βββ manifest.json
βββ package.json
βββ styles.css
βββ tsconfig.json
```
---
## π οΈ Building & Development
### Prerequisites
- [Node.js](https://nodejs.org/) (v18 or higher recommended)
- `npm` package manager
### Build Steps
1. **Clone the repository:**
```bash
git clone https://github.com/DevAbdallahAbdelrahim/obsidian-vtabs-engine.git
cd obsidian-vtabs-engine
```
2. **Install dependencies:**
```bash
npm install
```
3. **Build production bundle:**
```bash
npm run build
```
This performs strict TypeScript type checking (`tsc --noEmit`) and bundles `main.js` via `esbuild`.
4. **Watch mode for development:**
```bash
npm run dev
```
---
## π¦ Manual Installation
1. Create a directory named `obsidian-vtabs-engine` in your vault's plugin directory:
`/.obsidian/plugins/obsidian-vtabs-engine/`
2. Download `main.js`, `manifest.json`, and `styles.css` from the latest release.
3. Place these files directly into `/.obsidian/plugins/obsidian-vtabs-engine/`.
4. Reload Obsidian and enable **VTabs Engine** in **Settings > Community Plugins**.
---
## π License: AGPLv3 & Cloud/SaaS Freedom
VTab Engine is licensed under the **GNU Affero General Public License v3.0 (AGPLv3)**.
AGPLv3 is GPLv3 plus one addition: GPLv3's copyleft obligation is triggered by _distributing_ a copy of the software. That leaves a well-known gap β a company can take GPL code, modify it, run it only on their own servers, and offer it as a hosted service, and because they never hand anyone a literal copy of the binary, they're never obligated to share their modifications. AGPLv3 closes that gap: if you run a modified version of this code and let others interact with it over a network, you must also make that modified source available to those users (AGPLv3 Β§13).
For an Obsidian plugin specifically, which runs locally on each user's own machine, that clause mostly sits dormant in ordinary use β installing and using TabEngine doesn't involve "interacting with someone else's server" in the sense the clause targets. Where it matters is the scenario it's there to prevent: if this code (or a fork of it) ever gets embedded into a hosted product β a cloud note-taking service, a managed Obsidian-as-a-service offering, anything users reach over a network β AGPLv3 guarantees those users get the same right to the source that a locally-installed copy already gives you. It's forward-looking protection against exactly one thing: someone else's SaaS wrapper closing off what was open.
Practically, for contributors and users of the plugin itself, this changes very little day to day β you can install it, modify your own copy, and use it exactly as freely as any permissively-licensed plugin. The obligation only activates for someone who takes the code into a network-served product.