gezel

Build on Gezel The engine behind the app is yours to build on.

The desktop app is one way into a local service that runs the crew, the craftbooks, the tools and the models. The same service answers a command line, an SDK for your own apps, and AI Apps that install right into Gezel.

Open source under the MIT license and published on npm. It all runs on the person’s own computer, with no Gezel account or server in between.

npm install -g @bendyline/gezel-cli
Developer docs 
Desktop app the workshop window gezel CLI terminals and scripts Your app through gezel-app-sdk
gezeld the Gezel service, on your computer
  • Projects
  • Crew
  • Craftbooks
  • Scripts and tools
  • Knowledge
  • AI Apps
On this computer llama.cpp · MLX · DwarfStar · Device app models In the cloud Claude · Codex · OpenAI · Copilot
Every way in reaches the same service, and the service reaches every model.

Three ways to build

Start from a terminal, from your own app, or from inside Gezel. All three reach the same crew and the same models.

The command line

Build workflows with the CLI

The gezel command drives the same service the desktop app uses. Start craftbooks, send one-shot prompts and wait for the results from a terminal, a script or a server.

Install @bendyline/gezel-cli with Node.js 24 or newer. You don’t need to install or open the desktop app.

Terminal
# Install once
$ npm install -g @bendyline/gezel-cli

# Start a craftbook in this folder’s project and wait
$ gezel do summarize-long "Summarize notes.txt for the board" --wait

# Set any parameter by name
$ gezel do powerpoint-deck "A deck about Delft" audience=investors

# One-shot prompt, reply on stdout
$ gezel run "Draft a friendly reminder about Friday’s deadline"
  • Run any craftbook as a task

    gezel do starts any of 290+ tested plans in the folder’s project. Plain words become the request and key=value sets parameters. Add --wait --json for one result and an exit code a script can branch on.

  • One-shot prompts

    gezel run sends a prompt and prints the reply. It uses the service that’s already running, or starts one for that single call and shuts it down afterwards.

  • No desktop app required

    The npm package works on its own, including on first use and on a server. It finds or starts your own background service, and gezel start --web opens the full interface in a browser.

  • Watch and steer the crew

    List, inspect, pause and resume tasks across every project. gezel mode sets how active AI may be, from read-only to full play, and gezel stop --keep-running is the emergency brake.

  • Models, engines and media

    See which catalog models fit this computer, pull one and make it the default, or export it as a portable .gezmodel file. Make images, video and narration from the terminal too.

  • Build knowledge catalogs

    Compile a folder of Markdown into a portable .gezk catalog with keyword and semantic search. Search it offline, then install it so your crew can cite it.

Connected apps

Add local AI to your app

Give a Node.js or Electron app OpenAI-style chat and embeddings on local models. Gezel takes care of model downloads, consent and the inference service, and your app keeps its own interface.

Install @bendyline/gezel-app-sdk in your app. The Node entry needs Node.js 24 or newer.

TypeScript
import { connect } from '@bendyline/gezel-app-sdk';

// The person approves this app once, in Gezel.
const app = await connect({
  appId: 'acme.notes',
  appName: 'Acme Notes',
  scopes: ['openai'],
  tokenStorage, // keep the token in the OS keychain
});

const models = await app.models();
const stream = await app.chat({
  model: models.data[0].id,
  messages: [
    { role: 'user', content: 'Give this note a short title.' },
  ],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}
  • OpenAI-style APIs

    List models, chat with or without streaming, create embeddings, and make sure a model is installed and warm. The list can include the person’s helpers, each with its own character and tuned model.

  • Consent built in

    Ask for the narrowest scope and the person approves it in Gezel. Access to projects, knowledge or images also shows a code in your app to type into Gezel. Any connection can be revoked in Settings → Integrations.

  • With or without Gezel installed

    connectOrHost uses the person’s Gezel when it’s running and starts a private one inside your app when it isn’t. Models they already have are reused, and a bundled .gezmodel lets a first run work offline.

  • Your tools, offered to the crew

    Register tools whose handlers run in your app. Helpers see them beside Gezel’s own, arguments are checked against your schema first, and every call shows up in the transcript and History.

  • The full product API

    Pair the SDK with @bendyline/gezel-client to work with projects, tasks, chats and scripts through a typed client, while the SDK keeps discovery, pinned TLS and the scoped token.

  • Just the models, if that’s all you need

    @bendyline/gezel-inference runs on-device engines such as llama.cpp and MLX in your own process, with no projects, chats or tools attached. DocBlocks uses it for writing and review.

AI Apps

Build apps that live in Gezel

Package a page, scripts, a crew and craftbooks into one app that installs into a project. A language trainer, a research room or a board game can each feel like its own application, with the whole workshop underneath.

Build it with the gezel app commands, by hand, or with an AI agent.

Terminal
# Scaffold a source folder that already validates
$ gezel app new my-app --with-page
$ cd my-app

# Every finding at once, then a package
$ gezel app validate .
$ gezel app pack .             # → my-app-1.0.0.gezapp

# Review and install it, then make a folder its project
$ gezel app add my-app-1.0.0.gezapp
$ cd ~/reading-circle && gezel app apply my-app
  • One package, every part

    A project type ties it together: setup questions, the crew, craftbooks, scripts, seed data, schedules and an Output page. Use only the parts your app needs. A page and a folder are already an app.

  • An interface in plain HTML

    The Output page is ordinary HTML, CSS and JavaScript. Gezel provides window.gezel to read the files it declares, watch them change, query indexed tables and call declared tools, and the page follows Gezel’s theme.

  • Scripts with declared powers

    Actions and checks are TypeScript built on @bendyline/gezel-sdk. Each script lists the capabilities it needs and runs in Gezel’s sandbox. Pages have no raw write API, so every change goes through a declared tool.

  • A crew and repeatable work

    Give the app helpers with a working character each, and craftbooks that turn a job into checked steps. Or reuse any of the 41 characters and 290+ craftbooks in the catalog.

  • Validate, pack and share

    add shows the publisher, contents and dependencies before anything installs, and never runs what’s inside. Share a .gezapp privately, serve its page as a mini-site, or contribute it to the public collection.

  • Made for AI agents to build

    Live JSON Schemas, validate --json with stable rule ids, and three example apps of graded size let an AI agent build an app with the same loop a person uses.

More building blocks

Every package is open source and semver-versioned, and needs Node.js 24 or newer. Install the one at the top of your use case; npm brings in the rest.

The full package map 

Built on the same guardrails

Stays on the computer

The service listens only on the person’s own machine, over an encrypted local connection whose credential changes every time it starts. API keys go straight to their provider. There’s no Gezel server to pass them through. The security model

Consent people can see

Each app asks for the narrowest scope it needs, and the person approves it in Gezel. Wider access also shows a code in your app for them to type in. Every connection can be revoked in Settings → Integrations. Integrations

Code that stays in bounds

Scripts declare the capabilities they use and run in a sandbox, behind an operating-system wall where one is available. App pages change files only through declared tools, so every change stays auditable. The script SDK

Start building tonight.

Free and open source, for macOS, Windows and Linux.

npm install -g @bendyline/gezel-cli

Developer docsDownload the desktop app