Controlling the Working Directory

Lesson updated November 2, 2026: Examples no longer set active_model = "devstral-2" (Devstral has been removed from the API). Without this key, the project uses the model defined in your user configuration. Reminder: a project .vibe/config.toml loads only within a trusted folder. Source: Configuration.

November 2, 2026 Update — Devstral. Devstral 2 (devstral-2512) reached its end-of-life on July 31, 2026, and Devstral Small 2 on March 31, 2026: calls to these models are no longer guaranteed. The official model table redirects them to Mistral Medium 3.5, which is itself deprecated in favor of Mistral Large 4. Codestral (codestral-2508) remains generally available for code completion. Check the model table to see where -latest aliases point before reusing these examples.

The Launch Directory Defines the Project

When you run vibe, the agent adopts the current directory as its working directory. This choice matters: it determines the entire project context, since Vibe scans the directory tree, reads configuration files, and infers the project type from this location.

cd /home/user/projects/my-api
vibe
# → Vibe analyzes the my-api project

Launching Vibe from your home directory instead of the repository gives you an agent that doesn’t understand your code—not because it can’t, but because it’s looking in the wrong place. In practice, the cd is part of the command.

Working Elsewhere Without Moving

Sometimes cd isn’t possible or convenient. The --workdir option explicitly designates the target directory:

vibe --workdir /home/user/projects/my-api

The behavior is strictly identical to launching from that folder: project scanning, file path resolution, and shell commands all use this directory as their base. This option comes in handy for automation scripts where you don’t control the current directory, when juggling multiple projects without switching terminals, and in CI/CD pipelines to point to a freshly cloned repository. The script use case is the most illustrative, allowing you to process a series of projects in a loop:

# In a script
for project in api frontend worker; do
  vibe --workdir "/projects/$project" \
       --prompt "Check for npm vulnerabilities" \
       --output json > "audit-$project.json"
done

Organizing Multi-Project Work

In interactive mode, the cleanest approach is one terminal—or tmux pane, or screen session—per project:

# Terminal 1: Backend API
cd /projects/api-backend
vibe

# Terminal 2: Frontend
cd /projects/frontend-react
vibe

# Terminal 3: Infrastructure
cd /projects/infra-terraform
vibe

Each instance then has its own context, session, and history, preventing you from mixing Terraform reasoning with React logic.

This separation extends down to configuration. Placing a .vibe/config.toml file in each project tailors the agent’s behavior to the specific codebase. For a Python API:

# Python API Project
# /projects/api-backend/.vibe/config.toml
cat > .vibe/config.toml << 'EOF'
system_prompt_id = "python_expert"

[tools.bash]
permission = "ask"
EOF

And for a React frontend, adding an MCP server:

# React Frontend Project
# /projects/frontend-react/.vibe/config.toml
cat > .vibe/config.toml << 'EOF'
system_prompt_id = "react_expert"

[[mcp_servers]]
name = "fetch"
transport = "stdio"
command = "uvx"
args = ["mcp-server-fetch"]
EOF

The precedence rule is simple to remember: project configuration (./.vibe/config.toml) overrides global configuration (~/.vibe/config.toml). Each repository can thus enforce its own model, system prompt, and MCP servers without requiring you to change anything when switching between them.

Trusted Folders

The working directory also determines what Vibe is allowed to do without asking you. The trusted folders system relies on ~/.vibe/trusted_folders.toml, which lists locations where certain automatic actions—auto-approve in particular—are permitted.

# ~/.vibe/trusted_folders.toml
trusted = [
  "/home/user/projects/my-api",
  "/home/user/projects/frontend",
]

If you enable auto-approve in a directory missing from this list, Vibe warns you that it isn’t considered trusted. This is exactly the safeguard you want when cloning an unknown repository to help a colleague.

Referencing Files and Changing Directories Mid-Session

In your conversations, @ accepts both paths relative to the working directory and absolute paths, with autocomplete working in both cases.

# Relative path (recommended)
Explain the code in @src/api/routes.ts

# Absolute path
Explain the code in @/home/user/projects/my-api/src/api/routes.ts

Prefer relative paths: they read better and remain valid regardless of the user or machine, which matters when sharing a prompt with a colleague.

Finally, nothing stops you from navigating elsewhere during a session using a shell command:

!cd /other/project && ls

However, know what you get: the project context from the initial scan remains tied to the launch directory, and Vibe doesn’t automatically rescan the new folder. The agent will see the listed files but will still reason based on the original project architecture. For a true context switch, open a new session.

Key Takeaways

• Vibe uses the current directory as the project context at launch
• --workdir lets you specify a directory without navigating to it
• One terminal per project is the cleanest approach for multi-project work
• Per-project .vibe/config.toml customizes behavior for each codebase
• The Trust Folder system secures auto-approve on a per-directory basis
• Relative paths with @ are recommended for readability