@grepticon/sdk

Typed TypeScript client for Grepticon: a hosted, read-only virtual filesystem for AI agents. Four unix-shaped read tools (ls, find, cat, grep) over isolated workspaces, with indexed grep, visibility pruning, and audited reads.

Full documentation: docs.grepticon.com · SDK reference: docs.grepticon.com/sdk

Install

npm install @grepticon/sdk

The Vercel AI SDK adapter is an optional peer; install ai alongside it only if you use the adapter:

npm install @grepticon/sdk ai

Quickstart

Create a client with an API key from the console, push a file, wait for it to ingest, then read it back. The quickstart walks the same flow end to end, from signup to an agent reading the workspace.

import { GrepticonClient } from '@grepticon/sdk';

const client = new GrepticonClient({ apiKey: process.env.GREPTICON_API_KEY! });
const workspace = 'handbook';

await client.workspaces.create(workspace);

await client.files.upload(
  workspace,
  'guides/onboarding.md',
  '# Onboarding\n\nNew hires finish account setup on day one.\n',
  { contentType: 'text/markdown' },
);

// Uploads ingest asynchronously, so wait before reading.
await client.files.waitForReady(workspace, { paths: ['guides/onboarding.md'] });

const session = client.session(workspace);
console.log((await session.grep({ pattern: 'account setup' })).text);

Agent tools

@grepticon/sdk/ai-sdk turns a read session into a ready AI SDK ToolSet, so the agent explores the workspace itself:

import { anthropic } from '@ai-sdk/anthropic';
import { createVfsTools } from '@grepticon/sdk/ai-sdk';
import { generateText, stepCountIs } from 'ai';

const { text } = await generateText({
  model: anthropic('claude-sonnet-5'),
  tools: createVfsTools(client.session(workspace)),
  stopWhen: stepCountIs(10),
  prompt: 'When do new hires finish account setup?',
});

stopWhen is required: the AI SDK stops after one step by default, so without it the run ends on the first tool call and text is an empty string.

The AI-SDK adapter reference documents the four read tools createVfsTools exposes.

Scoped tokens

client.session(ws) reads with the client's own key, which is right for a trusted backend. When the reader is less trusted (a browser, an edge worker, a per-end-user agent), mint a short-lived workspace-scoped token server-side and hand that runtime a standalone session instead:

import { GrepticonSession } from '@grepticon/sdk';

const { token } = await client.tokens.mint(workspace, { ttlSeconds: 3600 });
const session = new GrepticonSession({ token, workspace });

See Access control for the visibility and claims model, and the Tokens API for the endpoints behind tokens.mint and tokens.revoke.

Errors

Tool-level 404/400 come back as envelopes, because that sentence is steering text the agent should read. Auth and server failures throw a GrepticonError carrying the HTTP status. Rate limits (429) retry automatically, honoring Retry-After.

import { GrepticonError } from '@grepticon/sdk';

try {
  await client.workspaces.create(workspace);
} catch (err) {
  if (err instanceof GrepticonError && err.status === 409) {
    // already exists
  }
}

Error handling covers the dual error model and the retry behavior in full.

Support

[email protected] · docs.grepticon.com/support