README.md

Agents

ADE does not ship a standalone agents hub page. Agent behavior is delivered through three runtime surfaces: the CTO, regular lane-bound chat sessions, and machine-owned personal chats. This feature folder documents identity, persona overlays, capability modes, the smart-memory system, and the ADE CLI tool bridge the project surfaces share.

The former worker/hiring agents were removed. There is one persistent identity — the CTO — and everything else is an ephemeral chat session. Regular sessions bind a visible lane; personal sessions use an internal compatibility lane that is never exposed as project context.

Source file map

Path	Role
apps/desktop/src/main/services/cto/ctoStateService.ts	CTO identity, session logs, daily/onboarding state, immutable doctrine, personality overlays, and system-prompt preview.
apps/desktop/src/main/services/cto/ctoMemoryService.ts	The CTO's smart-memory file store (MEMORY.md, thread-state.md, daily logs, search, injection sections).
apps/desktop/src/main/services/ai/tools/ctoOperatorTools.ts	CTO operator tools for chat spawning, lanes/PRs/git/tests, Linear reads/writes, and the saveMemory / searchMemory / readMemory memory tools.
apps/desktop/src/main/services/agentTools/agentToolsService.ts	Detects external CLI tools on PATH.
apps/ade-cli/src/cli.ts	Agent-focused ade command surface and text/JSON output formatters. Includes the ade ios-sim (alias ade ios, ade simulator) family — see iOS Simulator feature, the ade --socket app-control ... driver for live Electron apps, and the ade --socket browser ... driver for the in-app browser. `ade secrets list
apps/ade-cli/src/adeRpcServer.ts	Private ADE action RPC: registers actions, handles JSON-RPC, applies session-identity-based filtering, builds lane-scoped ADE guidance / ADE_AGENT_SKILLS_DIRS for CLI launches, injects an explicitly enabled and verified direct Computer Use MCP client into tracked Codex launches, and returns GitHub + ADE PR URLs from PR creation tools when available.
apps/desktop/src/main/utils/codexComputerUse.ts	Security boundary for direct Codex Computer Use: explicit config opt-in, stable/cache candidate resolution, executable check, and strict OpenAI code-signature identity verification.
apps/desktop/resources/agent-skills/ade-cli-control-plane/SKILL.md	Agent-facing ADE CLI control-plane guidance.
apps/desktop/resources/agent-skills/ade-mosaic/SKILL.md	Agent-facing schema for Mosaic v1 interactive cards: an agent emits a fenced ```mosaic JSON block to ask the user for structured input (select / multiselect / number / input / approval / table) and the submitted answers return as the next user message. Discovered on demand rather than named in the adeBundledAgentSkills bootstrap list; parsing/rendering live in apps/desktop/src/shared/chatMosaic.ts (see chat composer-and-ui.md).
apps/desktop/src/main/services/cli/adeCliService.ts	Desktop-side install / status / uninstall surface for the ade launcher.
apps/desktop/src/shared/adeCliGuidance.ts	Canonical agent-prompt guidance builder for finding and using ade, reading Agent Skills on demand, using socket-backed live surfaces, registering proof, and cleaning up processes. Injected into Work chats, CLI launches, ADE Code/TUI sessions, the CTO, and mobile-started runtime work.
apps/desktop/src/shared/agentSkillRoots.ts	Resolves and formats Agent Skill roots injected into prompts and CLI environments.
apps/desktop/src/shared/ctoPersonalityPresets.ts	CTO personality overlays.
apps/desktop/src/shared/types/cto.ts	CTO identity, capability mode, personality, onboarding, memory, and prompt-preview types.

Agent surfaces

CTO

One persistent project-level identity. The CTO carries a structured CtoIdentity document (name, persona, personality preset, communication style, constraints, model preferences, onboarding state, optional prompt extension) plus a smart-memory system that survives sessions, compaction, and model switches. See CTO and Identity and Personas.

Regular chat agents

Ephemeral sessions bound to a lane. They have no persistent identity document; the session state lives in the transcript and resumes across restarts. New Codex agents default to GPT-5.6 Sol, with Terra and Luna immediately below it and GPT-5.5 retained. Provider-native web, MCP/connector, image, and subagent activity is normalized into compact transcript events so every client can show what the agent did without dumping raw SDK/app-server envelopes.

On macOS, Codex agents can use the canonical mcp__computer_use tool when the user explicitly enabled the bundled Computer Use plugin or MCP server and the standalone OpenAI helper passes signature verification. The same path is installed for native Work chat and tracked Codex CLI start/resume; normal MCP elicitation consent still applies.

Personal chat agents

Ephemeral machine-owned sessions with no user-visible project, lane, repository, or PR identity. They share provider/model/turn infrastructure with regular chat but receive a neutral general-assistant prompt and a scratch cwd. Project ADE guidance, project slash-command discovery, orchestration/Linear metadata, and project workflow tools are not injected. See Personal chats.

Agent CLI install / auth from chat

When a chat targets a provider whose CLI is missing or unauthenticated on the active runtime, the chat surfaces an inline AgentCliAuthCard. The card is built by classifyAgentCliError from apps/ade-cli/src/services/agentRegistry.ts and gives the user a tracked terminal action for install or login.

The important invariant is runtime locality: a desktop window bound to a remote ade serve daemon launches the install/auth command on that remote machine, not locally.

Identity shape

type CtoIdentity = {
  name: string;
  version: number;
  persona: string;
  personality?: CtoPersonalityPreset;
  customPersonality?: string;
  communicationStyle?: CtoCommunicationStyle;
  constraints?: string[];
  systemPromptExtension?: string;
  onboardingState?: CtoOnboardingState;
  modelPreferences: CtoModelPreferences;
  updatedAt: string;
};

Capability modes

CtoCapabilityMode is persisted per CTO session log:

• full_tooling — the session connected to the ADE CLI/action bridge.
• fallback — the bridge was unavailable and the adapter used its own built-in tool set.

Tool access tiers

Tier	CTO	Regular chat	Personal chat
Provider-native general tools (reasoning, web, scratch files/shell as permitted)	yes	yes	yes
ADE project workflow guidance/actions	yes	yes	no
CTO operator (spawnChat, lanes/PRs/git/tests, memory tools)	yes	no	no
Linear tools	yes (when connected)	no	no

Standalone chat sessions connected through the ADE CLI have elevated tools hidden from tool listing and execution at the ADE CLI server boundary.

Prompt composition

The project surfaces use buildCodingAgentSystemPrompt with different identity/context prefixes; personal chat deliberately does not:

• CTO: immutable CTO doctrine, active personality overlay, persona, continuity model, memory-system guidance, environment knowledge, recent session context, injected durable memory, and the user-defined prompt extension.
• Regular chat: lane context, workflow tool guidance, and permission-mode framing.
• Personal chat: a compact general-assistant directive stating that no repository/project is attached and that explicit filesystem/shell work must remain inside the supplied scratch cwd.

Smart memory and reconstruction

The CTO's durable memory lives in files under .ade/cto/ (MEMORY.md, thread-state.md, daily/<date>.md) owned by ctoMemoryService. A deterministic flush writes the rolling summary before compaction and before model switches; a best-effort LLM upgrade refines it. refreshReconstructionContext() re-injects identity plus memory after compaction and switches. Full details in Identity and Personas.

Session logs

The CTO maintains an append-only session log. Each entry carries session id, summary, started/ended timestamps, provider, model id, capability mode, and a previous-hash pointer (prevHash) so logIntegrityService.ts can verify the chain.

IPC surface

Representative channels:

Channel	Purpose
ade.cto.getState	Fetch CTO identity and recent sessions.
ade.cto.updateIdentity	Patch identity fields.
ade.cto.ensureSession	Create or fetch the CTO's persistent chat session.
ade.cto.listSessionLogs	Read the CTO session log.
ade.cto.previewSystemPrompt	Generate a system-prompt preview for the UI.
ade.cto.getMemory / updateMemory / searchMemory	Read, rewrite, and search durable memory.

Fragile and tricky wiring

• Post-compaction identity re-injection. The CTO identity session calls refreshReconstructionContext() after chat context compaction. Missing this path loses the persona and durable memory mid-session.
• Personality preset lookup. getCtoPersonalityPreset() falls back to strategic on unknown input. Keep preset ids stable.
• Deterministic memory flush is the guarantee. The LLM summary upgrade is best-effort; the durable write must never depend on it.
• Daily log integrity hashes. Session log entries carry prevHash; manual row deletion breaks the chain and is detected by logIntegrityService.
• Standalone-chat tool filtering at ADE CLI boundary. Filtering is applied in apps/ade-cli/src/adeRpcServer.ts from the initialize payload's identity.

Detail docs

• Identity and Personas — identity storage, reconstruction, personality presets, immutable doctrine, and the memory system.
• Tool Registration — ADE CLI integration, action registration, role-based filtering, and capability fallback.

Related docs

• Personal chats — projectless agent sessions and their machine-scope isolation contract.
• CTO — the CTO thread and settings surface.
• Chat README — session lifecycle and identity session filtering.
• Chat Agent Routing — provider and model selection for agents.
• Chat Tool System — universal, workflow, and coordinator tool details.