#A3S Code

A3S Code is the Rust runtime behind the a3s code terminal application. You can also embed it in an IDE, runner, service, or desktop application. It handles the agent loop, context, tool calls, permission checks, child tasks, asynchronous Workspace retrieval, durable evidence, and session recovery.

Version 8.1.0 makes the complete product capability inventory discoverable from all four SDKs and promotes a3s-search v3.1.0 with Moli as the default JavaScript-capable search backend. Release packages carry the matching Moli sidecar for supported targets; processes that share a user account reuse one verified cache rather than installing a browser per application.

Install the a3s CLI when you want to work in a terminal. When building a product, use the Rust crate, Node.js package, Python package, or Go module with its matching native bridge. They emit the same events, so every UI does not need its own agent loop.

#Choose an entry point

#What it includes

#What is new in v8.1.0

• web_search is powered by a3s-search v3.1.0. Google, Baidu, Bing, and Brave browser engines use Moli by default; Chrome/Chromium and Lightpanda remain explicit compatibility backends. The first-use runtime is selected in this order: package sidecar, verified per-user cache, system executable, and finally a digest-pinned HTTPS download.
• The Moli installer uses an atomic staging/receipt protocol and a cross-process lock at ~/.cache/a3s-code/moli (or A3S_CODE_MOLI_CACHE_DIR). A second A3S Code process waits for the first install and reuses the same executable. Set autoDownloadMoli: false when a host must fail closed rather than access the network.
• Rust, Node.js, Python, and Go expose the same sdk_capabilities inventory, state-graph operations, Moli diagnostics, and typed search configuration. Use the inventory to feature-detect a build instead of parsing package files.
• Native Node packages and Python wheels include their target Moli sidecar and provenance metadata. Linux musl packages explicitly carry an MOLI_UNAVAILABLE marker because upstream Moli does not publish a musl binary; those hosts must provide a system Moli executable or choose another backend.

#Earlier v7.0 additions

• Session-owned Workspace Retrieval builds one bounded text catalog asynchronously, reuses incremental BM25 postings, and can publish exact in-memory vector partitions without delaying session construction or adding a vector database.
• Dense semantics are explicitly host-enabled. Exact search, glob, BM25, Code Intelligence, RRF, and the optional deterministic reranker run locally on CPU; a host can inject an in-process CPU embedding callback when semantic search is useful.
• Rust, Node.js, Python, and Go expose typed line, fixed-window, and recursive chunking, readiness and batching metrics, optional deterministic reranking, cancellation, current-source digest verification, and bounded cleanup. Non-text assets are rejected before chunking or embedding.
• Product builds use zvec-rust for lexical FTS/BM25 and A3S Memory for exact semantic vectors. Native lexical handles are bounded and temporary; semantic vectors are released with the owning session.
• Model-bound run evidence records the effective capability and policy identity, retrieval generation, input shape, repeated Tool-result context, and normalized usage without retaining new prompt, source, vector, credential, or endpoint plaintext.

Go consumers must use the v7 module path: github.com/A3S-Lab/Code/sdk/go/v8.

v6.9 introduced the shared priority/FIFO scheduler, bounded personal and project instruction chains, governed lifecycle hooks, isolated Harness Git worktrees, deterministic Tool-result evidence, and exact cognitive-package generation bindings.

v6.8 presents one compact search schema for grep, glob, and dependency-free BM25 ranking, plus one model-visible task schema for focused or bounded fan-out delegation. Legacy direct host aliases remain readable without consuming model schema tokens. The same release adds exact, replay-safe run admission for headless hosts and exposes its snapshot/replay result through the Node.js, Python, and Go SDKs.

The v6.7 local download tool streams HTTP(S) resources through SSRF-safe redirect validation into adjacent temporary files, supports adaptive 1–4 connection Range transfers, and can verify a 64-character expected_sha256 before atomic promotion. It is a permission- and HITL-governed workspace mutation and is not registered for remote workspace backends. See Tools.

Search uses a structurally gated cascade: a Moli tier included in the default Core feature set, HTTP/RSS engines, then native APIs. A completed cascade that remains below the structural retrieval requirements fails closed instead of presenting weak candidates as successful evidence. No external semantic verifier or reranker is required. Delegated contexts share bulkheads, retry budgets, and identical-request coalescing; see Tools.

A run roughly follows this path:

Agent / AgentSession
  -> collect project context
  -> optional plan
  -> select tools or child tasks
  -> check permission and ask the user when needed
  -> execution
  -> publish events and verification results
  -> save the session

#Install

For the interactive terminal workspace, 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.

Install an SDK when embedding A3S Code:

npm install @a3s-lab/code
pip install a3s-code
cargo add a3s-code-core
go get github.com/A3S-Lab/Code/sdk/go/v8

The v8.1.0 Python package supports CPython 3.10–3.14 through one cp310-abi3 wheel per platform. Intel Macs use the macosx_12_0_x86_64 wheel and require macOS 12 or newer. See Python wheel platforms for the bootstrap flow and the No module named pip repair command.

#Configure

A3S Code uses ACL. Keep real API keys, private model endpoints, local config paths, and tenant/user identifiers out of commits. Commit templates that resolve credentials from the environment.

default_model = "provider/model-id"
max_parallel_tasks = 4
auto_parallel = false

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

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

storage_backend = "file"
sessions_dir = ".a3s/sessions"

search {
  headless {
    backend = "moli"
    auto_download_moli = true
    max_tabs = 4
  }
}

auto_parallel = false disables automatic parallel child-agent fan-out only. Manual task calls and SDK session.tasks(...) fan-out remain available unless manual delegation is disabled separately.

The Moli sidecar is selected automatically by the SDK package. For a source checkout or a minimal Core build, set A3S_CODE_MOLI_EXECUTABLE to a verified executable, or let the first search call download the pinned release into the shared cache.

#Use the TUI

Run a3s code from the workspace you want the agent to inspect:

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

The TUI discovers config from A3S_CONFIG_FILE, then .a3s/config.acl walking upward from the current directory, then ~/.a3s/config.acl.

Common first-run flow:

/init          # inspect the repository and create or update AGENTS.md
/model         # pick a configured provider or account-backed model
/effort        # choose low, medium, high, xhigh, max, or ultracode
/ide           # open the workspace tree and terminal editor
/help          # open the full command and shortcut guide

#Rust Runtime Quick Start

use a3s_code_core::{Agent, AgentEvent, SessionOptions};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent = Agent::new("agent.acl").await?;
    let session = agent
        .session_builder("/path/to/workspace")
        .options(
            SessionOptions::new()
                .with_planning(true)
                .with_max_parallel_tasks(4)
                .with_tool_timeout(120_000),
        )
        .build()
        .await?;

    let result = session
        .send("Find the authentication entry points.", None)
        .await?;
    println!("{}", result.text);

    let (mut rx, _handle) = session
        .stream("Summarize the test strategy.", None)
        .await?;
    while let Some(event) = rx.recv().await {
        match event {
            AgentEvent::TextDelta { text } => print!("{text}"),
            AgentEvent::End { .. } => break,
            _ => {}
        }
    }

    Ok(())
}

Rust construction is async-first. The synchronous Agent::session method only works when memory and the other required resources are already initialized; options that require async setup return CodeError::AsyncSessionBuildRequired. A session-option MCP manager always uses the async path while discovering tools.

Calls such as session.tool(...) come from your application, not the model. Check access in your application before exposing them to users.

#Continue reading

• A3S Code TUI explains installation, config discovery, slash commands, and effort profiles.
• SDKs and APIs explains Go module and bridge installation; the Go examples then stay beside Node.js and Python throughout the shared guides.
• Filesystem-first covers AGENTS.md, ACL, AgentDir, Skills, tools, and schedules.
• API contract lists the Node.js API covered by integration tests.
• Sessions covers creation, streaming, run state, saving, resuming, and cancellation.
• Tools covers direct calls, typed errors, structured output, and QuickJS programs.
• Workspace retrieval covers opt-in semantics, chunking, lifecycle, quality metrics, and safe CPU-only defaults.
• Tasks and orchestration cover child agents and fixed workflows.
• Security, hooks, and verification cover checks before, during, and after execution.
• Memory and persistence cover reusable facts and session recovery.