Doc Space

Grid gives your connected assistants a shared view of software and reported work. GitHub supplies repository metadata, Vercel supplies project and deployment metadata, and participating agents supply their own activity, job progress, deadlines, and handoffs.

1. Connect Claude Code, Codex, or Claude web using the instructions below.
2. Ask for grid_status and the last seven days of grid_projects. Ask the assistant to include source and observation times.
3. Register the session before tracking work. Retain its returned agent and job IDs.
4. Report progress during work, then save a concise handoff when another session should continue.

“Use Grid to summarize my software activity over the last seven days, show registered agents and open jobs with their latest report times, and identify recorded deadlines that need attention.”

Grid’s service uses deterministic application code and external metadata APIs. You can use it from your existing signed-in Claude and Codex clients. Model API usage is zero, with all assistant work running through your signed-in clients. Your client’s subscription and tool-use limits still apply. Hosting and GitHub requests use the existing services’ allowances.

Claude Code

Add Grid at user scope to make it available across projects, then authenticate.

claude mcp add --transport http --scope user grid https://usegrid.cloud/mcp
claude

In Claude Code, run /mcp, select Grid, and choose Authenticate. Complete Grid sign-in and choose Allow access. Return to the MCP panel to inspect the connection and tools, then ask for Grid status to check a real call. If Grid is already configured, start with the MCP panel. You can also inspect its configuration from the shell with claude mcp get grid.

Official Claude Code MCP instructions

Codex

codex mcp add grid --url https://usegrid.cloud/mcp
codex mcp login grid --scopes grid:read,grid:write
codex mcp get grid

Complete the browser sign-in and consent flow. Open a Codex session with the configured server and ask it to call Grid. A read-only connection can request grid:read. For headless use, add --no-browser to the login command. If a client-registration error occurs, retry login with --oauth-client-registration dcr.

codex mcp add grid --url https://usegrid.cloud/mcp \
  --bearer-token-env-var GRID_MCP_TOKEN

Official Codex MCP instructions

Claude web and account connectors

1. Open Customize → Connectors, then add a custom web connector. Team or Enterprise workspaces may require an owner to add it in organization settings first.
2. Name it Grid and enter https://usegrid.cloud/mcp.
3. Choose OAuth sign-in. If client identity options appear, choose Register automatically, which uses Grid’s dynamic registration support.
4. Connect, sign in to Grid, review the requested permissions, and choose Allow access.
5. Enable Grid for the conversation through the connectors menu, then request a Grid tool call.

Account connector availability and controls depend on your Claude workspace. OAuth authorization is separate for the web connector and each CLI connection.

Official Claude custom connector instructions

Local Codex CLI and Claude Code OAuth sign-ins and tool discovery were verified on 11 November 2026. Complete the flow in each additional client or device to authorize that connection.

The Overview reads connected sources and persisted reports. The preserved demo workspace provides an interactive issue-tracker reference with fictional seed data. Demo edits persist in the current browser, including the original storage keys for compatibility.

Demo groups and command-palette results carry demo labels. Reset demo data affects local demo edits. Real agent activity, deadlines, and handoffs are persisted by the server and accessed through Grid’s private API and MCP tools.

Inventory coverage

GitHub inventory includes repositories owned by the configured GitHub account that the server token can access. Vercel inventory includes projects in the configured team. Grid reads metadata and status fields for this inventory. Repository names, descriptions, language, privacy, archive state, topics, and last push time come from GitHub. Framework, project timestamps, and deployment states come from Vercel.

Repositories and deployments are matched using Vercel’s recorded GitHub repository ID or owner/name connection. Multiple Vercel projects can link to one repository. Unmatched repositories and deployment-only projects remain visible. Each match requires recorded repository-link evidence.

Time windows and counts

• grid_projects accepts a trailing window of 1–90 whole days, defaulting to 7. Responses include exact since and until timestamps. The web Overview uses seven days.
• Commit counts use GitHub-indexed default-branch commits with commit timestamps inside that window. They measure commits, while push-event totals and lines changed require separate metrics. Search indexing can lag.
• Deployment counts include Vercel deployment attempts created inside the window, including preview, production, and failed attempts.
• GitHub search exposes at most 1,000 indexed results. Pagination limits, incomplete search, permission failures, or rate limits can make counts partial. Grid labels partial results and uses unavailable values when it cannot establish a count.

Status, activity, and freshness

Project status reflects the production deployment state recorded by Vercel. The latest deployment attempt is also available, so a failed attempt can be inspected alongside the production build. Last activity takes the latest available repository push, Vercel project update, or deployment timestamp. A ready deployment describes Vercel’s recorded state. Live uptime is established by an HTTP probe.

Each inventory response includes a check time, per-source state, provenance links, and coverage notes. Inventory snapshots are cached in a Vercel process for up to five minutes per day-window, and concurrent reads can share one in-progress request. Refresh in the UI requests the endpoint again and can receive that cached snapshot. Reported work is read from persistent storage on each records request. Always use the returned timestamps when interpreting freshness.

Empty, zero, partial, unavailable, and unconfigured have different meanings. An empty registered-agent list represents zero returned agent reports. An unavailable source means the request failed or access is missing. A count of zero is meaningful only within its returned window and coverage.

Use one stable agent ID for a real session and one stable job ID for each piece of work. Omit an ID on first creation to receive a generated one, then retain it for updates. Supported identifiers use letters, numbers, underscores, periods, colons, and hyphens, up to 120 characters. The following payloads illustrate a workflow and create records only when a connected client submits them.

Register and heartbeat

{
  "id": "session-your-run-id",
  "name": "Your session name",
  "client": "codex",
  "status": "active",
  "roleId": "tesla-engineers",
  "team": "Engineering",
  "source": "Your actual client or run reference"
}

Send this shape to grid_register_agent. Clients are codex, claude, or other. Agent statuses are active, idle, and offline. A heartbeat is another registration call with the same ID and required fields. Grid assigns the report timestamp. Report at meaningful progress points and within five minutes while active when the client can call tools.

Create and update a job

{
  "id": "job-your-work-id",
  "title": "Your actual assigned work",
  "agentId": "session-your-run-id",
  "status": "running",
  "summary": "Observed progress and the next concrete step",
  "source": "Assignment or run reference"
}

Send this shape to grid_report_job. Valid states are queued, running, blocked, completed, failed, and cancelled. Update the same ID as work progresses. Include a concise blocker or verified result in summary. Completion should identify what finished and the evidence, such as a commit, test result, or deployment URL. Register an agent before referring to its ID. Use the inventory’s returned project ID when relating work to software.

Grid preserves creation time and assigns each update time and credential principal. Reusing a job ID replaces its current report while retaining supplied optional fields from the existing record. Include the fields you intend to keep accurate on every update. A stalled heartbeat leaves the last reported job state available for inspection.

Close the loop

1. Read the relevant project, active jobs, and handoffs before starting.
2. Register the session and report the job as queued or running.
3. Report milestones, blockers, or an explicitly assigned deadline as they occur.
4. Record completion, failure, or cancellation from observed work.
5. Save a handoff with decisions and next steps, then report the session idle or offline when appropriate.

Grid starts with two configurable templates, CTO and Tesla Engineers. CTO covers technical priorities, dependencies, and reviewing reported progress. Tesla Engineers covers assigned implementation, testing, deployment evidence, and blockers. Register a real session with roleId to associate it with a role. Role configuration supplies responsibilities and expectations. Agent records supply observed activity.

Read templates with grid_roles. Configure a template with grid_configure_role, including its ID, name, team, responsibilities array, source, and optional group. Responsibilities accept 1–12 entries of up to 240 characters each. Team and group are workspace routing labels that can group reports for a project or working unit.

defaultDeadlineHours is an optional role policy, accepting an integer from 1 to 8,760. The starter templates leave it unset. When you explicitly configure it, the first creation of a job linked to an agent using that role gets a policy-sourced deadline derived from that creation time. Later progress updates preserve the original due time. Explicit completion or cancellation of that job marks its policy-generated deadline done or cancelled.

Choose this policy only when that duration reflects your intended workflow. Existing manual deadlines remain explicit records. Configuring a role or label stores configuration, and a participating client performs and reports the work.

A handoff is a concise shared record another authorized assistant can read before continuing work. It carries summary, decisions, next steps, source, and optional project, job, or agent relationships. Grid stores and retrieves these entries as context. Learning across tasks happens through reading these saved summaries. Each client uses the records returned to its conversation under that client’s own settings.

{
  "id": "handoff-your-unique-checkpoint",
  "summary": "What was actually completed and what remains",
  "decisions": [
    "A decision made during the work, with its reason"
  ],
  "nextSteps": [
    "The next concrete action for the receiving session"
  ],
  "projectId": "Use the actual project ID when applicable",
  "jobId": "job-your-work-id",
  "agentId": "session-your-run-id",
  "source": "Commit, issue, deployment, or assignment reference"
}

Send this shape to grid_record_handoff. Summary accepts up to 3,000 characters. Decisions and nextSteps each accept up to 20 entries of 500 characters. Source accepts up to 240 characters. Use an empty array when there are no decisions or next steps. Link only the identifiers that apply.

Saved entries are immutable. The server supplies creation time and reportedBy. Retrying the same content with the same ID returns the existing entry. New information belongs in a new handoff ID. Read with grid_handoffs, using query, projectId, or jobId to locate context. Lists are paginated, so continue from nextOffset when more entries exist.

Ask the receiving assistant to read the latest project handoffs, check current jobs and deployment evidence, then state what it will continue. A handoff records the writer’s observations and decisions, and source links allow the next assistant to verify them.

Create an assigned deadline with grid_set_deadline. Include title, dueAt as an ISO 8601 timestamp with timezone, status, source, and the applicable project or job ID. For example, ask an agent to record a due time you have already agreed, using the correct local timezone. The server stores the normalized timestamp. Deadline states are open, done, and cancelled.

Manual deadlines come from an explicit assignment. Optional role-based deadlines come from an explicitly configured defaultDeadlineHours policy. The stored source distinguishes their provenance. Keep IDs stable when revising an existing deadline. Review the result after an update to confirm the due time and related work.

The Vercel schedule 0 * * * * invokes authenticated reconciliation at the start of each UTC hour. It saves a last-run timestamp, source, agent IDs whose last heartbeat is older than five minutes, and open deadline IDs whose due time has passed. The scheduled snapshot reflects that check time. Direct agent reads also expose current heartbeat freshness.

Use grid_reconcile to refresh tracking immediately. Reconciliation uses recorded timestamps and statuses. Agents explicitly report job completion. Grid’s checks run as deterministic code with zero model API usage. Schedule execution depends on Vercel and storage availability, so inspect lastRunAt to verify a recent run.

Read tools require grid:read. Write tools require grid:write and appear for an authorized write connection. Optional arguments can be omitted. Paged lists default to offset 0 and limit 25, accept a limit of 1–25, and return total and nextOffset. Use returned IDs for relationships.

Every write includes a source or supplies one from the authenticated operation. Most short text fields have validation limits. A tool error returns a sanitized failure. Check required fields, referenced IDs, permissions, and source configuration before retrying. A retry with a known ID avoids creating an extra agent, job, or deadline record.

Private workspace access

Grid is a single private workspace. The docs and OAuth discovery metadata are public. Inventory, agent activity, jobs, deadlines, roles, and handoffs require an authenticated browser session or MCP credential. Authorized clients share this workspace. A write client can update records by identifier, and reportedBy records the authenticated credential principal.

Browser access uses an owner sign-in key and an HttpOnly session cookie. OAuth uses authorization-code flow with PKCE S256, exact registered redirects, short-lived access tokens, and rotating refresh grants. Access tokens last one hour. Refresh grants expire after 30 days and rotate when used. The consent screen shows the client and requested permissions. A fixed agent bearer token is an optional separate credential.

Server configuration

• GRID_GITHUB_TOKEN reads accessible repository metadata and writes Grid’s private state. GRID_GITHUB_OWNER selects the inventory owner.
• GRID_VERCEL_TOKEN reads the configured team. GRID_VERCEL_TEAM_ID scopes that data. The optional team slug is used for dashboard links.
• GRID_STATE_REPOSITORY selects the private repository. GRID_BASE_URL establishes the canonical issuer and endpoint.
• GRID_OWNER_KEY_HASH and GRID_MCP_TOKEN_HASH hold key hashes. GRID_SESSION_SECRET signs sessions and OAuth tokens. CRON_SECRET authenticates scheduled checks.

These values belong in protected server-side Vercel environment variables. Keep source access scoped to the intended account, team, and state repository. Rotation means updating the corresponding protected value and redeploying the Grid project, then checking inventory or authentication with the replacement credential. Rotate the signing secret to invalidate existing signed sessions and tokens, and reconnect clients afterward. Updating the fixed agent-token hash requires updating its clients.

Persistence and retention

Reported state lives in state.json on the private grid-data Git branch. State writes use GitHub revision checks to reconcile concurrent updates. Deployments from that branch are disabled, so production builds follow changes on the application branch. Git history retains earlier revisions. The implementation caps the state at 2 MB, with up to 2,000 agents, 10,000 jobs, 10,000 deadlines, 100 roles, and 1,000 handoffs within that total size.

Store concise summaries, decisions, links, and progress. Keep raw credentials and full transcripts in their appropriate systems. Grid’s reporting connection exposes the records agents submit and the metadata its server reads. Visibility covers sessions that explicitly register and report through Grid. A client must be active and able to make a tool call to report a heartbeat. The Vercel-hosted integration and hourly checks run within this existing project.

Allow access leaves the client waiting

The callback content-security-policy issue was corrected, and successful browser consent and OAuth completion were verified with the actual local Codex and Claude Code clients. Start a fresh login in the client to obtain a fresh authorization request. Keep the requesting client running until its callback completes. An old consent page can contain expired state or a one-use authorization code.

The browser cannot open a local callback

Keep the requesting CLI open. Codex supports a headless login flow with --no-browser. In Claude Code, reopen the MCP authentication panel and follow its displayed browser instructions. Keep that URL private because it contains temporary authorization data. Keep it within the requesting client and authorization browser.

Grid is configured but tools are missing

Inspect the server with the client’s get command or MCP panel. Complete authentication, enable Grid for that conversation, and refresh or restart the client’s MCP connection after a release. Read-only access exposes read tools. Reauthorize with write scope when the intended workflow includes reporting.

The endpoint displays an authorization error or HTTP 405

A direct browser visit sends GET. Grid serves Streamable HTTP MCP over authenticated POST. Use an MCP client and the exact /mcp URL. An unauthenticated private request receives 401. A disallowed request origin receives 403. Verify service operation through an authenticated MCP client.

Projects are missing or counts differ

Check source status and coverage notes. Confirm the configured GitHub owner, repository permissions, Vercel team, and token validity. Compare the exact returned time window. Allow for the five-minute snapshot cache and GitHub indexing delay. Check the Vercel repository link when a deployment is unmatched.

An agent is stale or its job still says running

Inspect lastSeenAt and the job’s latest summary and update time. Ask the participating session to report if it is still available. A stale flag describes an old heartbeat. Record a job-state change from observed progress or an explicit user decision.

A write fails

Confirm write scope and complete required input. Register referenced agents and create referenced jobs first. Use an existing role ID. For an immutable handoff, reuse an ID only with identical content. If source configuration or storage is unavailable, inspect the protected server configuration and sanitized logs, then retry with stable IDs.

Hourly checks are old

Inspect lastRunAt and the latest reconciliation error. Run grid_reconcile with write access. The operator should verify the production Vercel schedule, CRON_SECRET, and private state write access, then confirm a later successful run.

11 November 2026

• Grid branding, private Overview, and this expanded Doc Space.
• Server-side GitHub and Vercel inventory with verified repository matching, source timestamps, coverage notes, and explicit count windows.
• Authenticated remote MCP, owner web sign-in, scoped OAuth, optional fixed agent bearer authentication, and private cross-device records.
• Agent registration, heartbeats, job progress, explicit deadlines, configurable CTO and Tesla Engineers role templates, and optional role deadline policies.
• Hourly deterministic reconciliation and immediate write-scoped checks.
• Immutable shared handoffs for summaries, decisions, and next steps between connected clients.
• Allow access callback policy correction, with successful OAuth sign-in and tool discovery verified in local Codex CLI and Claude Code.
• Original demo issue-tracker routes and browser-local data compatibility retained with visible demo labels.

Production build identity and commit history are available to authorized clients through the Grid project’s inventory and linked source systems. A successful connection in one client authorizes that client. Additional clients complete their own sign-in.