GoalT docs

Python 3.10 or newer. The MCP server depends on the mcp package, which needs 3.10+. If pip installfails with “Requires-Python >=3.10” on macOS, you probably have more than one Python and pip points at the wrong one; check python3 --version and use python3 -m pip install ….

For the plugin: Claude Code. For the dashboard's editor links: VS Code (optional).

First install the server's dependencies once:

$ python3 -m pip install "goaltree[mcp]"

Then, inside a Claude Code session:

$ /plugin marketplace add GOAL-T/goaltree
$ /plugin install goalt@goalt-marketplace

This registers the MCP tools and the activity hook. GoalT never installs packages when the server starts: if a dependency is missing, bootstrap.sh stops and prints the exact command to run instead.

$ git clone https://github.com/GOAL-T/goaltree.git
$ cd goaltree
$ claude mcp add --transport stdio goalt -- bash "$(pwd)/bootstrap.sh"

You get the MCP tools but not the live “Claude is currently…” pulse, because the hook is only registered by the plugin install.

The core engine is on PyPI as goaltree and only needs networkx. Extras: [mcp] for the Claude Code server and dashboard, [viz] for matplotlib drawing, [all] for both.

from goaltree import GoalGraph

g = GoalGraph()
g.add_root("root", "Ship v2 of the product")
g.add_goal("a", "Improve onboarding", parents=["root"])
g.add_goal("b", "Improve performance", parents=["root"])
g.add_goal("c", "Fix export bug", parents=["a", "b"])  # depends on both

print(g)

GoalGraph(root='root')
  1.000  Ship v2 of the product (root)
  1.000  Fix export bug (c)
  0.500  Improve onboarding (a)
  0.500  Improve performance (b)

Why the shared bug fix scores as high as the root is explained in Concepts.

Onboard an existing codebase: run /goalt:startin the project. Claude reads the README, package manifest, folder structure and database migrations if present, then builds a tree of the project's real functional areas and links the files and backend artifacts that implement each one.

Start from scratch:describe the goals in plain language, for example “Create a goal tree for shipping v2, with onboarding and performance as sub-goals and a shared bug fix that depends on both. Show me the priorities and open the dashboard.”

Once a tree exists, Claude keeps it current as it works: it marks the goal it is working on, and when it adds a new goal it tells you in one line. Say so if you don't want the tree updated.

• load_tree: Load the goal tree saved for a project. Claude is told to call this first, so a tree from an earlier session is picked up instead of rebuilt.
• create_tree: Start a new tree with one root goal. Passing project_root turns on saving and uncommitted-changes tracking.
• add_goal: Add a goal under one or more parents, optionally with related files and backend artifacts.
• link_artifacts: Attach files or backend artifacts (tables, edge functions…) to an existing goal.
• list_priorities: List every goal by its computed value, highest first.
• set_active_goal: Mark the goal Claude is working on right now, with a short reason. Best-effort.
• clear_active_goal: Clear that marker when the work is done.
• open_dashboard: Return the local dashboard URL, http://127.0.0.1:8765.
• reset_tree: Discard the current tree.

• Activity pulse. Every edit, read and shell command pulses the header, through a Claude Code hook. The hook sends only the tool name and file path to the dashboard on 127.0.0.1.
• File-edit highlighting. Editing a file linked to a goal lights that goal green, by path matching, with no extra tool call.
• Uncommitted work. A background thread polls git status every few seconds and marks goals amber while their files differ from HEAD.
• Node panel. Click a goal to see its description, related files and backend artifacts, and its current changes.
• VS Code links. Files open in VS Code; files with uncommitted changes get a side-by-side diff.

The tree auto-saves to <project_root>/.goalt/tree.json on every change and loads again next session. Add .goalt/ to .gitignoreif you don't want to commit it. Nothing is uploaded anywhere; see the privacy policy.

• File-to-goal matching is a suffix match on paths, so ambiguous relative paths in unusual layouts can mismatch.
• Uncommitted-changes tracking assumes one git repository at project_root and polls on an interval, so changes show up with a short lag.
• Loading a saved tree at server startup is a guess based on the working directory; load_tree with the real project root is the reliable path.