Skip to main content

Workspace paths and semantic indexing

Primary folder vs extra read roots​

  • Primary local path is your main workspace. The agent can read files there, and semantic search (search_indexed_docs) indexes this tree in the background (subject to file-type and size limits).
  • Extra read roots (one path per line under Workspace) extend read, grep, and terminal access to additional directories. Writes still stay under the primary path.

By default, extra roots are not embedded: they are for on-demand tools only.

Indexing extra paths for search (opt-in)​

Enable “Also index extra paths for semantic search” when you want search_indexed_docs to include those folders alongside the primary workspace—for example, a large reference repo on your Desktop you want to compare without switching the primary folder.

Notes:

  • Embedding large trees can take time and uses your embedding provider; grep and read_text_file stay the best options when you need immediate coverage.
  • At most 16 roots participate in a single semantic search (primary + extras, in order).
  • Chat attachments only accept individual files (images, PDFs, text/code). Dropping a whole folder does not attach it; with a local workspace set, a native folder drop can add that path as an extra root and turn on indexing when the app has filesystem paths on dropped files.

File attachments vs workspace​

Attachments are for small artifacts in the message. They do not replace workspace scope and do not drive the doc index.

@search path picker (chat input)​

In the AI input, type @search or @search/ plus a path fragment (same idea as the workspace path search). Matching folders and files appear in the suggestion list—no need to paste full paths into “Extra read roots” by hand.

  • Folder: adds that directory as an extra read root and turns on semantic indexing for extra paths (same as a folder drop).
  • File: adds the parent folder as an extra read root (indexed) and injects a one-shot note on the next message so the model knows which file you picked.

You still need a local primary workspace set first; @search only attaches reference paths on top of it.