Development
Plugin
voicetree
The spatial IDE for recursive multi-agent orchestration. It's like an Obsidian graph-view that you work directly inside of.
Plugin Signal64/100Solid
maintained68
capable37
documented100
adopted63
Install
$ npx -y skills add voicetreelab/voicetree --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
What's inside
Skills
2/playwright-debugMoved to .claude/skills/playwright-debug/playwright-debugThis skill should be used when the user asks to "debug the electron app", "connect playwright to VoiceTree", "take screenshots of the running app", "interact with the live UI", "inspect the running application", or "test UI elements live". Provides step-by-step instructions for
Commands
3README
1Voicetree: a graph-based mindmap for building HITL coding-agent systems
Voicetree has two primitives: nodes and edges. A node is either a markdown file, a set of nodes (folder), or a terminal based agent (Claude code, Codex, OpenCode, Gemini etc. ).
There's a small API (& vt CLI) for interacting with them. From this, agent swarms, recursive task decomposition, shared human-agent memory, and self-improving workflows all fall out as consequences.
The system is expressive enough to restructure itself at runtime, and because agents and humans share the same API, that self-modification stays stable and observable.
Think of it as a game engine for agentic systems. Unity gives you GameObjects, a lifecycle, and an API you write C# against. Voicetree gives you nodes, edges, lifecycles, and hooks - but your agents can also write against it, meaning the systems you build can improve themselves.
You are now building an agentic factory, so you can move up to higher levels of abstraction, building the system that builds itself. Build the self-building factory.
(claim, p=0.4 - Markdown hypergraphs have become the de-facto programming language for agent cognition system swarms (augmented brains) in 2027)
Why?
| Challenge | Voicetree Solution |
|---|---|
| Manual agent coordination | Agents can breakdown tasks into subgraphs and recursively spawn children terminals |
| 4-10 agent terminals is overwhelming | Spatially organise agents, tasks and progress on the graph |
| Agents don't know what you know | You share the same memory graph with agents |
| Agents suffer context-rot and lack memory | Defaults to short, focussed sessions with automatic handover |
Early-beta: powerful but rough. We (the startup/lab building it) use Voicetree daily as our AI-forecasting and research tool — development is spiky as a result, and external contributors are very welcome.
API summary
A lightweight API (agent-first, local-only) for a set of operations on these primitives and their lifecycles (for all the interactions you would want for human-in-the-loop agent orchestration: defining workflows, context switching between agent+human contexts, seeing progress as graph etc.)
- CRUD of agents with an in-memory markdown hypergraph based database.
- This includes agent context state (agents can send messages to other agents)
- lifecycle hooks, letting you program & trigger automations
- Graph search, visualisation & navigation. ASCII for the agents, pixels for the human. (Yes this has a UI)
- agent orchestration tools, such as
- run(Agent,node) // default behaviour is collect nearby nodes as context and send_message(agent, local_graph(node)) it into the spawned agent
Obsidian meets Claude Code. Built from first principles for the most efficient human-AI interaction system possible.
Install
Download links macOS (Apple Silicon) | macOS (Intel) | Windows | Linux
MacOS
brew tap voicetreelab/voicetree && brew install voicetree
Linux
curl -fsSL https://raw.githubusercontent.com/voicetreelab/voicetree/main/install.sh | sh
Windows: https://github.com/voicetreelab/voicetree/releases/latest/download/voicetree.exe
Docker (sandboxed — keeps agents off your host filesystem)
docker run -d --rm -p 6080:6080 \
-v voicetree-project:/home/vt/project \
-v voicetree-claude:/home/vt/.config/claude \
--shm-size=1g \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
ghcr.io/voicetreelab/voicetree:latest
# then open http://localhost:6080/vnc.html?autoconnect=1&resize=remote
See docker/README.md for details. amd64 only for now.
Run VoiceTree in the browser (no Electron): a monorepo-only dev command (@voicetree/cli isn't published yet) — see docs/browser-mode.md.
How It Works
Your agents (Claude Code, Codex, Opencode, Gemini etc.) live inside the graph, next to their tasks, plans, and progress updates.
Context retrieval: Agents see all nodes within a configurable radius and can semantic search against local embeddings.
Spatial layout: Location-based memory is the most efficient way to remember things.
Externalized working memory: Each node represents a concept at any level of abstraction. The graph structure mirrors your mental model - relationships between ideas are represented exactly as you think about them, offloading cognitive load to the canvas.
In Detail
Nodes are markdown files, connections are wikilinks to the .md file paths. You open rich markdown editors directly within the graph by hovering over a node, (or use speech-to-graph mode).
You can spawn coding agents on a node, the contents of that node will become the agents task, and it will also be given all context within an adjustable distance around them, and can semantic search against local embeddings. This means agents see what you see. You share the same memory, the same second brain. The graph structure allows for context retrieval to be targeted to only what is most relevant rather than dumping entire conversation history - avoiding the 30-60% performance degradation from context rot1.
Agents can build their own subgraphs, decomposing their tasks into small connected chunks of work. You can glance at the high-level structure and progress of these, and zoom in to the details of what matters most. For example, ask a Voicetree agent to divide their plan into nodes of data-model, architecture, pure logic, edge logic, UI components, and integration. This lets you carefully track the planning to implementation for what matters most: the high level changes & core logic.
Agents can then spawn and orchestrate their own parallel subagents to work through these dependency graphs. In Voicetree, subagents are just native terminals so you have full transparency and control over them unlike with other CLI agents.
As your project & context grows, the Voicetree approach scales. You use your brains most efficient form of memory: remembering the location of where things are. Each node can represent any concept at any level of abstraction. You can see and reason about the structure between these concepts more easily as it is represented exactly as your brain represented them. This lets you externalise your working memory, freeing up cognitive load for the real problem-solving.
Voice Mode
Capture ideas hands-free with speech-to-graph.
Why speaking works: Speaking activates deliberate (System 2) thinking - verbalizing forces you to think about what you are doing. Japanese train conductors use "point and calling" (shisa kanko) to reduce errors by 85% for the same reason. Speech also engages different brain regions than writing, with lower cognitive load for idea generation. It's usually messy and hard to store/retrieve, so we turn voice into a structured mindmap.
Backtracking without mental load: Go arbitrarily deep down a problem. The graph holds the chain of "why am I doing this?" so you don't have to.
Tangibility: Thought becomes visible and persistent. This isn't just documentation; Making progress tangible is a prerequisite for flow states.
Development
A pnpm monorepo (app in webapp/) with a Python backend.
Prereqs: Node 22+, pnpm 10 (corepack enable); Python 3.13 + uv for python backend only. Run pnpm install once (and after deps change).
Run the app
pnpm --filter voicetree-webapp run electron # Electron desktop app (the packaged build)
vt webapp --project <path> [--port <n>] [--lan] [--no-open] # Browser webapp; <> required, [] optional
--port default 3000
--lan expose to phone/tablet on your network
--no-open don't auto-open browser.
Perf stack: Electron auto-attaches local profiling (Grafana/Tempo/Loki/Pyroscope, Go binaries) at the lite tier. Skip it with PERF_STACK=0. vt webapp never attaches it.
Python Backend
uv sync && uv run pytest
Workflow
vt-sync # catch up (use instead of git pull)
git commit -am "..." # commit as you go
vt-pr "feat: ..." # push + open PR into dev
License
BSL 1.1, converts to Apache 2.0 after 4 years. See LICENSE.
Telemetry
We collect anonymous usage telemetry. You can disable this by setting VITE_DISABLE_ANALYTICS=true in webapp/.env. You can read more about this here.
Contact
Questions? Join the Discord. Feedback is valuable - ping us with thoughts, criticisms, or feature requests.
Footnotes
-
Chroma Research, "Context Rot: How Increasing Input Tokens Impacts LLM Performance" (July 2025). 30-60% performance gaps between focused (~300 token) and full (~113k token) prompts. https://research.trychroma.com/context-rot ↩
File tree
1619voicetreelab/voicetreeView on GitHub
.ckignore
.claude/
hooks/
collect-changed-files.cjs
hook-config.json
lib/
config.cjs
quality-checker.cjs
quality-check.cjs
run-per-edit.cjs
stop-quality-check.cjs
plugins/
.claude-plugin/
marketplace.json
playwright-debug/
.claude-plugin/
plugin.json
skills/
playwright-debug/
SKILL.md
settings.agent.json
settings.json
settings.local.json
skills/
playwright-debug/
SKILL.md
.codeql-config.yml
.codex/
hooks/
hooks.json
run-per-edit.cjs
.coveragerc
.dockerignore
.env.example
.github/
workflows/
branch-verification.yml
ci-gate.yml
docker.yml
lint.yml
main.yml
measures-budget-gate.generated.yml
release.yml
secret-scan.yml
.gitignore
.gitleaks.toml
.gitmodules
.jscpd.json
.npmrc
.python-version
.rgignore
AGENTS.md
architecture.md
backend/
__init__.py
benchmarker/
__init__.py
input/
8k.txt
igsm_op14_ip20_force_True_2_problem_question.txt
igsm_op17_ip20_force_True_0_problem_question.txt
igsm_op19_ip20_force_True_7_problem_question.txt
ilan_transcript.txt
nolima_16k_vegan.txt
nolima_8k_spain.txt
nolima_twohop_spain.txt
og_vt_transcript.txt
owl_transcript.txt
russian_improvement.txt
user_guide_qa_audio_processing.txt
visionary_demo.txt
voiceTree_clustering.txt
yc_demo.txt
quality_logs/
latest_quality_log_igsm_op14_ip20_force_True_2_problem_question.txt
latest_quality_log_igsm_op17_ip20_force_True_0_problem_question.txt
latest_quality_log_og_vt_transcript.txt
latest_quality_log_visionary_demo.txt
latest_quality_log_voiceTree_clustering.txt
latest_quality_log_yc_demo.txt
quality_log_igsm_op14_ip20_force_True_2_problem_question.txt
quality_log_igsm_op17_ip20_force_True_0_problem_question.txt
quality_log_og_vt_transcript.txt
quality_log_old.txt
quality_log_visionary_demo.txt
quality_log_voiceTree_clustering.txt
quality_log_yc_demo.txt
quality_log.txt
src/
__init__.py
config.py
evaluation_prompts.py
evaluator.py
file_utils.py
meta_prompts.md
quality_LLM_benchmarker.py
README.md
transcript_processor.py
claude.md
context_retrieval/
__init__.py
arch.md
content_filtering.py
context_output.txt
dependency_traversal.py
full_context.txt
performance_comparison_driver_v2.py
QA_test_questions/
1.md
2.md
3.md
4.md
vt_1.md
retrieve_context.py
todo.md
traverse_all_relevant_nodes.py
logging_config.py
markdown_tree_manager/
__init__.py
EMBEDDING_ARCHITECTURE.md
embeddings/
__init__.py
chromadb_vector_store.py
create_node_embeddings_tsv.py
embedding_manager.py
graph_flattening/
__init__.py
analyze_tree_structure.py
tree_flattening.py
tree_to_markdown.py
graph_search/
__init__.py
tree_functions.py
vector_search.py
markdown_to_tree/
__init__.py
comprehensive_parser.py
file_operations.py
link_extraction.py
markdown_to_tree.py
metadata_extraction.py
node_loader.py
yaml_parser.py
markdown_tree_ds.py
sync_markdown_to_tree.py
TREE_UTILS_README.md
utils.py
markdownTreeProjectDefault/
1_Orphan_Node_1.md
2_Orphan_Node_2.md
4_Parent_Node.md
parent_pid_watchdog.py
paths.py
readme-dev.md
settings.py
sse/
__init__.py
context.py
event_emitter.py
tests/
__init__.py
animal_example/
ashen_crag/
18_Squirrel_Newborn_Average_Calculation_Ashen_Crag.md
22_Adult_Chinchilla_Count_Calculation_Ashen_Crag.md
30_Chipmunk_Newborn_Average_Ashen_Crag_Equals_Eagle_Newborn_Average_Hamilton_Farm.md
31_Adult_Rat_Count_Ashen_Crag_Equals_Adult_Crow_Count_Hamilton_Farm.md
38_Adult_Squirrel_Count_in_Ashen_Crag_Calculation.md
39_Beaver_Newborn_Average_in_Ashen_Crag_Calculation.md
4_Porcupine_Newborn_Average_in_Ashen_Crag_Summation.md
40_Adult_Capybara_Count_in_Ashen_Crag_Calculation.md
41_Adult_Guinea_Pig_Count_in_Ashen_Crag_Calculation.md
5_Rat_Newborn_Average_in_Ashen_Crag_Equals_Parrot_Newborn_Average_in_Bundle_Ranch.md
9_Adult_Chipmunk_Count_in_Ashen_Crag_Summation.md
bundle_ranch/
2_Adult_Parrot_Count_Difference_in_Bundle_Ranch.md
23_Crow_Newborn_Average_Quantity_Bundle_Ranch.md
7_Adult_Crow_Count_in_Bundle_Ranch_Calculation.md
8_Parrot_Newborn_Average_in_Bundle_Ranch_Calculation.md
hamilton_farm/
12_Adult_Crow_Count_in_Hamilton_Farm.md
19_Adult_Eagle_Count_in_Hamilton_Farm_Quantity.md
21_Blue_Jay_Newborn_Average_Equality_Hamilton_Farm.md
29_Parrot_Newborn_Average_Hamilton_Farm_Calculation.md
3_Eagle_Newborn_Average_in_Hamilton_Farm_Equals_Parrot_Newborn_Average_in_Bundle_Ranch.md
6_Adult_Blue_Jay_Count_in_Hamilton_Farm.md
jefferson_circus/
20_Eagle_Newborn_Average_Calculation_Jefferson_Circus.md
24_Crow_Newborn_Average_Calculation_Jefferson_Circus.md
25_Parrot_Newborn_Average_Calculation_Jefferson_Circus.md
28_Adult_Eagle_Count_Jefferson_Circus_Calculation.md
33_Adult_Parrot_Count_Jefferson_Circus_Equals_Parrot_Newborn_Average_Hamilton_Farm.md
36_Adult_Crow_Count_in_Jefferson_Circus_Quantity.md
mayer_aquarium/
26_Crow_Newborn_Average_Quantity_Mayer_Aquarium.md
27_Adult_Crow_Count_Mayer_Aquarium_Equals_Crow_Newborn_Average_Jefferson_Circus.md
32_Blue_Jay_Newborn_Average_Mayer_Aquarium_Calculation.md
34_Parrot_Newborn_Average_Mayer_Aquarium_Calculation.md
35_Adult_Blue_Jay_Count_in_Mayer_Aquarium_Calculation.md
37_Adult_Parrot_Count_in_Mayer_Aquarium_Equality.md
unspecified/
1_Mathematical_Relationships_in_Animal_Populations.md
10_Chinchilla_Newborn_Average_Calculation.md
11_Parrot_Adult_Count_Relation.md
13_Beaver_Adult_Count_Calculation.md
14_Crow_Newborn_Average_Calculation.md
15_Porcupine_Adult_Count_Equality.md
16_Guinea_Pig_Newborn_Average_Calculation.md
17_Capybara_Newborn_Average_Calculation.md
conftest.py
fixtures/
real_example_folder/
code-extraction/
3_1_1_Xavier_Moved_Loading_Logic_to_MarkdownTree_Constructor.md
3_1_Xavier_Extracted_Load_Directory_Function.md
3_Extract_Content_to_New_File.md
4_Load_Directory_Script.md
5_Load_Markdown_Files.md
integration-testing/
34_1_Bob_Integration_Test_Implementation_for_Module_Loading.md
34_Overall_Integration_Test.md
35_1_Bob_Testing_Strategy_for_Decentralized_Module_Loading.md
35_Testing_Difficulty_of_Decentralized_Module_Loading.md
37_1_Bob_Complete_Integration_Test_Methodology_Answer.md
37_Integration_Test_Methodology_Question.md
38_Perform_Git_Diff_for_Integration_Test.md
39_Propose_Integration_Test.md
introduction/
1_Introduction_to_Current_Work.md
29_Log_Architecture_Decision.md
meta/
.claude/
settings.local.json
.obsidianignore
module-self-loading/
16_Assess_load_underscore_dur_py_Relevance.md
17_Chunk_Processor_Responsibility.md
18_Problem_load_dur_py_Return_Value.md
19_Decision_to_Remove_load_dur_py.md
20_Implement_Markdown_Loading_in_server_py.md
28_Call_Load_Subdirectory.md
30_Module_Self-Loading_Strategy.md
32_1_1_Bob_Recommendation_Maintain_Module_Self_Loading_Strategy.md
32_1_Bob_Module_Self_Loading_Strategy_Evaluation_Complete.md
32_Evaluate_Module_Self-Loading_Strategy.md
33_Consult_AI_for_Strategy_Evaluation.md
36_Test_Module_Self-Loading_Strategy.md
new-projects/
21_New_Artificial_Intelligence_Project.md
22_New_Web_Application_Development_Project.md
23_Concurrent_Request_Machine_Learning_Algorithms.md
24_Concurrent_Request_Web_Development.md
25_Concurrent_Request_Mobile_Development.md
31_New_Software_Development_Initiatives.md
46_New_Software_Development_Initiatives.md
47_System_Functionality_and_Testing.md
shell-fixtures/
infllm.sh
transcript_history.txt
voicetree.sh
transcript-history/
11_1_1_Zoe_Transcript_History_Implementation_Complete.md
11_1_Zoe_Transcript_History_Analysis_Complete.md
11_Identify_and_Modify_Code_for_Transcript_Saving.md
12_Relocate_Transcript_History_Loading.md
15_1_Zoe_History_Injection_Implemented.md
15_Inject_Existing_History_into_Chunk_Processor.md
27_Implement_History_Manager_for_Transcripts.md
40_Verify_Transcript_File_Creation.md
41_Decision_Save_All_Transcript_Text.md
42_Bug_Unprocessed_Text_in_History.md
43_Solution_Divorce_History_Text_Processing.md
44_Decision_Outcome_Save_to_Comment.md
45_Instruct_Agent_to_Save_Transcript.md
7_Load_Transcript_History.md
8_Save_Transcript_History.md
vector-loading/
10_1_Yara_Vector_Loading_Status_Investigation_Complete.md
10_Investigate_Vector_Loading_Status.md
14_Re-evaluate_Vector_Loading_Investigation_Focus.md
2_Read_History_Markdown_Vectors.md
6_Load_Vector_Files.md
9_Current_Vector_Loading_Status.md
workflow-merging/
13_1_Alice_Workflow_Merger_Analysis_Complete.md
13_Evaluate_Workflow_Merging.md
26_Observation_on_Workflow_Overcomplication.md
integration_tests/
__init__.py
benchmarker/
__init__.py
context_retrieval/
__init__.py
test_embedding_search_data/
advanced-tech/
16_Quantum_Computing_Basics.md
17_Blockchain_Technology.md
18_Artificial_Intelligence_Ethics.md
19_Neural_Network_Training.md
20_Transformer_Models.md
creative/
11_Cooking_Italian_Cuisine.md
12_Garden_Plant_Care.md
13_Travel_Photography_Tips.md
14_Fitness_Training_Programs.md
15_Music_Theory_Fundamentals.md
search-state/
seen_nodes_Henry.csv
tech-core/
1_Machine_Learning_Basics.md
10_Web_Development_Frameworks.md
2_Deep_Learning_Architectures.md
3_Natural_Language_Processing.md
4_Computer_Vision_Applications.md
5_Data_Preprocessing_Techniques.md
6_Model_Evaluation_Metrics.md
7_Python_Programming_Basics.md
8_Database_Management_Systems.md
9_Cloud_Computing_Platforms.md
test_embedding_search_integration.py
test_infinite_llm.py
test_refactoring_integration.py
test_score_sanity_check.py
test_traverse_all_relevant_nodes.py
test_vector_search_integration.py
live_system/
__init__.py
test_system_llm_live.py
markdown_tree_manager/
__init__.py
test_recency_from_filesystem.py
test_stale_vector_cleanup.py
test_vector_storage_creation.py
markdownTreeProjectDefault/
1_Root.md
mocked/
__init__.py
test_integration_llm_mocked.py
test_load_directory_endpoint.py
test_retrieve_context.py
test_server_startup_load.py
test_workflow_node_removal.py
text_to_graph_pipeline/
__init__.py
chunk_processing_pipeline/
test_chunk_processor_tree_actions.py
test_convert_append_to_child_for_long_nodes.py
test_pipeline_e2e_with_di.py
test_pipeline_e2e_with_real_embeddings.py
test_tree_action_decider_workflow.py
test_incomplete_chunk_handling.py
test_orphan_linking_behavior.py
qa_example/
community-legal/
14_GPT-SoVITS_Usage_Agreement.md
15_GPT-SoVITS_Official_Communication_Group.md
19_GPT-SoVITS_Disclaimer.md
ecosystem/
32_GPT-SoVITS_Ecosystem_and_Development.md
33_Speech_Synthesis_Technologies.md
37_GPT-SoVITS_Project_Ecosystem.md
39_GPT-SoVITS_Development_Update_Logs.md
40_GPT-SoVITS_Project_Ecosystem.md
41_GPT-SoVITS_Development_Update_Logs.md
43_GPT-SoVITS_Project_Ecosystem_and_Core_Components.md
44_GPT-SoVITS_Development_and_Update_Logs.md
features/
10_GSV_Training_Set_Expansion.md
11_GSV_Supported_Languages.md
12_GSV_Text_Front-End_Improvements.md
13_GPT-SoVITS-V2_Features.md
20_GPT-SoVITS-V1_Achievements.md
3_Text-to-Speech_TTS_Technology.md
4_Speech_Synthesis_Technologies.md
5_GPT-SoVITS_TTS_Limitation.md
6_GSV_Audio_Control.md
7_GSV_Training_and_Inference_Flexibility.md
8_GSV_Cross-Language_Generation.md
9_GSV_Low-Quality_Audio_Synthesis_Improvement.md
fundamentals/
35_Speech_Synthesis_Technologies.md
38_Speech_Synthesis_Fundamentals.md
42_Speech_Synthesis_Fundamentals.md
45_Speech_Synthesis_Fundamentals_and_Technologies.md
inference/
25_Inference_Consistency_Verification.md
26_Cantonese_ASR_Support.md
27_Speech_Synthesis_Speed_Adjustment.md
28_Accelerated_Inference.md
29_GPT_Chinese_Fine-tuning_BERT_Inconsistency.md
30_Fast_Inference_Branch.md
meta/
36_Meta-commentary_on_Node_Connection_Testing.md
overview/
1_GPT-SoVITS_Software.md
2_GPT-SoVITS_User_Manual.md
34_GPT-SoVITS_Project_Overview.md
training-data/
18_GPT-SoVITS_Voice_Training_Set_Source.md
tutorials/
... 1600 moreShowing a partial view of a very large repo.
FAQ
voicetree is a Claude Code plugin with 2 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes playwright-debug, playwright-debug. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is voicetree?
- The spatial IDE for recursive multi-agent orchestration. It's like an Obsidian graph-view that you work directly inside of.
- How do I install voicetree?
- Run these in Claude Code: npx -y skills add voicetreelab/voicetree --agent claude-code. Then prompt normally.
- Does voicetree auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is voicetree free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.