Browse context like a filesystem

Examine a workspace with ls, tree, grep, and cat through the CLI, the API, or MCP.

Coding agents work best with filesystem commands. They list a directory, grep for a string, and read a file. Orcha mounts each workspace as a read-only virtual filesystem, so that agents and people can examine context in this way. This path has the same authorization, citations, and usage analytics as all other access paths. This path cannot write. The shell has no write commands.

The virtual tree

Path	Contents
`/README.md`	A file that tells what is mounted
`/files`	Workspace files and folders
`/memories`	Curated memories. Each memory has a README with `useWhen` guidance, its file members, and pointers to its folder, synced-document, and database members
`/databases`	Structured databases. Each record shows as a markdown file, with the fields first and then the page body
`/sources`	Connected read-only sources. Documents have provider citations

A folder-scoped token sees only a reduced /files tree. Paths outside the scope do not exist. Orcha does not mount soft-deleted content.

Three ways in

CLI (best for people, coding agents, and CI):

npm install -g @tryorcha/cli
orcha login                          # or: export ORCHA_TOKEN=orca_...
 
orcha cat /README.md
orcha ls -l /files
orcha tree -L 2 /files
orcha exec "rg -i 'rate limit' /files | head -20"
orcha stat /files/Guides/api.md      # entity id, deep link, citation, freshness
orcha search "how do we enforce plan limits"

orcha agent-setup prints a snippet for CLAUDE.md or AGENTS.md. The snippet teaches an agent the layout and the commands. orcha status shows the credentials and the workspace that the CLI uses. Two global flags work before or after each subcommand. --cite adds citations to the output. --json returns the raw response. The CLI reference lists each command, flag, and exit code.

REST (any HTTP client):

curl -X POST https://app.tryorcha.com/api/v1/vfs/exec \
  -H "Authorization: Bearer orca_your_token" \
  -H "Content-Type: application/json" \
  -d '{"script": "rg -i \"rate limit\" /files | head -20"}'

MCP: the browse_context tool accepts the same script argument. Thus agents that connect over MCP get the same behavior without shell access.

The command set

pwd, cd, ls [-l], tree [-L n], find [-name glob] [-type f|d] [-maxdepth n], cat [-n], grep/rg (-i, -n, -l, -r, -F), head/tail [-n N], wc [-l|-w|-c], stat, help.

Use | to pipe output. grep, rg, head, tail, and wc accept piped input. Use ; or && to chain commands.

rg is recursive and shows line numbers by default. grep needs -r to go into directories. ls -l shows sizes, update dates, and useWhen hints. Memories and folders use these hints to tell an agent when they are relevant.

Orcha runs scripts in its own restricted parser, and not in a real shell. Orcha rejects redirection (>), substitution (`, $(...)), and unknown commands.

Citations and budgets

Each response has a citation for each file that has returned content. The citation has the path, entity type and ID, title, deep link, and freshness. stat <path> shows the same data for one node. When you quote content, also give its citation.

Each execution has a scan budget and an output limit. The scan budget limits the files opened, bytes read, nodes visited, and wall clock time. If a limit stops the execution, the output tells you. Orcha does not silently return partial results. To stay in the limit, use a narrower path, add -maxdepth, or pipe through head. Failures are also machine-readable. The response has a bash-style failed status, and the CLI exits with a non-zero code.

When to browse and when to search

Use browse commands (ls, tree, find, rg, cat) for structural questions. Examples are what exists, where an item is, and which files contain an exact string. Use search (orcha search, search_context) for semantic questions. Search gives ranked, fused retrieval. The two methods work together. A typical agent makes one search_context call to find the correct area. Then it uses browse commands to read the exact content.