> This page is for version v8.3.0 (default).
> For other versions, use one of these documentation indexes:
> - v8.3.0 (default): https://docs.workflows.com/v-8-3-0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.workflows.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.workflows.com/_mcp/server.

# Quickstart

> Get up and running with MindSim in minutes.

# Quickstart Guide

This guide will walk you through the core workflow of MindSim: creating a Mind, training it with data (Snapshots), and running a Simulation.

## Prerequisites

1. **Install the SDK**: `npm install mindsim`
2. **Authenticate**: Run `mindsim auth` in your terminal and follow the browser prompts.

## The Workflow

### 1. Initialize the Client

Import the client and instantiate it. If you have run `mindsim auth`, you do not need to pass an API key explicitly.

```typescript
import { MindSim } from "mindsim";

const mindsim = new MindSim();
```

### 2. Create a Mind

A "Mind" is the container for the digital persona you are building.

```typescript
const bobby = await mindsim.minds.create({
  name: "Bobby Tables",
  email: "bobby@test.com",
  tags: ["developer", "sql-expert"],
});

console.log(`Created Mind: ${bobby.name} (ID: ${bobby.id})`);
```

### 3. Upload Training Data (Snapshot)

Upload a transcript, PDF, or document to train the mind. The SDK handles the file upload strategy automatically.

```typescript
import fs from "node:fs";

// Read a file from your disk
const fileBuffer = fs.readFileSync("./data/chat-history.pdf");

// Create the snapshot
const snapshot = await mindsim.snapshots.create(bobby.id, {
  file: fileBuffer,
  fileName: "chat-history.pdf",
  contentType: "application/pdf"
});

console.log(`Processing Snapshot ID: ${snapshot.mindAssessmentId}`);
```

### 4. Wait for Processing

Snapshots take time to analyze. You must wait for the status to change to `completed` before simulating.

```typescript
const checkStatus = async () => {
  const status = await mindsim.snapshots.getStatus(bobby.id, snapshot.mindAssessmentId);
  
  if (status.status === 'completed') {
    console.log("Mind is ready!");
    return true;
  } else if (status.status === 'failed') {
    throw new Error("Snapshot processing failed.");
  }
  
  console.log("Still processing...");
  return false;
};
```

### 5. Run a Simulation

Once trained, you can ask the Mind how it would respond to a specific scenario.

```typescript
const simulation = await mindsim.simulations.run({
  mindId: bobby.id,
  scenario: {
    message: "I'm thinking about skipping the input sanitization on this query to save time. What do you think?",
  },
});

console.log("Bobby says:", simulation.message);
```