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.
Architecture
For maintainers. Using Akeru Bot? See docs/user.
Akeru Bot is a server runtime that owns agent sessions, workspaces, and version control, plus clients (web, desktop, mobile) that talk to it over one authenticated Effect RPC WebSocket. The server is the execution boundary: every provider process, bot command, git operation, and filesystem read happens there, never in the client.
┌────────────────────────────────────────────────┐
│ Clients: apps/web, apps/desktop, apps/mobile │
│ shared runtime: packages/client-runtime │
│ connection supervisor, RPC session, Atom state│
└──────────────────┬─────────────────────────────┘
│ Effect RPC over WebSocket (/ws)
│ contract: packages/contracts
┌──────────────────▼─────────────────────────────┐
│ apps/server │
│ orchestration engine (event-sourced) │
│ provider driver registry (6 built-in drivers) │
│ checkpointing, VCS, filesystem │
└──────────────────┬─────────────────────────────┘
│ per-driver transport
┌──────────────────▼─────────────────────────────┐
│ Provider transports: Codex, Claude, Grok, │
│ Kimi For Coding, OpenCode, OpenCode Go │
└────────────────────────────────────────────────┘
The RPC boundary
The client/server contract is an Effect RPC group, not a hand-rolled push protocol. rpc.ts
declares WS_METHODS and assembles WsRpcGroup; each member is either unary or a server stream
(stream: true). Streaming members such as orchestration.subscribeShell,
orchestration.subscribeThread, and subscribeServerConfig replace what used to be a broadcast push
bus: a client subscribes to what it needs and the server pushes only on that subscription.
ws.ts serves the group. websocketRpcRouteLayer mounts GET /ws, authenticates the upgrade
through EnvironmentAuth.authenticateWebSocketUpgrade, then hands the socket to
RpcServer.toHttpEffectWebsocket. Authorization is per method: RPC_REQUIRED_SCOPE maps each method
to a scope, and authorizeEffect/authorizeStream enforce it. Holding a valid socket is not
authorization to call everything on it. See environment-auth.md.
On the client, session.ts opens the socket and builds the typed client.
RpcSessionFactory is the service; a session exposes client, initialConfig, ready, probe,
and closed. It performs one attempt and does not retry. Retry, backoff, and offline policy belong
to the connection supervisor.
Shared client runtime
packages/client-runtime holds every non-visual client concern: connection lifecycle,
authentication, RPC, cached environment data, and domain state as Atom factories. Web and mobile
compose it the same way (apps/web/src/connection/runtime.ts and
apps/mobile/src/connection/runtime.ts mirror each other, differing only in platform-specific
background-activity layers) and differ beyond that only in the platform layer they supply and the
UI they build on top. React components never construct transports, retry loops,
or RPC clients. See connection-runtime.md.
Orchestration is event-sourced
The server does not mutate app state directly. Clients dispatch typed commands; the engine turns them into persisted events; projections derive the read model.
OrchestrationEngine.ts serializes this. dispatch offers a CommandEnvelope onto
commandQueue and awaits its result; a single worker fiber takes envelopes one at a time, so command
processing is totally ordered. For each envelope processEnvelope:
- checks the durable command receipt, making retries idempotent;
- runs
decideOrchestrationCommand(decider.ts) to produce events from command plus current state, pure and side-effect free; - inside one SQL transaction, appends events to the event store, applies them to the in-memory read
model via
projector.ts, projects them into persisted tables, and writes the accepted receipt; - after commit, swaps in the new read model, cleans up attachments, and publishes committed events to subscribers. Attachment cleanup failures are logged and do not reject committed commands.
Because persistence and projection share a transaction, the read model cannot durably disagree with the event log. On dispatch failure the engine rereads persisted events past the starting sequence and reconciles.
ProjectionSnapshotQuery.ts is the persisted read model. Client thread snapshots load
activity payloads in 25-row primary-key batches and project each batch before the next read. Shell
summary refresh uses SQL aggregates for latest user-message time, pending approval count, and
actionable-plan status, plus user-input lifecycle rows only. Provider command metadata paths use
thread shells; turn start uses a single-message query. Runtime ingestion uses a joined thread
context and keyed message, plan, and task-activity lookups instead of hydrating a full thread.
upsertMany exists for projector cursors. Runtime projectEvent still commits each projector
separately because attachment cleanup runs after each projector transaction. Combining those
commits is shared with checkpoint attachment-transaction work and is not done here.
Command and event names live in orchestration.ts. Some commands are client
dispatchable (thread.create, thread.turn.start, thread.approval.respond); others are internal
and produced only by server-side reactors (thread.message.assistant.delta,
thread.turn.diff.complete).
A turn is complete when its session leaves running status, projected by
settledTurnStateForSessionStatus in projector.ts. Checkpoint work settling later
does not define turn end.
Drainable workers
Follow-up work runs asynchronously in queue-backed workers built on DrainableWorker
or the keyed provider worker:
ProviderRuntimeIngestion normalizes provider runtime streams into orchestration commands,
ProviderCommandReactor dispatches provider calls in response to intent events, and
CheckpointReactor captures and reverts workspace checkpoints.
DrainableWorker pairs a transactional queue with a transactional count of outstanding items.
enqueue atomically offers and increments; processing always decrements. drain retries until the
count reaches zero, so a test can await "queue empty and current item finished" instead of sleeping.
Each of the three services exposes drain for exactly this.
ProviderCommandReactor uses a keyed worker with four concurrent lanes. Commands for the same
thread run in FIFO order; unrelated threads can progress while session setup waits. Its drain
retains the subscription sequence barrier and repeats when worker execution publishes more events.
Workspace entry refreshes run in the background with at most two concurrent scans. Requests for the same workspace coalesce into generations. Entry searches and lists await the latest requested generation, while checkpoint publication only queues the refresh. Browsing and content search remain separate workspace services.
Mastra attachment preparation reads bytes asynchronously in attachment order. Before admitting the turn, the controller checks that the session is still current and has not been interrupted or stopped during preparation.
Runtime receipts are a test-only mechanism. RuntimeReceiptBusLive in
RuntimeReceiptBus.ts publishes nothing; only the test layer is PubSub-backed. Do not
build production behavior on receipts.
Provider event logs in EventNdjsonLogger.ts drop canonical deltas and native
streaming chunks (Codex item/realtime methods, Claude content-block deltas, ACP
agent_message_chunk/agent_thought_chunk, OpenCode text/reasoning part updates) before
serialization. ACP request diagnostics stay on by default; full protocol logging is opt-in through
the Grok provider settings and filters the same transient session updates. Async drain/close behavior for this file is owned
separately by the desktop log-drain work and is not changed here.
Provider drivers
Six drivers ship built in, registered in builtInDrivers.ts as BUILT_IN_DRIVERS:
Codex, Claude, Grok, Kimi For Coding, OpenCode, and OpenCode Go. A driver declares its kind and config schema and creates a
scoped adapter; ProviderInstanceRegistry owns live instances and ProviderAdapterRegistry resolves
an instance to its adapter, so ProviderService routes session and turn operations without knowing
which agent is behind them. See providers.md.
Checkpointing
Each turn is bracketed by workspace checkpoints so diffs and reverts are exact. CheckpointStore
captures state as hidden Git refs through the VCS driver's checkpoint operations;
CheckpointDiffQuery answers turn and full-thread diff requests; CheckpointReactor coordinates
baseline capture, completed-turn capture, diff projection, and reverting both the workspace and the
provider conversation. The storage contract is VcsCheckpointOps in
VcsDriver.ts, implemented for Git in the same directory.
Startup
serverRuntimeStartup.ts runs a fixed lifecycle: start keybindings, settings, and
reactors; publish welcome; signal command readiness (logged as Accepting commands); wait for the
HTTP listener via markHttpListening; publish ready; fork the heartbeat; then either print headless
output or open the browser. Command readiness precedes the listener, so a socket that opens can
already dispatch.
Related
Effect conventions and migration metric
Server code should keep effectful work inside Effect.gen and named Effect.fn functions, model
resources with scoped layers and Effect.acquireRelease, and use Effect services such as Clock,
DateTime, FileSystem, HttpClient, and ChildProcessSpawner at system boundaries. Decode
untrusted data with Schema and represent expected failures with Schema.TaggedErrorClass.
ManagedRuntime is the bridge for legacy callbacks; do not scatter Effect.runPromise calls through
library code.
The migration tracks two signals in production .ts files under apps/server/src:
- Runtime escapes:
Effect.runPromise,Effect.runSync, andEffect.runForkin library code. - Promise bridges:
Effect.tryPromiseandEffect.promiseused to cross an imperative boundary.
Tests (*.test.ts) and the standalone serviceLauncher.ts bundle are excluded from both counts.
Each matching call site counts once. Run node scripts/effect-migration-metric.ts for a
production-source report. It is a reporting tool rather than a CI gate. The 2026-09-22 audit
counted 58 runtime escapes and 76 Promise bridges.
Effect language-service diagnostics run at error severity in every typecheck and cannot be
switched off inline. @effect-diagnostics comments are rejected like lint suppressions; the few
categories of code that cannot use Effect services get a config override with a written reason.
See Lint.
Pure data and mapping modules are not migration targets when they have no I/O or lifetime state.
apps/server/src/serviceLauncher.ts is also excluded: it is a deliberately Node-only standalone
bundle packed separately by build:bundle, and adding Effect imports would break that deployment
boundary. The audit also leaves type-only provider service shapes and the legitimate
returnEffectInGen cases in place.