Browse context like a filesystem

Coding agents are at their best with filesystem verbs: list a directory, grep for a string, read a file. Orcha mounts every workspace as a read-only virtual filesystem so agents (and you) can explore context that way, with the same authorization, citations, and usage analytics as every other access path. Nothing here can write; the shell has no write commands at all.

The virtual tree

Folder-scoped tokens see a pruned /files tree only. Out-of-scope paths do not exist, and soft-deleted content is never mounted.

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 that teaches an agent the layout and commands. orcha status shows which credentials and workspace are in play, and two global flags work before or after any subcommand: --cite appends citations to the output, --json returns the raw response.

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 takes the same script argument, so MCP-connected agents get identical semantics 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. Pipe with | (grep, rg, head, tail, wc accept piped input) and chain with ; or &&.

rg is recursive with line numbers by default; grep needs -r to descend into directories. ls -l shows sizes, updated dates, and useWhen hints, which is how bundles and folders tell an agent when they are relevant.

Scripts run in Orcha's own restricted parser, never a real shell. Redirection (>), substitution (`, $(...)), and unknown commands are rejected outright.

Citations and budgets

Every response includes a citation for each file whose content was returned: path, entity type and ID, title, deep link, and freshness. stat <path> shows the same for any single node. Quote content with its citation.

Each execution is bounded by a scan budget (files opened, bytes read, nodes visited, wall clock) and an output cap. When a limit trips, the output says so explicitly instead of returning silently partial results; narrow the path, add -maxdepth, or pipe through head. Failures are machine-readable too: the response carries a bash-style failed status and the CLI exits non-zero on it.

When to browse and when to search

Browse (ls, tree, find, rg, cat) answers structural questions: what exists, where something lives, which files contain an exact string. Search (orcha search, search_context) answers semantic questions with ranked, fused retrieval. They complement each other; a common agent loop is one search_context call to land in the right area, then browse commands to read precisely.