Project Context

Project Context allows Vocoding to understand your development environment. When context is configured, your prompts include relevant information about:

• Your tech stack (React, Node, Python, Rust, etc.)
• Project constraints and requirements
• Code conventions (from CLAUDE.md, .cursorrules, etc.)
• Architecture decisions
• Git branch and workspace information

This results in more accurate, project-specific prompts.

---

Why Use Project Context?

Without Context

You say: "Create a login form"

Output: Generic form code, unknown framework, no conventions applied

With Context

You say: "Create a login form"

Output: React 19 + TypeScript + Tailwind form with:

• Your project's validation patterns
• Your component naming conventions
• Your state management approach
• Your preferred libraries

---

The Project Context View

Access via sidebar or Cmd + 3 / Ctrl + 3.

Workspace Selector

In the header bar of any view, the workspace selector dropdown lets you quickly switch between project contexts. Each workspace has its own project profile, tech stack, and context sources.

---

Setting Up Project Context

Step 1: Create a Project Profile

1. Go to Project Context view (Cmd + 3)
2. Click New Profile
3. Fill in:

Field	Description	Example
Name	Project identifier	"My App Frontend"
Stack	Technologies used	Auto-detected or manual
Constraints	Requirements/limits	"No external dependencies"

4. Click Save

Step 2: Set Project Root

1. In your profile, click Select Folder
2. Navigate to your project root
3. Select the folder containing .git or package.json

Why? This allows Vocoding to:

• Auto-detect your tech stack
• Find AI config files (CLAUDE.md, .cursorrules)
• Show git branch information
• Understand project structure

Step 3: Review Auto-Detected Stack

When you set a project root, Vocoding automatically scans for marker files:

File	Detected Stack
package.json	Node.js / JavaScript
Cargo.toml	Rust
requirements.txt	Python
pyproject.toml	Python
go.mod	Go
pom.xml	Java
tauri.conf.json	Desktop app

Framework detection (from package.json):

Indicator	Framework
react in dependencies	React
vue in dependencies	Vue
next in dependencies	Next.js
angular in dependencies	Angular
svelte in dependencies	Svelte

The detected stack appears as tech stack chips with icons for framework, language, and package manager.

Step 4: Enable Context Sources

Vocoding auto-discovers AI config files in your project:

File	Description
CLAUDE.md / .claude.md	Claude Code instructions
.cursorrules	Cursor IDE rules
.codex.md	Codex instructions
.gemini.md	Gemini instructions
conventions.md	Project conventions
.copilot-instructions	GitHub Copilot rules

Managing context sources:

1. In your profile, find the AI Configuration section
2. Global toggle -- Enable or disable all context sources at once
3. Individual toggles -- Enable or disable specific files
4. Each file shows its size and estimated token count

---

Context Budget

Understanding Token Limits

LLMs have context limits. Vocoding manages this automatically:

[System prompt] + [Agent prompt] + [Project context] + [Your input] = Total tokens

The total must fit within the model's context window. Vocoding prioritizes the most relevant context.

Context Truncation

If context exceeds the budget:

1. Older conversation messages are truncated first
2. A context truncation indicator appears in the chat
3. Most recent context and your latest input are always preserved

Tips to Stay in Budget

1. Prioritize sources -- Enable only the most relevant config files
2. Keep files concise -- Avoid verbose context files; focus on what matters
3. Disable unused sources -- Don't include every config file
4. Use larger models -- Models with bigger context windows handle more context

---

Runtime Context

The right panel > Context tab in Chat view shows real-time information:

• Workspace info: Project name, root path, git branch
• AI Config files: Which are active, with toggles
• Tech stack chips: Detected framework, language, package manager
• Runtime context: Currently active application, attached files count

---

Multiple Workspaces

When to Use Multiple Workspaces

• Different projects -- Each repository has its own profile
• Different roles -- Backend vs frontend development
• Different teams -- Team-specific conventions and constraints

Creating Multiple Profiles

1. Project Context view > Click New Profile
2. Create profiles for each context
3. Switch between them using the workspace selector in the header bar

Example Setup

My Work
+-- Profile: "App Frontend"
|   +-- Stack: React + TypeScript + Tailwind
+-- Profile: "App Backend"
|   +-- Stack: Node.js + Express + PostgreSQL
+-- Profile: "Mobile App"
    +-- Stack: React Native + TypeScript

Workspace-Scoped Context

Each workspace maintains its own:

• Project root path
• Tech stack detection
• AI config file toggles
• Constraints and conventions

Switching workspaces instantly changes the context that Vocoding uses for optimization.

---

Best Practices

1. Keep Context Files Updated

Outdated context leads to outdated prompts.

• Review context files when your stack changes
• Update conventions when team practices evolve
• Remove deprecated sections

2. Be Specific, Not Verbose

Good:

## Stack
React 19, TypeScript 5.8, Tailwind 3.4, Zustand 5

## Rules
- Functional components only
- No any types
- Use shallow selectors for state management

Bad:

## Introduction
This is a project we started in 2023 and have been
working on ever since. It's really important...
[500 more words of backstory]

3. Use Constraints Wisely

Constraints should be:

• Actionable: "No external dependencies"
• Verifiable: "Must compile with strict mode"
• Relevant: "Must work offline"

Not:

• Vague: "Should be good"
• Unrealistic: "No bugs ever"

4. Test Your Context

1. Create a profile and set the project root
2. Run a few prompts
3. Check if the output references your stack and conventions
4. Adjust context sources as needed

---

Troubleshooting

Context not being included

1. Check that a profile is active (selected in workspace selector)
2. Verify context sources are enabled (check the toggles)
3. Verify your project root path is correct
4. Check that AI config files exist at the project root

Wrong stack detected

1. Verify the project root points to the correct folder
2. Check that marker files exist (package.json, Cargo.toml, etc.)
3. Manually set the stack in your profile if auto-detection is incorrect

Context files not found

1. Verify the project root path
2. Check file names match exactly (case-sensitive)
3. Files must be at the project root or in supported subdirectories

Context too large (truncation)

1. Edit context files to be more concise
2. Disable low-priority sources
3. Use a model with a larger context window
4. Remove verbose sections from config files