How gcontext works

gcontext is a cloud workspace an AI agent connects to over MCP. One idea drives everything: structure lives in the cloud, execution stays on your machine.

In the cloud: a virtual filesystem of folders and markdown files (docs, tasks, integrations, scripts) plus the NAMES of your secrets. This is what every connected agent, on any machine, sees identically.
On your machine: script execution (tool_run_script, tool_run_shell) and secret VALUES (~/.gcontext/.env, chmod 0600; OS keychain opt-in). Values never leave the machine; tool output is scrubbed of them before the agent sees it.

The dashboard at the web app shows the same workspace visually: typed folders as buildings on a map, a Types page, a Secrets tab, and a Context page that shows exactly what the agent receives.

The filesystem

Plain absolute paths (/stripe/info.md). tool_write_file auto-creates parent folders; tool_delete removes a file or a whole folder recursively. _-prefixed paths are the system files:

Path	What it is
`/_types.md`	YOUR type definitions: every `##` heading is a folder type the agent follows. User-editable.
`/_docs/`	Platform docs (this file, typed-folders, scripts, secrets). Kept current by gcontext.
`/_components/`	Optional React renderers per type (`task.jsx`, `integration.jsx`) for the dashboard.
`/_commands/`	`<name>.md` + `<name>.py` pairs exposed to MCP clients as slash commands.
`/_playbook.md`	The user's "how we work" rules; `tool_overview(playbook=True)` returns it to answer "what's the best way to...".

Folders become visible, typed things on the dashboard only via frontmatter, see /_docs/typed-folders.md.

Reading efficiently (the read loop)

Context is the scarce resource. Locate first, then read narrowly:

tool_grep scoped with path_prefix or glob (regex if needed) to find WHERE.
tool_read_file with offset/limit to read just the matching region (a grep hit at line N + offset=N-1, limit=20 beats a whole-file read; partial reads return the total line count so you can follow up precisely).
Widen only if needed.

Supporting tools:

tool_glob("**/llms.txt") finds files by name in one call; * crosses folder boundaries.
tool_read_many([paths]) batches related files (info.md + module.yaml + task.md) in one round trip; a missing file never fails the batch.
tool_list_dir(path, depth=1..3) returns a subtree in one call; typed folders carry folder_type so you don't need a read just to learn what a folder is.
tool_overview() is a live snapshot: counts, path tree, which secrets are set. tool_overview(daily=True) digests recent activity: active work, folders going stale, missing secrets.

Never read whole files one by one to find something.

Secrets, scripts, commands

Each has its own doc, read on demand:

/_docs/secrets.md: NAMES registered in the cloud, VALUES filled locally (tool_secrets(action="register") then tool_setup_secrets), used in scripts via os.environ.
/_docs/scripts.md: writing and running Python locally with tool_run_script, the inline -> stored -> command promotion ladder, and slash-command conventions.

MCP surface beyond tools

Resources: every workspace file is an mcpfs:// resource; @-mention one in a client to load it into context directly.
Prompts: use_integration(name) loads an integration's doc + secret names; check_secrets verifies local values; daily_overview renders the digest. Every /_commands/<name>.md appears as the slash command /<name> (see /_docs/scripts.md).
Connect instructions: on connect the agent gets a short index (live counts + the doc list above), never the doc bodies. Push nothing, pull everything.

Conventions the agent should honor

Follow /_types.md templates exactly when creating typed folders (extra frontmatter fields are fine).
Check /_playbook.md (or call tool_overview(playbook=True)) before recommending a way of working; offer to record new rules there.
Keep docs you write skimmable: an info.md says what a thing is and how to ask for it, not an essay.