#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, Workspace access, and session recovery.

Install the a3s CLI when you want to work in a terminal. Use the Rust crate, Node.js package, or Python package when you are building a product. They emit the same events, so every UI does not need its own agent loop.

#Choose an entry point

#What it includes

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

#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"

auto_parallel = false disables automatic parallel child-agent fan-out only. Manual parallel_task remains available unless manual delegation is disabled separately.

#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.
• 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.
• 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.