/hq-cowork-files — Inspect HQ vault objects from a sandboxed agent

Reads vault objects on demand from inside Cowork, where the hq CLI and the local sync index aren't reachable. Routes through the host-side MCP server.

Args: $ARGUMENTS — an action plus its target. Infer the action from intent if not explicit.

Action	Purpose	Needs
browse	List objects under a vault path	path optional (defaults to root)
cat	Stream one object to text	path required
acl	Show the access-control list for a prefix	path required
search	Match vault object keys by path/name (NOT content)	query (or path) required
shared-with-me	List grants made to you	—
get	Materialize a file/prefix into local HQ on the host	path required; into optional

Call the tool

{
  "action": "cat",
  "path": "companies/foo/knowledge/x.md",
  "company": "<slug>",     // omit to parse from path
  "personal": false,
  "into": "<dir>"          // action=get only
}

Call mcp__hq__hq_files. For search, pass the query as query (or path).

Notes

• search matches keys, not content. It's a path/name match over vault object keys — not full-text search. For content search use /hq-cowork-search (qmd), which is a different index.
• get writes to the host's local HQ, not into the sandbox. The sandboxed agent won't see the materialized files unless the mounted HQ folder is shared. Prefer cat to read content directly into the session.
• Cross-company isolation. company defaults to the slug parsed from the path; pass it explicitly when that's ambiguous. Never operate across a company boundary you weren't asked to.

When to use this instead of /hq-files

Only inside Cowork or another sandboxed plugin host. On a host-side session, prefer the unprefixed /hq-files (or hq files).

Why this skill exists

hq files authenticates with the user's Cognito session under ~/.hq and reads the cloud vault — neither is visible from Cowork's Linux VM. The host-side MCP server runs the real hq files <action> and returns output to the sandboxed agent.