#A3S Code TUI

a3s code is the interactive terminal workspace for A3S Code. It is shipped by the a3s CLI, drives the Rust a3s-code-core runtime, and renders the runtime event stream with a3s-tui.

Use the TUI when you want the ready coding-agent product in a terminal. Use a3s-code-core when you are embedding the same runtime in another Rust host, runner, IDE bridge, or controlled product surface.

#Surface Map

#Install And Start

Run the installer for your platform:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.sh | sh

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
irm https://raw.githubusercontent.com/A3S-Lab/a3s/main/install.ps1 | iex

The scripts select the release archive for the current system and architecture and verify its SHA-256 digest. You can also use brew install a3s-lab/tap/a3s or cargo install a3s.

After installation, run the CLI from the workspace the agent should inspect:

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

The top-level a3s update command reaches the same updater as TUI /update.

#First Launch And Config

The TUI discovers config in this order:

1. A3S_CONFIG_FILE
2. .a3s/config.acl while walking upward from the current directory
3. ~/.a3s/config.acl

On first launch, when no config exists, the CLI creates a starter ~/.a3s/config.acl and opens it in the built-in editor. Use /config later to edit the active ACL file from inside the TUI.

Project-local config can set models, providers, an optional A3S OS endpoint with os = "https://...", flow_dir, agent_dir, mcp_dir, skill_dir, storage, memory, delegation, and asset paths. Keep real keys, private provider URLs, tenant identifiers, and user-specific paths out of committed examples. Resolve credentials through environment variables:

default_model = "provider/model-id"
max_parallel_tasks = 8
os = env("A3S_OS_URL")

providers "provider" {
  apiKey = env("PROVIDER_API_KEY")
  baseUrl = env("PROVIDER_BASE_URL")

  models "model-id" {
    tool_call = true
    limit = {
      context = 128000
      output = 4096
    }
  }
}

#Capability Overview

a3s code combines the coding chat loop, file and config editing, durable context, memory, local asset development, optional host integrations, runtime fan-out, trusted runtime views, and engineered automation loops.

DeepResearch writes progressively publishable artifacts to .a3s/research/artifacts/<run-id>/report.md and .a3s/research/artifacts/<run-id>/index.html. The independent a3s-deep-research crate owns orchestration, evidence admission, typed claim-graph compilation, quality gates, and rendering; CLI, TUI, and A3S Web share one typed runner and supply only product adapters.

The request language is pinned across planning, admission, and publication. Comprehensive publication requires report-wide volume and source diversity plus a multi-step analytical chain in every resolved material dimension: multi-source facts, comparison, mechanism or trade-off analysis, cross-source synthesis, and a supported implication or applicability boundary. Repeated openings, near-duplicate claims, and source-by-source summaries do not satisfy that gate. A closed narrative plan selects natural headings and paragraph groups without changing evidence; rendering uses continuous prose and keeps traceability in a collapsed disclosure.

The self-contained HTML follows A3S Web's design tokens with a sticky left action menu, centered editable report, sticky right table of contents, save and print actions, and a responsive stacked layout. Each run also records a bounded .a3s/research/runs/<run-id>/journal-v2.jsonl projection without absolute artifact paths. Complete material coverage publishes synthesized; supported incomplete work may publish depth-gated qualified; failed synthesis preserves source_backed; and an empty safe-source set produces no_evidence.

#Browser, Office, And OCR Through A3S Use

A3S Use is an independently released first-use component. Before terminal takeover, a3s code reuses a healthy install or installs the verified release when networking and automatic setup are allowed. --offline, A3S_OFFLINE=1, and A3S_NO_AUTO_INSTALL=1 remain strict no-mutation boundaries. Setup failure is non-fatal and remains visible through /use. Runtimes and model assets can also be prepared explicitly:

a3s install use --source release
a3s install use/browser

# Optional OfficeCLI compatibility provider. Native Office is built into Use.
a3s install use/office

# Install or repair the pinned local PP-OCRv6 models.
a3s install use/ocr
a3s use ocr doctor --json

When the parent Use binary is ready, Code consumes its versioned capability registry and watches both generation and content revision. Provider changes and extension enable, disable, install, or upgrade events then hot-plug their MCP and verified SKILL.md surfaces into the current session. If first-use setup was disabled or failed, install the parent explicitly and restart Code once; later capability changes do not require a restart.

Use /use or /use status to inspect the binary path/version, registry convergence, provider readiness, MCP connection/tool count, and verified/loaded Skills. /use repair prints non-destructive repair guidance only. It never runs an installer or changes extension state.

The primary coding model intentionally does not receive raw mcp__use_* definitions. It sees a dedicated use worker through task and delegates application work to that worker. The worker can see only mcp__use_*; it cannot use shell, workspace, unrelated MCP, or recursive delegation tools. Managed Skills provide domain guidance but cannot widen this permission boundary. Ask naturally, for example, “Use Browser to inspect this page,” “Use Office to update this workbook,” or “Use OCR on this scan.” If a capability is unavailable, the worker reports the typed failure instead of falling back to another tool. The default Browser surface includes doctor and a bounded installer; missing managed Browser files can therefore be prepared inside the Use worker only after parent TUI confirmation.

The projected routes are intentionally distinct:

MCP behavior metadata is escalation-only. An operation is frictionless only when it declares readOnlyHint=true, openWorldHint=false, and is not destructive. Missing annotations, open-world access, mutation, destruction, or submit risk asks the parent TUI; a parent denial remains authoritative. Office mutations are never retried automatically. In particular, use.office.outcome_unknown means the change may already have been applied, so the worker preserves the evidence and stops.

Structured MCP output is not flattened away: Code retains output schemas, structuredContent, images, text/blob resources, protocol metadata, and SHA-256-addressed bounded artifacts for the normal transcript/tool-result path.

#Browser, Office, And OCR Through A3S Use

A3S Use is an independently released first-use component. Before terminal takeover, a3s code reuses a healthy installation or installs the 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; install the parent explicitly and restart Code once if first-use preparation was disabled or failed.

When Use is ready, Code consumes its versioned registry and gives the initial MCP projection a separate bounded window. Browser, native Office, OCR, and installed extension routes are exposed only through a dedicated use worker. The primary model never sees raw mcp__use_* tools, and the worker cannot use the workspace, shell, unrelated MCP servers, or recursive delegation. Managed Skills provide domain guidance without widening that boundary.

#Interaction Model

The main screen is an event-driven transcript. User messages, model text, reasoning deltas, tool starts, streamed tool output, approvals, subagent progress, plans, memory events, and final summaries arrive as structured runtime events and are rendered incrementally.

Assistant Markdown is source-backed and newline-gated. Stable rows are paced through an adaptive commit queue, deep or stale queues catch up automatically, and active tables remain in a replaceable tail until completion. Tail updates reuse the wrapped transcript prefix; terminal resize still reflows both regions from raw source without truncating headings, code, URLs, graphemes, or cells.

The UI keeps long-running work observable. The transcript can show streamed model text, tool input/output, progress deltas, approvals, runtime view buttons, dynamic-workflow artifacts, subagent activity, queue entries, memory events, and context-fill warnings. Ctrl+T opens the complete live semantic transcript, including the current Markdown tail and full tool output. The /tasks panel reads the current session's authoritative task snapshots while the parent turn keeps streaming. It keeps every running task plus bounded recent history, refreshes every second, preserves selection across reordering, searches task metadata, progress, and output, opens full details, and requires a second matching cancellation action. The standalone a3s top command shows local process activity outside the TUI.

/permissions remains available while the parent turn streams. It separates ephemeral session grants from project grants stored in .a3s/permissions.acl, preserves selection while filtering, and opens the authoritative canonical arguments. X or Delete must be repeated on the same row before revocation. Both scopes update the live checker immediately; project removal then performs an atomic a3s-acl rewrite and restores the grant if persistence fails. Revocation affects future checks only and does not cancel tools already running.

Pending follow-ups use Lane priority and FIFO metadata, while each row retains its submission-time execution mode, attachments, and Plan state. /queue selects rows by stable sequence: Up/Down or the wheel moves selection, Enter or S sends the selected row now, Delete or D removes one row, and C opens a separate clear confirmation. Esc closes the modal without changing the composer draft. During a live turn, Enter on an empty composer sends the queue head now.

Prompt recall remains available through Up/Down. For longer sessions, /history or Ctrl+R opens a fuzzy-searchable catalog capped at 100 matches. Results rank by relevance and recency, repeated prompts retain distinct positions, repeated Ctrl+R cycles matches, and Enter or Tab restores the selected prompt. Esc closes the panel without changing the existing draft.

/copy selects the current live assistant tail when one exists, then falls back to the latest committed assistant response. /copy transcript uses the same stable semantic Markdown projection as /export: user and assistant messages, visible tool lifecycle/output, and visible delegated-task results. Private reasoning, transient UI notices, terminal-width-dependent rows, and hidden duplicate cells are excluded. Native clipboard delivery is reported only when verified; otherwise the TUI describes the OSC 52 request and its 64,000-byte UTF-8 payload bound.

/export generates a unique session-and-time filename in the workspace root. An optional path is interpreted relative to the workspace, may target an existing directory, and is created atomically with private permissions. Parent traversal, escaping symlinks, missing parent directories, and existing targets are rejected instead of overwriting or writing outside the workspace.

#Sessions And Safety

Core session snapshots auto-save under <workspace>/.a3s/tui/sessions/v1/sessions; TUI-owned per-session state is stored under <workspace>/.a3s/tui/session-state/v1. Exiting prints the complete a3s code resume <session-id> command and highlights it when color output is enabled. a3s code resume without an id resumes the newest saved session in the current workspace. Resume restores the selected model and credential source, effort profile, execution mode (default, plan, or auto), and syntax theme. /fork copies the current transcript into a new session id while keeping the original. /fork worktree also creates an a3s/fork-<id> branch in a sibling .a3s-worktrees directory, transfers tracked and untracked workspace content through a binary patch, and copies the complete session into that isolated workspace. It excludes TUI persistence from the patch, never changes the real Git index, and prints the exact command for opening the fork.

Ordinary user turns retain bounded pre/post Git tree checkpoints. /rewind forks the pre-turn conversation and reverses the last file patch only after a whole-patch conflict check succeeds. A later edit to a touched file causes a full refusal instead of an overwrite. HEAD, the real Git index, and the original session remain unchanged. In a non-Git workspace, conversation rewind still works and reports that file rewind was unavailable. /clear starts a fresh conversation.

If exit interrupts a durable /goal, the goal is saved as paused. The resumed TUI presents Resume goal and Leave paused: resume continues the next goal iteration without changing the restored execution mode, while leave enters the session with the goal paused so /goal resume can continue it later.

The TUI owns human-in-the-loop approval, but approval is a sandbox-boundary event rather than a tool-category event:

Shift+Tab cycles Default, Plan, and Auto. A running or queued turn keeps the mode captured when it was submitted. Permission and confirmation routing are snapshotted at run admission; delegated, parallel, Skill, and background descendants keep that snapshot after the composer advances to another mode. Tool execution timeouts and confirmation timeouts are tracked separately, so waiting for a human does not consume the command runtime budget.

/permissions makes remembered grants inspectable and revocable. Session and project scopes remain distinct, exact arguments are available through Enter, and a second matching X or Delete is required. Project changes use an atomic a3s-acl rewrite; revocation affects future checks only.

All local filesystem work stays under active workspace services and A3S Code permission policy. Local chat, file edits, subagents, MCP, memory, asset drafting, and DynamicWorkflowRuntime work without /login. Account-backed runtime tools, hosted asset publishing, trusted view links, and hosted activity panels are available only when a host explicitly configures and registers them.

#Tool Runtime

A3S Code TUI exposes tools through the session registry, not by letting the model run arbitrary host APIs. Each tool call carries a name, JSON arguments, streamed output, timeout policy, permission decision, and traceable event id.

#Local process sandbox

Before terminal takeover, the TUI reuses a verified user-wide managed SRT installation or the exact support tree carried by an official CLI archive. The release tree is accepted only after its package graph, file types, size bounds, and complete normalized digest match the CLI. It requires Node.js 20.11 or newer, performs the Core capability handshake, and does not select a global srt installation.

There is no silent host fallback. Offline mode and A3S_NO_AUTO_INSTALL=1 may use verified state or the release payload without mutation. Source and Cargo installs without that payload may use a fixed npm development bootstrap only when automatic first-use setup is allowed. If no verified boundary is available, Default asks before running an exact Bash invocation on the host and Auto denies Bash. With the managed runtime, routine commands inherit an OS-enforced boundary that:

• denies outbound networking, local listeners, and Unix sockets;
• limits writes to the workspace and a private per-run scratch directory;
• keeps repository, A3S, agent, editor, and tool control metadata read-only;
• blocks reads from common credential stores and removes ambient secrets from the command environment;
• denies existing .env* files at every governed source-tree depth and masks pre-existing multi-link source files for both reads and writes;
• preserves bounded streaming output, timeout, cancellation, and process-group cleanup.

The TUI also enables Core's local workspace credential policy for built-in file operations. Direct and range reads, writes, edits, patches, and both manifest-backed and fallback grep enforce the same sensitive-path and source-hardlink rules. Explicit sensitive targets fail closed and broad grep filters them without exposing matching content. Ordinary package-store hardlinks remain readable unless they alias a discovered credential inode. Read-only Git diff is regenerated only for allowed changed paths; option-like revisions cannot become Git flags, and displayed remotes omit embedded HTTP credentials and query tokens.

Delegated tasks, Skills, and dynamic workflow steps inherit the same sandbox, permission checker, and parent confirmation boundary. Child-local Ask decisions retain the worker's configured confirmation behavior, but a parent Ask or tool-owned escalation remains governed by the parent provider. A child-local allow rule or automatic confirmation provider cannot weaken the TUI boundary.

The CLI release, Homebrew formula, and standalone self-update preserve the same verified support tree. npm is a development fallback, not the production release supply path.

This local process sandbox is the low-latency boundary for routine repository commands. A3S Code owns permission and escalation policy; the sandbox provider owns OS enforcement. A3S Runtime owns provider-neutral Task and Service lifecycle and placement, not per-command approval. Dependency-heavy, untrusted, OCI, or stronger-isolation workloads belong on A3S Box or a provider selected through A3S Runtime.

#Effort Profiles

/effort rebuilds the active session with a different depth profile. The design scales work on three axes:

• Thinking budget for providers that expose extended thinking.
• Tool-round budget and continuation count for all providers.
• Model-agnostic prompt guidance for rigor, verification, and decomposition.

All effort levels keep local task and parallel_task available, with the TUI session limiting explicit sibling fan-out through max_parallel_tasks. Runtime-driven automatic delegation is disabled for low through max; signed-in Codex models still receive the corresponding native reasoning.effort value. ultracode enables automatic delegation, planning, goal tracking, and dynamic-workflow guidance, but the pre-analysis gate still decides whether a turn actually needs planning or fan-out. Synthesis-only continuations cannot start another delegation wave.

#Dynamic Workflows Vs /flow

A3S Code has two workflow concepts and they are intentionally different:

Dynamic workflow scripts are runtime artifacts, not a separate TypeScript SDK. They run inside the existing program QuickJS sandbox and may call only the tools that the host allows through ctx.

export default async function run(ctx, inputs) {
  if (inputs.kind === 'workflow') {
    return {
      type: 'schedule_steps',
      steps: [
        {
          step_id: 'inspect',
          step_name: 'inspect_workspace',
          input: { query: inputs.input.query },
        },
        {
          step_id: 'fanout',
          step_name: 'parallel_task',
          input: {
            tasks: [
              {
                task_id: 'tests',
                agent: 'explore',
                description: 'Find test coverage',
                prompt: 'Inspect relevant tests and coverage gaps.',
              },
              {
                task_id: 'risk',
                agent: 'review',
                description: 'Review risk',
                prompt: 'Review the approach for regressions.',
              },
            ],
          },
        },
      ],
    };
  }

  if (inputs.step_name === 'inspect_workspace') {
    const hits = await ctx.grep(inputs.input.query, { glob: '*.rs' });
    return { hits };
  }

  return { ok: true };
}

PTC is hosted by QuickJS, so parallel_task stays native to the host. When a workflow needs parallel local subagents, it schedules a Flow step named parallel_task; the TUI host executes the native implementation outside QuickJS. If A3S OS registers a runtime tool after /login, dynamic workflow PTC steps may also call ctx.tool("runtime", ...).

#Optional A3S OS Runtime And Views

Add an A3S OS endpoint to config.acl, then sign in:

os = "https://os.example.com"

/login

Signed-out behavior is intentionally useful but local: chat, file editing, workspace tools, local MCP, local asset drafting, memory, /ctx, /kb, task, parallel_task, dynamic_workflow, DeepResearch with validated local reports, and local loops keep working.

Signed-in behavior adds A3S OS asset publication, runtime tools, trusted view links, and asset activity panels without changing the local-first TUI contract.

#Command Reference

These commands are available outside the asset-specific flows:

Asset command families include /agent, /mcp, /skill, /flow, /okf, and /loop. Their publish, deploy, run, open, logs, status, list, activity, clone, review, and local development forms are scoped to the selected asset family.

#Headless Smoke Mode

Set A3S_CODE_TUI_SMOKE=1 to exercise the same AgentSession::stream() integration without taking over the terminal. This is useful for release smoke checks of the configured model/session path.

A3S_CODE_TUI_SMOKE=1 a3s code

#Related Pages

1. A3S CLI Code TUI
2. Commands
3. Tools
4. Memory
5. Sessions
6. Security