Vibe Environments

A vibe is a named project context in VibeControls. It is the organizational unit that ties together your work — environment variables, notes, sessions, documentation, and metadata all live under a vibe.

Think of a vibe as a smart project folder: it knows which machine it lives on, which sessions belong to it, and what environment it operates in.

What a Vibe Contains

Each vibe can hold:

• A filesystem path pointing to the project directory on the agent's machine
• An agent assignment — which machine this vibe runs on
• Environment variables scoped to this project
• Tags for organization and search
• Notes — markdown documentation attached to this vibe
• Docs site — a compiled documentation site built from the vibe's content
• Sessions — all terminal sessions started within this vibe
• Metadata — custom key/value fields for your own use

Vibes can also be nested: a parent vibe can contain child vibes, letting you model monorepos, product suites, or any hierarchical relationship between projects.

Vibe Types

When creating a vibe, choose a type that best describes what it represents. The actual enum values stored on the Vibe.type field:

Type	Best For
PROJECT	A standalone project or application (default)
WORKSPACE	A workspace containing multiple related projects
REPOSITORY	A single git repository (Vibecontrols can auto-detect git metadata)
MONOREPO	A multi-package monorepo (typically the parent vibe with PACKAGE children)
PACKAGE	One package inside a monorepo
CUSTOM	Anything else — e.g., a deployment environment, an experiment, an ad-hoc folder

The type is primarily informational and used for filtering / icon selection — it helps you and your team understand what each vibe represents at a glance.

Creating a Vibe

1. Navigate to Vibes in the sidebar
2. Click New Vibe
3. Fill in the required fields:

• Name — a short, descriptive name
• Type — Project, Repo, or Environment
• Agent — which agent (machine) this vibe is on
• Path — the filesystem path on that machine (e.g. /home/user/projects/my-app)

4. Optionally add a description, tags, and environment variables
5. Click Create

The new vibe will appear in your Vibes list immediately.

Vibe Detail Page

Click any vibe in the list to open its detail page. From here you can:

• View and edit the vibe's metadata
• Start a new session in this vibe's context
• Browse attached notes
• Open the vibe's docs site
• Manage environment variables
• View the vibe's sessions history

Environment Variables

Environment variables scoped to a vibe are automatically available to sessions started within that vibe. This lets you store things like API endpoints, feature flags, or paths that are specific to this project.

Adding Environment Variables

1. Open the vibe detail page
2. Click the Environment tab
3. Click Add Variable
4. Enter a key and value
5. Click Save

Variables can be marked as secret — secret values are stored encrypted and never shown in plain text after creation (you can only overwrite them, not reveal them).

Variable Inheritance

When vibes are nested, child vibes inherit environment variables from their parent. If a child vibe defines a variable with the same key as a parent, the child's value takes precedence.

Vibe Metadata

The Metadata tab lets you attach arbitrary key/value pairs to a vibe. This is useful for:

• Linking to external systems (e.g. a Jira project key, a GitHub repo URL)
• Storing operational notes visible to automation
• Adding custom labels used by your team's conventions

Tags

Tags help you organize and find vibes across your workspace. You can add any number of tags to a vibe and then filter the Vibes list by tag.

To add tags:

1. Open the vibe detail page
2. Click Edit or find the tags field in the sidebar
3. Type a tag name and press Enter
4. Click Save

Archiving and Restoring Vibes

When a project is no longer active but you want to keep its history, you can archive the vibe instead of deleting it.

Archiving a Vibe

1. Open the vibe detail page
2. Click the ... menu (top right)
3. Select Archive
4. Confirm the action

Archived vibes are hidden from the default Vibes list but remain searchable. Their sessions, notes, and environment variables are preserved.

Restoring an Archived Vibe

1. In the Vibes list, enable Show archived using the filter menu
2. Find the archived vibe
3. Click ... → Restore

The vibe returns to active status immediately.

Deleting a Vibe

Permanent deletion removes the vibe and all its associated data (sessions, notes, environment variables). This action cannot be undone.

To delete a vibe:

1. Open the vibe detail page
2. Click ... → Delete
3. Type the vibe name to confirm
4. Click Delete permanently

Navigating Nested Vibes

The Vibes list shows a breadcrumb trail for nested vibes. You can expand a parent vibe to see its children, or switch to the Hierarchy view for a tree representation of all your vibes and their relationships.

Tips

• Use the Repo vibe type for code repositories — VibeControls can surface git branch, last commit, and status information automatically when the vibe is associated with an agent that has the repo plugin installed.
• Keep environment variables in vibes rather than hardcoding them in session scripts — this makes it easy to swap values without editing multiple places.
• Nest vibes to mirror your actual project structure, then use the parent vibe's sessions page to get a high-level view of all activity across its children.