A3S Code

A3S Code is the Rust runtime behind a3s code. It keeps coding-agent sessions observable while the harness owns context assembly, tool execution, permission policy, delegation, dynamic workflow execution, workspace access, memory, persistence, verification evidence, and run replay.

a3s-code-core is the embeddable Rust runtime. a3s code is the ready terminal workspace shipped by the a3s CLI; it drives A3S Code sessions and renders their event stream with the a3s-tui framework.

Install the CLI when you want the interactive product. Install the Rust crate when you are building another host, runner, IDE bridge, or controlled product surface around the same runtime.

Surfaces

Capability Map

The execution shape is:

Agent / AgentSession
  -> context assembly
  -> optional planning and goal tracking
  -> selected tools, delegated child tasks, or dynamic workflow steps
  -> permission and confirmation policy
  -> execution
  -> trace, artifacts, memory, and verification evidence
  -> compaction and persistence

Install

Install the CLI when you want the interactive terminal workspace:

brew install A3S-Lab/tap/a3s

# or from crates.io
cargo install a3s

# or from the CLI repository
cargo install --git https://github.com/A3S-Lab/Cli

Install the Rust runtime crate when embedding 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, OS gateway model, or account 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(
        "/path/to/workspace",
        Some(
            SessionOptions::new()
                .with_planning(true)
                .with_max_parallel_tasks(4)
                .with_tool_timeout(120_000),
        ),
    )?;

    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(())
}

Direct Rust host tool calls are privileged control-plane operations. Gate them in the embedding application before exposing them to users.

Entry Points

• A3S Code TUI explains install, config discovery, slash commands, effort profiles, dynamic workflows, OS Runtime, and RemoteUI.
• A3S CLI Code TUI covers CLI startup, resume, update, smoke mode, and terminal lifecycle boundaries.
• Filesystem-first covers reviewable project and AgentDir conventions.
• Sessions covers lifecycle, streaming, run state, persistence, and cancellation.
• Commands distinguishes TUI commands from host command-registry handlers.
• Tools covers direct tools, typed tool errors, structured output, and QuickJS programs.
• Memory and Persistence cover reusable facts, session snapshots, and recovery paths.
• Security covers permissions, confirmations, hooks, and verification gates.
• Verification covers command evidence, reports, and summaries.
• Tasks covers model-driven child-task delegation.