---
name: treeviz-agent
description: "Use for agent-driven phylogenetic tree visualization in TreeViz: load Newick/Nexus/.treeviz.json sessions, import leaf or node metadata, choose row keys, plan tracks, style clades, add node marks, tip connections, legends and attribute names, tune layouts and label culling, check legibility at a zoom, search and inspect nodes, and export figures through the hosted TreeViz browser API (window.__treeviz in ?api=1 mode)."
---

# TreeViz Agent

TreeViz is a browser-based tree visualization tool. Keep biological reasoning,
file preparation, and interpretation in the agent; use TreeViz for deterministic
parsing, metadata binding, layout, styling, diagnostics, and export.

Default hosted runtime:

```text
https://treeviz.newlineages.com/?api=1
```

Headless runtime for browser automation:

```text
https://treeviz.newlineages.com/?mode=headless&api=1
```

This public skill does not vendor the TreeViz browser app or frontend source.
Use the hosted app unless the user explicitly provides another TreeViz runtime.
Guide: `https://fmschulz.github.io/treeviz/AGENTS/`. Runtime entry:
`https://treeviz.newlineages.com/agent`.

Install this whole directory, not only `SKILL.md`: copy `treeviz-agent` to
`~/.claude/skills/` or `.claude/skills/` for Claude Code, or to
`~/.codex/skills/` or a repo's `.agents/skills/` for Codex, then restart the
agent. The guide lists the commands. The agent also needs a way to drive a
browser, such as Playwright, agent-browser, or Claude in Chrome, because every
call runs in the hosted page.

## Core Workflow

1. Open TreeViz with `?api=1` and wait for `window.__treeviz`.
2. Import a tree or restore a `.treeviz.json` session. For the hosted examples, read
   `/examples/manifest.json` for `source.publication` citations, optional
   `recipe: { prompt, url }` entries, and each `sessionUrl`, and read the Example
   Catalog in `references/hosted-runtime.md` for what each example contains. Read each
   provenance audit before reusing reconstructed geometry or derived annotations.
   Adapt the input and styling instructions to the supplied data; restore
   `sessionUrl` for the exact example.
3. Inspect `getSession()`, `commands()`, `palettes()`, and `getDiagnostics()`.
   `describeFigure()` gives a compact summary of the figure.
   `describeCommand(id)` gives one command's schema and a checked example.
   `findNodes(query)` returns stable keys by name, regex, or metadata value.
4. For metadata, call `planMetadataImport(source, format, prompt)` before import.
5. Import metadata with the suggested row key, flags, and leaf identifier source.
6. Add or update tracks through `track.add`, `track.update`, and `track.reorder`.
7. Apply clade styles, conditional rules, node marks, or session connections as needed.
   `execute(id, args)` resolves to `{ ok, value }` or `{ ok: false, error }`
   and does not throw. Use `validate(id, args)` to check arguments without
   running the command, and `executeBatch(steps)` to run dependent edits as one
   unit that rolls back on the first failure.
8. Tune layout with `view.set-layout`, automatic scale, spacing, labels, and legend commands.
9. `await api.whenSettled()`, then check `getDiagnostics()`, `getRenderDiagnostics()`, and layout metrics. See the waits in `references/browser-api.md`.
10. Export evidence: `.treeviz.json` for state, SVG/PNG/PDF for figures, and screenshots when visual quality is the claim.
    `exportImage({ scale: 2 })` returns the Export panel's PNG as a data URL.

## Visualization Defaults

- Start metadata-heavy figures in rectangular layout.
- Try circular or radial layout only when labels and metadata remain readable.
- For circular figures, set the opening angle, rotation, auto-fit, and optional
  opening or interior fills through `view.set-layout`. Use
  `view.set-tip-alignment` with `alignment: 'label'` for tip-to-track guides.
- Shape radial collapsed-clade wedges with `view.set-collapsed-wedge-options`:
  fill source, opacity, gap, minimum body, outline, and data sizing.
- Keep metadata tracks contiguous; use `metadataGap: 0` unless separation is useful.
- Keep `branchScaleMode` on `auto` unless fixed geometry is required. Setting a
  manual branch scale freezes the automatic width and spacing calculation.
- Reduce whitespace by tuning leaf spacing, metadata scale, metadata gap, label
  size, and export cropping before enlarging the canvas.
- Use palette ids from `palettes()`. Prefer `okabe-ito` for categorical data;
  `Viridis`, `Magma`, `Cividis`, or `Blues` for sequential data; and
  `blue-orange`, `RdBu`, or `BrBG` for diverging data.
- Use `categoryColors` when exact category colors must survive a session upload.
- Use `binary-dots` tracks for leaf symbols such as presence/absence markers.
- Use `displayMode: 'symbol'` or `'wedge'` for compact color-strip or bar
  lanes. Bar tracks can use ordered `bins` or `autoBins`.
- Use support labels and internal-node markers for branch support when the tree carries numeric internal-node labels.
- Use exact style attributes for data-defined node circles and branch
  width/color; enable pretty terminal branches when the user asks for styled
  leaf-facing terminal branches.
- For abundance trees, store display-ready diameters, widths, and colors in
  node metadata. Add horizontal names with `tree.style-clade` and
  `{ label, cladeLabelPlacement: 'node', cladeLabelFontSize }`. Node placement
  works on internal and terminal nodes, and font size accepts fractional values
  from 1 to 96 pixels. Set `showScaleBar: false` through `view.set-layout` when
  taxonomic depth should remain visible without a distance scale.
- To preserve a source circular layout, store degrees from 0 through 360 in
  direct node metadata and select the key with `circularAngleAttribute` through
  `view.set-layout`. Opening and rotation still apply. Missing or invalid
  values fall back per node. Keep angles in traversal order for arc connectors
  and collapsed spans. Pass `null` to restore automatic angles. Rectangular and
  radial layouts ignore this setting.
- For a source radial layout, select `radialXAttribute` and `radialYAttribute`
  through `view.set-layout`, or use **Node X coordinate** and **Node Y
  coordinate** under **Controls > Layout**. Every node needs both direct
  metadata values as finite numbers or nonempty numeric strings; positive Y
  points down. An incomplete pair or invalid coordinate uses automatic radial
  layout and reports `render.radial-coordinates-invalid`. Pass both keys as
  `null`, or set both selectors to **Automatic**, to clear them. Circular and
  rectangular layouts ignore them.
- For one-off webapp edits, use Controls > Exact styling for data attributes,
  Style clade for clade branch/label styling, and Inspector for direct
  selected-node circle diameter/color and branch width/color.
- Use `view.set-conditional-style-rules` for metadata-driven thresholds,
  ranks, missing values, and category conditions.
- Use `session.import-node-metadata` and `nodemark.add` for pie, donut, or bar
  marks at named internal nodes.
- Put connections in the saved session. Endpoints use exact leaf names or
  unique internal-node names, with leaf names taking precedence. Set
  `geometry: 'straight'` for constant-width lines; the default `ribbon` is
  bowed and tapered. Resolve ambiguous, unbound, hidden, and collapsed
  endpoint diagnostics before export. Preserve unique internal labels when
  preparing a topology for clade endpoints.
- Use explicit legend titles and item labels when exporting publication figures.
  Place, move or hide sections with `view.set-figure-legend-placement` and
  `{ sectionKey, visible, x, y }`. Custom legend keys are `custom:0`,
  `custom:1`, etc. Explicit section visibility overrides the
  global `view.set-figure-legend-visibility` command. Stored `x` and `y` are
  stage pixels. The open stage keeps each box inside itself and below the
  toolbar, and moves a clipped or overlapping box to a free slot, so check the
  rendered result. A stored `view.scaleBarPosition` off the stage is drawn in
  view the same way.
- Give attribute encodings (branch colour, node-circle colour, wedge fill) a
  legend through `legends` on the session document and readable picker names
  through `attributeLabels`; set `view.figureLegendVisible` when the figure
  should open with the legend shown.
- For a combined numeric size/color legend, use a session JSON
  `continuous-scale` legend with `title`, `axisLabel`, `colors`, `domain`,
  nondecreasing `sizeRange` with a positive maximum, `transform`, `ticks`, and
  optional `scale` and `orientation`. `orientation: 'horizontal'` runs low to
  high left-to-right. `scale` defaults to `1` and accepts `0.1` to `4`. TOML
  legends define swatches only.
- Add `secondaryAxis: { axisLabel, domain, transform, ticks }` to a continuous
  legend when color and size need separate numeric scales. Horizontal primary
  labels are upright below and secondary labels are upright above; vertical
  axes are left and right. See `references/browser-api.md`.
- On crowded radial figures set `collapsedWedgeLabelDeclutter: true` and
  `allowLabelOverlap: false`; culled labels return as the reader zooms in.
  `collapsedWedgeLabelOrientation: 'branch'`, the default, reads each label
  along the branch entering its clade; `'bearing'` reads it out from the
  centre.
- Set `collapsedCladeSpacing: 'compact'` through `view.set-layout` to give
  each collapsed clade at most 12 leaf slots. The default `proportional` gives
  one slot per descendant leaf.
- Treat high unmatched-leaf or unmatched-row counts as a binding problem to fix or report.

## Reference Loading

Load only the reference needed for the task:

- `references/browser-api.md`: command discovery, hosted API methods, current
  feature commands, and JavaScript examples.
- `references/session-workflows.md`: metadata import, session review, clade resolution, and command mapping.
- `references/render-qa.md`: automatic layout, occupancy metrics, screenshots,
  and export QA.
- `references/example-inputs.md`: deterministic 30-leaf and 100-leaf example recipes with metadata and support markers.
- `references/large-taxonomy-trees.md`: large taxonomy-tree workflows, metadata-derived categories, rerooting, and dense exports.
- `references/hosted-runtime.md`: hosted URLs, public files, the example
  catalog and its session URLs, and live API smoke testing.
- `references/wrapper-api.md`: published Python 0.8.2 package and notebook workflows.

## Helper Scripts

- `scripts/check-live-api-smoke.ts`: Playwright smoke test for the hosted browser API.
- `scripts/postprocess-treeviz-export.py`: repeated SVG/PNG cleanup with Pillow
  and `rsvg-convert`.
- `scripts/reroot-newick-by-metadata.py`: repeatable Newick rerooting from TSV/CSV metadata.

## QA Rules

- Always `await` API calls before issuing dependent commands.
- Check `getDiagnostics()` after import and after major edits.
- Check `getRenderDiagnostics()` after a render when the renderer may omit an
  item, such as a connection with an unresolved endpoint.
- Check `getLayoutMetrics()` after layout changes.
- After restore and after each edit, `await api.whenSettled()`. It waits for
  fonts, a rendered frame, and a still camera and metrics, and rejects after
  `timeoutMs` (default 30000). Pass a larger `timeoutMs` for a very large tree.
  Confirm that exported SVG dimensions match the settled stage before saving a
  thumbnail.
- Take `mark = api.getDiagnostics().at(-1)?.seq ?? 0` before a batch and read
  `getDiagnostics({ since: mark })` to see what that batch added.
- Judge legibility at the zoom the reader will use: labels hold their screen
  size above zoom 1, so `labelsVisible` and `labelsCulled` at fit differ from
  the counts at 2x. Call `view.zoom`, `await api.whenSettled()`, read the metrics again.
- Start layout QA with `contentOccupancyX`, `contentOccupancyY`,
  `labelsClipped`, `labelCollisions`, `trackDensity`, and `p75BranchPx`.
- Do not claim visual quality from configuration alone; inspect a recent screenshot, SVG, PNG, or PDF.
- For Python-generated sessions, run `validate_session(session)` and inspect `binding_diagnostics(session)`.
- Save final state as `.treeviz.json` when a user may need to reopen or revise the visualization.