Agents

BLXAde supports several agent surfaces. They share the same project and tool runtime, but with different principals (what each client is allowed to do).

Global Agent

The Global Agent is the built-in in-app assistant (OpenRouter).

Setup

1. Open Settings → Connections (or complete the Global Agent onboarding step).
2. Save your OpenRouter API key.
3. Verify the connection.
4. Choose a tool-capable model and optional thinking/effort level.

Keys are stored in the native OS keyring after import. A one-shot ~/.blxade/.env import is supported; the plaintext file is deleted only after a successful import.

What it can do

The Global Agent receives the broadest built-in tool set, including:

• Project open/create/switch/close
• Terminal list/spawn/read/send/control/wait/follow
• Browser preview control
• Canvas node control (screenshot, move, handoff)
• Todo, GitHub, Markdown, Mermaid, Maker/Plan, Loops, Usage, Music, Memory, image generation (where configured)
• Semantic app control (Settings sections, navigation, node lifecycle) — see App control
• Orchestration tools to delegate/list/cancel/track sub-agent tasks (agent_task_*, agent_updates_read, …)

Context for long runs stays RAM-only in the native process; the UI shows bounded history.

Runs and phases

• One active run at a time (AlreadyRunning if a second starts)
• Cancel via UI / Esc (system shortcut) when supported
• Phases stream reactively (thinking, executing app/project/terminal/loops/ images/GitHub, finalizing, cancelling)
• Terminal outcomes go to the Notification Center (completed / needs input / failed) without storing full answer text durably

Handoff from agent terminals

From an agent terminal header, Handoff asks the Global Agent to read a masked terminal history and write a compact Markdown handoff to the clipboard via a dedicated tool call. Success requires that write to complete.

Local agent CLIs

BLXAde discovers installed agent CLIs and can place them as terminal nodes.

Settings → Agents

• Rescan discovery
• Enable agents for the canvas menu
• Install or remove hooks (opt-in, marker-guarded)
• Install or remove per-agent MCP so the CLI talks to the running BLXAde app

Supported provider kinds for MCP adapters include Antigravity, Claude, Codex, Cursor, Gemini, Grok, Kimi, and OpenCode (exact availability depends on what is installed on your machine).

Agent CLI tool scope

Agent CLIs using BLXAde MCP get project, terminal, browser, orchestration, GitHub, Markdown, Mermaid, Maker/Plan, and scoped memory tools — not the full Global-only set (for example some music/canvas/app-control tools stay Global).

Hermes

Hermes is a separately installed local agent controlled through Hermes’ TUI Gateway.

• Open the Hermes node from the canvas Apps menu
• Sessions list splits This project vs other Hermes sessions
• Project sessions can receive a managed BLXAde MCP overlay (blxade-managed)
• Global/unclassified sessions use an unprivileged gateway without managed MCP

Configure sidebar defaults and related options under Settings → Hermes.

Local MCP server

While BLXAde is running:

• A loopback-only (127.0.0.1) Streamable-HTTP MCP server starts
• Bearer authentication is required
• An ephemeral descriptor is written under ~/.blxade/run/ and removed on exit
• The blxade-mcp sidecar bridges stdio clients into the running app

External MCP clients

Generic external clients typically see:

• Project tools
• Loopback browser display/close

They do not get arbitrary project code execution or the full agent catalog.

Tool catalog note

V1 does not load user plugins. Tools are a compiled, validated catalog shipped with the app (projects, terminals, browser, usage, music, todo, markdown, mermaid, makers, loops, image-gen, canvas, app-control, memory, …).

Hermes boot prep

When Hermes is enabled, startup may show progressive boot status while Gateways warm. Preparation is fail-soft: the app continues if prep is slow; first real sessions may finish MCP reload then.

Related settings