Bots are reusable agents with an identity, role, instructions, model, tools, and workspace. They execute work in threads, can join project teams, and can be created from templates.

​
Open and manage a bot

Open Bots in the workspace at ai.allternit.com or Allternit Desktop. Choose a bot from the rail to open its bot screen, create a bot with the wizard, or browse a template. The bot’s ⋯ menu includes Make main bot, Promote, Duplicate and Delete.

​
The Bots rail

From top to bottom: Only one bot is the main bot at a time. Making a bot the main bot removes the flag from the previous one. On desktop, drag a bot from the Bots list (or a promoted icon) onto the main bot tile to make it the main bot, or onto the promoted row to promote it. On a phone, use the bot’s ⋯ menu. Needs-you items appear on the bots home and the project page, not in the rail. The phone drawer (ai.allternit.com phone layout and the m.allternit.com PWA) shows the same rail.

​
Your main bot

Every account has a main bot. It is your first stop: it answers directly, or hands a job to the bot that owns it and tells you who has it. The hand-off starts a task thread for that bot (on its screen and in the project) and the result comes back to the main chat; see Bots handing work to other bots. It sees the status of your bots’ threads (titles and progress), not their conversations, and never sends, posts, pays, signs or deploys without your approval.
  • The first bot you create becomes your main bot when you don’t have one yet. Built-in bots that come with the app (such as Gizzi) don’t count.
  • No main bot yet: the main bot tile opens Set up your main bot. It explains what the main bot does, then Set up A:// creates A:// from the main bot template (the same for every account) and opens its main chat with A:// greeting you first (see Bots greet you first). If you already have an A:// bot, it is reused instead of creating a second one. You can also pick one of your existing bots instead.
  • The setup opens by itself once per app session when you enter Bot Mode without a main bot. Not now closes it; the tile keeps offering it.
  • The A:// main bot template is not listed in the template gallery or in Create bot.

​
Bot screen

The bot screen opens with a large header: the bot’s photo, name, description, where it runs, its phone number, email and channels, and its status. Open phone opens the bot’s phone. Edit bot in the banner is the single entry point for editing its profile. The Settings tab and the thread’s Bot settings gear open its settings. The Chat + threads tab is the default:
  • Main chat. Every bot keeps one always-on main chat. It knows the status of the bot’s threads but not their full context, so long-running preferences and decisions stay clean. A bot with no main chat yet shows Start main chat; nothing is sent from you until you write.
  • Threads. The bot’s threads, grouped as Needs you, Working, Queued and Idle, with a project filter and search. + New thread starts a task thread; Incognito starts a private thread. Threads idle for 7 days fold into Stale (threads waiting on you never go stale). Click a thread to open it.
On desktop the main chat and threads sit side by side; on a phone they stack. The other tabs are Routines, Memory, Computer, Performance and Settings. Banner color. Use the color control in the bot header to choose a background. A:// starts with a neutral background; its avatar is the living Allternit orb and its name uses the A:// wordmark. The Bots home To: menu lets you choose a bot and defaults to the main bot or your last selection. Settings → Phone and reach holds the bot’s phone number (texting and voice calls on or off, change number), its phone, its email and channels with connect buttons, and who it can text, call or email without asking you. The rest of the bot’s configuration follows below it. The standalone Bot Hub was removed from the workspace. Its old agent-hub navigation entry aliases the Bots launch surface. Use Bots, bot home, or Project home rather than looking for the former hub tabs.

​
Bots greet you first

A bot’s main chat opens with a message from the bot, not from you: a short hello, what it does, and a question (for A://: “Hi, I’m A://, your main bot… What should I take off your plate today?”). Its suggestions sit under the greeting as chips; tap one to send it. For a bot made from a template, the first chip is the template’s first task and the rest are its starter prompts. The chips go away once you’ve sent something.
  • Nothing is sent as you. Setting up a bot from a template no longer sends its first task for you or starts a model turn. The composer is ready at once.
  • The greeting is static text from the bot’s profile (Settings → Personality → Welcome message, with Starter prompts for the chips). It shows immediately, without waiting for a model.
  • It stays. A new main chat stores the greeting as the bot’s first message (no model turn), so it survives reloads, shows on your other devices and is part of the bot’s context. Bots made before this, and chats on a runtime that doesn’t store it yet, show the same greeting at the top of the main chat from the profile.
  • Only the main chat greets. Task threads, incognito threads and later context windows open without it. The same greeting shows in Allternit Desktop, at ai.allternit.com (including the phone layout) and in the m.allternit.com PWA.
For developers: the greeting is botGreetingFor() in src/lib/bots/bot-greeting.ts (allternit-ai), rendered by BotGreeting in the bot chat view. openBotCanonicalChat() stores it when it creates a main chat by posting role: "assistant", noReply: true and metadata.source: "bot-greeting" to POST /api/v1/agent-sessions/:id/messages; the chat view hides that stored copy and draws the greeting from the profile, so it never shows twice. Template welcomes live in each template’s welcome field ({name} becomes the bot’s name).

​
Bot, thread, and subagent

Several threads can belong to one bot. A new thread does not replace the bot’s always-on main chat. A group-chat mention can open a task thread and show a live card in the room.

​
Configuration and access

Choose a model and harness the runtime can actually use. Connect the needed tools, skills, secrets, and computer before assigning dependent work. Configure role instructions and review requirements for external actions. A template is a starting recipe, not evidence that every dependency is connected. The canonical contract lives in the allternit-ai repo, src/lib/bots/BOT_AGENT_CONTRACT.md and is enforced by validateBot() in src/lib/bots/bot-contract.ts. Bot secrets use server-side secret references rather than credential values in shared recipes. Saved templates omit credentials, memory, and live threads.

​
Identity and isolated settings

A bot turn runs as the bot. The runtime marks it with a bot field on the session message, and that marker changes four things.
  • Identity. The bot’s persona (SOUL.md, its own workspace instruction files, its instructions, and its memory) comes first in the system prompt. The Code-mode “Allternit Shell, an AI coding agent” header is left out and short, neutral operating guidance takes its place. A bot does not introduce itself as a coding CLI or offer the owner’s slash commands.
  • No personal instruction files. Bot turns do not load ~/.claude/CLAUDE.md, the ~/.gizzi identity and legacy prompts, or any CLAUDE.md, AGENTS.md, or GIZZI.md found by walking up from the session folder, including files a read tool would otherwise pick up. Only files from the bot’s own agent workspace are included, through the persona.
  • No personal skills. Skills under ~/.claude, ~/.agents, ~/.openclaw, ~/.codex, or a project’s .claude/skills are hidden from bot turns. Built-in skills and skills managed in the app (~/.allternit/skills) remain available.
  • Claude CLI brain. Claude Code starts with --setting-sources "", --disable-slash-commands, and --strict-mcp-config, with the bot’s prompt passed as --system-prompt instead of being appended. Your Claude Code login still works, because sign-in is stored outside the settings files. No separate CLAUDE_CONFIG_DIR is used: on macOS that would change the keychain entry and sign the bot out. A login that depends on an apiKeyHelper in ~/.claude/settings.json is not available to bots.
Tool access follows the bot’s configuration: For restricted bots, Claude Code runs in default permission mode with --permission-prompt-tool stdio, and the runtime answers each request. An unattended turn, such as a channel message or a routine, that reaches an approval waits until someone answers it in the app. Code-mode sessions and other non-bot sessions behave as before.

​
Work and deliverables

The rail and project thread list expose work status, including server-started turns. Open a thread to steer it, inspect subagents, review artifacts, or stop active work. Generation checkpoints let long work move to a fresh model context while preserving the thread’s identity. A bot’s computer opens in the ACI pane. Artifact editor modes for Docs, Sheets, and Slides use separate artifact sessions; they are not offered as editor-pane modes inside bot threads.

​
Routines and subscriptions

Every routine runs as a bot. The bot’s Routines tab lists its routines with the schedule in plain words, the next run, the last result, the last 10 runs (each with a link to the thread it wrote to), Run now and Pause / Resume. A failing routine shows a notice on the tab, on the bot’s rail status line and in Inbox → Needs attention, and sends a notification. After 3 failed runs in a row it pauses itself. Routines with no bot appear under Needs a bot with an assign action. See Bot routines. Template routines start paused unless explicitly enabled during setup. Inspect schedules and access before enabling them. Connected consumer subscriptions have a separate Sessions-computer flow and require human initiation. Connecting a subscription does not make it an unattended model lane for scheduled bots.

​
Developer references

Bot records use the Agents API. Durable thread, project coordinator, and saved-template routes live in the private Allternit API data plane; each guide lists its runtime routes. See API overview for the public Cloud API and private runtime boundary.

​
Thread and project panes

A thread’s one-row top keeps the bot avatar, vendor provenance chip, and controls together. The avatar opens the bot screen, the bot name opens the pane, and the thread title opens the thread switcher. Use the pane menu for Thread, Browser, or Computer. On the phone, ⋯ includes Computer, the pane opens full screen, and Back returns to chat. See Thread controls and history. Bot Mode and Projects → Bot share one server project list. Projects support pin/archive, shared server context files, a per-device folder, coordinator instructions, and a pane for Threads, Library, Routines, and Browser. A thread’s model and permissions come from its bot; bot projects have no separate model or permission selectors. See Project context and panes.

​
Vendor and channel appearance

Every carried vendor (see Subscriptions) has its own thread look, with a neutral fallback for any vendor that has none yet. Slack, Telegram, Discord, WhatsApp, Microsoft Teams, email, and SMS have channel looks. Appearance does not change the connection lane or its availability. The composer remains Allternit’s by default; a vendor composer skin is an opt-in developer flag. See Vendor looks and composer setting. Gemini and Copilot are new carried vendors and are not yet verified against the live services. Sign in under Settings → Subscriptions, read the provider-terms warning, and inspect the connection before relying on it. Their connection lane is ui_bridge and best effort.

​
Edit workspace files with chat

Open Settings → Workspace & Config → Workspace to edit the bot’s personality and workspace files. The editor uses the full width, with Edit with chat across the bottom on desktop and phone. Select a file and either edit it directly or describe a change in chat. Review the suggested file, then choose Apply and save, or Discard. Saving writes the file to the bot’s runtime workspace and clears its cached copy; the bot reads the saved configuration from its next message. Changes do not rewrite earlier conversations. A bot without workspace files starts with its default files. Chat suggestions require a live Allternit Cloud sign-in and an available Cloud model, and use your Cloud allowance. Default suggestions choose a model from the live Cloud catalog, preferring the configured model family; this does not change the bot’s configured brain. If the model cannot answer, the editor remains available for direct edits. Switching files clears the previous file’s suggestions. A suggestion for content you have since edited must be regenerated, and a failed save remains an error rather than being marked applied. For developers: BotWorkspaceEditor saves through agentWorkspaceFS and invalidates the bot’s file cache. WorkspaceChatPanel proposes the complete selected file through the chat completion endpoint; a proposal is saved only when the user applies it.

​
Bot Inbox on Desktop

The Inbox shows bot messages through the local Factory API in Allternit Desktop. A deployment without that API explains where bot messages are available; a failed request offers Try again. Connecting a phone or external channel is a separate setup step under Phone and reach.

​
Layout and rail placement

Settings stays in the bot’s section tabs. Workspace files use the full page width, with Edit with chat underneath the editor and runtime information below it. Agent Gateway messaging uses the same channel marks as Phone and reach. Drag a bot onto the main tile to make it your main bot. Drop onto a promoted bot to replace that slot; dragging one promoted bot onto another swaps their positions. Release over the destination to place it; press Escape to cancel a drag. On touch screens, use the bot’s menu to promote it. Bot mascots sit on the composer’s top edge without nested tile and circle frames. Template characters use their animated sheets in the composer, rail, bot headers, launch screen and avatar previews. Hovering or focusing a bot wakes its animation; active threads drive the working state. Portrait-only avatars breathe and react to hover. Reduced-motion preferences show still poses, and hidden or off-screen sprites pause. Hover text uses the selected bot’s name and description. Session transcripts and composers keep a bounded reading width on large screens.

​
Watching a bot’s computer

In Settings → Tools, the tool list uses the connected-app catalog’s owned tool metadata. Existing qualified tool names are preserved. A failed catalog request displays its error with Retry; it does not appear as an empty catalog. Desktop also guards the optional macOS socket QoS hint against EINVAL so that the older Electron HTTP client can continue the request without showing a fatal error dialog. The live computer screen includes a message box for steering the bot’s running thread. If there is no running thread, it uses the open thread belonging to that bot, or its main chat. While you have control, enter an optional Hand-back note before choosing Hand back. The note is submitted to the bot’s thread after control returns. Failed messages reappear in the message field for retry. Pending safety approvals are restored when reopening the viewer and checked against their server status. Approvals, computer selection and connection status use the same shared viewer on Desktop and phone. The Computer steps panel shows the current action and saved steps. Choose a run and a step, scrub the timeline, or choose Replay to review recorded screens. Replay is read-only and never repeats an action on the computer. Snapshots are redacted before storage; a failed capture or redaction leaves the step visible with no snapshot. History keeps the last 500 steps per computer for up to 30 days; full images have a 100 MB budget per computer, with older full images evicted first. Runs from before recording was installed have no retrospective screenshots. While you have control, Send clipboard, Get clipboard, and Upload file move text and files between your device and the computer. You can also drop a file onto the screen (25 MB per file). The transfer result shows its destination path; uploads use a unique name to avoid overwriting files. If your browser cannot access the clipboard, use the text field. Focus the computer view and press ⌘/Ctrl + Shift + H to take over or hand back. These controls and run history are available on Desktop, the web phone layout, and the PWA. Workspace & Config adapts to its panel width, including the bot phone window on Desktop. Narrow panels stack configuration cards, scroll file tabs horizontally, wrap editor actions, and place Edit with chat below the file editor. This is shared by the web phone layout and the m.allternit.com PWA.

​
Animated character avatars

In Create or Edit Bot, open Look → Characters. Gizzi Family keeps its clay art with breathing and hover motion; Gizzi Brawl uses its animated sheets. Gizzi YouTube includes twelve show characters. Office Professionals now offers the Allternit Series cast, including Imani, Mara, Nia and Theo, with their prepared 2D expressions. Existing saved Office Professionals avatars remain available to bots that already use them. Avatars share consistent visible sizing even when their source images have different padding. Codex Carry characters have transparent backgrounds. Character expressions follow activity where available, and hover or keyboard focus wakes the preview. Offscreen and hidden-window animations pause, and reduced-motion settings show still art. The category field in Create and Edit Bot shows your saved category. Open its glass dropdown and use arrow keys to move, Enter to choose, or Escape to close.