VoiceTree Documentation

Voicetree is a graph-based mindmap designed for building Human-in-the-Loop (HITL) coding-agent systems. It uses a markdown hypergraph where nodes represent markdown files, folders, or terminal-based agents (e.g., Claude Code, Gemini, etc.), and edges represent connections between them.

Key features include:

• Shared Memory: Humans and agents share the same memory graph, allowing agents to see the same context as the user.
• Recursive Task Decomposition: Agents can break down tasks into subgraphs and spawn child terminals/agents.
• Spatial Organization: Tasks and progress are organized spatially on a graph to reduce cognitive load.
• Context Management: Uses a configurable radius and semantic search to provide agents with relevant context, preventing "context rot" (performance degradation caused by excessive input tokens).

The benchmarking module is composed of three primary files:

• config.py: Centralizes configuration constants, including API rate limits, directory paths, file names, and the DEFAULT_TEST_TRANSCRIPTS.
• evaluator.py: Contains the QualityEvaluator class, which handles LLM-based evaluation, loading workflow prompts, packaging output for evaluation, and managing result logging.
• quality_LLM_benchmarker.py: The main orchestration script providing a clean, async interface for running the benchmarks.

@vt/measures is the central package for codebase measurement, health-gate tests, CI dashboard CheckDefs, metric report writers, and measurement runner CLIs.

It organizes code into several functional areas:

• Health metrics: Vitest tests located in src/health/.
• CI dashboard CheckDefs: Located in src/checks/tier_N/.
• Shared primitives: Discovery, graph, complexity, purity, and writer primitives located in src/_shared/.
• Runner CLIs: Located in src/_runners/.

The backend/benchmarker/ package provides tools for evaluating the system's output and performance. It includes:

• 4-stage Quality Scoring Framework: A structured way to score the quality of generated trees.
• Automated Benchmarking: Systems to run repeatable tests.
• Performance Regression Detection: Tools to identify if updates degrade system performance.
• Analysis Tools: Debugging and analysis utilities for benchmark results.

The text_to_graph_pipeline is responsible for the core transformation logic. It is divided into two primary functional areas:

Tree Management

Located in backend/text_to_graph_pipeline/tree_manager/, this component handles:

• DecisionTree: The core data structures representing the graph.
• Buffer Management: Unified management for streaming input.
• Tree-to-Markdown: Conversion of the internal tree state into markdown format.

Agentic Workflows

Located in backend/text_to_graph_pipeline/agentic_workflows/, this component handles:

• 4-stage LLM Pipeline: A processing pipeline based on LangGraph.
• State Management: Maintaining state across different pipeline stages.
• LLM Integration: Integration with the Gemini API.
• Debugging: Tools for workflow visualization and debugging.

When a folder is expanded and the anchor context node becomes visible in the projection, the system restores the terminal's prior visibility state:

• Previously Visible: If the floating window was visible before the collapse, its display style is restored, and its position re-resolves relative to the now-visible cytoscape node.
• Previously Minimized: If the terminal was minimized before the collapse, the minimized badge is restored on the cytoscape node, but the floating window itself remains hidden.

In version 1, Voicetree uses a 'Daemon-First' architecture where vt-graphd acts as the canonical owner of live project state. This shifts the ownership of the mounted watcher, read/write path configuration, parsed graph, and server-side session view state away from the Electron main process and into the daemon.

Key Architectural Shifts

• Source of Truth: vt-graphd owns the live project state. Libraries like @vt/graph-model and @vt/graph-state are implementation details used by the daemon rather than cross-process ownership boundaries.
• Electron's Role: The Electron main process now functions primarily as a transport adapter for renderer IPC.
• Split Responsibility: There is a deliberate split between graph/live-state traffic (which proxies to the daemon) and agent-control tooling (which remains in the Electron-embedded tool side).

The @vt/graph-state package acts as a unified data-layer contract sitting between the pure @vt/graph-model (which handles filesystem-to-graph primitives) and the UI shells (like Cytoscape).

It is a pure state-machine module that manages:

• Unified State: Combines graph data, selection, and layout.
• Commands: Dispatches actions that mutate state.
• Projections: Provides a project() method to transform the internal state into a format suitable for rendering (e.g., for Cytoscape or CLI ASCII views).

Unlike @vt/graph-model, @vt/graph-state does not have filesystem coupling; it focuses strictly on UI-state and command orchestration.

VoiceTree supports a fractal (multi-level) architecture model where detailed diagrams are co-located with the code they describe. This is achieved by placing architecture.md files in subdirectories.

How to refine a parent node:

1. Create an architecture.md file in a subdirectory.
2. Add YAML frontmatter to the file specifying the refines key with the NodeId of the parent node from the higher-level diagram.

Constraint: All click targets in a descendant architecture.md file must reside within the directory subtree of the parent node's click target. This ensures structural consistency across levels.

---
refines: ParentNodeId
---

```mermaid
flowchart TD
    ... 

Voicetree stores terminal recovery metadata in a specific directory within your project. This location is used to reconcile active and exited agent sessions.

Canonical Path: <projectRoot>/.voicetree/terminals/

Note that this path is derived from the project root, not from the writeFolder or environment variables. When interacting with the system, ensure you are referencing the .voicetree directory at the root of your project.