Native Desktop API

Direct, profile-bound HTTP bindings to a running Hermes Desktop server. Discover operations on the target server; mutations are not automatically retried.

Choose your client · Reliability · All public exports

AsyncHermesDesktop

AsyncHermesDesktop(
    http: AsyncClient,
    profile: str,
    *,
    token: str | None = None,
    owns_client: bool = False,
)

cron instance-attribute

cron = DesktopCron(self)

files instance-attribute

files = DesktopFiles(self)

git instance-attribute

git = DesktopGit(self)

skills instance-attribute

skills = DesktopSkills(self)

sessions instance-attribute

sessions = DesktopSessions(self)

plugins instance-attribute

plugins = DesktopPlugins(self)

remote classmethod

remote(
    *,
    base_url: str,
    profile: str,
    token: str | None = None,
    timeout: float = 30,
    http_client: AsyncClient | None = None,
) -> AsyncHermesDesktop

for_profile

for_profile(profile: str) -> AsyncHermesDesktop

capabilities async

capabilities() -> DesktopCapabilities

config async

config() -> dict[str, Any]

configure async

configure(updates: dict[str, Any]) -> Any

aclose async

aclose() -> None

DesktopCron

DesktopCron(client: AsyncHermesDesktop)

client instance-attribute

client = client

list async

list() -> list[CronJob]

get async

get(job_id: str) -> CronJob

create async

create(options: CronCreate) -> CronJob

Create through the native scheduler, including atomic paused creation.

pause async

pause(job_id: str) -> CronJob

resume async

resume(job_id: str) -> CronJob

remove async

remove(job_id: str) -> Any

update async

update(job_id: str, updates: CronUpdates) -> CronJob

trigger async

trigger(job_id: str, *, timeout: float = 86400) -> CronJob

runs async

runs(
    job_id: str, *, limit: int = 20
) -> builtins.list[dict[str, Any]]

delivery_targets async

delivery_targets() -> builtins.list[dict[str, Any]]

blueprints async

blueprints() -> builtins.list[dict[str, Any]]

instantiate async

instantiate(
    blueprint: str, values: dict[str, str]
) -> CronJob

DesktopFiles

DesktopFiles(client: AsyncHermesDesktop)

client instance-attribute

client = client

list async

list(path: str) -> dict[str, Any]

read_text async

read_text(path: str) -> dict[str, Any]

write_text async

write_text(path: str, content: str) -> dict[str, Any]

data_url async

data_url(path: str) -> dict[str, Any]

default_cwd async

default_cwd() -> dict[str, Any]

DesktopGit

DesktopGit(client: AsyncHermesDesktop)

client instance-attribute

client = client

status async

status(path: str) -> dict[str, Any] | None

review async

review(
    path: str,
    scope: Literal["uncommitted", "branch"],
    *,
    base: str | None = None,
) -> dict[str, Any]

diff async

diff(
    path: str,
    file: str,
    *,
    scope: str = "uncommitted",
    base: str | None = None,
    staged: bool = False,
) -> str

file_diff async

file_diff(path: str, file: str) -> str

Full file against HEAD, including staged and unstaged changes.

change async

change(
    action: Literal["stage", "unstage", "revert"],
    path: str,
    file: str | None = None,
) -> Any

commit async

commit(
    path: str, message: str, *, push: bool = False
) -> Any

push async

push(path: str) -> Any

create_pr async

create_pr(path: str) -> Any

branches async

branches(path: str) -> dict[str, Any]

switch async

switch(path: str, branch: str) -> Any

worktrees async

worktrees(path: str) -> DesktopWorktreeList

add_worktree async

add_worktree(
    path: str, options: DesktopWorktreeOptions
) -> dict[str, Any]

remove_worktree async

remove_worktree(
    path: str, worktree_path: str, *, force: bool = False
) -> Any

DesktopSkills

DesktopSkills(client: AsyncHermesDesktop)

client instance-attribute

client = client

list async

list() -> builtins.list[DesktopSkill]

content async

content(name: str) -> SkillContent

save async

save(name: str, content: str) -> Any

create async

create(
    name: str, content: str, *, category: str | None = None
) -> dict[str, Any]

toggle async

toggle(name: str, enabled: bool) -> dict[str, Any]

official async

official() -> builtins.list[HubSkill]

sources async

sources() -> dict[str, Any]

search async

search(
    query: str, *, source: str = "all", limit: int = 20
) -> HubSearch

preview async

preview(identifier: str) -> HubSkill

scan async

scan(identifier: str) -> HubScan

install async

install(identifier: str) -> SkillProcessReceipt

Start the native installer. This receipt is not installation success.

uninstall async

uninstall(name: str) -> SkillProcessReceipt

update async

update() -> SkillProcessReceipt

Hermes's update operation updates installed Hub skills as a batch.

DesktopSessions

DesktopSessions(client: AsyncHermesDesktop)

client instance-attribute

client = client

messages async

messages(
    session_id: str,
    *,
    limit: int = 100,
    order: Literal["latest", "oldest"] = "latest",
) -> dict[str, Any]

DesktopPlugins

DesktopPlugins(client: AsyncHermesDesktop)

client instance-attribute

client = client

catalog async

catalog(
    *, capabilities: DesktopCapabilities | None = None
) -> NativePluginCatalogResponse

Read the complete native catalog, including recalled-entry metadata.

Discover the exact REST operation first, or supply a discovery snapshot from this owning deployment. Discovery/auth/network failures propagate; a missing operation is unsupported, not an empty catalog. This performs no installation and never retries a failed request.

Although the HTTP client sends its profile, this existing native route does not scope installed-state annotations to that query parameter. Discard installed/installed_sha/update_available/runtime_status and join the exact profile's RPC inventory before presenting installed state.