voicetreelab/voicetree: a spatial graph IDE for orchestrating coding agents

What Voicetree is for, and who it is for

Running four to ten coding-agent terminals at once is a coordination problem before it is a compute problem. Each session starts cold, you paste context in, and the agent has no idea what the other sessions know. Voicetree's answer is to make the workspace itself the shared state: a graph of nodes where a node is a markdown file, a folder of nodes, or a terminal-based agent such as Claude Code, Codex, OpenCode or Gemini.

The README frames the target user directly. It lists four challenges and pairs each with a mechanism: manual agent coordination against agents that break tasks into subgraphs and spawn child terminals; terminal overload against spatial organisation of agents and progress; agents not knowing what you know against a shared memory graph; and context rot against short focused sessions with automatic handover. The project describes itself as "Obsidian meets Claude Code" and as early-beta, "powerful but rough", used daily by the lab that builds it for AI-forecasting and research work. That last sentence matters more than the feature table: the maintainers say development is spiky because the tool is their own working instrument, and they invite external contributors on that basis.

Nodes, edges and the shared memory graph

The data model is small. Nodes are markdown files; edges are wikilinks to the .md file paths. Because the graph is backed by an in-memory markdown hypergraph database, the same structure serves as the document store and as the agent context store. Hovering a node opens a rich markdown editor in place, and the README also mentions a speech-to-graph mode.

Context retrieval is the part worth understanding. The README states that agents see all nodes within a configurable radius and can semantic search against local embeddings. When you spawn an agent on a node, that node's contents become the task and the agent also receives the surrounding context within an adjustable distance. The stated reason is context rot: the README cites a 30 to 60 percent performance degradation and argues that targeted graph retrieval avoids dumping entire conversation history. Treat that number as the project's claim, not a measured result.

Orchestration is exposed through a small API and a `vt` CLI. The README summarises one default: `run(Agent,node)` collects nearby nodes as context and sends the local graph of that node into the spawned agent. Lifecycle hooks let you program automations, and agents can send messages to other agents, which the README says is what makes recursive task decomposition and self-restructuring workflows possible.

Installing Voicetree and spawning a first agent

Installation is a desktop download or a package manager. On macOS the README gives a Homebrew tap:

brew tap voicetreelab/voicetree && brew install voicetree

After that, launching the app should open the graph canvas. On Linux the README points at an install script:

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

Windows users are directed to the release executable, voicetree.exe. Release assets are also listed for macOS Apple Silicon, macOS Intel and Linux AppImage.

If you would rather keep agents off the host filesystem, the README provides a Docker path that serves a browser-accessible desktop over port 6080:

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

The same service is described in docker-compose.yml, which reads an .env file and maps 6080:6080 with the volumes `project` and `claude-config`. The .env.example explains why the API key is the practical route: no browser is preinstalled in the container, so the OAuth flow is awkward, and `ANTHROPIC_API_KEY` is the required variable. `OPENAI_API_KEY` and `GEMINI_API_KEY` are listed as optional for other agent CLIs installed via install-agents.sh.

For a first real use, the workflow the README describes is: create or open a markdown node, write the task into it, spawn a terminal agent on that node, and let the agent collect nearby nodes as context. The agent can then decompose its own work into connected subgraphs, which you inspect by zooming out for structure and in for detail.

Where the early-beta label shows through

The README is unusually candid, and the gaps are worth listing before you commit a team to this. Browser mode without Electron exists, but the README states it is a monorepo-only dev command because `@voicetree/cli` is not published yet. If your plan depends on scripting Voicetree from CI or another machine, that plan has no supported entry point right now.

The Docker image is amd64 only. Apple Silicon users running the container will hit emulation, and the README gives no timeline for an arm64 image. The container also has no browser preinstalled, which is why the API-key route is recommended over OAuth; that is a real constraint on how you authenticate agents inside the sandbox.

The repository layout suggests a large surface for a project at this stage: a TypeScript monorepo with pnpm workspaces, a separate Python backend with strict mypy settings, cloud functions, infra, a perf stack, and an evals directory. That breadth is not a defect, but it does mean the install paths above are the supported ones and the rest is internal to the lab. The README also notes that development is spiky because the maintainers use the tool daily for their own research. Spiky development is a maintenance property, not a marketing line: expect the graph model and the API to move between minor versions. The last push to the repository was on 2026-06-07, and the most recent release listed is v3.0.2 from 2026-06-06.

How it differs from a plain terminal multiplexer or Obsidian alone

The obvious comparison is tmux or a terminal multiplexer plus a notes app. A multiplexer gives you panes and a session name; it has no concept of a node, no context inheritance, and no memory shared with an agent. Voicetree's difference is that the layout is the context: proximity in the graph is what an agent retrieves, so moving a plan node next to a task node changes what the spawned agent sees.

Obsidian alone is the other comparison, and the README invites it with the Obsidian graph-view framing. Obsidian gives you markdown files, wikilinks and a graph view you look at. Voicetree is a graph you work inside: terminals live on nodes, and the same API is available to the agents, which is what the README means by the system being expressive enough to restructure itself at runtime. If you only want linked notes and no agents, Obsidian does that with a far smaller install and no beta caveats.

Against a hosted agent orchestration platform, the trade is reversed. Voicetree's API is described as agent-first and local-only, with an in-memory markdown hypergraph database. That keeps your notes and agent state on your machine, and it also means there is no server-side coordination layer to fall back on if the local process dies.

Licence, maintenance and upgrade cost

The repository records the licence as NOASSERTION, which means GitHub could not map the LICENSE file to a known identifier. That is not the same as having no licence, but it does mean you should read the LICENSE file in the repository root yourself before you build anything commercial on top of it. Nothing in the README describes commercial terms, contributor agreements or a relicensing policy, so there is no stated answer to give here.

On maintenance, the facts are the last push on 2026-06-07 and releases v3.0.0, v3.0.1 and v3.0.2 within the first week of June 2026. The README states that development is spiky and that the lab uses Voicetree daily. Upgrades are the practical cost: the desktop app installs from a package manager or a release binary, so updating is a reinstall rather than a pinned dependency you can freeze. If you adopt it, keep your markdown nodes in a directory you control, since the graph is built from files and the Docker path already mounts the project directory as a volume. That way a version change cannot take your notes with it.

Editorial conclusion

Voicetree suits engineers already running several coding-agent terminals who want their task notes, plans and agent sessions in one spatial graph, and who accept early-beta roughness. It is the wrong tool if you need a stable, documented orchestration API or a published CLI: the README states the CLI is not published yet and browser mode is monorepo-only. Before adopting, verify that your agent CLI of choice runs inside the graph on your platform, and read docker/README.md if you intend to sandbox, since the image is amd64 only for now.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. voicetreelab/voicetree on GitHub