Install
Typed Graph works on desktop and mobile. Pick one:
- Community plugins (recommended): open Typed Graph in Obsidian, or go to Settings → Community plugins → Browse → Typed Graph → Install → Enable. Directory page: community.obsidian.md/plugins/typed-graph.
- BRAT, for beta builds: install Obsidian42 - BRAT, run BRAT: Add a beta plugin and enter
Volland/typedgraph. - Manual: from the latest release copy
main.js,manifest.jsonandstyles.cssinto<vault>/.obsidian/plugins/typed-graph/, reload, enable.
VS Code extension
Without Obsidian, the Typed Graph extension shows typed backlinks and the graph for the markdown and @lat:/@tg:-annotated code in a workspace, and offers to run tg init. It is published on the VS Code Marketplace and on Open VSX as pavlyshyn.typegraph-vscode.
- VS Code: search TypeGraph in the Extensions view and install, or run
code --install-extension pavlyshyn.typegraph-vscode. - VSCodium, Cursor, Windsurf, Gitpod, Theia (editors that use Open VSX): search TypeGraph in the Extensions view and install, or run
codium --install-extension pavlyshyn.typegraph-vscode. - From source:
npm install && npm run package:vscodebuildspackages/vscode/typegraph.vsix.
Settings: typegraph.roots (folders that form the graph, default ["."]), typegraph.ignore (folder names to skip, default ["node_modules"]) and typegraph.fullGraphLimit (most nodes the whole-project graph draws, default 2000).
Commands: TypeGraph: Open Graph shows the active file's neighborhood. TypeGraph: Open Full Graph, or the Whole project toggle in the panel, draws every node and edge, keeping the most connected ones past the limit. TypeGraph: Export Graph as HTML saves a self-contained page that works offline, and TypeGraph: Export Graph as PDF saves a one-page vector PDF with searchable labels and the node and edge counts in its caption. All four are buttons in the Backlinks view title bar, and the two exports are in the panel toolbar. Exports write only the file you pick.
Quick start
- Give a note a type: add
type: Personto its frontmatter. - Write an edge line:
knows:: [[Bob]] {since: 2020}. - Add a query block anywhere:
```graph-query MATCH (a:Person)-[r:knows]->(b) RETURN a, r, b ```
- Open the explorer with Typed Graph: Open graph view or the ribbon icon.
Edges
An edge is one line in a note; the note is the source.
knows:: [[Bob]]
knows:: [[Carol]] {since: 2018, label: "met at conf"}
-distrusts:: [[Eve]]
+trusts:: [[Bob]]
- works_at:: [[Acme]], [[Initech]] {role: engineer}
| Part | Meaning |
|---|---|
type:: | Edge type. Graph Link Types lines work unchanged. |
- / + prefix | Sign: −1 or +1 (default +1). weight is an ordinary property. |
{…} | Properties: numbers, booleans, quoted or bare strings, lists. |
{id: "…"} | Pins the edge id; otherwise it is source#type#target#n. |
| heading | The nearest heading above is recorded with the edge. |
Lines in code blocks and frontmatter are ignored. Malformed property blocks keep the edge and appear in Show diagnostics. Links to missing notes become faded stub nodes.
Typed nodes
Every note is a node. Frontmatter type becomes its labels; a list gives several:
--- type: [Person, Employee] age: 40 ---
Frontmatter fields, title and path are node properties.
Schema notes
Notes directly in Types/ (configurable) declare types. schema: describes the type named by the note's title, and its body is that type's template:
---
schema:
properties:
status: {kind: text, default: active, values: [active, alumni]}
born: {kind: date, required: true}
aliases: list
edges: {knows: Person, worksAt: Company}
visualization:
color: "#7c5cff"
shape: ellipse
icon: user
label: name
edges:
knows: {color: orange, line: dotted}
---
## Notes
One note can also describe a whole subsystem: several types under schemas: and edge types with their own properties under edgeTypes:.
---
schemas:
Person: {properties: {email: {required: true}}, edges: {worksAt: Company}}
Company: {uri: schema:Organization, properties: {founded: date}}
edgeTypes:
worksAt:
from: Person
to: Company
properties: {since: date, role: {values: [engineer, manager]}}
visualization: {color: green}
---
- Kinds:
text,number,boolean,date,datetime,link,list. Properties takerequired,many,values,defaultanduri. edgesis a list of allowed outgoing edge types, or a map to target types (worksAt: Company) or to{target, many, required}. Omit it to allow any edge.uriaccepts an IRI or a CURIE such asschema:Person; add prefixes with aprefixes:key.- New typed note (command, ribbon menu, or a folder's context menu) uses the
templatenote if set, else theschema:note's body, else a template generated from the schema. It never overwrites a note. VS Code has TypeGraph: New Typed Note and the same templates. idgives new notes identifiers (TGS 0.2):uuid,uuid7(time-ordered, so ids sort by creation),timestamp(YYYYMMDDHHmm) orluhmann(1,1a,1a1,2). A list names apropertyfor each;auto: falsekeeps an id for when you ask, andfilename: trueprefixes the file name. Luhmann ids are made by New child note and New sibling note from a note that has one, or New top-level note for the next number.- Templates may use
{{title}},{{date}},{{time}},{{id}},{{<id property>}}and, for a child or sibling,{{parent}},{{parent-id}}and{{parent-link}}. A line that names the parent is dropped when there is none; other braces, such as edge embeds, stay as written. - Validation is advisory: required and allowed values, lists, allowed, required and single edges, edge endpoints and edge properties. Issues show in the status bar and Show diagnostics.
- Export schemas as SHACL and Import SHACL shapes exchange schemas with RDF tools, as do
tg schema exportandtg schema import.
The format is an open specification, Typed Graph Schema (TGS) 0.2, with a JSON Schema and conformance examples; 0.1 stays published, and every 0.1 schema note is valid 0.2.
AsciiDoc notes
An .adoc file is a note like a Markdown one. Everything the graph reads hides in a comment or a header attribute, so Asciidoctor renders the file exactly as it would without it.
////
type: Chapter
status: draft
////
= Metagraphs
:tg-pages: 12
// @tg: cites:: [[Pavlyshyn 2024]] {page: 12}
[#definition]
== Definition
A metagraph generalizes a hypergraph.
| Form | Meaning |
|---|---|
leading //// block | YAML properties, as frontmatter; type gives labels. A block that is not YAML is reported. |
:tg-key: value | A property with a one-line YAML value. The leading block wins when both set a key. |
// @tg: type:: [[X]] | A typed edge. A //// block starting with @tg holds one edge per line. Edge syntax outside a comment is not an edge. |
| anchoring | A comment above a heading belongs to that section; elsewhere to the section it sits in. The edge records it as section. |
xref:, <<…>> | Plain links when link edges are on. |
include:: | An ordered includes edge with leveloffset, tags and lines; a source file include ends at its code node. |
A link without an extension matches .md and .adoc notes; when both exist it is reported as ambiguous. Obsidian, VS Code and the sidecar index .adoc files by default (a setting turns it off); tg reads the files matched by notes in .tg/config.json, for example { "notes": ["book/**/*.adoc"] }, which tg init proposes. The OKF export skips AsciiDoc notes. Details are in TGS 0.3.
Edge property embeds
We met in {{edge: Alice -knows-> Bob . since}}.
{{edge: met-2020 . since}}
{{edge: met-2020}}
Find an edge by endpoints and type or by pinned id; . property shows one value, otherwise a small table. Put a sign before the type to require it: --distrusts-> (negative), -+knows-> (positive). Embeds referencing unpinned edges get a diagnostic suggesting an id.
Query blocks
A graph-query block is an optional header, a blank line, then the query.
```graph-query view: table columns: who, since backend: builtin node.Person: color=#e5484d, shape=hexagon edge.knows: line=dashed MATCH (a:Person)-[r:knows]->(b) RETURN a.title AS who, r.since AS since ```
| Option | Values |
|---|---|
view | auto (graph when the result has nodes, relationships or paths), table, graph |
columns | Table columns to show, in order |
height | Graph height in pixels (100–4000) |
backend | builtin or ladybug (needs the sidecar) |
code | show (default) or hide source-code nodes in graph results |
forces | Initial layout forces, e.g. center=0.3, repel=12, link=0.6, distance=200, edgeRepel=0.4, labelRepel=0.8, pinOnDrag=true |
display | e.g. arrows=true, edgeLabels=true, fade=0.12, nodeSize=0.75, linkSize=0.5, hide=requirement|feature |
pin | self (default), none, or note names; the first goes to the centre |
controls | show (default), open or hide the graph controls button |
node.<Type> / edge.<type> | Style overrides for this block |
Results refresh live. Graphs larger than the element limit fall back to a table. The gear button's Copy as block options writes the current forces, display and pin lines for you.
Variables and metadata
A block can refer to the note it sits in with {{…}} variables. Each one is replaced by a Cypher literal before the query is parsed, so this block always shows its own note's neighbourhood, wherever you paste it:
```graph-query
MATCH (me {path: {{path}}})-[r]-(x)
WHERE x.status = {{fm.status}}
RETURN me, r, x
```
| Variable | Value for Projects/Atlas/Plan.md |
|---|---|
{{path}} | "Projects/Atlas/Plan.md" |
{{name}} | "Plan.md" |
{{title}} | "Plan", the file name without extension (frontmatter title is {{fm.title}}) |
{{folder}} | "Projects/Atlas"; "" at the vault root |
{{extension}} | "md" |
{{fm.<key>}} | Any frontmatter value (also {{frontmatter.<key>}}; dots walk into maps). Strings are quoted, numbers and booleans plain, lists stay lists. |
Unknown names and values that are not literals become null. Nothing is evaluated: write {{fm.budget}} * 2, not {{fm.budget * 2}}. Variables work on both backends.
Every query can also use metadata that Typed Graph adds on its own, with no schema: n.path, n.title, n.stub and every frontmatter key on nodes; type(r), r.sign, r.id and every {property} on edges. The Graph view also binds the parameter $activeFile. The query cheat sheet lists all of it on one page, including the Section, Requirement and code nodes of tg cypher.
openCypher subset
- Clauses:
MATCH,OPTIONAL MATCH,WHERE,WITH,RETURN [DISTINCT],ORDER BY,SKIP,LIMIT. - Patterns: labels, property maps,
-><--,[:a|b],[:knows*1..3],p = (...). - Aggregates:
count(*),count,sum,avg,min,max,collect(withDISTINCT). - Functions:
id type labels keys properties startNode endNode length nodes relationships toLower toUpper trim replace substring split left right size coalesce toString toInteger toFloat abs round floor ceil sign head last reverse. - Built-ins:
n.stub,n.title,n.path,r.id,r.sign, and every frontmatter key or edge property by name. See Variables and metadata.
CREATE, SET, DELETE, MERGE and REMOVE are rejected. UNWIND, UNION, CALL, CASE and =~ are not in the built-in subset; use backend: ladybug for those.Styling
Every attribute resolves on its own; the most specific source wins:
- Block header (
node.Person: color=red) - Schema note
visualization - Settings → Type styles / Edge styles
- Defaults: a stable color per type; negative edges dashed red with a tee arrow
Node attributes: color, shape (ellipse, rectangle, round-rectangle, diamond, hexagon, triangle, star), icon (Lucide name), label (property shown instead of the title). Edge attributes: color, line (solid, dashed, dotted).
Graph view
- Empty query: follows the active note's neighborhood.
- Enter a query and press Run or ⌘/Ctrl+Enter.
$activeFileis the path of the last active Markdown note, soMATCH p = (n {path: $activeFile})-[:knows*1..2]->(y) RETURN pfollows you as you switch notes. It isnulluntil a note has been active.- Right-click or long-press a node to expand it; double-click or ⌘/Ctrl-click to open its note.
- Select a node or edge to see its properties and where each style came from.
Node names
A node is named after its note's file name. Frontmatter title: Billing spec replaces the file name, in the graph and in queries. Frontmatter subtitle: billing keeps the title and adds to it in the graph only, so specs/billing/spec.md shows as spec — billing instead of one of many spec nodes. OpenSpec accepts frontmatter in spec.md and design.md. A type's visualization.label property still wins over both.
This is a separate view. Obsidian's core Graph view is left untouched, because it has no plugin API and patching it breaks on Obsidian updates. It still draws one plain line per linked pair of notes, with no edge types, signs or properties.
Color types in the core Graph view
You can still color nodes by type in the core Graph view, without any plugin code. Open the core Graph view, expand Groups, choose New group, and enter a property search such as [type:Person], then pick a color. Add one group per type. The first matching group wins, so order groups from most to least specific.
The sidecar
An optional headless Node service over a read-only copy of your vault. It powers the Ladybug backend, vector search, GraphRAG and MCP.
npm install && npm run build:sidecar OBSIGRAPH_VAULT=/path/to/vault OBSIGRAPH_DATA=/path/to/data OBSIGRAPH_TOKEN=change-me \ node packages/sidecar/dist/server.mjs
Docker: packages/sidecar/Dockerfile and compose.example.yaml mount the vault :ro, run as non-root and publish on host loopback only.
| Endpoint | Purpose |
|---|---|
GET /health | Liveness (no token) |
GET /status | Graph, mirror and vector state |
POST /query | {query, params, backend} → {columns, rows} |
POST /search | Vector search, optional then Cypher with $hits |
POST /retrieve | GraphRAG retrieve |
POST /vectors/rebuild | Re-embed after a model change |
POST /mcp | MCP over streamable HTTP |
| Variable | Default |
|---|---|
OBSIGRAPH_VAULT, OBSIGRAPH_DATA | /vault, /data |
OBSIGRAPH_TOKEN / OBSIGRAPH_TOKEN_FILE | required (except --stdio) |
OBSIGRAPH_HOST, OBSIGRAPH_PORT | 127.0.0.1, 8765 |
OBSIGRAPH_POLL_MS | 0 (set e.g. 5000 on macOS bind mounts) |
OBSIGRAPH_LADYBUG, OBSIGRAPH_VECTORS | on; set 0 to disable |
OBSIGRAPH_EMBED_PROVIDER, _URL, _MODEL, _KEY/_KEY_FILE | ollama, http://localhost:11434, nomic-embed-text |
Ladybug backend
The sidecar mirrors the graph one-way into LadybugDB. Set the sidecar URL and token in plugin settings, then use backend: ladybug in a block. Queries the built-in parser reads are translated so they return the same results. A 52-query conformance suite keeps the two engines in agreement.
Other read Cypher (UNWIND, CASE, UNION, =~) runs on LadybugDB untranslated, against the mirror layout. The result carries a notice saying so. In that layout:
- Every note is a
Node, withtitle,path,stuband alabelslist. - Each edge type is its own relationship table.
- Properties are typed columns named
p_<name>_<kind>. The kind iss(text),n(number),b(boolean),lsorln(lists) orj(anything else).
```graph-query
backend: ladybug
view: table
MATCH (p:Node)-[c:contributes]->(proj:Node)
WHERE list_contains(p.labels, "Person")
RETURN p.title AS person, proj.title AS project,
CASE WHEN c.p_hours_n >= 100 THEN "core" ELSE "helper" END AS involvement
```
Vector search
Notes are chunked by heading with title, type and frontmatter as context; each edge becomes a sentence like Alice (Person) knows Bob (Person) - met at NeurIPS. Embeddings come from local Ollama by default.
POST /search
{"query": "machine learning", "target": "nodes", "k": 5, "types": ["Person"],
"then": "MATCH (p)-[:works_at]->(c) WHERE id(p) IN $hits RETURN c.title"}
GraphRAG
POST /retrieve
{"question": "Who works with Alice on search?", "k": 5, "depth": 1}
Returns the best chunks of the vector hits and of their graph neighbors (hits first, then by distance), each with path, heading, score and role, plus the connecting edges. Hub expansion is capped and flagged.
MCP for agents
claude mcp add typed-graph \ -e OBSIGRAPH_VAULT=/path/to/vault -e OBSIGRAPH_DATA=/path/to/data \ -- node /path/to/packages/sidecar/dist/server.mjs --stdio
Tools: cypher_query, vector_search, graphrag_retrieve — all read-only. Over HTTP use POST /mcp with the bearer token.
Security
- The vault is never written: mounted read-only, with every write confined to the data directory.
- Bearer token on everything but
/health; loopback bind by default; body and time limits. - Read-only queries enforced twice on Ladybug: a guard and a read-only database snapshot.
- Retrieved note text is marked as untrusted content for agents.
CLI: tg
tg works on a lat.md/ folder, the same format as lat.md. Sections can carry typed edges as well as plain links: a line - motivated_by:: [[constraints#GDPR]] {since: 2} after a section's leading paragraph is a named edge with properties in tg cypher, and an ordinary wiki link for lat.md. Install with npm install -g @typedgraph/cli. It finds the project by walking up to the nearest lat.md/ or .tg/ folder; --dir overrides. Exit codes: 0 ok, 1 findings, 2 usage or internal error. --json prints machine-readable output on read commands.
tg check [md|code-refs|index|sections] | Validate links (including source files and symbols), @lat: and @tg: references, require-code-mention coverage, directory index files and the 250-character leading-paragraph rule. |
tg locate <query> | Find sections by id, short id or fuzzy name. |
tg section <query> | Show a section with its links, what references it and the code that does. |
tg refs [--scope md|code|md+code] <query> | Sections and code that reference a section. |
tg expand <text> | Replace [[refs]] in text with full ids and locations. |
tg search [--limit n] [--lexical] <query> | Lexical ranking by default. With TG_EMBED_PROVIDER=ollama|openai or a key (TG_EMBED_KEY, or LAT_LLM_KEY) it fuses lexical and vector ranks. TG_EMBED_URL and TG_EMBED_MODEL pick the endpoint and model. Vectors are cached in .tg/; tg reindex rebuilds them. |
tg cypher [--code off|annotated|all] <query> | Read-only openCypher over the section graph: Section nodes (section, title, file, depth, summary), contains and references edges, Requirement and Scenario nodes from spec frameworks, and with --code CodeFile and CodeSymbol nodes; every property is listed in the query cheat sheet. Pattern predicates such as WHERE NOT ()-[:x]->(s) are not supported; use OPTIONAL MATCH with a count. |
tg edges [--type t] [--to s] [--file f] | List annotation edges from code to sections. |
tg gen <target> | Print agents.md, claude.md, cursor-rules.md, skill.md or graph-skill.md. |
tg init, tg hook, tg mcp | See Agents and hooks. |
tg export, tg import, tg schema | See Export and import. |
tg migrate [dir] [--dry-run] [--json] [--infer] [--keep-lat] [--no-setup] [--no-since] [--force] | Migrate a lat.md project to an ontology-aware tg project: swap the agent setup (as tg init --migrate), type docs files by their path or SHALL content, turn each plain link whose sentence names a relation into a typed edge line (candidates come from the ontology in Types/; --infer also applies a single candidate without a cue word), add the properties the edge type declares (since from git, strength from MUST or should, level from test paths), and upgrade @lat: comments to @tg: implements:: or verifies::. Writes by default, refuses files with uncommitted changes unless --force, and lists every link left plain with its sentence and candidates; the tg-migrate skill resolves those. |
tg ontology [check] [--schema-folder Types] [--json] | List the project's ontology: every type in Types/ with its properties and allowed edges, every edge type with its endpoints and properties. check reports typed edges in docs and code whose name is not declared (with a did-you-mean), whose source or target type is not allowed, or whose properties are undeclared or out of range, and exits 1 on findings. Also the MCP tool tg_ontology. |
tg validate [--vault dir] [--schema-folder Types] [--only codes] [--ignore codes] [--schema-only] [--frontmatter-edges] [--strict] [--format text|json|sarif] | Validate a vault against its schema notes without Obsidian, with the same findings as the plugin's diagnostics list: edge syntax, schema declarations, required properties and edges, edge endpoints, style values and edge embeds. Every finding has a stable code (the TGS diagnostic names, edge-syntax, style, embed). Declaration problems are errors and everything else warnings; exit 1 on errors, or on any finding with --strict. --schema-only checks just the schema notes, --frontmatter-edges reads links in frontmatter properties as edges, and --format sarif writes SARIF 2.1.0 for GitHub code scanning. See CI. |
tg okf check [dir] | Check any folder against Open Knowledge Format v0.2 conformance: concepts need parseable frontmatter with a string type, index files no frontmatter (except okf_version at the root), log date headings YYYY-MM-DD. Broken links, wikilinks and missing descriptions are warnings. Exit 1 only on errors. |
Validating in CI
A GitHub Actions job that fails on schema errors and shows every finding as a code scanning annotation:
- run: npx -y @typedgraph/cli validate --format sarif > tg.sarif || true
- uses: github/codeql-action/upload-sarif@v3
with: { sarif_file: tg.sarif }
- run: npx -y @typedgraph/cli validate --strict # or drop --strict to fail on errors only
For a pre-commit hook, tg validate --schema-only checks only the schema notes and is fast on any vault size.
Annotations in code
Two comment forms link code to docs, in //, # and block comments:
// @lat: [[auth#Token expiry]] a plain reference
// @tg: implements:: [[auth#Token expiry]] {since: 2} a typed edge
// @tg: -contradicts:: [[design#Stateless sessions]] a negative edge
// @tg: implements:: [[a#X]], tests:: [[b#Y]] several edges
// @tg: [[a#X]] same as @lat:
@lat: follows lat.md's exact pattern (a // or # comment and one link). @tg: uses the same type:: [[Target]] {props} grammar as notes, so signs, properties and several edges work as they do there. The edge starts at the declaration that follows the comment within three lines (a class member is Class#member); otherwise it belongs to the file and tg check warns. A schema note's edges list gives advisory checks on edge types.
Source links in docs, [[src/server.ts#App#listen]], are checked against the file. Supported: TypeScript and JavaScript (.ts .tsx .js .jsx .mts .cts .mjs .cjs), Python, Go, Rust and C (.c .h). Symbols are found with regex finders, so a file whose strings or braces do not balance, or a class written on one line, is reported as "cannot tell" and never as a missing symbol.
Code in the graph
Source files and symbols can appear as derived CodeFile and CodeSymbol nodes, keyed by path and path#Class#method, with contains edges and the annotation edges. They are built in memory and never written to disk or to your vault.
- Modes.
off(the plugin default),annotated(the CLI default: annotated symbols, what annotations point at, and their files) andall. In the CLI use--codeorTG_CODE. - In Obsidian. Settings → Code in the graph and Code folder, or the Code dropdown in the Graph view. A
graph-queryheader linecode: hideremoves code nodes from one block. Code nodes have their own shapes and colors, below any style you configure. - Links agree with nodes.
[[src/auth.ts#login]]in a note ends at theCodeSymbolnode, never at a stub.
Agents and hooks
tg init [--agent claude,codex,cursor,github-copilot,opencode,kilocode,pi,oh-my-pi,agents] [--only|--skip instructions,hooks,skills,specs,ontology] [--spec openspec,speckit,kiro,bmad,gsd,adr|none] [--install-spec] [--docs lat.md|tg.md] [--dry-run] [--yes] [--migrate]sets a project up for your coding agents and writes the files, listing each one it created or updated. In a terminal it is a short setup first: tick the agents (the ones it detects, including those OpenSpec set up, come ticked), what to set up or update, and your spec frameworks; for a framework you tick that is not set up yet it offers to run the framework's own installer. In scripts and CI it asks nothing and uses the detected agents and every part;--yesskips the questions in a terminal too.--dry-runonly prints the diff of what it would change.--writeis still accepted for older scripts and changes nothing.- instructions: a block between
%% tg:begin %%markers inCLAUDE.md(Claude Code) orAGENTS.md(Codex, GitHub Copilot, OpenCode, Kilo Code, Pi, Oh My Pi, other agents), or.cursor/rules/tg.mdc. - hooks: Claude Code hooks in
.claude/settings.jsonand thetgMCP server in.mcp.json. - skills:
tg-docs(maintain lat.md),tg-graph(Cypher over the graph),tg-trace(link spec requirements and ADRs to code, tests and docs),tg-impact(what a code change touches) andtg-audit(audit specs against code), in each agent's skills folder:.claude/skills,.agents/skills,.cursor/skills,.github/skills,.opencode/skills,.kilocode/skills,.pi/skillsor.omp/skills. - specs (formerly
openspec, still accepted): choose your spec frameworks (OpenSpec, Spec Kit, Kiro-style specs, BMAD, Get Shit Done, ADRs) with--specor the checklist, and install the missing ones with--install-specor by picking an installer in the terminal. Each framework's stage skills and commands (speckit-implement,kiro-spec-tasks, …) get a tg block written with that framework's ids; Kiro gets.kiro/steering/tg.md; ADRs without a folder getdocs/adr/0001-record-architecture-decisions.mdand a template. For OpenSpec, its propose, apply, archive and explore skills (and/opsxcommands) get a<!-- tg:begin -->block with the tg steps for that stage, andopenspec/config.yamlgetstg:rules that make every generated task list annotate code withimplements, tests withverifies, list the capability in the lat.md docs'openspec:frontmatter and end withtg checkandtg trace. Your own rules and comments are kept; re-running afteropenspec updaterestores the blocks. - ontology:
lat.md/code-ontology.md, the schemaTypes/code-types.mdand a template per type inTemplates/, so New Typed Note in Obsidian or VS Code creates a Decision or Requirement ready to fill in, plusTypes/spec-types.mdwith the types of the chosen spec frameworks (UserStory,AcceptanceCriterion,ADR, …), rewritten on every run.
lat.md/(compatible with thelatcommand) ortg.md/. An existinglat.md/is always used; in a project with neither,tg initasks which to create, or takes--docs lat.md|tg.md, and every command, hook and installed instruction then uses that folder. An existing lat.md block is replaced only with--migrate, which also swaps thelat hookcommands and thelatMCP entry.--no-openspec,--no-ontologyand--skills-onlystill work.- instructions: a block between
tg hook claude UserPromptSubmit|Stopandtg hook cursor stopare called by the agent. The prompt hook reminds it to search first, expands[[refs]]in your prompt and adds the top lexical hits. The stop hook blocks finishing whentg checkfails or five or more code lines changed with little change inlat.md/. Hooks always exit 0.tg mcpservestg_locate,tg_section,tg_search,tg_expand,tg_check,tg_refs,tg_cypherandtg_edgesover stdio:claude mcp add tg -- tg mcp.
Export and import
tg export <out> [--vault dir] [--folder sub] [--force]writes vault notes under<out>/lat.md/. Typed edges becometype: [[link]], property blocks are dropped,{{edge: …}}embeds become their value, notes get a level-1 heading and directory index files if missing, and links to notes outside the export become plain text. It then runs the normal check and prints a loss report. Round trips are not guaranteed. It refuses a non-empty target without--force.tg export <out> --format okf [--default-type T] [--title T]writes an Open Knowledge Format bundle at<out>/instead. Wikilinks become bundle-absolute markdown links, and typed edge lines keep their type, sign and properties (knows:: [Bob](/People/Bob.md) {since: 2020}), so Typed Graph reads the bundle back into the same graph. Every concept gets a stringtype(defaultNote), plus atitleanddescriptionif missing. Notes namedindex.mdorlog.mdare renamed, embedded attachments are copied, and every folder gets anindex.md. The command prints a change report and verifies the result withtg okf check.tg import <path> [--mount] [--into name]copies alat.md/folder (or the one inside a project) into the current vault or project, or symlinks it with--mount. It refuses a non-empty destination and never changes the source.tg schema export <out.ttl> [--vault dir] [--schema-folder Types] [--base iri]writes every type and edge type in the schema folder as W3C SHACL shapes in Turtle, following the TGS mapping. The output is deterministic, so it diffs cleanly.tg schema import <file.ttl> [--layout auto|per-type|single] [--into name] [--force]turns SHACL shapes into schema notes: one note per type by default, or all of them in one note. It rewrites only the schema keys of existing notes, leaves alone notes that also declare types missing from the file (unless--force), and prints a drop report of SHACL features outside the TGS subset.
In Obsidian, notes under a lat.md/ folder get working [[file#Heading#Sub]] links and show link and section problems in the diagnostics list. Files are not modified.
Settings
| Maximum graph elements | Above this, graphs show as tables. |
| Maximum path depth | Cap for unbounded * patterns (default 10). |
| Default query backend, Sidecar URL, Sidecar token | For backend: ladybug. |
| Schema folder, Show diagnostics | Type schemas and the issue counter. |
| Type styles, Edge styles | JSON style defaults. |
| Refresh delay | Debounce before blocks re-run. |
| Code in the graph, Code folder | Show source symbols as nodes (off, annotated, all) and which vault folder to scan. |
| AsciiDoc notes | Index .adoc files as notes (on by default). |
FAQ
Does it change my notes?
No. The plugin and the sidecar only read notes. Only New typed note and its child, sibling and top-level variants, Create schema note and Import SHACL shapes write files, on request; the import changes only the schema keys of notes in the schema folder.
Do I need Graph Link Types or Dataview?
No. Typed Graph reads the same type:: [[Target]] lines on its own.
Does my vault leave my machine?
Not by default. Embeddings use local Ollama; a hosted endpoint is only used if you configure one.