Skip to content

Quick Start

A walkthrough with screenshots is in the article Bring your own AI agent to Google Sheets on Medium.

Before you start: GridShell's Sheets add-on is a client - it needs a running GridShell server to connect to. If you don't have one yet, see Installing the Library and Running the server first; anyone on your team can run the server, it doesn't need to be you.

You run the server, and it makes its own credentials

There's no GridShell account or central login. You (or your team) run the server yourself, and it generates its own auth token the first time it starts - copy that into the add-on, see Connect to a server below; GridShell never issues or stores the token.

Install the add-on

  1. Open the GridShell listing on the Google Workspace™ Marketplace and click Install, or open a Google Sheet™ and use Extensions → Add-ons → Get add-ons, search for GridShell, install it.
  2. Open a Google Sheet.
  3. Reload the spreadsheet. A GridShell menu appears (under Extensions, or as its own top-level menu depending on your Workspace settings).

Until you've saved a server address (next section), opening GridShell shows a short welcome dialog with setup pointers. It goes away for good once you save one.

Connect to a server

  1. GridShell menu → Open - opens the sidebar.
  2. Expand Settings.
  3. Under Server address, choose ws:// (local server, no certificate) or wss:// (remote server, requires a valid TLS certificate on the server side), and enter host:port, e.g. localhost:3000 or yourdomain.com:3000.
  4. A token generated by the server (see Getting the token) is required by default; paste it into the Auth token field below. You only need to do this once per Google account; it carries over into every other spreadsheet you use GridShell in.
  5. Leave the other settings at their defaults for now (see Settings & Limitations for what each one does) and click Save.

Settings take effect the next time you open a shell, not retroactively on one already open.

Open, reattach, close, and kill a shell

  • Open a new shell: click + New shell in the sidebar. GridShell is capped at 2 concurrent shells per document in the free tier and the button disables once you hit the cap.
  • Reattach to a running shell: click its row in the Opened shells list. This reopens the same session and whatever was running keeps running, nothing restarts.
  • Close the dialog without stopping the shell: just close the dialog window. The shell keeps running on the server - reopen it later from the same row. It is only killed once its connection has been lost (for example the sheet was closed) for the server's idle-kill time, 12 hours by default.
  • Kill a shell: hover its row and click the bin icon. This terminates the shell process immediately and removes it from the list - not reversible.
  • Close everything at once: GridShell menu → Close all sessions.
  • Rows can be dragged to reorder: a shell's row label updates automatically from the shell's own reported window title (e.g. it'll say "claude" once you launch Claude™ Code inside it), unless you've turned that off in Settings.

What you can't do (yet)

A few things are worth knowing before you start:

  • Two shells per document, free tier. Side-by-side sessions on different spreadsheets still work; this cap is on concurrent shells within one document.
  • URL Guard is on by default and blocks an agent from inserting a handful of formulas that take an arbitrary URL, which can leak data or mislead (IMPORTDATA, IMPORTXML, IMPORTHTML, IMPORTFEED, IMAGE, IMPORTRANGE, HYPERLINK). Turn it off in Settings if you trust the document and the agent you're working with - it asks for confirmation every time.
  • One spreadsheet per session. There's no way for the agent to reach a different open spreadsheet from within one shell today.
  • No native Sheets custom functions (=FUNCTION() callable from a cell) - the agent can still compute custom logic and write results into the sheet, just not as a cell formula.
  • A single batch of operations is capped at roughly 4.5 minutes of execution time, regardless of your Google account type.

Full detail on all of these, including what's deliberately restricted for a future Pro tier vs. what simply isn't built yet, is in Settings & Limitations.