Start with ctxindex
Install ctxindex, index one local file without an Account, and return a useful result.
ctxindex gives shell-capable agents one local, typed interface over mail, calendars, files, and Extension-defined context. The shortest trustworthy path starts with a local directory: no Account, OAuth flow, or provider traffic.
ctxindex requires Bun 1.3.14. The CLI is published as ctxindex; Extension authors use @ctxindex/extension-sdk and @ctxindex/profiles.
bun add --global ctxindex
ctxindex --helpgit clone https://github.com/barisgit/ctxindex.git
cd ctxindex
bun install
bun cli --helpReplace ctxindex with bun cli in the remaining commands.
Create local context
Create one file and initialize local state.
mkdir -p "$HOME/context"
printf 'Project Aurora kickoff is Tuesday at 10:00.\nOwner: Maya Chen.\n' \
> "$HOME/context/aurora.txt"
ctxindex initCreate a Realm, then connect the directory as one Source.
ctxindex realm add work --name "Work"
ctxindex source add local.directory \
--realm work \
--label work-files \
--config-root-path "$HOME/context"Materialize the Source and search it.
ctxindex sync --source work-files --format json
ctxindex search "Aurora kickoff" \
--realm work \
--kind file \
--local-only \
--format jsonA successful search returns a stable Ref in a bounded result envelope:
{
"results": [
{
"ref": "ctx://01J00000000000000000000000/file/aurora.txt",
"profile": { "id": "file", "version": 1 },
"sourceId": "01J00000000000000000000000",
"origin": "local",
"title": "aurora.txt"
}
],
"warnings": [],
"pagination": { "offset": 0, "limit": 20, "hasMore": false }
}Pass the returned Ref through unchanged:
ctxindex get 'ctx://01J00000000000000000000000/file/aurora.txt' --format json
ctxindex export 'ctx://01J00000000000000000000000/file/aurora.txt' --format jsonDo not reconstruct provider-owned Ref suffixes. Copy the Ref returned by ctxindex.