maskin
AI run the shop. Humans set direction, agents execute.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 21 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sindre-ai/maskin with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sindre-ai/maskin'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/sindre-ai--maskin)HTML
<a href="/listings/sindre-ai--maskin"><img src="/api/listings/sindre-ai--maskin/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
π Zero-click setup (from Claude Code)
Paste this single prompt into Claude Code (or any MCP-compatible agent) to have it bootstrap the whole thing for you:
Clone https://github.com/sindre-ai/maskin, cd into it, follow the "Onboarding a new user from Claude Code" section of CLAUDE.md, and hand off to the list_marketplace MCP tool.
Claude will clone, `pnpm install`, start the dev stack in the background, wait for the startup banner, wire the MCP server into your Claude Code config using the auto-provisioned API key + workspace, run `/reload-plugins` so the Maskin tools are immediately available in the same session, and then ask you which template to set up (development / growth / custom). From clone to a running pipeline in one message, no session restart.
Manual setup
# Clone and install git clone https://github.com/sindre-ai/maskin.git && cd maskin pnpm install # Start everything (Docker + migrations + backend + frontend) pnpm dev # macOS / Linux pnpm dev:win # Windows (cmd / PowerShell)
`pnpm dev` boots PostgreSQL + SeaweedFS via Docker, runs migrations, then starts the backend (`http://localhost:3000`) and frontend (`http://localhost:5173`). When the backend prints its startup banner, pick one of the two paths below.
β Get started from the browser
1. Open `http://localhost:5173` and create an account. 2. Create your first workspace from the UI. 3. (Optional) Connect MCP from **Settings β MCP** later if you want agents to drive the workspace.
β‘ Get started from Claude Code (no UI)
On a fresh database, `pnpm dev` automatically creates a default actor + workspace and prints a ready-to-run `claude mcp add` command in the startup banner β including the API key. Two steps from there:
1. **Connect MCP** β copy the `claude mcp add maskin β¦` line from the dev banner and run it. (Disable this auto-bootstrap with `MASKIN_AUTO_BOOTSTRAP=false` if you want to create credentials yourself.)
2. **Configure the workspace.** In Claude Code, paste one of:
Configure my Maskin workspace with the "development" template.
Configure my Maskin workspace with the "growth" template.
Configure my Maskin workspace with a custom template.
The first two apply pre-built templates (object types, statuses, custom fields, seed objects). The third walks you through a short questionnaire and tailors the workspace to whatever you're working on. Claude will ask a couple of light tailoring questions (workspace name, what you're building, near-term goal) β answer any, all, or none. Total time: under 3 minutes.
Rename the default actor and workspace whenever you're ready β from the UI (Settings β Profile / Workspace) or via MCP (`update_actor`, `update_workspace`). Run `list_marketplace` again any time on a different workspace by passing `workspace_id`.
> Want demo data instead? Run `pnpm db:seed` for a pre-populated example workspace.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md Β· README Β· 383 lines
- # Maskin
- [](LICENSE)
- [](https://github.com/sindre-ai/maskin/actions/workflows/ci.yml)
- [](https://github.com/sindre-ai/maskin/stargazers)
- [](https://www.typescriptlang.org/)
- [](https://nodejs.org/)
- An open-source workspace where AI agents run product development autonomously. Humans set direction, agents execute.
- ## What is this?
- - **Open-source workspace** where AI agents run product development end-to-end
- - **Core pipeline:** Insights (signals from users, data, market) -> Bets (hypotheses to validate) -> Tasks (concrete work items) -> Feedback Loop
- - **Agents are first-class citizens** -- they create insights, propose bets, break down tasks, and execute. Humans course-correct
- - **Everything is an API** -- UI and agents use the same endpoints. No special agent interface, no separate human interface
- - **Unified object model** -- insights, bets, and tasks are all "objects" with the same schema, connected by relationships
- ## Prerequisites
- - **Node.js β₯ 20**
- - **pnpm 9.15.0** (`npm install -g pnpm@9.15.0`)
- - **Docker + Docker Compose** β must be installed and running. `pnpm dev` / `pnpm dev:win` boot PostgreSQL + SeaweedFS via `docker-compose`, so the app cannot start without Docker. Docker Desktop (macOS/Windows) bundles Compose; on Linux install `docker-compose-plugin`.
- ## Quick Start
- ### π Zero-click setup (from Claude Code)
- Paste this single prompt into Claude Code (or any MCP-compatible agent) to have it bootstrap the whole thing for you:
- ```
- Clone https://github.com/sindre-ai/maskin, cd into it, follow the "Onboarding a new user from Claude Code" section of CLAUDE.md, and hand off to the list_marketplace MCP tool.
- ```
- Claude will clone, `pnpm install`, start the dev stack in the background, wait for the startup banner, wire the MCP server into your Claude Code config using the auto-provisioned API key + workspace, run `/reload-plugins` so the Maskin tools are immediately available in the same session, and then ask you which template to set up (development / growth / custom). From clone to a running pipeline in one message, no session restart.
- ### Manual setup
- ```bash
- # Clone and install
- git clone https://github.com/sindre-ai/maskin.git && cd maskin
- pnpm install
- # Start everything (Docker + migrations + backend + frontend)
- pnpm dev # macOS / Linux
- pnpm dev:win # Windows (cmd / PowerShell)
- ```
- `pnpm dev` boots PostgreSQL + SeaweedFS via Docker, runs migrations, then starts the backend (`http://localhost:3000`) and frontend (`http://localhost:5173`). When the backend prints its startup banner, pick one of the two paths below.
- ### β Get started from the browser
- 1. Open `http://localhost:5173` and create an account.
- 2. Create your first workspace from the UI.
- 3. (Optional) Connect MCP from **Settings β MCP** later if you want agents to drive the workspace.
- ### β‘ Get started from Claude Code (no UI)
- On a fresh database, `pnpm dev` automatically creates a default actor + workspace and prints a ready-to-run `claude mcp add` command in the startup banner β including the API key. Two steps from there:
- 1. **Connect MCP** β copy the `claude mcp add maskin β¦` line from the dev banner and run it. (Disable this auto-bootstrap with `MASKIN_AUTO_BOOTSTRAP=false` if you want to create credentials yourself.)
- 2. **Configure the workspace.** In Claude Code, paste one of:
- ```
- Configure my Maskin workspace with the "development" template.
- ```
- ```
- Configure my Maskin workspace with the "growth" template.
- ```
- ```
- Configure my Maskin workspace with a custom template.
- ```
- The first two apply pre-built templates (object types, statuses, custom fields, seed objects). The third walks you through a short questionnaire and tailors the workspace to whatever you're working on. Claude will ask a couple of light tailoring questions (workspace name, what you're building, near-term goal) β answer any, all, or none. Total time: under 3 minutes.
- Rename the default actor and workspace whenever you're ready β from the UI (Settings β Profile / Workspace) or via MCP (`update_actor`, `update_workspace`). Run `list_marketplace` again any time on a different workspace by passing `workspace_id`.
- > Want demo data instead? Run `pnpm db:seed` for a pre-populated example workspace.
- ## Architecture
- ```
- maskin/
- βββ apps/
- β βββ dev/ # Backend API server (Hono.js)
- β β βββ src/
- β β β βββ index.ts # App entry, middleware, route mounting
- β β β βββ routes/ # REST endpoints
- β β β β βββ objects.ts
- β β β β βββ actors.ts
- β β β β βββ workspaces.ts
- β β β β βββ relationships.ts
- β β β β βββ triggers.ts
- β β β β βββ events.ts
- β β β β βββ sessions.ts
- β β β β βββ integrations.ts
- β β β β βββ graph.ts
- β β β βββ services/
- β β β β βββ trigger-runner.ts # Cron + event-based automation
- β β β β βββ session-manager.ts # Container-based agent sessions
- β β β β βββ container-manager.ts # Docker container lifecycle
- β β β β βββ agent-storage.ts # S3 agent file pull/push
- β β β βββ lib/
- β β β βββ llm/ # LLM provider adapters
- β β β βββ openai.ts
- β β β βββ anthropic.ts
- β β βββ Dockerfile
- β βββ web/ # Frontend (React + TanStack)
- β β βββ src/
- β β βββ routes/ # File-based routing (TanStack Router)
- β β βββ components/ # UI primitives, shared, and feature components
- β β βββ hooks/ # TanStack Query hooks per resource
- β β βββ lib/ # API client, auth, SSE, utilities
- β βββ e2e/ # E2E tests (Playwright)
- β βββ src/
- β βββ tests/ # Test specs (auth, CRUD, navigation)
- β βββ fixtures/ # Auth fixtures
- β βββ helpers/ # API test helpers
- βββ scripts/
- β βββ dev.sh # Dev startup script (bash/macOS/Linux)
- β βββ dev.mjs # Dev startup script (Windows cmd/PowerShell)
- β βββ openrouter-conformance.mjs # Tool-use + reply-language check of a model on the funded OpenRouter route (spends credit; see header)
- βββ packages/
- β βββ db/ # Drizzle ORM schema + migrations
- β βββ auth/ # API key auth (keys stored as issued; hashing planned)
- β βββ shared/ # Zod schemas for validation
- β βββ realtime/ # PG NOTIFY -> SSE bridge
- β βββ storage/ # Abstract StorageProvider with S3 implementation
- β βββ mcp/ # MCP server (39 tools, stdio + HTTP transport)
- βββ docker-compose.yml
- βββ turbo.json
- βββ package.json
- ```
- **Key design decisions:**
- - **Modular monorepo** -- pnpm workspaces + Turborepo for builds. Each package is independently importable
- - **Event-sourced activity** -- every mutation logs an event. Agents and humans see the same audit trail
- - **Container-based agent execution** -- Docker container sessions (SessionManager) for running Claude Code, Codex, or custom CLIs
- ## Tech Stack
- | Layer | Choice | Why |
- |-------|--------|-----|
- | Runtime | Node.js >= 20 | Native fetch, stable ESM |
- | Language | TypeScript 5.7+ | Type safety across monorepo |
- | API Framework | Hono.js + OpenAPIHono | Fast, lightweight, edge-ready |
- | ORM | Drizzle ORM | Type-safe SQL, zero overhead |
- | Database | PostgreSQL 16 | JSONB for metadata, NOTIFY for real-time |
- | Validation | Zod | Shared schemas between API, frontend, and MCP |
- | Auth | API keys (stored as issued, hashing planned) | Simple, agent-friendly. No cookies or sessions |
- | Real-time | PG NOTIFY -> SSE | No extra infra (no Redis, no WebSocket server) |
- | Agent Protocol | MCP (Model Context Protocol) | Standard protocol for external AI agents |
- | Frontend | React 19 + TanStack Router + TanStack Query | File-based routing, server state caching |
- | Styling | Tailwind CSS 4 + shadcn/ui | Utility-first CSS with Radix UI primitives |
- | Object Storage | S3-compatible (SeaweedFS for dev) | Agent file persistence (skills, learnings, memory) |
- | Containers | Docker + dockerode | Ephemeral agent execution environments |
- | Build | Turborepo | Parallel builds, dependency-aware caching |
- | Linting | Biome | Fast, replaces ESLint + Prettier |
- ## Data Model
- All product work is represented as **unified objects** -- insights, bets, and tasks share the same table with a `type` discriminator. This keeps the schema flat and lets agents reason across object types uniformly.
- ### Tables
- | Table | Purpose |
- |-------|---------|
- | **actors** | Humans and AI agents. Both are first-class. Stores type, name, API key (stored as issued, hashing planned), system prompt, LLM config, and memory |
- | **workspaces** | Isolated environments. Each workspace has its own settings including valid statuses per object type |
- | **workspace_members** | Many-to-many join between actors and workspaces with roles (owner, member) |
- | **objects** | The core table. Every insight, bet, and task is an object with: type, title, content, status, metadata (JSONB), and owner |
- | **relationships** | Typed edges between objects: `informs`, `breaks_into`, `blocks`, `relates_to`, `duplicates` |
- | **events** | Append-only activity log. Every mutation is recorded with actor, action, entity reference, and data payload |
- | **triggers** | Automation rules. Either cron-based or event-based. Each trigger targets an actor and includes an action prompt |
- | **integrations** | External service connections per workspace (OAuth-based) |
- | **sessions** | Container-based agent execution sessions. Tracks lifecycle: pending -> running -> completed/paused/failed/timeout |
- | **session_logs** | Append-only log output from container sessions (stdout/stderr/system), used for SSE streaming |
- | **agent_files** | Metadata index for agent files stored in S3 (skills, learnings, memory) |
- ## API Endpoints
- All endpoints are under `/api`. Most require `Authorization: Bearer <api-key>` and `X-Workspace-Id` headers.
- ### Health and Metadata
- | Method | Path | Description |
- |--------|------|-------------|
- | GET | `/api/health` | Liveness check (no auth, no database) |
- | GET | `/api/health/db` | Database readiness check (no auth) |
- | GET | `/api/openapi.json` | OpenAPI spec (no auth) |
- ### Objects (Insights, Bets, Tasks)
- | Method | Path | Description |
- |--------|------|-------------|
- | POST | `/api/objects` | Create an object |
- | GET | `/api/objects` | List objects (filter by type, status, owner) |
- | GET | `/api/objects/search` | Search objects by text in title/content |
- | GET | `/api/objects/:id` | Get object by ID |
- | GET | `/api/objects/:id/graph` | Get object with all relationships and connected objects |
- | PATCH | `/api/objects/:id` | Update object (title, content, status, metadata) |
- | DELETE | `/api/objects/:id` | Delete object |
- ### Actors
- | Method | Path | Description |
- |--------|------|-------------|
- | POST | `/api/actors` | Create actor and get API key (no auth for humans; an agent needs the caller's API key and a workspace_id the caller belongs to) |
- | GET | `/api/actors` | List actors (optionally filtered by workspace) |
- | GET | `/api/actors/:id` | Get actor details |
- | PATCH | `/api/actors/:id` | Update actor |
- | POST | `/api/actors/:id/api-keys` | Regenerate API key |
- ### Workspaces
- | Method | Path | Description |
- |--------|------|-------------|
- | POST | `/api/workspaces` | Create workspace |
- | GET | `/api/workspaces` | List workspaces for current actor |
- | PATCH | `/api/workspaces/:id` | Update workspace (name, settings) |
- | POST | `/api/workspaces/:id/members` | Add member to workspace |
- | GET | `/api/workspaces/:id/members` | List workspace members |
- ### Relationships
- | Method | Path | Description |
- |--------|------|-------------|
- | POST | `/api/relationships` | Create relationship between objects |
- | GET | `/api/relationships` | List relationships (filter by source, target, type) |
- | DELETE | `/api/relationships/:id` | Delete relationship |
- ### Triggers
- | Method | Path | Description |
- |--------|------|-------------|
- | POST | `/api/triggers` | Create automation trigger |
- | GET | `/api/triggers` | List triggers in workspace |
- | PATCH | `/api/triggers/:id` | Update trigger |
- | DELETE | `/api/triggers/:id` | Delete trigger |
- ### Events
- | Method | Path | Description |
- |--------|------|-------------|
- | GET | `/api/events` | SSE stream of real-time events (supports `Last-Event-ID` for replay) |
- | GET | `/api/events/history` | Paginated event history (filter by entity_type, action, since) |
- ### Sessions (Container-based Agent Execution)
- | Method | Path | Description |
- |--------|------|-------------|
- | POST | `/api/sessions` | Create a container session |
- | GET | `/api/sessions` | List sessions |
- | GET | `/api/sessions/:id` | Get session details |
- | POST | `/api/sessions/:id/stop` | Stop a running session |
- | POST | `/api/sessions/:id/pause` | Pause and snapshot a session |
- | POST | `/api/sessions/:id/resume` | Resume a paused session |
- | GET | `/api/sessions/:id/logs` | Paginated log history |
- | GET | `/api/sessions/:id/logs/stream` | SSE stream of live logs |
- ### Graph (Batch Operations)
- | Method | Path | Description |
- |--------|------|-------------|
- | POST | `/api/graph` | Atomic batch create (objects + relationships in one transaction) |
- ### Integrations
- | Method | Path | Description |
- |--------|------|-------------|
- | GET | `/api/integrations` | List integrations for workspace |
- | GET | `/api/integrations/providers` | List available providers |
- | POST | `/api/integrations/:provider/connect` | Start OAuth/connection flow |
- | GET | `/api/integrations/:provider/callback` | OAuth callback (no auth) |
- | DELETE | `/api/integrations/:id` | Disconnect integration |
- ### Webhooks
- | Method | Path | Description |
- |--------|------|-------------|
- | POST | `/api/webhooks/:provider` | Incoming webhook handler (no auth) |
- ### MCP HTTP Transport
- | Method | Path | Description |
- |--------|------|-------------|
- | POST | `/mcp` | Streamable HTTP transport for MCP clients |
- ## Agent System
- Agents run as container sessions β ephemeral Docker containers running CLI agents (Claude Code, Codex, custom CLIs).
- - **Triggered by events or cron** -- the TriggerRunner watches for matching events or schedules and spawns container sessions
- - **All actions logged as events** -- every agent action appears in the event stream, attributed to the agent actor
- - **Configurable per agent** -- each agent has its own system prompt, tools list, and persistent memory
- - **Full lifecycle management** -- create, run, stop, pause (snapshot), resume
- - **Live log streaming** -- stdout/stderr streamed via SSE in real-time
- - **Persistent agent files** -- skills, learnings, and memory stored in S3-compatible storage, pulled into containers on start and pushed back on completion
- - **Configurable** -- custom images, environment variables, timeouts, working directories
- ### External Agents (MCP)
- External agents connect via the Model Context Protocol (39 tools available), supporting both stdio and HTTP transport.
- - **Full workspace access** -- CRUD for objects, relationships, actors, workspaces, triggers, sessions, integrations
- - **Works with any MCP-compatible client** -- Claude Code, Claude Desktop, OpenAI agents, custom implementations
- - **Authenticated via API key** -- same auth as any other actor
- ## MCP Reference
- Maskin exposes 73 MCP tools over both stdio and HTTP. See **Quick Start β Get started from Claude Code** above for the one-command setup. Other clients (Claude Desktop, OpenAI agents, custom implementations) use the same env vars (`API_BASE_URL`, `API_KEY`, `WORKSPACE_ID`) β point them at `pnpm --filter @maskin/mcp start` for stdio, or `POST http://localhost:3000/mcp` for HTTP.
- The first tool a new agent should call is `list_marketplace` β it lists the available marketplace loops, and `install_loop` installs the one the user picks.
- ## Docker
- ```bash
- # Full stack (PostgreSQL + SeaweedFS + dev server)
- docker-compose up
- # Just the database and storage
- docker-compose up postgres seaweedfs -d
- ```
- The dev server container runs migrations on startup and serves at `http://localhost:3000`.
- ## Development
- ```bash
- # Start everything (Docker + migrations + dev servers)
- pnpm dev
- # On Windows (cmd/PowerShell):
- pnpm dev:win
- # Build all packages
- pnpm build
- # Run tests
- pnpm test
- # Run E2E tests (requires running dev server)
- pnpm test:e2e
- # Lint (Biome)
- pnpm lint
- # Lint and auto-fix
- pnpm lint:fix
- # Format
- pnpm format
- # Type checking
- pnpm type-check
- # Database: generate migration from schema changes
- pnpm db:generate
- # Database: run pending migrations (automatically run by pnpm dev)
- pnpm db:migrate
- # Database: seed demo data
- pnpm db:seed
- ```
- ### Environment Variables
- | Variable | Required | Default | Description |
- |----------|----------|---------|-------------|
- | `DATABASE_URL` | Yes | -- | PostgreSQL connection string |
- | `PORT` | No | `3000` | Server port |
- | `S3_ENDPOINT` | No | `http://localhost:8333` | S3-compatible storage endpoint (SeaweedFS for dev) |
- | `S3_BUCKET` | No | `agent-files` | Storage bucket name |
- | `S3_ACCESS_KEY` | No | `admin` | S3 access key |
- | `S3_SECRET_KEY` | No | `admin` | S3 secret key |
- | `S3_REGION` | No | `us-east-1` | S3 region |
- | `S3_PUBLIC_ENDPOINT` | No | `S3_ENDPOINT` | Address browsers use to reach storage for presigned uploads/downloads of large files. Set it when `S3_ENDPOINT` is an internal host. The bucket needs CORS: see `docs/runbooks/large-file-uploads.md` |
- ## License
- Apache 2.0 β see [LICENSE](LICENSE) for details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If itβs helped, pass it on.