SDK API Reference / WorkspaceSDK

Class: WorkspaceSDK

WorkspaceSDK — manages workspace documents, git, and wiki-links

Constructors

Constructor

new WorkspaceSDK(workspacePath): WorkspaceSDK

Parameters

workspacePath

string

Returns

WorkspaceSDK

Properties

workspacePath

readonly workspacePath: string

Methods

buildFileIndex()

buildFileIndex(): Map<string, FileIndexEntry[]>

Build file index for wiki-link resolution (cached per SDK instance)

Returns

Map<string, FileIndexEntry[]>

---

commitAll()

commitAll(message?): void

Commit all uncommitted workspace changes (external edits, moves, etc.)

Parameters

message?

string

Returns

void

---

createDocument()

createDocument(opts): WorkspaceDocument<ItemFrontmatter>

Create a new document

Parameters

opts

CreateDocumentOptions

Returns

WorkspaceDocument<ItemFrontmatter>

---

createFromTemplate()

createFromTemplate(templateName, overrides): WorkspaceDocument<ItemFrontmatter>

Parameters

templateName

string

overrides

CreateDocumentOptions

Returns

WorkspaceDocument<ItemFrontmatter>

---

fileHistory()

fileHistory(filePath, limit?): object[]

Get git history for a document

Parameters

filePath

string

limit?

number = 10

Returns

object[]

---

flushGit()

flushGit(): void

Flush pending git commits

Returns

void

---

getAcceptedGuides()

getAcceptedGuides(): WorkspaceDocument<GuideFrontmatter>[]

Get accepted guides (for injection into agent context)

Returns

WorkspaceDocument<GuideFrontmatter>[]

---

getBacklinks()

getBacklinks(fileName): object[]

Get backlinks to a document

Parameters

fileName

string

Returns

object[]

---

getConfig()

getConfig(): WorkspaceConfig | null

Returns

WorkspaceConfig | null

---

getCurrentBranch()

getCurrentBranch(): string

Returns

string

---

getGitRemoteUrl()

getGitRemoteUrl(name?): string | null

Parameters

name?

string

Returns

string | null

---

getGoalNextTask()

getGoalNextTask(goalFileNameOrPath): WorkspaceDocument<ItemFrontmatter> | null

Get the next actionable item for a goal

Parameters

goalFileNameOrPath

string

Returns

WorkspaceDocument<ItemFrontmatter> | null

---

getGoalProgress()

getGoalProgress(goalFileNameOrPath, opts?): GoalProgressResult

Get goal progress by checking linked item statuses.

When opts.includeTransitiveDeps is true, performs BFS graph traversal through item wiki-links to discover items not directly linked to the goal.

Parameters

goalFileNameOrPath

string

opts?

GoalProgressOptions

Returns

GoalProgressResult

---

getName()

getName(): string

Returns

string

---

getRecentDocuments()

getRecentDocuments(limit?): string[]

Return the most recently accessed document fileNames, newest first

Parameters

limit?

number = 20

Returns

string[]

---

getSummary()

getSummary(filter?): object

Get workspace summary for display

Parameters

filter?

ScanFilter

Returns

object

goals

goals: object[]

name

name: string

path

path: string

taskCounts

taskCounts: Record<string, number>

---

getTasksByStatus()

getTasksByStatus(filter?): TasksByStatusResult

Get items grouped by status

Parameters

filter?

ScanFilter

Returns

TasksByStatusResult

---

gitPull()

gitPull(opts?): string

Parameters

opts?

branch?

string

remote?

string

token?

string

Returns

string

---

gitPush()

gitPush(opts?): string

Parameters

opts?

branch?

string

remote?

string

token?

string

Returns

string

---

init()

init(name?): void

Initialize a new workspace (create folders, tdx.json, CLAUDE.md, git init)

Parameters

name?

string

Returns

void

---

listTemplates()

listTemplates(kind?): WorkspaceDocument<TemplateFrontmatter>[]

Parameters

kind?

DocumentKind

Returns

WorkspaceDocument<TemplateFrontmatter>[]

---

logDocumentAccess()

logDocumentAccess(fileName): void

Record a document access event in the workspace access log

Parameters

fileName

string

Returns

void

---

moveTask()

moveTask(fileNameOrPath, status): WorkspaceDocument<ItemFrontmatter> | null

Move an item to a new status

Parameters

fileNameOrPath

string

status

TaskStatus

Returns

WorkspaceDocument<ItemFrontmatter> | null

---

readDocument()

readDocument<T>(filePathOrName): WorkspaceDocument<T> | null

Read a single document by path or filename

Type Parameters

T

T = Record<string, unknown>

Parameters

filePathOrName

string

Returns

WorkspaceDocument<T> | null

---

removeGitRemote()

removeGitRemote(name?): void

Parameters

name?

string

Returns

void

---

renameDocument()

renameDocument(filePathOrName, newSlug): RenameDocumentResult | null

Rename a document and update all wiki-link backlinks across the workspace.

Parameters

filePathOrName

string

Current file path, name, or stem

newSlug

string

New slug for the file (date prefix preserved automatically)

Returns

RenameDocumentResult | null

Rename result with old/new paths and list of updated backlink files, or null if not found

---

resolveWikiLinks()

resolveWikiLinks(body): ResolvedWikiLink[]

Resolve wiki-links in a document body

Parameters

body

string

Returns

ResolvedWikiLink[]

---

scanDocuments()

scanDocuments<T>(kind): WorkspaceDocument<T>[]

Scan documents of a specific kind

Type Parameters

T

T = Record<string, unknown>

Parameters

kind

DocumentKind

Returns

WorkspaceDocument<T>[]

---

scanKnowledge()

scanKnowledge(filter?): WorkspaceDocument<Record<string, unknown>>[]

Search across knowledge documents (notes, guides, references)

Parameters

filter?

accessedWithin?

number

kinds?

DocumentKind[]

query?

string

tags?

string[]

Returns

WorkspaceDocument<Record<string, unknown>>[]

---

scanTasks()

scanTasks(filter?): WorkspaceDocument<ItemFrontmatter>[]

Scan items/goals with optional filters

Parameters

filter?

ScanFilter

Returns

WorkspaceDocument<ItemFrontmatter>[]

---

setGitRemote()

setGitRemote(url, name?): void

Parameters

url

string

name?

string

Returns

void

---

setName()

setName(newName): void

Rename this workspace by updating tdx.json and committing the change.

Parameters

newName

string

Returns

void

---

updateDocument()

updateDocument(filePathOrName, updates): WorkspaceDocument<Record<string, unknown>> | null

Update a document's frontmatter and/or body

Parameters

filePathOrName

string

updates

body?

string

frontmatter?

Record<string, unknown>

Returns

WorkspaceDocument<Record<string, unknown>> | null

---

initAt()

static initAt(name, options?): WorkspaceSDK

Initialize a workspace at a standard location

Parameters

name

string

options?

github?

string

Returns

WorkspaceSDK

---

listWorkspaces()

static listWorkspaces(): WorkspaceListEntry[]

List all available workspaces under the default work root.

Returns

WorkspaceListEntry[]