Chataway Developers
Concepts

Folders, files & "Open with"

Work on the user's files in place — a folder the user grants, one file they open with your app, or your own storage — with versions, conflict checks, backups, change events and an "Open in …" entry in the Files panel.

A store app can't see the project. With app API 4 it can ask for a folder in it — each one it declares, up to five — and work on the files there from its panel: list, read, write, rename, trash and watch. The user decides whether to allow it, and can take it back at any time. A user can also open one file with your app from the Files panel.

Your panel never gets a path on disk. Every call names a root and a path inside it.

RootWhat it isHow you get it
folder:<id>A folder from your contributes.folders, in the chat's workspaceThe user allows it after app.folders.request(id)
file:<handle>One file the user opened with your appThe user clicks Open in … in the Files panel
storageYour app's own storage in this projectAlways yours

#Declare a folder

plugin.json
json
{
  "requires": { "hostApi": 4 },
  "grants": ["folders"],
  "permissions": ["Open and save the notes in the folder you choose (Markdown files only)"],
  "contributes": {
    "folders": [{
      "id": "notes",
      "label": "Notes",
      "suggested": "notes/",
      "extensions": [".md"],
      "access": "readwrite",
      "reason": "Sketch Notes opens and saves your notes here."
    }]
  }
}
FieldRules
idA lowercase letter, then lowercase letters, digits or _ (≤ 48). Unique.
label≤ 40 characters.
suggestedA relative folder in the workspace (notes/). No .., no hidden folders. This is the folder the user allows; Chataway creates it if it's missing.
extensions1–20 lowercase extensions with the dot (.md, .excalidraw). Your app sees only these files.
accessread or readwrite.
reason10–200 characters. Shown when you ask. Say what you read and what you write.

Up to 5 folders. contributes.folders needs the folders grant and requires.hostApi ≥ 4. Adding a folder in an update, or widening its access or file types, needs human review and the user's consent again.

#Ask for it

ts
import { connect, folderRoot } from '@chataway/apps/bridge';

const app = await connect();
const [notes] = await app.folders.list();       // { id, label, …, granted: { path, at } | null }

grantButton.onclick = async () => {
  const r = await app.folders.request('notes');  // from a click
  if (r.granted) render(r.root!);                // 'folder:notes'
};
if (notes.granted) render(folderRoot('notes'));

folders.request must run inside a click or key handler in your panel (click only); otherwise it fails with needs-gesture. Chataway asks "Let Sketch Notes read and edit files in notes/?" ("read files in" for access: "read") with your reason and file types, and the user picks Allow or Don't allow. Allow grants the suggested folder. The answer is { granted: true, root, path }, or { granted: false } when the user says no. path is for display only. A folder that is already granted in this workspace answers at once, without asking — unless an update changed it from read to readwrite: then the user is asked again, and Allow upgrades the grant.

A grant belongs to the workspace it was given in. A standalone chat has its own workspace, so there your app asks again (folders.list shows granted: null), and allowing it there moves the grant. app.folders.revoke(id) gives it back; the user can also remove it on your app's page in Apps. Switching your app off in a project, or uninstalling it, forgets its folder grants and open files there — it asks again next time.

#Read and write

ts
const root = folderRoot('notes');
const { entries, truncated } = await app.fs.list({ root, recursive: true });
const note = await app.fs.read({ root, path: 'ideas.md' });     // { path, mime, size, version, text }
await app.fs.write({ root, path: 'ideas.md', text: note.text + '\n- one more', ifVersion: note.version });
MethodParamsResult
fs.list{ root, path?, recursive? }{ entries: [{ path, name, kind, size, mtime, version? }], truncated } — up to 2000 entries
fs.read{ root, path, as? }{ path, mime, size, version, text?, data? } — without as, text files come back as text and others as base64 data; as: 'text' or 'base64' picks
fs.write{ root, path, text? | data?, ifVersion? }{ path, version } — data is base64, a Uint8Array, an ArrayBuffer or a Blob
fs.rename{ root, from, to }{ path, version? } — files and folders; version for a file
fs.trash{ root, path }{ trashed } — needs a click; Chataway asks the user, and a no is cancelled
fs.restore{ root, path }{ path, version }
fs.watch / fs.unwatchroot{ watching }
fs.onChangeroot, handlerA function that stops watching

Paths are relative to the root, with / separators. '' is the root itself. A file: root has one file, at path ''. Folders are created as needed when you write. mtime is in milliseconds.

A file's version is the first 16 hex characters of the SHA-256 of its bytes. fs.read and fs.write always give it. fs.list gives it for files up to 1 MB, and for at most 200 files per listing — read a file to get the version of a bigger one.

recursive: true goes 20 levels deep and doesn't go into folders whose name starts with . or into node_modules (they are listed, not entered).

#Conflicts

The user, their chat agent or another window may change a file while your panel has it open. Pass the version you read as ifVersion, and Chataway refuses a write over someone else's change:

ts
import { BridgeError } from '@chataway/apps/bridge';

try {
  await app.fs.write({ root, path, text, ifVersion: loaded.version });
} catch (e) {
  if (e instanceof BridgeError && e.code === 'conflict') {
    // e.details.current = the version on disk now (null if the file is gone)
    return askReloadOrOverwrite();
  }
  throw e;
}
ifVersionMeans
a versionWrite only if the file is still at this version.
nullThe file must not exist yet (create, never overwrite).
omittedOverwrite. A backup is still kept.

fs.rename never overwrites: renaming onto a name that exists fails with conflict, and nothing moves.

#Backups and undo

Before Chataway overwrites or trashes a file for your app, it keeps a copy in its own data folder: up to 20 per file, up to 200 MB per app, oldest first out. fs.restore({ root, path }) brings back the newest copy — undo for your last overwrite or trash — and uses it up, so the next fs.restore goes one step further back. Whatever the restore replaces goes to the system Trash. With no copy left, it fails. fs.trash moves the file to the system Trash, so the user can also get it back from there.

#Watch for changes

ts
const stop = await app.fs.onChange(root, (e) => {
  // { root, path, kind: 'changed' | 'created' | 'deleted', version? }
  if (e.path === openPath && e.version !== loaded.version) showReloadBanner();
});

fs.onChange calls fs.watch and listens for fs-change events of that root. Events are debounced (150 ms) and include changes made outside your panel: the user's chat agent editing a note shows up the same way. You also get events for your own writes, so compare version before you reload. Events only name files your app can see (your types, no secrets, nothing in node_modules). The watcher doesn't follow symbolic links. When your panel closes or reloads, its watches end.

#What your app can't see

Chataway checks every call, whatever your panel sends:

  • Only inside the root. No .., no absolute paths, no symbolic links that lead out of the folder.
  • Only your file types. Files with other extensions don't appear in fs.list and can't be read or written (denied). Folders are always listed.
  • Never secrets. .env files, keys, credential files (.ssh/, .npmrc, credentials.json…) and .git/ are invisible, even inside a granted folder. Names are compared the way macOS and Windows compare them — case and Unicode look-alikes fold — so .ENV or Credentials.JSON are caught too.
  • access: "read" means read. Writes, renames, trash and restore fail with denied.
  • No agent settings. In a folder or "Open with" root, your app can never write, rename, trash or restore a file coding agents read as instructions (CLAUDE.md, CLAUDE.local.md, AGENTS.md, GEMINI.md, .cursorrules…), a hidden file, or anything inside a hidden folder (.claude/, .github/, .vscode/…). The call fails with HTTP 403 agent-file (denied in the panel).
  • Only what you can see moves. Renaming or trashing a folder fails when it holds anything your app can't see (files of other types, secret files or .git, symbolic links). The root itself can't be trashed, and a file: root can't be renamed — save a copy with fs.write instead.
  • Limits. 25 MB per file, 600 file operations a minute per app, 2000 entries per fs.list. Over the rate, calls fail with busy until the minute has passed.

#"Open with"

contributes.fileHandlers adds an entry to the Files panel's menu for files of your types — Open in Sketch Notes. The user's click hands your panel that one file and nothing else:

plugin.json
json
"contributes": {
  "fileHandlers": [{
    "id": "open",
    "label": "Open in Sketch Notes",
    "extensions": [".md"],
    "panel": "main",
    "view": "editor",
    "access": "readwrite"
  }]
}
FieldRules
idA lowercase letter, then lowercase letters, digits or _ (≤ 48). Unique.
label≤ 40 characters, e.g. Open in Sketch Notes.
extensionsAs for folders.
panelOne of your contributes.panels[].id.
viewOptional: the view to open.
accessread or readwrite for that file.

Up to 10 handlers; they need the folders grant. Chataway opens your panel with context.params.open = { root, name, handlerId }. If the panel is already open, it gets an open event instead. app.onOpen() covers both. The file: root works for 24 hours, until Chataway restarts, and until your app is switched off in the project; after that, calls on it fail and the user opens the file again.

ts
app.onOpen(async ({ root, name }) => {
  const file = await app.fs.read({ root, path: '' });
  editor.load(name, file.text!, file.version);
  saveButton.onclick = () => app.fs.write({ root, path: '', text: editor.value, ifVersion: file.version });
});

#Your own storage

The storage root is your app's own folder in this project. It needs no grant and no requires.hostApi for your own code. What agents may see of it is set by storage zones.

#In the mock host

The mock host keeps an in-memory file system with the same versions, conflicts, backups and events:

ts
const app = await connect({
  mock: {
    manifest,                                        // folders and handlers come from it
    fs: { 'folder:notes': { 'ideas.md': '# Ideas' }, storage: { 'db/state.json': '{}' } },
    grantedFolders: ['notes'],                       // or let folders.request grant it
    open: { name: 'todo.md', content: '- [ ] milk' }, // as if opened with "Open in …"
  },
});
app.mockHost!.writeFile('folder:notes', 'ideas.md', '# Ideas\n- edited elsewhere'); // fs-change, and a conflict for a stale write
app.mockHost!.openFile('other.md', '# Other');                                       // an 'open' event

folders.request grants at once unless you pass grantFolders: false. readFile, deleteFile and grantFolder are there for tests.