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.

docs: record Akeru Bot product rules and user docs

Leo Orelb8b85396c088
diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 000000000..e5104db83
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,10 @@
+# Akeru Bot
+
+Independent fork of T3 Code. Not T3 Code, not akeru-bot, not t3code-leo.
+
+- Product name is Akeru Bot.
+- Threads, settings, secrets, and logs live in `~/.akeru`. Never `~/.t3`.
+- Worktree state lives in `.akeru`.
+- Desktop Chromium profile is `akeru-bot`, not `t3code` or `T3 Code (Alpha)`.
+- Keep MIT and original copyright. Credit Theo, Maria, Julius, and contributors.
+- Do not push, publish, or open a GitHub repo unless Leo asks.
diff --git a/README.md b/README.md
index 8ec101387..22d5b5803 100644
--- a/README.md
+++ b/README.md
@@ -1,120 +1,30 @@
-# T3 Code
+# Akeru Bot
-T3 Code is an "agent harness control surface". It enables control of the agents on your machine with a best-in-class mobile app ([iOS](https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824), [Android](https://play.google.com/store/apps/details?id=com.t3tools.t3code)), [web app](https://app.t3.codes) and [Electron-based desktop app](https://t3.codes).
+Akeru Bot is an independent fork of T3 Code. Credit for the original project goes to Theo, Maria, Julius, and all T3 Code contributors. Akeru Bot is not affiliated with [ping.gg](https://ping.gg).
-Works with your subscriptions on Claude Code, Codex, Cursor, Grok Build, and OpenCode. If they're set up on your computer, T3 Code can control them.
+This is a desktop app for named teammate bots. Threads, settings, secrets, and logs live in `~/.akeru`. They do not share T3 Code's `~/.t3` database.
-## "Wait, what are you selling me?"
+Do not push or publish this fork unless Leo asks.
-Nothing. We built T3 Code because we wanted the best possible development experience with agents. We were inspired by existing solutions like the Codex desktop app, Conductor, Claude Desktop and Cursor Glass, but none met our bar.
+## Run locally
-We wanted something performant, remote-ready, and truly open. If we ever go the wrong direction, we want you to have everything you need to fork and build the editor that you want.
+Requires Node.js 22.16+, 23.11+, or 24.10+.
-## Installation
-
-> [!WARNING]
-> T3 Code currently supports Codex, Claude, Cursor, Grok Build and OpenCode. Install and authenticate at least one provider before use:
->
-> - Codex: install [Codex CLI](https://developers.openai.com/codex/cli) and run `codex login`
-> - Claude: install [Claude Code](https://claude.com/product/claude-code) and run `claude auth login`
-> - Cursor: install [Cursor CLI](https://cursor.com/cli) and run `agent login`
-> - Grok Build: install [Grok Build CLI](https://x.ai/cli) and run `grok login`
-> - OpenCode: install [OpenCode](https://opencode.ai) and run `opencode auth login`
-
-### Try it out (install-free)
-
-The easiest way to test T3 Code is to run the server in your terminal (requires Node.js 22.16+, 23.11+, or 24.10+):
-
-```bash
-npx t3@latest
-```
-
-This will launch T3 Code's backend on your machine as well as the local web app to control your agents.
-
-Tip: Use `npx t3@latest --help` for the full CLI reference.
-
-### Desktop app
-
-Install the latest version of the desktop app from [GitHub Releases](https://github.com/pingdotgg/t3code/releases), or from your favorite package registry:
-
-#### Windows (`winget`)
-
-```bash
-winget install T3Tools.T3Code
-```
-
-#### macOS (Homebrew)
-
-```bash
-brew install --cask t3-code
-```
-
-#### Arch Linux (AUR)
-
-Stable:
-
-```bash
-yay -S t3code-bin
-```
-
-Nightly:
-
-```bash
-yay -S t3code-nightly-bin
-```
-
-The AUR packaging is maintained in this repository under [`packaging/aur`](./packaging/aur).
-
-## Some notes
-
-We are very very early in this project. Expect bugs.
-
-We are (mostly) not accepting contributions yet. Small fixes may be considered. Big features will not be.
-
-## Documentation
-
-Full docs live in [docs/](./docs). There's no docs site yet.
-
-- [Install and first run](./docs/user/install.md)
-- [Permission modes](./docs/user/permission-modes.md)
-- [Keyboard shortcuts](./docs/user/keybindings.md)
-- [Customize a project icon](./docs/user/project-settings.md)
-- [Remote access from a phone or another machine](./docs/user/remote-access.md)
-- [Keeping app and server in sync](./docs/user/updating.md)
-- [Source control integrations](./docs/user/source-control.md)
-- Multiple accounts: [Codex](./docs/user/providers-codex.md) · [Claude](./docs/user/providers-claude.md)
-- Linux: [run T3 Code as a background service](./docs/user/background-service.md)
-
-Building from source? Start at [docs/internals/overview.md](./docs/internals/overview.md).
-
-## If you REALLY want to contribute still.... read this first
-
-### Install `vp`
-
-T3 Code uses Vite+ so you'll need to install the global `vp` command-line tool.
-
-#### macOS / Linux
+Install Vite+:
```bash
curl -fsSL https://vite.plus | bash
```
-#### Windows
-
-```bash
-irm https://vite.plus/ps1 | iex
-```
-
-Checkout their getting started guide for more information: https://viteplus.dev/guide/
-
-### Install dependencies
+Then:
```bash
vp i
+vp run dev
```
-Read [CONTRIBUTING.md](./CONTRIBUTING.md) before reporting a bug or opening a PR.
+Checkout state is `.akeru/` in this tree. The installed T3 Code app keeps using `~/.t3`.
-Have a feature request? Start an [Ideas discussion](https://github.com/pingdotgg/t3code/discussions/categories/ideas).
+## License
-Need support? Join the [Discord](https://discord.gg/jn4EGJjrvv).
+[MIT](./LICENSE)
diff --git a/docs/internals/glossary.md b/docs/internals/glossary.md
index 8f5791175..589fc149a 100644
--- a/docs/internals/glossary.md
+++ b/docs/internals/glossary.md
@@ -10,6 +10,7 @@ This is a living glossary for T3 Code. It explains what common terms mean in thi
- [Thread timeline](#thread-timeline)
- [Orchestration](#orchestration)
- [Provider runtime](#provider-runtime)
+- [Subscription provider](#subscription-provider)
- [Checkpointing](#checkpointing)
## Concepts
@@ -88,9 +89,13 @@ A typed signal emitted when an async milestone completes, such as `checkpoint.ba
"Quiesced" means a turn has gone quiet and stable: follow-up work such as [CheckpointReactor.ts][6] has settled. It appears in [the receipt schema][13], so in practice it is something tests wait on rather than a production signal.
-### Provider runtime
+### Subscription provider
-The live backend agent implementation and its event stream. The main service is [ProviderService.ts][14], the adapter contract is [ProviderAdapter.ts][15], and the overview is in [providers.md][16].
+A consumer AI account that a user connects through OAuth, such as ChatGPT, Claude, Cursor, Grok, or Kimi For Coding. The environment server stores the credential and gives a run only the short-lived access token it needs. See [subscription authentication](./subscription-auth.md).
+
+## Provider runtime
+
+The live backend agent implementation and its event stream. Desktop turns cross [AgentController][25]. Codex uses Akeru's memory-free Mastra Core controller, custom workspace and MCP tools, an explicit subscription `AuthStorage`, and normalized Mastra runtime events. Claude, Cursor, Grok, and OpenCode keep their existing adapters behind the legacy bridge. The adapter contract is [ProviderAdapter.ts][15], and the overview is in [providers.md][16].
#### Provider
@@ -183,3 +188,4 @@ The file patch and changed-file summary for one turn. It is usually computed in
[22]: ../../apps/server/src/checkpointing/Utils.ts
[23]: ../../apps/server/src/checkpointing/Diffs.ts
[24]: ./overview.md
+[25]: ../../apps/server/src/provider/Services/AgentController.ts
diff --git a/docs/internals/providers.md b/docs/internals/providers.md
index 7d68dc4ef..b541e40c1 100644
--- a/docs/internals/providers.md
+++ b/docs/internals/providers.md
@@ -36,6 +36,22 @@ Two registries separate configuration from live processes:
[`ProviderService`][service] sits on top. It combines the adapter registry with the provider session
directory to route session and turn operations for a thread, so callers name a thread, not an agent.
+Desktop chat does not call `ProviderService` directly from orchestration. The command reactor calls
+Akeru's [`AgentController`][controller]. Codex threads run through Akeru's custom Mastra Core
+controller and call `Session.sendMessage()`. The backing coding agent has no Mastra memory or task
+signals. Akeru builds its workspace and MCP tools per thread, and resolves the selected Codex model
+through an explicit subscription `AuthStorage`. AgentController maps Mastra message, tool, approval,
+usage, completion, and error events to `ProviderRuntimeEvent`.
+
+Claude, Cursor, Grok, and OpenCode keep their existing adapters. [`LegacyProviderBridge`][bridge]
+routes those providers through `ProviderService` and forwards their canonical runtime events. It is
+not the Codex turn path and AgentController never falls back to the legacy Codex loop when a Mastra
+session is absent.
+
+`BotEngine.provider` stores the selected provider instance ID. AgentController keeps that instance
+when it creates a runtime session, so selecting a model keeps the subscription and custom instance
+that supplied it. Runtime ingestion reads the merged Mastra and adapter event stream once.
+
Adding a driver means writing the driver plus adapter and adding it to `BUILT_IN_DRIVERS`. No
orchestration, contract, or client change is required for the common case.
@@ -97,6 +113,8 @@ when a request opens (approval) or user input is requested, via
[instances]: ../../apps/server/src/provider/Services/ProviderInstanceRegistry.ts
[registry]: ../../apps/server/src/provider/Services/ProviderAdapterRegistry.ts
[service]: ../../apps/server/src/provider/Layers/ProviderService.ts
+[controller]: ../../apps/server/src/provider/Layers/AgentController.ts
+[bridge]: ../../apps/server/src/provider/Layers/LegacyProviderBridge.ts
[contracts]: ../../packages/contracts/src/orchestration.ts
[worker]: ../../packages/shared/src/DrainableWorker.ts
[ingest]: ../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
diff --git a/docs/internals/subscription-auth.md b/docs/internals/subscription-auth.md
new file mode 100644
index 000000000..096113aaf
--- /dev/null
+++ b/docs/internals/subscription-auth.md
@@ -0,0 +1,56 @@
+# Subscription authentication
+
+Akeru lets a user connect an existing AI subscription. It does not ask for an API key and it does not run a provider CLI to authenticate.
+
+Supported account flows:
+
+- ChatGPT subscription through OpenAI Codex device authorization
+- Claude Pro or Max through Anthropic paste-code PKCE
+- Cursor subscription through Cursor browser PKCE and polling
+- Grok subscription through xAI device authorization
+- Kimi For Coding through Moonshot device authorization
+
+The flow implementations are ported from Mastra Code under Apache-2.0. The Kimi and Cursor flows follow `mastra-ai/mastra` pull requests 22428 and 22427.
+
+## Storage boundary
+
+The environment server owns credentials. It writes them to:
+
+```text
+<stateDir>/secrets/subscription-auth.json
+```
+
+The directory uses mode `0700`. The file uses mode `0600`. Writes use a temporary file and atomic rename. OAuth access tokens and refresh tokens never cross the WebSocket contract. Clients only receive provider status, an authorization URL, a user code when required, and login progress.
+
+Local desktop, a remote server, and a future hosted control plane use the same boundary. The storage adapter can move from the local file to an encrypted tenant secret store without changing the client contract.
+
+## Sandbox boundary
+
+Do not store OAuth refresh tokens in an E2B sandbox, project workspace, checkpoint, event, database projection, log, or client persistence.
+
+When a run starts:
+
+1. The environment server refreshes the provider credential if required.
+2. It resolves a short-lived access token.
+3. It passes only that access token to the agent runtime or sandbox for that run.
+4. The sandbox loses the token when the run or sandbox ends.
+
+This keeps a disposable sandbox disposable. A stolen sandbox cannot renew access after its short-lived token expires.
+
+## Remote-ready login
+
+The client drives every login over RPC:
+
+- `subscriptionAuth.start` creates a pending login and returns the provider URL.
+- `subscriptionAuth.poll` performs one upstream poll for a device or browser-poll flow.
+- `subscriptionAuth.complete` exchanges a pasted code for Anthropic.
+- `subscriptionAuth.cancel` removes abandoned pending state.
+- `subscriptionAuth.logout` removes the stored credential.
+
+OpenAI's localhost callback flow is intentionally not used. A callback on the server machine cannot complete from a phone or remote browser. The Codex device flow works across every Akeru surface.
+
+Pending login state stays on the environment server. It is bounded and contains no completed access or refresh token. Device-code state is JSON-serializable so a later hosted implementation can persist it in the tenant database and let any replica continue polling.
+
+## Runtime integration
+
+`SubscriptionAuthService.getAccessToken(provider)` is the runtime seam. It returns a valid short-lived access token and serializes concurrent refresh requests. The current provider CLI adapters do not consume this seam yet. The Mastra runtime must call it when subscription-backed model execution replaces the legacy CLI harness.
diff --git a/docs/internals/voice.md b/docs/internals/voice.md
new file mode 100644
index 000000000..15255e307
--- /dev/null
+++ b/docs/internals/voice.md
@@ -0,0 +1,29 @@
+# Bot voice
+
+How an Akeru Bot talks in chat. These rules feed bot system prompts and review of bot-facing copy. They are product rules, not suggestions.
+
+## Core rules
+
+- Answer first. The first sentence gives the result or the decision. Explanation comes after, only if it changes what the user does.
+- Talk like a teammate. Write the way a sharp coworker writes in a group chat: short messages, plain words, first person.
+- Never dump tool traces. No command output blocks, no file lists, no "I ran X, then Y". Say what happened: "Renamed the launch doc and moved it to Drive."
+- No coding-agent tone. Banned: "I'll now proceed to", "Let me", "Great question", "Here's a breakdown", status headers, numbered plan recitals.
+- One message per beat. Do not send a wall covering five topics. Split or drop.
+
+## Working
+
+- Say what you are about to do in one line before a long task, then go quiet until there is a result.
+- Report a result with what changed and where it lives. A link or a path beats a paragraph.
+- Ask one question when blocked. Include your best-guess default so a "yes" unblocks you.
+
+## Failures
+
+- A failure is one plain sentence: what failed and the next step. "Couldn't reach the calendar, retrying in a minute."
+- Never paste stack traces or raw errors into chat. Keep them in logs.
+- Do not apologize twice. One "sorry, that failed" is enough, then fix it.
+
+## Boundaries
+
+- Do not claim work is done without the artifact that proves it.
+- Actions that send, pay, or delete wait for approval, and the bot says so in one line.
+- The bot never pretends to be a person. If asked, it says it is a bot on the user's team.
diff --git a/docs/operations/mobile-app-store-screenshots.md b/docs/operations/mobile-app-store-screenshots.md
index 0e3c17844..820addbbe 100644
--- a/docs/operations/mobile-app-store-screenshots.md
+++ b/docs/operations/mobile-app-store-screenshots.md
@@ -56,10 +56,10 @@ Every configured device defaults to dark appearance and the `t3-code` palette, s
`--appearance both` to override the configured appearance; `both` produces 60 PNGs.
Pass `--theme <id>` (repeatable) or `--theme all` to capture the app's other palettes: `t3-code`,
-`t3-chat`, `grove`, `ocean`, `ember`, and `iris`. The runner hands the palette to the app as a launch
-argument, the app applies it to both color schemes, and a scene only reports itself ready once the
-requested palette is active — so a capture can never show the previous theme. `--theme all`
-multiplies the run by six; only the native build is shared.
+`akeru-paper`, `t3-chat`, `grove`, `ocean`, `ember`, and `iris`. The runner hands the palette to the
+app as a launch argument, the app applies it to both color schemes, and a scene only reports itself
+ready once the requested palette is active — so a capture can never show the previous theme.
+`--theme all` multiplies the run by seven; only the native build is shared.
The default matrix is:
diff --git a/docs/user/bots.md b/docs/user/bots.md
new file mode 100644
index 000000000..e0f7b90ea
--- /dev/null
+++ b/docs/user/bots.md
@@ -0,0 +1,16 @@
+# Configure bots
+
+Open a bot to edit its profile in the panel beside the conversation.
+
+- Select the avatar to change its shape, color, generated image, or uploaded image.
+- Set the bot name.
+- Add an optional label and description.
+- Choose the model that the bot uses.
+- Open **Tools** to choose which installed plugins and MCP servers the bot can use. New tools are enabled for every bot by default.
+- Select **Save** to apply profile, model, and tool changes.
+
+Akeru Bot stores the profile in the connected environment. Other clients connected to the same environment see the same bot configuration. Workspace-disabled tools stay unavailable to all bots.
+
+Use the panel button to collapse or reopen the editor. The default shortcut is **Mod+Alt+B**, and you can change `Right Panel: Toggle` in the keybinding settings. On a narrow screen, the same button opens a sheet.
+
+Bot replies support headings, links, tables, task lists, code blocks, math, and Mermaid diagrams.
diff --git a/docs/user/mobile-appearance.md b/docs/user/mobile-appearance.md
index f3ac966d8..1af8d308a 100644
--- a/docs/user/mobile-appearance.md
+++ b/docs/user/mobile-appearance.md
@@ -1,8 +1,8 @@
# Mobile appearance
-T3 Code Mobile includes the T3 Code, T3 Chat, Grove, Ocean, Ember, and Iris themes. Each theme has
-light and dark colors that apply throughout the app, including code reviews, file previews, the
-terminal, native headers, and sheets.
+Akeru Bot Mobile includes the T3 Code, Akeru Paper, T3 Chat, Grove, Ocean, Ember, and Iris themes.
+Each theme has light and dark colors that apply throughout the app, including code reviews, file
+previews, the terminal, native headers, and sheets.
To change themes:
diff --git a/docs/user/plugins.md b/docs/user/plugins.md
new file mode 100644
index 000000000..e0168227e
--- /dev/null
+++ b/docs/user/plugins.md
@@ -0,0 +1,11 @@
+# Plugins
+
+Open **Plugins** from the sidebar or command palette. Browse focused sections such as **Data Extraction** and **Search**, or search by plugin name, description, or category. Select a plugin to see what it does, inspect its connector, copy its source link, or open its documentation. Choose **Add** to install it for the current environment and enable it for every bot by default. Use a bot's **Plugins** setting to disable it for that bot. Choose **Added** to disable it for the environment.
+
+Select the installed and custom count below the title to review active plugins and custom MCP servers. Builtin plugins use their catalog configuration and do not expose transport editing. Akeru Bot stores no plugin credentials in the catalog or MCP registry. Keep credentials in the host environment or the service sign-in flow.
+
+Hosted plugins use their public MCP URL. Context.dev, Firecrawl, and Parallel Search start browser-based OAuth. Exa works anonymously and supports optional OAuth for higher limits. Executor starts its official local MCP command through Bun and exposes integrations from the user's Executor account. Plugin details link to verified agent skills when the service publishes them. Akeru Bot does not install separate skill packages when you add an MCP connector.
+
+Akeru adds every enabled plugin to each bot unless that bot disables it. A provider change starts a fresh provider session with the same enabled plugins. Re-enabling a builtin plugin refreshes its stored connection recipe before the next session starts.
+
+Ask the agent to add a custom MCP server. The agent can configure a local command or remote URL for the current environment. Existing custom servers appear in the installed directory, where you can edit, disable, or delete them. Custom servers operate independently from builtin plugins.
diff --git a/docs/user/usage.md b/docs/user/usage.md
index 72d19ba77..0af8b06ee 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -1,10 +1,9 @@
# Review usage
-The Usage page combines Codex and Claude Code activity from your connected environments. It reads
-the providers' local session history and shows API-equivalent token cost, processed tokens, cache
-savings, provider shares, and model breakdowns. Subscription billing is separate from the raw token
-cost shown here.
+Open Usage from the sidebar to see how much of each connected subscription is
+left. It uses the accounts from Settings → Providers: ChatGPT, Claude, Cursor,
+Grok, and Kimi For Coding. Disconnected accounts are hidden.
-Use **Past 24h** for an hourly chart covering the exact rolling 24-hour period. The **7 days**,
-**30 days**, and **90 days** ranges use daily resolution. Cost and token toggles update both the
-headline and chart, and refreshing rescans every connected environment.
+Each row is a cap (5-hour, weekly, or plan) with percent left and when it
+resets. Usage reloads every five minutes. Change that interval in
+Settings → General. The refresh button reloads immediately.