Working with Vibes

A vibe is a named project context — it knows the path on disk, which agent runs it, what type of project it is, and what environment variables apply. See the concept overview.

Vibes are database records, not files. There's no vibe.yaml to write — you create vibes via the CLI or the web app, and the agent picks them up.

What you'll learn

• Create a vibe
• List + switch vibes
• Configure env vars + git metadata
• Vibe hierarchy (parent/child)

Create

vibecontrols vibes create \
  --name my-api \
  --path /home/me/code/my-api \
  --type REPOSITORY \
  --description "REST API service"

Vibe types (VibeType enum):

Type	Use for
PROJECT	A general project (default)
WORKSPACE	A multi-project workspace
REPOSITORY	A single git repo
MONOREPO	A multi-package repo
PACKAGE	One package inside a monorepo
CUSTOM	Anything else

Vibe statuses (VibeStatus enum): ACTIVE, INACTIVE, ARCHIVED, ERROR. New vibes start as INACTIVE; they go ACTIVE when an agent attaches.

List

vibecontrols vibes list                    # all vibes in your current workspace
vibecontrols vibes list --status ACTIVE    # filter
vibecontrols vibes list --agent <agentId>  # vibes attached to one agent

Update

vibecontrols vibes update <vibe-id> \
  --git-branch main \
  --env-var NODE_ENV=development \
  --env-var DATABASE_URL=postgres://...

Environment variables are stored as JSON on the Vibe model and passed to sessions started inside the vibe.

Git metadata

The vibe tracks gitBranch, gitRemote, and arbitrary gitStatus JSON. The agent's git plugin (/api/git/* endpoints) keeps these in sync.

Hierarchy

A vibe can have a parentId, forming a tree. Useful for monorepos:

# parent
vibecontrols vibes create --name monorepo-root --path /home/me/code/monorepo --type MONOREPO
# child packages
vibecontrols vibes create --name api    --path /home/me/code/monorepo/packages/api    --type PACKAGE --parent <root-id>
vibecontrols vibes create --name web    --path /home/me/code/monorepo/packages/web    --type PACKAGE --parent <root-id>
vibecontrols vibes create --name shared --path /home/me/code/monorepo/packages/shared --type PACKAGE --parent <root-id>

Children appear nested under their parent in the web app and on vibecontrols vibes list --tree.

Archive / delete

vibecontrols vibes archive <vibe-id>
vibecontrols vibes delete  <vibe-id>   # soft-delete; sets deletedAt

Next steps

• Sessions & Terminals — open terminals inside a vibe
• VibeDecks — build action buttons for a vibe
• Notes — attach markdown notes to a vibe