Gezel Mcp

Gezel helps you build a crew of named AI companions with distinct roles and tools, then put them to work on your projects. Their conversations, memory, and work are stored on your computer as ordinary files.

Instead of starting with an anonymous chat, you meet the Meester: a guildmaster who helps you decide which specialists you need and puts a crew together. Each gezel has a name, role, working style, tools, sessions, and durable project context. You can use local models or connect a supported cloud provider.

Project status: early preview. Gezel is usable, but installers, data formats, extension APIs, and model support may still change. Keep backups of important work and expect rough edges. Please report issues.

What “local-first” means

Gezel does not put a Bendyline cloud service between you and your models. The daemon, application state, projects, sessions, documents, memories, and rebuildable indexes live on the machine running Gezel. Primary state is stored in inspectable files where practical.

The default data location depends on how the daemon is hosted:

Local-first does not mean that every configuration is offline. Gezel uses the network when you choose a cloud model provider, install or invoke a networked toolset, search the web, download models or native engines, pair a remote inference device, or check for updates. Content sent to those services is governed by their policies. A local-model-only setup can keep inference local, but downloads and update checks can still use the network.

Packaged installs communicate with gezeld over loopback TLS using scoped bearer credentials. Gezel also runs model-authored tools and scripts, so treat untrusted content as potentially hostile and choose the security level appropriate for the project. Shared-machine deployments have an additional caveat: every account allowed to read the machine service's runtime credential is trusted as a first-party client.

Read Security Architecture for the threat model, enforced controls, and known limitations. Report vulnerabilities privately through Security Policy. Third-party components and their licenses are recorded in NOTICE.

Every release publishes a SHA256SUMS manifest and SLSA build provenance for each installer, so a download can be checked against what the pipeline actually produced. macOS and Windows installers are additionally signed and, on macOS, notarized; Linux packages are not GPG-signed, which makes these checks the verification path there. Verifying your download has the per-platform commands.

Architecture

Electron desktop app ─┐
CLI / other clients ──┼── loopback HTTPS + bearer token ──► gezeld
                      │                                     ├─ file-backed Store
                      │                                     ├─ sessions, tasks, memory
                      │                                     ├─ local/cloud model providers
                      │                                     └─ per-session MCP tool bridge
React UI ◄────────────┘

The Electron app is an OS integration shell and supervisor. The gezeld service owns state, provider routing, tools, background work, and the HTTP API. Clients use @bendyline/gezel-client instead of assuming the service runs in-process, so the same protocol works with embedded, per-user, system-service, and configured remote hosting modes.

The main workspace packages are:

See AGENTS.md for the full runtime model, disk layout, package map, and engineering conventions.

Develop locally

Source builds require Node.js 24 or newer and the pnpm version pinned by the repository (11.15.1). CI uses Node 24, whose bundled Corepack can provision that pnpm version:

corepack enable
corepack prepare [email protected] --activate
pnpm deps:install
pnpm build
pnpm dev

Useful checks before proposing a change:

pnpm typecheck
pnpm lint
pnpm test
pnpm test:e2e:web:run

The optional visual regression suite compares reviewed desktop, tablet, and phone baselines with pnpm test:e2e:visual on macOS 26 ARM64; it is available locally or by manual workflow and does not block CI.

Implementation contributions are not currently accepted. We do welcome issue reports and proposal-only pull requests; read Contributing and the specs/ guide before opening one. Contributors should also read the engineering guide, UX direction, and Code of Conduct.

License

Gezel is licensed under the MIT License. Distributed builds also contain third-party software under additional terms; see NOTICE.md.