Code TUI

a3s code launches the interactive A3S Code terminal workspace. The CLI owns startup, config discovery, session resume, updater handoff, and terminal lifecycle. The agent loop itself lives in the Rust a3s-code-core runtime and the screen is rendered with a3s-tui.

For the full product capability guide, see A3S Code TUI.

Start

Run the TUI from the workspace the agent should inspect:

a3s code
a3s code resume <session-id>
a3s code resume
a3s code update

a3s code resume without an id resumes the newest saved session in the current workspace. a3s code update enters the same updater path as /update inside the TUI.

Config Discovery

Config discovery checks, in order:

On first launch, when no config is found, the CLI creates a starter ~/.a3s/config.acl and opens it in the built-in editor. Real provider credentials should be supplied through environment variables or a host secret system rather than committed into repository files.

Project-local config can set model/provider choices, OS endpoint, flow_dir, agent_dir, mcp_dir, skill_dir, memory and session storage, delegation, and asset paths.

Session Lifecycle

Sessions are persisted under the current workspace's TUI session store. On exit, the CLI prints the exact resume command for the current session.

The TUI can also branch and reset state from inside the session:

Runtime Boundaries

The terminal app is not a hosted service. It binds four local surfaces into one interactive product:

Local work remains available without /login: chat, file edits, workspace tools, MCP, memory, /ctx, /kb, task, parallel_task, local asset drafting, DynamicWorkflowRuntime, DeepResearch fallback, and local loops.

After /login, the session also registers the OS runtime tool and unlocks RemoteUI ViewLinks, OS asset publishing, Function as a Service, Workflow as a Service, Knowledge service deployment, and asset activity panels.

Use Workers

Before terminal takeover, Code reuses a healthy A3S Use installation or installs its verified release when networking and automatic setup are allowed. --offline, A3S_OFFLINE=1, and A3S_NO_AUTO_INSTALL=1 remain strict zero-network, zero-receipt boundaries. Setup failure is non-fatal and Code continues without application routes.

When Use is ready, Code gives initial registry discovery one second and initial MCP projection a separate five-second budget. Ready Browser, native Office, OCR, and installed extension routes are advertised before the first model turn; slower routes continue converging in the background.

Code registers one restricted use worker in the live task and parallel_task agent catalogs. It can call only mcp__use_* tools: it cannot use the workspace, shell, unrelated MCP servers, or recursive delegation. The primary model never receives the raw application tools.

The TUI projects standard child progress into a capability-oriented lifecycle. For example, mcp__use_browser__browser_open appears as Using Browser while live and Used Browser after completion. Terminal outcomes remain explicit, so a failed Office run renders as Agent failed: Used Office. Multiple capability routes are deduplicated, and a restored tracker snapshot reconstructs the same identity. This presentation uses the existing subagent events and does not add a private RPC protocol.

WebView First Use

Before terminal takeover, Code also reuses a healthy webview component or installs its checksum-verified platform release. The resolved absolute path is passed directly to RemoteUI and Agent Island, so a managed install does not depend on PATH refresh. Setup failure is non-fatal and emits recovery commands: a3s doctor webview and a3s install webview.

Offline mode and A3S_NO_AUTO_INSTALL=1 remain strict no-network, no-receipt boundaries. macOS and Linux are the broad managed-component targets; WebView also has a verified Windows x86_64 release and first-use lifecycle. Broader native Windows component support remains on the roadmap, and WSL follows the Linux contract.

Slash Command Families

The CLI command palette delegates to the A3S Code TUI command registry:

/flow is OS Workflow as a Service for workflow assets. It is intentionally separate from DynamicWorkflowRuntime, the local A3S Flow-backed runtime used by ultracode and ? DeepResearch for per-turn dynamic orchestration.

Effort And Dynamic Work

/effort changes the active depth profile. The TUI scales thinking budget, tool-round budget, continuation count, and prompt guidance from low through max. ultracode is the deepest profile: trivial turns can still run directly, while complex turns may use planning, goal tracking, dynamic_workflow, native host-side parallel_task, and signed-in runtime.

PTC scripts run inside QuickJS, so they do not execute parallel_task directly. Dynamic workflows schedule a Flow step named parallel_task; the TUI host then runs the native local fan-out implementation outside QuickJS.

Updates

/update, a3s code update, and a3s self update use the same self-update machinery. The hidden legacy a3s update route exists only for transition compatibility; optional components use a3s upgrade. Homebrew installs refresh the tap and upgrade the formula. Standalone installs download the matching release asset, swap the a3s binary, and verify the target version before treating the update as successful. If restart fails after a successful update, the TUI prints the resume command for the saved session.

Headless Smoke Mode

Set A3S_CODE_TUI_SMOKE=1 to exercise the agent-stream integration without taking over the terminal:

A3S_CODE_TUI_SMOKE=1 a3s code

This is useful for release smoke validation of startup, config discovery, model selection, session creation, and AgentSession::stream() wiring.

Related Pages

1. A3S Code TUI
2. CLI Commands
3. CLI Updates
4. A3S Code Commands