Skip to content

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.

18.6 KB
Raw Blame

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

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".

Related Docs