file-attributes

name: file-attributes
description: read sublimated metadata from local files via extended attributes — version, author, commit hash, AI attribution

read sublimated metadata directly from local files via macOS extended attributes. no API calls needed — version, author, commit hash, and AI attribution are available on every synced file.

reading xattrs

every file synced via sublimated's FileProvider carries metadata as extended attributes. read them with xattr -p:

# web URL for the file
xattr -p "com.sublimated.url#PS" README.md
# → sublimated.com/anton/blog/readme_md


# item ID (stable across renames/moves)
xattr -p "com.sublimated.id#PS" README.md
# → itm_01JQXYZ...


# current version number
xattr -p "com.sublimated.version#PS" README.md
# → 42


# BLAKE3 content hash
xattr -p "com.sublimated.content-hash#PS" README.md
# → blake3-a1b2c3d4...


# who created this file
xattr -p "com.sublimated.created-by#PS" README.md
# → Alice


# who last modified this file
xattr -p "com.sublimated.modified-by#PS" README.md
# → Bob


# what kind of actor last modified it
xattr -p "com.sublimated.modified-by-type#PS" README.md
# → person


# last commit hash
xattr -p "com.sublimated.commit#PS" README.md
# → abc123def456

xattr reference

xattr key (with flag suffix)	value	notes
`com.sublimated.url#PS`	web link	`sublimated.com/{space}/{path}`
`com.sublimated.id#PS`	item ID	stable across renames
`com.sublimated.version#PS`	version number	integer, increments on each edit
`com.sublimated.content-hash#PS`	BLAKE3 hash	files only, nil for folders
`com.sublimated.created-by#PS`	author name	who created the file
`com.sublimated.modified-by#PS`	author name	who last edited the file
`com.sublimated.modified-by-type#PS`	actor type	`person`, `ai_agent`, or `bot`
`com.sublimated.commit#PS`	commit hash	last commit that touched this file

modified-by-type values

person — human user editing via Finder, CLI, or web
ai_agent — AI assistant (Claude, GPT, etc) editing via API or MCP
bot — automated system (CI, sync, transform)

use this to determine if a file was last touched by a human or AI. useful for:

audit trails ("who wrote this code?")
trust scoring ("is this AI-generated?")
workflow routing ("send human-written files to review, auto-approve bot changes")

reading from filesystem (Finder → server)

sublimated reads two macOS metadata attributes from synced files and stores them server-side:

filesystem xattr	server key	table	notes
`com.apple.metadata:kMDItemFinderComment`	`finder_comment`	item_text_attrs	Finder "Get Info" comment
`com.apple.metadata:kMDItemKeywords`	`spotlight_keywords`	item_json_attrs	Spotlight keywords array

set a Finder comment via Get Info (Cmd+I) or:

xattr -w com.apple.metadata:kMDItemFinderComment "$(python3 -c "import plistlib; import sys; sys.stdout.buffer.write(plistlib.dumps('my comment'))")" README.md

platform notes

xattrs are macOS-only (FileProvider). on Linux/Windows, same data is accessible via the API and git
the #PS suffix is added by xattr_name_with_flags() — it means SYNCABLE + NO_EXPORT
folders get all xattrs except content-hash (folders have no content hash)
xattrs are set by the FileProvider extension, not by scripts — they appear automatically on synced files