Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
Glossary
For maintainers. Using Akeru Bot? See docs/user.
This is a living glossary for Akeru Bot. It explains what common terms mean in this codebase.
Table of contents
- Project and workspace
- Thread timeline
- Roster organization
- Orchestration
- Channels
- Provider runtime
- Subscription provider
- Image provider
- Interface language
- Checkpointing
- Dictation
- Stored-reply playback
Concepts
Project and workspace
Project
The workspace record behind a bot's chats. Users do not manage projects directly: they are an internal workspace detail of each bot, and clients no longer show project icons or read a project file. In the orchestration contracts, a project has a workspaceRoot and a title. It does not contain threads: OrchestrationProject and OrchestrationThread are separate arrays on the read model, and a project can have zero threads. See workspace-layout.md.
Workspace root
The root filesystem path for a project. In the orchestration model, it is the project checkout where new threads run, and the base directory for optional worktrees. See workspace-layout.md.
Worktree
A Git worktree used as an isolated workspace for a thread. If a thread has a worktreePath in the contracts, it runs there instead of in the main working tree. Clients no longer offer the local/worktree choice or the defaultThreadEnvMode setting, so new threads start in the project checkout. The server still honors a thread that was created with a worktree, and names its branch with the default text generation model (textGenerationModelSelection). Git operations live behind the VCS driver contract in apps/server/src/vcs/VcsDriver.ts, implemented by GitVcsDriverCore.ts.
Thread timeline
Thread
The internal durable record for one user-facing chat and its workspace history. In the orchestration contracts, a thread holds messages, activities, checkpoints, and session-related state. Interface copy and user documentation call this a chat or conversation. See projector.ts.
Turn
A single user-to-assistant work cycle inside a thread. It starts with user input and ends when the session leaves running status, which projector.ts treats as the authoritative completion signal (settledTurnStateForSessionStatus). Checkpoint and diff work may settle afterward without changing when the turn ended. See the contracts and ProviderRuntimeIngestion.ts.
Silent run
A running turn whose provider has sent no output for SILENCE_WATCHDOG_SILENT_MS (90 seconds). Ingestion records it as a turn.silent activity and clears it with turn.silent.cleared or the end of the turn. It is a status, not a failure: nothing interrupts the turn. See silence-watchdog.md.
Temporary worker
A short-lived helper a bot starts with the Task tool during its own turn. It runs in a hidden child thread under a narrower grant, cannot start workers of its own, and is canceled when the parent turn ends. It is not a bot and is separate from bot-to-bot delegation. See providers.md.
Roster organization
The live sidebar is BotRosterSidebar. Pins and the main Bots list are a client layout over bots and groups. They must not assign or remove group members, and they must not settle chats. Drag planning lives in roster.logic.ts; pointer cleanup, insertion-gap projection, and list motion live beside it in roster.pointer.ts, roster.drag.ts, and roster.motion.ts.
Activity
A user-visible log item attached to a thread. In the contracts, activities cover important non-message events like approvals, tool actions, and failures. They are projected into thread state in projector.ts.
Bot memory
Small, server-owned Markdown context attached to one named bot: USER.md, MEMORY.md, and one
bot-specific GROUP.md per group. It is distinct from bot instructions and thread observational
memory. See memory architecture.
Memory approval
A pending request from a bot to save a shared durable fact at project, group, or workspace scope.
It appears as a chat card and a bot inbox item, and either one decides it through
candidate.decide. See shared memory approvals.
Observational memory
An automatically generated, inspectable summary of older content in one thread. It complements the recent complete-turn window and never acts as a writable group-wide memory store. See memory architecture.
Orchestration
Orchestration is the server-side domain layer that turns runtime activity into stable app state. The main entry point is OrchestrationEngine.ts, with core logic in decider.ts and projector.ts.
Aggregate
The domain object a command or event belongs to. In the contracts, that is usually project or thread. See decider.ts.
Command
A typed request to change domain state. In the contracts, commands are validated in commandInvariants.ts and turned into events by decider.ts.
Examples include thread.create, thread.turn.start, and thread.checkpoint.revert.
Domain Event
A persisted fact that something already happened. In the contracts, events are the source of truth, and projector.ts shows how they are applied.
Examples include thread.created, thread.message-sent, and thread.turn-diff-completed.
Decider
The pure orchestration logic that turns commands plus current state into events. The core implementation is in decider.ts, with preconditions in commandInvariants.ts.
Projection
A read-optimized view derived from events. See projector.ts, ProjectionPipeline.ts, and ProjectionSnapshotQuery.ts.
Projector
The logic that applies domain events to the read model or projection tables. See projector.ts and ProjectionPipeline.ts.
Read model
The current materialized view of orchestration state. In the contracts, it holds projects, threads, messages, activities, checkpoints, and session state. See ProjectionSnapshotQuery.ts and OrchestrationEngine.ts.
Reactor
A side-effecting service that handles follow-up work after events or runtime signals. Examples include CheckpointReactor.ts, ProviderCommandReactor.ts, and ProviderRuntimeIngestion.ts.
Receipt
A typed signal emitted when an async milestone completes, such as checkpoint.baseline.captured, checkpoint.diff.finalized, or turn.processing.quiesced. Receipts are a test-only mechanism: the production RuntimeReceiptBusLive publish is a no-op and only the test layer is PubSub-backed. Do not build production behavior on them. See RuntimeReceiptBus.ts and CheckpointReactor.ts.
Quiesced
"Quiesced" means a turn has gone quiet and stable: follow-up work such as CheckpointReactor.ts has settled. It appears in the receipt schema, so in practice it is something tests wait on rather than a production signal.
Delegation
Work one bot sends to another with SendToAgent. It runs in a child thread and returns a handle at once. Its finished result is acknowledged exactly once, when the parent's next turn starts or when CheckAgent reads it. See delegation.md.
Waiting on children
A thread with queued, running, or blocked delegations. Derived by isThreadWaitingOnChildren, never persisted.
Channels
External channels connect a messaging conversation (Telegram, Slack, Discord, iMessage, or WhatsApp) to normal Akeru orchestration. See channels.md and the user guide.
Channel connection profile
A reusable record for one set of provider credentials, holding only safe display data such as the provider, a name, the external identity, and optional managementUrl and webhookUrl. Credentials live in the environment secret store, never on the profile. A profile can be saved unassigned and attached later.
Channel binding
The assignment of a channel connection profile to a bot and a project, carried on the bot record. It reports health through status, lastError, failureCategory, and lastSucceededAt. Statuses are connecting, connected, needs-reconnect, failed, blocked (project unavailable), not-live (WhatsApp without a public origin), and disconnected. See the health section of channels.md.
Channel origin
The provenance record on a thread or message that came from an external channel: provider, connection, external conversation and message identities, and sender display name. It drives thread subscriptions restored on startup and the origin label clients render.
Channel delivery
The per-reply delivery state (pending, sent, failed, unknown) mirrored from the durable delivery store onto each channel-originated assistant message. unknown means provider acceptance could not be proven; Akeru never reposts it automatically.
Dictation
Hold-to-talk capture on the active client that transcribes into the current composer draft. The
session, identity binding, and draft merging live in packages/client-runtime/src/dictation, which
also binds transcription to the environment's voice.transcribe RPC. Browser capture lives in
apps/web/src/lib/dictationCapture.ts and native capture in
apps/mobile/src/lib/expoDictationCapture.ts. A transcript is applied only while the environment,
thread, draft, and draft generation still match the ones captured at start.
Computer viewer
The client window that shows a bot's Daytona computer and hands input control between the bot and one
person. The state machine and the controller that serializes RPC calls live in
packages/client-runtime/src/state/computerViewer.ts and computerViewerController.ts. The web
client renders it; mobile only points to desktop or web. See
computer-control.md.
Stored-reply playback
Reading an existing assistant message on the current client speaker. Identity, spoken-text conversion, playback ownership, and the client-local automatic-readout preference live in packages/client-runtime/src/replyPlayback. Synthesis credentials and the speech operation belong to the live-call voice work, not this module. See reply-playback.md.
Subscription provider
A consumer AI account that a user connects through OAuth, such as ChatGPT, Claude, Grok, or Kimi For Coding. OpenCode Go uses an API key instead of OAuth. The environment server stores the credential and gives a run only the access token it needs. See subscription authentication.
Image provider
The subscription that creates images for a bot, ChatGPT or Grok, chosen per bot or by the global default and independent of the bot's chat provider. Bots reach it through the generate_image tool, and each finished image is saved as an ordinary chat attachment. See image-generation.md.
Interface language
A client-local preference for interface copy. Web, Electron, and native mobile each store their own selection. It never rewrites stored messages, bot names, instructions, paths, or protocol identifiers. See interface-translations.md and app language.
Provider runtime
The live backend agent implementation and its event stream. Desktop turns cross AgentController. Codex, Claude, Grok, Kimi, and OpenCode Go use Akeru's Mastra Core controller, custom workspace and MCP tools, exact-instance server-owned access, and normalized Mastra runtime events. Standard OpenCode remains the explicit compatibility runtime because its API exposes an OpenCode-owned agent session rather than a raw model transport. The adapter contract is ProviderAdapter.ts, and the overview is in providers.md.
Provider
The backend agent runtime that actually performs work. Six drivers ship built in: Codex, Claude, Grok, Kimi For Coding, OpenCode, and OpenCode Go. See ProviderService.ts, ProviderAdapter.ts, and CodexAdapter.ts as a representative adapter.
Session
The live provider-backed runtime attached to a thread. Session shape is in the orchestration contracts, and lifecycle is managed in ProviderService.ts.
Runtime seam
The single bridge where Promise-based code (Mastra callbacks, tool handlers, library promises) re-enters AgentController's Effect runtime. Its fibers belong to the controller's layer scope, so background failures are logged and shutdown interrupts in-flight work. See the runtime seam section of providers.md.
Runtime mode
The safety/access mode for a thread or session. The contracts define four values: approval-required, auto-accept-edits, auto, and full-access. See permission modes.
Interaction mode
The agent interaction style for a thread. Only default is in use. The contracts still accept the retired plan value so older stored threads, commands, and proposed plans decode, but clients no longer offer plan mode.
Assistant delivery mode
Controls how assistant text reaches the thread timeline. In the contracts, streaming updates incrementally and buffered accumulates text. Buffered delivery is not held until the turn completes: it spills once accumulated text would exceed 24,000 characters, and flushes at approval and user-input boundaries. See ProviderRuntimeIngestion.ts.
Snapshot
A point-in-time view of state. The word is used in multiple layers, including orchestration, provider, and checkpointing. See ProjectionSnapshotQuery.ts, ProviderAdapter.ts, and CheckpointStore.ts.
Model routing
The path a bot's saved model takes to its provider. On thread.turn.start the decider rewrites the
command's modelSelection from the responding bot's engine, Mastra drivers map the slug to a wire
id such as openai/<model> or anthropic/<model> and call session.model.switch, and standard
OpenCode re-sends modelSelection per turn through the legacy bridge. Validation fails closed at
bot.create/bot.update, at turn-start preflight in ws.ts, and at AgentController.inspectEngine,
and all three only trust a provider snapshot that reports status === "ready". See
providers.md and
provider-model-routing.md.
Model reroute
A runtime report that the provider served a different model than the one requested. Adapters emit
the model.rerouted runtime event and ingestion projects a model.rerouted activity line so the
change is visible. Today only the Codex adapter emits it. See
providers.md.
Model catalog
The per-driver model list, display names, and current-versus-legacy classification, built from models.dev. Bundled at apps/server/src/provider/model-catalog.json and refetched hourly by the server, so new models reach clients without a release. Replaces the older model manifest, which pre-catalog builds still read from main. See the provider architecture model catalog section.
Checkpointing
Checkpointing captures workspace state over time so the server can diff turns and restore earlier points. Clients no longer include a diff review panel; the server still captures checkpoints and turn summaries. The main pieces are CheckpointStore.ts, CheckpointDiffQuery.ts, and CheckpointReactor.ts.
Checkpoint
A saved snapshot of a thread workspace at a particular turn. In practice it is a hidden Git ref in CheckpointStore.ts plus a projected summary from ProjectionCheckpoints.ts. Capture and lifecycle work happen in CheckpointReactor.ts.
Checkpoint ref
The durable identifier for a filesystem checkpoint, stored as a Git ref. It is typed in the contracts, constructed in Utils.ts, and used by CheckpointStore.ts.
Checkpoint baseline
The starting checkpoint for diffing a thread timeline. This flow is surfaced through RuntimeReceiptBus.ts, coordinated in CheckpointReactor.ts, and supported by Utils.ts.
Checkpoint diff
The difference between two checkpoints. On-demand diffs stay as patches; automatic turn summaries use NUL-delimited Git numstat. Query logic lives in CheckpointDiffQuery.ts, summary parsing lives in Diffs.ts, and finalization is coordinated by CheckpointReactor.ts.
Turn diff
The file patch and changed-file summary for one turn. It is usually computed in CheckpointDiffQuery.ts, represented in the contracts, and recorded into thread state by projector.ts.
Practical Shortcuts
- If you see
requested, think "intent recorded". - If you see
completed, think "result applied". - If you see
receipt, think "async milestone signal, for tests". - If you see
checkpoint, think "workspace snapshot for diff/restore". - If you see
quiesced, think "all relevant follow-up work has gone idle".