# Studiograph

Team-based AI agent platform with Git-backed knowledge graphs. Studiograph helps creative services teams capture operational knowledge as Markdown entities with YAML frontmatter, organized into Git repositories, and enables AI agents to produce work reflecting real team context.

## Quick Start

### Prerequisites

- **Node.js** 20+
- **Git** installed and configured
- An API key from a supported LLM provider (Anthropic, OpenAI, Google, xAI, Groq, or OpenRouter)
- **Supported platforms**: macOS (Apple Silicon), Linux (x64/arm64), Windows (x64/arm64). Intel Macs are not supported due to a LanceDB dependency.

### Install

```bash
npm install -g studiograph
```

### Create a Workspace

```bash
studiograph init "My Studio"
```

This creates a workspace directory with a `.studiograph/` config folder — similar to how Git uses `.git/` — and scaffolds example entities to get you started.

To create repos on GitHub during init:

```bash
studiograph init "My Studio" --github --github-org my-org
```

### Clone an Existing Workspace

```bash
studiograph clone https://studiograph.example.com /path/to/local/copy
```

Authenticates as the workspace owner against a running Studiograph server,
mints a per-machine API token, persists it to `~/.studiograph/user.json`, and
clones every accessible repo. Subsequent `pull`/`push` runs are non-interactive
via the stored token.

### Boot the Workspace

```bash
cd my-studio
studiograph serve
```

This starts the local HTTP server + opens the web UI. The web chat panel is the canonical agent surface: a richer chat UX, real-time graph view, and inline editor. On first boot you'll be prompted to set up an AI provider and model.

If you want a terminal-side agent (Claude Desktop / Cursor integration), run `studiograph mcp` — it exposes the same toolset over MCP.

## How It Works

### Workspace Structure

A Studiograph workspace is a directory containing a `.studiograph/` configuration folder and one or more content repositories:

```
my-studio/
├── .studiograph/           # Config repo (workspace.json, team roster, migrations)
├── acme-rebrand/           # Folder (client project)
├── website-redesign/       # Folder (another project)
├── team-knowledge/         # Folder (processes, standards)
└── private/                # Personal folder — owner-private, its own git repo
```

### Folders

Each subdirectory is a **folder** — a Git repo containing related entities. Folders are lightweight and flexible: one per project, one for team knowledge, one for business operations, or however your team thinks.

### Entities

Entities are Markdown files with YAML frontmatter, stored in type-based directories within repos:

```
acme-rebrand/
├── project/
│   └── acme-rebrand.md
├── meeting/
│   └── kickoff-2024-01-15.md
├── deliverable/
│   └── brand-guidelines-v1.md
└── person/
    └── jane-doe.md
```

Each entity file looks like:

```markdown
---
entity_type: project
entity_id: acme-rebrand
name: "Acme Rebrand"
status: active
team:
  - [[alice-smith]]
  - [[bob-jones]]
related_projects:
  - [[website-redesign]]
created_at: 2024-01-15T10:00:00Z
updated_at: 2024-02-20T14:30:00Z
created_by: alice
updated_by: alice
---

# Acme Rebrand

Project notes and context go here...
```

Entity IDs are always kebab-case. Entities link to each other with wikilinks (`[[entity-id]]`), which work across repos.

There are 17 built-in entity types (project, meeting, person, organization, decision, task, document, etc.), and workspaces can define custom types via `schema_extensions` in `workspace.json`.

## CLI Commands

### Getting Started

| Command | Description |
|---------|-------------|
| `studiograph init <team-name> [dir]` | Initialize a new workspace |
| `studiograph clone <url> [dir]` | Clone an existing workspace from a running server |

### Daily Workflow

| Command | Description |
|---------|-------------|
| `studiograph serve` | Boot the local HTTP server + open the web UI |
| `studiograph pull` | Pull latest changes from remote |
| `studiograph push` | Push local commits to remote |

### Workspace Management

| Command | Description |
|---------|-------------|
| `studiograph folder` | Manage folders (add, list, rename, remove) |
| `studiograph provision` | Push workspace config to GitHub as a separate repo |
| `studiograph members` | Manage team members and roles |
| `studiograph index` | Rebuild search index |
| `studiograph lint` | Check entity completeness and broken wikilinks |
| `studiograph config` | View and update workspace configuration |

### Server & Deployment

| Command | Description |
|---------|-------------|
| `studiograph serve` | Start the HTTP server (Graph API, Chat API, webhooks) |
| `studiograph deploy railway` | Guided Railway deployment wizard |

### Integrations

| Command | Description |
|---------|-------------|
| `studiograph mcp` | Start the MCP server for Claude Desktop |
| `studiograph connector` | Configure third-party integrations (Linear, Slack, Figma, etc.) |
| `studiograph app` | Manage installed app plugins |
| `studiograph r2` | Configure Cloudflare R2 for asset storage |

## Integrations

### Claude Desktop & Claude Code (MCP)

Studiograph exposes a [Model Context Protocol](https://modelcontextprotocol.io/) server so any MCP client can read and write your knowledge graph directly.

**Claude Desktop** — add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "studiograph": {
      "command": "studiograph",
      "args": ["mcp", "/absolute/path/to/your/workspace"]
    }
  }
}
```

**Claude Code** — add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "studiograph": {
      "command": "studiograph",
      "args": ["mcp", "/absolute/path/to/your/workspace"]
    }
  }
}
```

If you're running from the workspace directory, you can omit the path: `studiograph mcp`.

MCP tools available: `list_repos`, `create_repo`, `list_entities`, `get_entity`, `search_entities`, `create_entity`, `update_entity`, `delete_entity`.

### Third-Party Connectors

Studiograph can connect to external services via MCP connectors. Built-in connector configs are available for:

- **Linear** — issues and project tracking
- **Slack** — messages and channels
- **Figma** — design files
- **Google Workspace** — docs, sheets, calendar
- **Granola** — meeting notes
- **Pipedrive** — CRM deals and contacts

Configure with:

```bash
studiograph connector add linear
```

Connector credentials are stored at `~/.studiograph/connectors/` with restricted file permissions.

## HTTP Server

`studiograph serve` starts a Fastify server with:

| Route | Method | Description |
|-------|--------|-------------|
| `/api/repos` | GET | List all repositories |
| `/api/repos/:repo/entities/:type` | GET | List entities by type |
| `/api/repos/:repo/entities/:type/:id` | GET | Get a single entity |
| `/api/repos/:repo/search` | GET | Search within a repo |
| `/api/search` | GET | Search across all repos |
| `/api/chat` | POST | Send a message to the agent |
| `/api/chat/stream` | GET | SSE streaming chat |
| `/webhooks/github` | POST | GitHub push webhook (auto-pull) |

Authentication uses bearer tokens set via the `API_KEYS` environment variable (semicolon-separated). When no keys are configured, the server runs in open dev mode.

## Deployment

### Railway

```bash
studiograph deploy railway
```

The guided wizard walks through setup. Required environment variables:

| Variable | Description |
|----------|-------------|
| `STUDIOGRAPH_CONFIG_REPO` | GitHub URL to your `.studiograph` config repo |
| `GITHUB_TOKEN` | Fine-grained PAT with repo Contents read access |
| `API_KEYS` | Semicolon-separated bearer tokens for client auth |
| `WEBHOOK_SECRET` | GitHub webhook HMAC-SHA256 secret (optional) |
| `PORT` | Set automatically by Railway |
| `STUDIOGRAPH_CLOUD_URL` | Optional Studiograph Cloud control-plane URL for hosted inference billing |
| `STUDIOGRAPH_CLOUD_ORG_ID` | Optional cloud organization ID for this managed runtime |
| `STUDIOGRAPH_CLOUD_WORKSPACE_ID` | Optional cloud workspace ID for this managed runtime |
| `STUDIOGRAPH_CLOUD_TOKEN` | Optional bearer token for machine-to-machine cloud billing calls |
| `STUDIOGRAPH_CLOUD_BILLING_REQUIRED` | Set to `1` to fail chat when cloud billing reservation/settlement fails |
| `STUDIOGRAPH_CLOUD_INFERENCE_ESTIMATE_CENTS` | Reservation estimate per chat turn, default `100` |

On first boot, the server clones the config repo and all content repos automatically.

## Development

### Setup

```bash
git clone <repo-url>
cd studiograph
npm install
npm run build
```

### Scripts

```bash
npm run build     # Compile TypeScript + copy prompt/skill files to dist/
npm run dev       # Watch mode (tsc --watch)
npm run test      # Run tests in watch mode (Vitest)
npm run lint      # ESLint
npx vitest run    # Run tests once (CI mode)
```

### Run a Single Test

```bash
npx vitest run src/core/__tests__/graph.test.ts
```

### Project Layout

```
src/
├── cli/           # Commander.js commands
├── core/          # Workspace, graph, validation, schema registry, types
├── services/      # Git, Markdown, CSV, vector search, assets, memory, lint
├── agent/         # AI orchestrator, tools, skills, system prompts
├── server/        # Fastify HTTP server and API routes
├── mcp/           # Model Context Protocol server and connector manager
├── auth/          # GitHub authentication (OAuth device flow)
└── utils/         # Preflight checks, version checking, git helpers
```

### Key Files

- `src/core/types.ts` — Zod schemas for workspace config, entities, repos
- `src/core/validation.ts` — All 17 built-in entity type schemas
- `src/core/graph.ts` — `BaseGraphManager` (CRUD for a single repo)
- `src/core/workspace-manager.ts` — `WorkspaceManager` (multi-repo coordination)
- `src/core/workspace.ts` — `.studiograph/` directory management
- `src/agent/orchestrator.ts` — AI agent setup with multi-provider support
- `src/server/index.ts` — Fastify server factory

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.
