Concepts

A quick tour of how Jean2 is structured. One server, any client, any number of workspaces.

The server

Jean2 is a single binary that runs as a background daemon on your machine. It handles everything — LLM communication, tool execution, session storage, and the API that clients connect to.

There's no container, no separate database process, no runtime to install. The binary bundles its own SQLite store, a built-in HTTP/WebSocket server, and the Bun runtime for running tools.

Clients

Clients connect to the server over WebSocket and REST. The protocol is the same whether the client is on the same machine or across the internet — local, Tailscale, VPN, or public.

Client	Platform
Desktop	Native app (macOS, Windows)
Web	npx @jean2/client — any browser, any platform

The desktop app and the web client are the same UI. Pick whichever is convenient.

Workspaces

A workspace is a directory on your machine that the agent works in. It's where tools read and write files, where the agent navigates, and where workspace-specific configuration lives.

You can have as many workspaces as you want. Switch between them instantly from any client.

Workspace-scoped configuration lives inside the workspace directory:

Path	Purpose
.jean2/mcp.json	MCP server connections
.agents/skills/	Skill definitions
AGENTS.md	Project-level instructions (injected into every session)

An agent working in one workspace cannot see or use MCP connections, skills, or AGENTS.md from another workspace.

Sessions

A session is a single conversation with the agent. It has its own message history, its own preconfig (which defines the system prompt, tools, and model), and its own permission state.

Sessions belong to a workspace. When you create a session, you pick a preconfig — that determines what the agent can do in that session.

Session features

• Compact — LLM-powered conversation summarization to stay within context limits
• Fork — Branch any session at any message
• Revert — Undo to any previous point
• Interrupt — Cancel running generation (cascades to subagents)
• Queue — Queue messages while the agent is busy

Configuration

All configuration lives in ~/.jean2/:

~/.jean2/
  .env               # API keys
  models.json        # Model definitions and defaults
  preconfigs/        # Agent personality presets
  prompts/           # Reusable prompt templates
  tools/             # Installed tools
  AGENTS.md          # Global instructions (every session, every workspace)
  data/
    agent.db         # SQLite database (sessions, messages, permissions)

Per-workspace configuration lives in the workspace directory (see Workspaces above).

Preconfigs

A preconfig defines what an agent is — its system prompt, available tools, model preferences, and capabilities. When you create a session, you pick a preconfig, and that determines the agent's behavior.

Jean2 ships with a few defaults (General, Code, Code Planning, Explore). You can create your own — drop a markdown or JSON file in ~/.jean2/preconfigs/ and it appears in the preconfig picker immediately.

Jean2 adds no hidden system message. The system prompt is exactly what you write — this is where the magic happens.

See Preconfigs for the full schema and examples.

Tools

Tools are scripts the agent can call — file operations, shell commands, web fetching, search, and anything else you add. They execute as sandboxed child processes and communicate via JSON on stdin/stdout.

Jean2 ships with 12 built-in tools (installed by jean2 init). You can also write your own or connect external tools via MCP.

See Tools for the full list and Writing Tools to create your own.