### Initialize and Run Voicetree Development Environment

Source: https://github.com/voicetreelab/voicetree/blob/main/readme.md

Commands to install dependencies and start the application or run backend tests. Requires Node.js 18+, Python 3.13, and uv.

```bash
cd webapp && npm install && npm run electron  # App
uv sync && uv run pytest                               # Backend
```

--------------------------------

### Run Quality Benchmarker

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/benchmarker/src/README.md

Execute the benchmarker from the project root or as a module. No specific setup is required beyond having Python installed.

```bash
python backend/benchmarker/quality_LLM_benchmarker.py
```

```bash
python -m backend.benchmarker.src.quality_LLM_benchmarker
```

--------------------------------

### Custom Execution Environment Extension

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/tests/system/test_lab/ARCHITECTURE.md

Example of extending the EndToEndTestLab class to implement custom environment setup.

```python
# Extend EndToEndTestLab
class CustomTestLab(EndToEndTestLab):
    def setup_custom_environment(self):
        # Custom environment setup
        pass
```

--------------------------------

### Install Voicetree on Linux

Source: https://github.com/voicetreelab/voicetree/blob/main/readme.md

Execute the installation script via curl to set up Voicetree on Linux environments.

```bash
curl -fsSL https://raw.githubusercontent.com/voicetreelab/voicetree/main/install.sh | sh
```

--------------------------------

### Install AudioTee Dependency

Source: https://github.com/voicetreelab/voicetree/blob/main/webapp/meta/todo/SYSTEM_AUDIO_CAPTURE_OPTIONS.md

Installs the AudioTee package for native Core Audio Taps access.

```bash
npm install audiotee
```

--------------------------------

### Install BlackHole via Homebrew

Source: https://github.com/voicetreelab/voicetree/blob/main/webapp/meta/todo/SYSTEM_AUDIO_CAPTURE_OPTIONS.md

Command to install the BlackHole virtual audio driver on macOS.

```bash
brew install blackhole-2ch
```

--------------------------------

### Install Requirements for GPT-SoVITS

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/context_retrieval/full_context.txt

Run this command in the GPT-Sovits folder to install necessary Python packages. Ensure you are in the correct directory.

```bash
runtime\python -m pip install -r requirements.txt
```

--------------------------------

### Wikilink Syntax Example

Source: https://github.com/voicetreelab/voicetree/blob/main/webapp/public/onboarding/voicetree/hover_over_me.md

Shows the syntax for linking to other nodes in the graph.

```markdown
[[to_the_other_nodes_relative_or_absolute_path.md]]
```

--------------------------------

### Install Voicetree on macOS

Source: https://github.com/voicetreelab/voicetree/blob/main/readme.md

Use Homebrew to install the Voicetree application on macOS systems.

```bash
brew tap voicetreelab/voicetree && brew install voicetree
```

--------------------------------

### Project Development Commands

Source: https://context7.com/voicetreelab/voicetree/llms.txt

CLI commands for installing dependencies, running development environments, executing tests, and building the application.

```bash
# Install dependencies
cd webapp && npm install  # Frontend
uv sync                    # Backend Python dependencies

# Run development
npm run electron           # Full Electron app
uv run python server.py    # Backend server only (port 8001)
npm run mcp               # MCP server standalone (port 3001)

# Run tests
uv run pytest             # Backend tests
npm run test              # Frontend tests
npm run test:e2e          # End-to-end tests

# Build for production
npm run electron:dist     # Build distributable
```

--------------------------------

### TypeScript Code Block Example

Source: https://github.com/voicetreelab/voicetree/blob/main/webapp/public/onboarding/voicetree/hover_over_me.md

Demonstrates syntax highlighting for TypeScript within a node.

```typescript
while (true) {
+  const x : string = "Hello World!"
-  // agents will automatically produce handover nodes with their diff  
  ...
}
```

--------------------------------

### Mermaid Diagram Example

Source: https://github.com/voicetreelab/voicetree/blob/main/webapp/public/onboarding/voicetree/hover_over_me.md

Displays a flowchart using Mermaid syntax.

```mermaid
flowchart LR
      A((Voice)) --> B((Tree))
```

--------------------------------

### Diff Example in Markdown

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/prompts/addProgressTreeManualFallback.md

Demonstrates the format for including code diffs within a Markdown node. Use this for changes under 40 lines, especially for production files.

```markdown
\```<language>
- old
+ new
\```
```

--------------------------------

### Example Graph Structures

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/prompts/addProgressTree.md

Visual representations of how to organize tasks by concern or phase using a tree-like structure.

```text
Split by concern (e.g. reviewing a diff with two unrelated change sets):
Task: Review git diff
├── Review: Collision-aware positioning refactor
└── Review: Prompt template cleanup

Split by phase + option (e.g. planning an implementation):
Task
├── High-level architecture
│   ├── Option A: Event-driven
│   └── Option B: Request-response
├── Data types
└── Pure functions
```

--------------------------------

### Define Component Input Data

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/prompts/SUBAGENT_PROMPT.md

Example format for the input data expected by the component.

```text
[Concrete example of input data]
```

--------------------------------

### Chatbot Interaction Example

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/benchmarker/input/nolima_16k_vegan.txt

Demonstrates a typical chat interaction with a bot, showing user messages and bot responses.

```text
<Shad> Got a lawyer. <ferret> Great ! <callmecheese> Huzzah! <DoDec> Which one did you get? ...
```

--------------------------------

### Custom Test Scenario Definition

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/tests/system/test_lab/ARCHITECTURE.md

Example of adding a new test case to the test_scenarios.json configuration file.

```json
// In test_scenarios.json
{
  "name": "Custom Test",
  "description": "Tests custom behavior",
  "agent_prompt": "Custom prompt",
  "validation_criteria": {
    "custom_rule": true
  }
}
```

--------------------------------

### Get Most Relevant Nodes

Source: https://context7.com/voicetreelab/voicetree/llms.txt

Retrieves nodes that are semantically relevant and recently modified. Can optionally use a query to guide relevance or default to branching factor.

```python
# Get most relevant nodes for context (combines recency + semantic relevance)
from backend.markdown_tree_manager.markdown_tree_ds import Node
relevant_nodes: list[Node] = get_most_relevant_nodes(
    decision_tree=tree,
    limit=12,
    query="API design patterns"  # Optional - if None, uses branching factor
)
```

--------------------------------

### Initialize and use TextBufferManager

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/text_to_graph_pipeline/text_buffer_manager/README.md

Demonstrates how to instantiate the manager, add text, and handle the resulting buffer state.

```python
from text_buffer_manager import TextBufferManager

# Create buffer manager
buffer = TextBufferManager()

# Add text - returns BufferResult with is_ready flag
result = buffer.add_text("Some transcribed text...")
if result.is_ready:
    # Process result.text through workflow
    # Then flush completed text
    buffer.flush_completed_text(completed_text)
```

--------------------------------

### Haystack Context Example

Source: https://github.com/voicetreelab/voicetree/blob/main/gsm_system/NoLiMa_example_question.md

An abbreviated example of the haystack context containing the embedded needle.

```text
...walked through the old town square, remembering the stories her grandmother used to tell. The bells of the church tower rang out across the valley. Marcus had always loved this time of year, when the leaves turned golden and the air grew crisp. He thought about his upcoming trip to Barcelona, where he would finally see the Sagrada Familia.

Actually, Stuart lives next to the Kiasma museum.

The conference was scheduled for next Tuesday, and preparations were already underway. Sarah checked her notes one more time, making sure she had covered all the important points. The presentation needed to be perfect - this was her chance to impress the board...
```

--------------------------------

### Run Integration and System Tests

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/claude.md

Execute the integration and system test suite using uv.

```bash
uv run pytest backend/tests/integration_tests/
```

--------------------------------

### Run Unit Tests

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/claude.md

Execute the unit test suite using uv.

```bash
uv run pytest backend/tests/unit_tests
```

--------------------------------

### run_tests.py Command Line Options

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/tests/system/test_lab/README.md

Overview of available command-line options for the run_tests.py script, including scenario selection, listing, configuration, and verbosity.

```bash
python3 run_tests.py [OPTIONS]

Options:
  --scenario TEXT     Run specific test scenario by name
  --list             List available test scenarios  
  --config TEXT      Test scenarios configuration file (default: test_scenarios.json)
  --verbose, -v      Verbose output
  --help             Show help message
```

--------------------------------

### Custom Type Safety Checker Violation Examples

Source: https://github.com/voicetreelab/voicetree/blob/main/meta/report.md

Examples of dictionary usage violations identified by the custom type checker.

```text
backend/markdown_tree_manager/markdown_tree_ds.py:22 - Dict type annotation found at line 22 - use dataclass or TypedDict instead
backend/markdown_tree_manager/markdown_tree_ds.py:22 - Raw dictionary literal found at line 22
backend/context_retrieval/test_chromadb.py:34 - Raw dictionary literal found at line 34
```

--------------------------------

### Run Tests with Custom Configuration

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/tests/system/test_lab/README.md

Use a custom JSON file for test scenario definitions instead of the default 'test_scenarios.json'. Specify the file path with the --config option.

```bash
python3 run_tests.py --config my_scenarios.json
```

--------------------------------

### List Available Test Scenarios

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/tests/system/test_lab/README.md

Display a list of all available test scenarios that can be executed. Use the --list flag.

```bash
python3 run_tests.py --list
```

--------------------------------

### GET /stream-progress

Source: https://context7.com/voicetreelab/voicetree/llms.txt

SSE endpoint for real-time workflow progress updates.

```APIDOC
## GET /stream-progress

### Description
Server-Sent Events endpoint for real-time workflow progress updates during text-to-graph processing.

### Method
GET

### Endpoint
/stream-progress
```

--------------------------------

### Emit Workflow Events

Source: https://context7.com/voicetreelab/voicetree/llms.txt

Examples of emitting specific workflow events using the SSEEventEmitter.

```python
queue = asyncio.Queue()
emitter = SSEEventEmitter(queue)

await emitter.emit(SSEEventType.PHASE_STARTED, {
    "phase": "tree_action_decision",
    "message": "Determining graph modifications"
})

await emitter.emit(SSEEventType.ACTION_APPLIED, {
    "action": "create_node",
    "node_id": 15,
    "title": "New Concept Node",
    "parent_id": 5
})

await emitter.emit(SSEEventType.WORKFLOW_COMPLETE, {
    "nodes_created": 3,
    "nodes_updated": 1,
    "processing_time_ms": 2500
})
```

--------------------------------

### Run Quality Benchmarker

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/claude.md

Execute the LLM quality benchmarking script.

```bash
uv run python backend/benchmarker/src/quality_LLM_benchmarker.py
```

--------------------------------

### Define Component Output Data

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/prompts/SUBAGENT_PROMPT.md

Example format for the output data produced by the component.

```text
[Concrete example of output data]
```

--------------------------------

### Twitter Hashtag Monitoring

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/benchmarker/input/nolima_16k_vegan.txt

Example of monitoring a Twitter hashtag for public sentiment and speeches.

```text
I stayed out of their range as I checked out the Twitter hashtag #Freethe9 as people made speeches, including some law professor who seemed to specialize in Twitter-sized sound bites.
```

--------------------------------

### Run Tests with Verbose Output

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/tests/system/test_lab/README.md

Execute tests and enable verbose logging for detailed output. Use the --verbose or -v flag.

```bash
python3 run_tests.py --verbose
```

--------------------------------

### Integration Test for Module Loading

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/tests/fixtures/real_example_folder/35_1_Bob_Testing_Strategy_for_Decentralized_Module_Loading.md

Uses a temporary directory fixture to set up test data and verify that system modules load correctly.

```python

def test_integration_module_loading():
    ** Setup test vault**
    with tempdir() as vault:
        setup_test_data(vault)
        
        ** Initialize system**
        tree = MarkdownTree(vault)
        history = HistoryManager()
        history.load_from_file(vault)
        
        ** Verify**
        assert len(tree.tree) == expected
        assert history.get() == expected
```

--------------------------------

### Agent Output Validator Extension

Source: https://github.com/voicetreelab/voicetree/blob/main/tools/tests/system/test_lab/ARCHITECTURE.md

Example of adding custom validation logic to the AgentOutputValidator class.

```python
# In output_validator.py
class AgentOutputValidator:
    def validate_custom_behavior(self, content, criteria):
        # Custom validation logic
        return validation_result
```

--------------------------------

### Initialize and Use FuzzyTextMatcher

Source: https://github.com/voicetreelab/voicetree/blob/main/backend/text_to_graph_pipeline/text_buffer_manager/buffer_management_handover.md

Demonstrates configuring the matcher with a custom threshold and performing text removal on source strings.

```python
from text_buffer_manager import FuzzyTextMatcher

# Create matcher with custom threshold
matcher = FuzzyTextMatcher(similarity_threshold=0.85)

# Find best match
source = "The cat sat on the mat. Next sentence."
target = "The cat sits on the mat."  # LLM changed verb tense

match = matcher.find_best_match(target, source)
if match:
    start, end, score = match
    print(f"Found match at {start}-{end} with {score:.0%} similarity")
    
# Remove matched text
result, success = matcher.remove_matched_text(source, target)
print(f"After removal: '{result}'")  # "Next sentence."
```

--------------------------------

### POST /load-directory

Source: https://context7.com/voicetreelab/voicetree/llms.txt

Loads or switches to a different markdown tree directory, initializing the graph structure and processors.

```APIDOC
## POST /load-directory

### Description
Loads or switches to a different markdown tree directory, initializing the graph structure, converter, and chunk processor for the specified vault path.

### Method
POST

### Endpoint
/load-directory

### Request Body
- **directory_path** (string) - Required - The file system path to the markdown vault.

### Response
#### Success Response (200)
- **status** (string) - Status of the operation.
- **message** (string) - Descriptive message.
- **directory** (string) - The loaded directory path.
- **nodes_loaded** (integer) - Number of nodes initialized.
```