docs blog library
github

Lexicon

Look up terms used in Jazz commands, configuration, and the interface.

What runs

Term What it is Where it lives
Agent A saved configuration: model, persona, tools, and reasoning settings. ~/.jazz/agents/<id>.json
Persona A system prompt plus a tool profile. Built-in: default, coder, researcher, summarizer. ~/.jazz/personas/
Skill An instruction bundle the agent loads on demand with load_skill. ~/.jazz/skills/, ~/.agents/skills/, ./skills/
Tool One callable capability: built-in, MCP-sourced (mcp_*), or user-declared. n/a
MCP server A local process or remote service that supplies tools. config
Workflow A file-defined prompt plus policy, runnable and schedulable. ~/.jazz/workflows/
Companion A specialist model used for image, audio, or video analysis or generation. See Model companions. agent configuration

Units of interaction

Term What it is How many
Conversation The thread. Identified by a caller-supplied key such as --conversation or a Telegram chat id. Holds the transcript. 1
Turn One user input through to one final answer. N per conversation
Run One execution of a turn. Has an id, a state, and a cost. 1 per turn
Iteration One LLM call and the tool batch it asked for, inside a run. N per run
Subagent A child run with its own context, working on a task delegated by its parent. N per run

A conversation contains many turns. Each run executes a prompt within that thread. Pass the same --conversation <id> to separate jazz run commands to continue one conversation.

Term What it is
Conversation log The append-only .jsonl whose replay yields a conversation. One file per conversation, one directory per agent, under ~/.jazz/history/conversations/.
Transcript The recorded messages and tool results in a conversation.

What the agent tracks about its own work

Term What it is Written by
Work state The agent’s account of what it is doing: goal, constraints, decisions, open questions, next step. One per conversation, discarded when the work ends. the model, via update_work_state
Todos The list of work, with status and priority. Rendered in the interface. the model, via manage_todos
Work journal Append-only record of what happened, written at each compaction. the runtime
Memory Facts that stay true between conversations. the model, via manage_memory

Goals and loops

Term What it is Started by
Goal An objective the agent keeps working toward, turn after turn, until it proves it holds with tool output. Each turn toward it is a cycle. See Goals and loops. the user (/goal, jazz goal), or accepting a proposal
Loop A prompt rerun on a schedule, in a conversation of its own, until it ends itself or hits a limit. Each rerun is a run. the user (/loop, jazz loop)

Content

Term What it is
Message One entry in a transcript: a role and content, sometimes tool calls or attachments. System prompts are never recorded; they are rebuilt every run.
Attachment A file going into a run.
Artifact A file coming out of one, tagged rendered (produced from data) or model (generated).
Composition An HTML chart, dashboard, calculator, or other visual page, optionally rendered to PNG. See Compositions.

Control

Term What it is
Approval A gated tool asking for a yes. Carries a toolCallId so an approver in another process can answer the right one.
Approval policy How much a run may approve for itself: read-only, low-risk, high-risk.
Risk level A tool’s own classification, which the policy is compared against.
Park A run stopping and saving itself because an approval needs a person who is not here. Resumed with jazz runs approve.
Interrupt Stopping in-flight tools from the terminal. Escape twice.
Compaction Summarizing older context to stay inside the window. Trimming removes older messages when summarizing cannot free enough room.

Connections and background work

  • Daemon: the background process that runs goals and loops and serves HTTP requests, webhooks, and peers.
  • Webhook: an authenticated endpoint that runs a fixed prompt with an external event’s payload.
  • Peer: a trusted remote agent that exchanges questions with your installation.
  • Wake trigger: a later run that resumes the conversation it was scheduled from.
  • Reminder: a scheduled note sent to you without starting an agent run.
  • Background job: a shell command run separately, with its result returned to the conversation later.
  • Remote handoff: moving a conversation to an SSH server with /detach, then reclaiming it and its file changes.

For file locations, see Runtime data.

machine-readable: /jazz/docs/concepts/lexicon.md · /llms.txt · /llms-full.txt