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
- Projects
- Crew
- Craftbooks
- Scripts and tools
- Knowledge
- AI Apps
- Open source, MIT license
- Packages on npm
- OpenAI-style model APIs
- No Gezel server in between
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.
Build workflows with the CLI
Start craftbooks, send one-shot prompts, and wait for the results from a terminal or a script.
The gezel command line
Add local AI to your app
OpenAI-style chat on local models for Node.js and Electron. Use the person’s Gezel, or host one inside your app.
Connected apps
Build apps that live in Gezel
Package a page, scripts, a crew, and craftbooks into one app that installs into a project.
AI Apps
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.
# 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 dostarts any of 290+ tested plans in the folder’s project. Plain words become the request andkey=valuesets parameters. Add--wait --jsonfor one result and an exit code a script can branch on. -
One-shot prompts
gezel runsends 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 --webopens the full interface in a browser. -
Watch and steer the crew
List, inspect, pause and resume tasks across every project.
gezel modesets how active AI may be, from read-only to full play, andgezel stop --keep-runningis 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
.gezmodelfile. Make images, video and narration from the terminal too. -
Build knowledge catalogs
Compile a folder of Markdown into a portable
.gezkcatalog 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.
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
connectOrHostuses 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.gezmodellets 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-clientto 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-inferenceruns 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.
# 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.gezelto 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
addshows the publisher, contents and dependencies before anything installs, and never runs what’s inside. Share a.gezappprivately, serve its page as a mini-site, or contribute it to the public collection. -
Made for AI agents to build
Live JSON Schemas,
validate --jsonwith 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.
-
Scripts
@bendyline/gezel-sdk
Typed automations that run inside a project: tools for your crew, hooks on a craftbook step, or gates that hold a step until the work is right.
-
Knowledge catalogs
@bendyline/gezel-knowledge
Compile, verify and search .gezkcatalogs from your own code, with full-text and vector search built in. -
Gezel’s tools over MCP
@bendyline/gezel-mcp
A stdio MCP server that gives any MCP host Gezel’s workspace, memory, document, task and media tools.
-
OpenAI and Ollama endpoints
Settings → Integrations
Point any tool that speaks OpenAI-style APIs at Gezel’s local address. Turn on Ollama emulation for tools that only look on Ollama’s port.
-
The typed client
@bendyline/gezel-client
The complete service API from TypeScript: projects, crew, chats, tasks, scripts, models, memories and usage.
-
The service itself
@bendyline/gezel-service
Run gezeldheadless or embed it in your own product: state, provider routing, chat sessions, tools, tasks and the HTTP API.
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