atman witnesses; code exists
Quickstart · Docs · Examples · Why atman?
# shell installer (macOS / Linux)
curl -fsSL https://atman.run/install.sh | sh
# or homebrew
brew install W-Mai/cellar/atman-cli
# or cargo
cargo install atman-cli --locked
atman init # scaffold ~/.config/atman/
atman doctor # verify config + providers
atman upgrade # update with the official installer
atman # launch the TUIOn Windows PowerShell, run irm https://atman.run/install.ps1 | iex; the installer places atman.exe in the user executable directory. The matching atman-daemon Windows artifact is published separately for daemon/Web use. Windows uses %APPDATA%\atman\config for configuration and %LOCALAPPDATA%\atman for session data.
atman upgrade downloads the official installer over HTTPS before executing it. On macOS and Linux it installs to Cargo home, usually ~/.cargo/bin; it does not upgrade a Homebrew installation. Use brew upgrade atman-cli for Homebrew, or cargo install atman-cli --locked for a Cargo-managed installation.
Set an API key via env var (ANTHROPIC_API_KEY / OPENAI_API_KEY) or inline in ~/.config/atman/config.toml:
[models."deepseek/deepseek-v4-pro"]
provider = "anthropic"
api_key = "sk-..."
context_budget = 1000000
[alias.smart]
model = "deepseek/deepseek-v4-pro"Tip
atman can run tools that edit files and execute commands. Start in a disposable repo until you understand the configured tools. Use contract.scope in your flow to statically limit what each flow can touch.
atman turns coding-agent workflows into reproducible flows written in the .at language — atman's own DSL for wiring LLM calls, tools, approvals, and sub-agents. Instead of a single chat where the model decides what to do next, you write a .at flow that decides what happens next; the LLM executes what it's assigned. Every run emits a typed event trace you can replay, audit, and monitor.
The managed agent template lives at examples/agent.at. It demonstrates a bounded recursive loop around llm.call, session context, plan/todo tools, history search, retries, and tool dispatch. Run it with:
atman run examples/agent.at --flow agent user_prompt="read Cargo.toml and list the workspace members"A Session contains independently addressable Flow instances. Each instance retains its conversation, inbox, Goal, execution state, and resource bindings across turns. Returning a final answer finishes the current turn; it does not destroy the instance. Flows can exchange messages and watch public results, with explicit grants for cross-Session access and privileged controls.
The main conversation and floating windows use the same Flow view. New floating windows start near the upper left and cascade diagonally. Reopening the same Flow in the running TUI restores its window position, size, and maximized state. Selecting a different Flow changes the recipient of input and controls while retaining each view's draft and reading position. Closing a window does not stop execution. The default Flow is the Session's initial view, with no extra authority.
Quick Ask opens an independent, read-only question from the composer's ?, the palette or selected text. Questions retain a captured source snapshot, their own model and draft, and support explicit refresh, copy and return to the source draft. They stay temporary until ◇ Keep saves them as a normal Flow in the same Session.
The input floats independently of document width, with a square outline, terminal-default background, a 96-column width that adapts to the viewport, and 4 editable rows by default. Its position and size use spring motion when switching focus or resizing; dragging the focused window carries the input synchronously. A fixed-width meter at the lower left selects reasoning intensity directly, with hover comparisons and a ⋯ menu for all supported choices, including default, auto, and none. The highest supported intensity displays a rainbow using the current theme's palette, including during hover previews. The model label opens a compact selector. Permissions occupy the upper-right border and open inside the existing text rows; drafts remain intact, saves use host acknowledgements, and Esc returns to editing. Escalation appears only in Eager mode without reserving a gap in other modes. Model, reasoning, and permission controls use the selected view's settings, along with its draft, quotes, attachments, and submission acknowledgements. The input itself cannot be dragged.
Click ↓ N new in the input border or press Ctrl+End to animate to the latest output and resume following it. Scrolling or selecting transcript text interrupts the transition. Main and floating conversations retain separate reading positions.
On TUI exit, a themed summary shows the final session's identity, invocation usage, work metrics, Goal, Plan, and atman --continue <uuid> command after restoring the terminal. Its layout adapts to terminal width and preserves aligned columns and padded identity and resume blocks. Unused automatic startup sessions are discarded without a summary or resume command.
The TUI retains direct access to its runtime and exposes authenticated loopback RPC for other clients. Sessions transfer individually between TUI and daemon hosts at safe execution boundaries; other sessions keep running. Exiting the UI leaves accepted work in its original background worker, then returns settled sessions to an available daemon. Shared hosts and ownership transfer describes discovery, credentials and crash recovery. Opening immutable history alone starts neither RPC nor a Profile writer.
Interrupted conversations retain pending input in Inbox and expose Recover R with mouse and keyboard controls. Input queue and execution recovery describes routing, insertion eligibility, cancellation, pauses, and recovery.
Project Hub (Ctrl+L) and pinned-project session entries open the selected session's default conversation directly. Click a project to show its sessions, then activate a session with Enter or one click to close the Hub and open its conversation. Sidebar project actions occupy one compact row. All opened sessions appear before five ordinary recent entries while retaining catalog order; focusing an existing session or project keeps its position. Opened conversations update their output tails in the background. The current view has an accent edge bar, other opened sessions use a subdued accent, and new completions remain highlighted until the session is reentered. Project names, sessions and supporting details use theme-defined grayscale levels, and the collapsed project tab has hover feedback. Narrow terminals use a drawer. Original history opens read-only; indexed history retains its recovery review.
Each session's ↗ control opens its bound conversation in a floating panel, including across projects. An opened session's × closes its views while retaining history, execution, drafts and pending acknowledgements. Closing an individual panel keeps the session open in the sidebar; closing the last session returns to Projects without creating a replacement session. With a session selected in the sidebar, O opens its panel and Delete closes the session.
| Entry | Purpose |
|---|---|
:sessions |
Open Switch Session: search, sort, filter by project, rename, and directly enter a conversation. |
:revert |
Review a user-turn boundary and retain the removed conversation as a branch; files stay unchanged. |
:branches |
Restore a retained branch, inspect a pending history change, or recover original input. |
:new-session |
Create a blank session immediately at a matching startup location; otherwise choose its project and working directory. |
:move-session |
Change session project membership and update navigation. Existing flows keep their working directories; new flows use the destination project. |
:projects |
Browse, pin, archive, and open projects and their sessions. |
:activity |
Switch the right sidebar between Overview and Activity. |
:panel |
Open the command palette for settings, tools, and existing panels. |
:delete-old-session |
Review deletion of a continued session's original history; also available as Delete Old Session in its panel. |
atman --continue <session-id> |
Reopen a recorded Session. Sending a message from published legacy history continues in a new session and preserves the original. |
New execution records live under runtime-v1/sessions/<session>/flows/<flow>/. Recovery retains committed work and pending input; it does not replay unknown external effects. See Session and Flow navigation, storage and migration, and approval controls.
Conversations retained only in project indexes appear as Indexed history in Switch Session and project session lists. Open a record to review its coverage and missing assets, then choose Recover transcript to create an independent history copy. Sending a message from that copy starts a new conversation with retained context. The source index stays unchanged; missing original logs and external files cannot be reconstructed from indexed text.
Unbound legacy TUI views discover sessions in bounded background workers with the existing picker progress indicator. Filtering, scope changes, closing and resizing remain available. Browsing reads message counts without repairing caches, refresh retains the selected session, and obsolete scans cannot replace newer results.
The right sidebar combines Goal / Plan / Todos and Context / MCP in Overview, with Tasks / Flow / History in Activity. Main and floating views share this layout. FlowHub, Links, WatchHub, Inbox History, Worktrees, Flow Workspace, and the management Session panel require the optional atman-tui/extended-panels Cargo feature. Runtime messaging, watchers, and storage remain active in default builds.
The left sidebar shows globally pinned projects, every opened session, five additional recent sessions per project and project-specific session creation. Opening a project's session pins that project. Pins persist across restarts; hiding the sidebar preserves them, and unpinning offers Undo. A project with open sessions remains visible until those sessions close. Sessions without project metadata appear in a local Sessions group. Use :project-sidebar, Toggle Project Sidebar in Ctrl+P, or the P tab to reopen it. Narrow terminals use a drawer. Ctrl+L opens the full project directory; Sort or S selects newest first, oldest first or name A–Z on both pages.
Project directory refresh and history search display compact animated progress while waiting for their replies. Visible conversation windows share the animation clock; hidden or completed loading indicators stop requesting frames.
Switching back to a healthy cached conversation restores its existing document immediately while incremental updates continue through its original reader. Each view retains its draft, quotes and input acknowledgements.
Initial conversation history and document preparation run in bounded background workers. A compact loading view remains responsive to typing, window changes and resizing. Switching away retains the preparation; completion updates its original view without taking focus. Drafts remain editable while loading and can be sent once the conversation is ready.
Settings panels read source-bound snapshots prepared in background workers, including authentication, model catalogs and local MCP configuration. Initial loading has compact animated feedback and keyboard/mouse Close and Retry controls; refresh preserves existing lists and drafts. Preference forms also load off the input path. Normal messages retain their draft until settings are ready, and saves keep their original persistence acknowledgement.
Document rendering uses prepared content without acquiring the execution message lock, keeping display, copying and resizing independent of that lock.
Live journal catch-up projects pages in bounded background workers. Slow refresh keeps the previous document visible with compact Updating feedback; switching views retains the read and its cursor, and completion does not change focus.
View-bound host controls and panel services run outside input and rendering polls. Each view retains its command order and original reply destination; execution stop, permissions and form decisions have independent workers. Pending preference saves can be hidden with Hide or Esc and reopened without losing their receipt or draft. Normal exit shows Finishing and keeps input, view changes and resizing available until accepted durable controls settle.
Suggestion generation and confirmation waiting do not delay exit. Installation admitted after acceptance finishes before cleanup; shutdown prevents an unstarted suggestion from publishing files.
Text and rich clipboard copies use an ordered background queue. Conversion and native clipboard access leave input responsive, completion stays with its original view, and exit waits for accepted copies. Plain text retains OSC 52 support; terminal writes stay serialized with rendering.
आत्मन् (ātman) — Sanskrit for self, the inner essence that witnesses thought but is not thought itself. The agent that watches the LLM's words and acts on them.
atman is a code interpreter for the .at language. It parses .at files, manages their runtime, and emits a typed event trace for every execution. The .at language is Turing-complete — it has variables, conditionals, recursion, fan-out, and Flow calls — so you can express any agent workflow as a deterministic program, not a prompt.
The LLM is just one node type inside that program. llm.call(...) is a stochastic node; everything around it (the tool dispatch, the approval gates, the retry loops, the Flow recursion, the context compaction) is deterministic orchestration written in an unambiguous, concrete, and inspectable language. You orchestrate the agent's entire workflow in .at; the LLM only executes what the flow assigns to it — the witness that observes, never the driver.
| Mainstream code agents | atman | |
|---|---|---|
| Orchestration | LLM-driven (model decides tool use) | Flow-driven (code decides, LLM executes) |
| Reproducibility | Non-deterministic | Deterministic .at flow orchestration, replayable event trace |
| Multi-model | One model per session | Cascade / ensemble / bridge across models in one flow |
| Tool safety | Prompt-level | 5-tier capability sandbox, statically checked at flow load |
| Workflow definition | Natural lang 8000 uage prompts | Typed DSL with schema validation + flow versioning |
| Session trace | Chat log | Typed events.jsonl (replayable, FTS5-searchable) |
| Sub-agents | Hard-coded agent types | Named Flow calls and explicit agent spawning |
| Headless | Limited | JSON-RPC daemon + SSE events + bearer auth |
A .at file declares flows, routes, lifecycle hooks, and static use bindings. Flows are block-based.
In .atman/lib/text.at, mark a flow public so another file can call it:
pub flow normalize(input: string) -> string {
return input
}
In .atman/commands/review.at, bind that flow by name:
use "project:text.at"::normalize
flow review(input: string) -> string {
return normalize(input).await
}
use "./lib/text.at"::normalize resolves beside the file containing the declaration. Use ::{normalize, tokenize as words} to bind several public flows, or use "./lib/text.at" as text and call text.normalize(input).await. A Flow call such as normalize(input) creates a cold Future; .await executes one call, while fanout [normalize(a), normalize(b)] runs both and returns ordered results. project: reads from <project>/.atman/lib/; user: reads from ~/.config/atman/lib/. Only flows declared in the entry file can be selected with --flow or exposed as slash commands.
Flow parameters, defaults, and return values are checked when a flow runs. Scalar, list, inline struct, and host payload annotations are enforced recursively; value and any are dynamic. PascalCase schema markers remain descriptive until named type declarations are available. atman run and slash commands decode integer, float, boolean, path, and JSON collection arguments from the selected flow signature.
atman init writes managed commands/agent.at and commands/spec.at templates. The agent first loads relevant rules and past confessions, then runs llm.call, retries, compaction, and tool dispatch; a candidate final response is checked before the loop exits. Requirements uncertainty stays in the normal conversation, where the agent thinks through the ambiguity and asks a focused question. It may suggest the opt-in spec workflow but does not automatically start it for new projects, non-trivial work, architecture changes, or uncertain requirements. See examples/agent.at for a smaller standalone agent-loop example.
Run /spec <request> in the TUI to explicitly start a synchronous requirements interview. The interview investigates project files, asks focused questions through multiline forms, stores research and design in configured project storage, publishes the design to the local preview, and waits for approval of that exact revision before returning. An explicitly requested design handled in the main agent uses the same revision-bound confirmation: the user response produces a session-local, single-use receipt, and only that receipt can approve or reject the materialized design.
loop is unconditional. A flow must leave it with break, return, an error, or cancellation; use continue to start the next iteration:
flow run_agent(user_prompt: string) -> string {
contract {
capabilities { shell: true }
invocation { user_message: user_prompt }
}
loop {
reply = llm.call(model: "smart", context: "session", tools: ["fs.read", "bash.spawn"])
tool_uses = extract_tool_uses(reply)
when is_empty(tool_uses) {
break
}
session.push(dispatch_all(tool_uses))
}
return text_concat(reply)
}
Use yield inside long-running language work to return control to the host executor once. The VM self-wakes and resumes at the following statement; no tool registration or .await is required:
loop {
when list.is_empty(items) {
break
}
items = list.tail(items)
yield
}
invocation.user_message maps a string parameter to the initial user message of an isolated flow.spawn context. CLI and daemon root turns record their input before flow execution, so the declaration does not append a second root message.
Run the managed flow through the default route after atman init, or run the example explicitly:
atman run examples/agent.at --flow agent user_prompt="read Cargo.toml and list the workspace members"flow.spawn can isolate a child flow in a managed Git worktree with workspace: "auto" or workspace: "retain". The default is workspace: "none", which preserves the existing working-directory behavior and does not require a Git repository.
Every spawn requires a single-use admission token from flow.instances(). Its session-scoped inventory makes existing work visible before another child is created; inventory changes invalidate unused tokens.
flow delegate() -> string {
inventory = flow.instances()
return flow.spawn(
flow: "subagent.at@implement",
spawn_token: inventory.spawn_token,
async: false,
workspace: "auto",
)
}
The policies are:
none— do not allocate a workspace.auto— release the worktree after any known terminal outcome when it is clean; preserve it asdirtywhen it contains changes.retain— preserve the worktree after the child terminates, even when it is clean.
For managed children, Git, filesystem, Bash, terminal, and other process-backed tools use the worktree as their default working directory. This binding is local to the child execution context and never changes the parent flow's or process's working directory. Runtime-generated session and child-flow identities own the workspace; caller-supplied owner fields are not trusted.
Bare repositories require a configured, policy-approved external workspace root. The daemon does not currently configure one, so managed child allocation from a bare repository fails clearly instead of choosing an arbitrary path. After a daemon restart, workspaces with active leases from an older daemon generation are marked orphaned for inspection; they are never deleted automatically. Orphan pruning remains an explicit, dry-run-first operation.
From examples/edit_and_verify.at:
flow edit_and_verify(file: path, instruction: string) -> EditResult {
contract {
scope {
read: [project_root]
write: [project_root]
}
capabilities {
shell: true
}
}
original = fs.read(file)
ok = user_confirm("Attempt edit-and-verify loop on " + shell_quote(instruction) + "?")
when ok == false {
return { status: "cancelled" }
}
result = fix_until_test_passes {
edit_flow: llm.call(
model: "smart",
messages: [
system_msg(@"prompts/edit.md"),
user_msg("iter=" + to_json_string(iter) + "\nprevious failure:\n" + prev_fail + "\n\ninstruction: " + instruction),
],
input: { file: file, original: original, instruction: instruction },
)
test: test.run(framework: "cargo", timeout_ms: 300000)
target: file
max_iters: 5
on_giveup: { status: "gave_up", iters: iters, last_fail: prev_fail }
}
audit = preview.push(
topic: "edit-and-verify",
title: "edit-and-verify: " + file,
content: "**iters:** " + to_json_string(result.iters) + "\n\n**status:** " + result.status,
)
return result
}
Run it:
atman run examples/edit_and_verify.at --flow edit_and_verify \
file="src/main.rs" instruction="add a --version flag"| Node | Syntax | Purpose |
|---|---|---|
| LLM | llm.call(...) |
Stochastic model call with prompt/messages, tools, context, retry, cache, and compaction |
| Tool call | fs.read(...), bash.spawn(...) |
Dispatch a registered tool |
| Flow call | name(args).await |
Execute a lexically bound Flow and return its result |
| Approval | user_confirm(msg) |
Pause for human approval |
| User input | user_ask(prompt, schema) |
Request structured user input |
| Fanout | fanout [...], fanout pending |
Run cold Flow calls concurrently or collect already evaluated values |
| Yield | yield |
Return control to the host executor once, then resume at the next statement |
| List | items[index], list.len, list.first, list.concat, list.map, list.filter, ... |
Index, inspect, combine, and transform list values |
| Composers | retry { ... }, fallback { ... } |
Retry or choose fallback execution |
Routed prompts pass message text directly to the selected entry. URL query strings, code, quotes, and multiline pastes do not switch the message into command-argument parsing. See input routing.
route "review " { flow: review_code }
route "fix " { flow: fix_issue }
default_route { flow: agent }
on session.start {
system_msg("boot")
}
on turn.end {
memory.confess("checked in")
}
See examples/ for the canonical flows covering agent loops, code review, hunk review, edit-and-verify, parallel exploration, mail, and more.
55+ built-in tools across 15 categories. MCP servers configured in mcp_servers.json connect at boot. The managed agent uses fixed MCP tools: mcp.status, mcp.tools, mcp.await, and mcp.call. Search the catalog with mcp.tools(query: ...), retrieve a tool's full input schema with mcp.tools(server: ..., tool: ...), then invoke it through mcp.call. Discovery results enter the conversation without changing the request's tool definitions. Proxy calls use the target tool's permissions, scheduling, and input validation.
Custom flows can expose native MCP tools with explicit selectors. A named selector waits for its server and reports an unavailable dependency. The broad "mcp.*" selector briefly discovers available servers and continues if another server fails or remains unavailable; it still expands into native tool definitions and is subject to the provider's tool limit. Use mcp.await when a server is required.
HTTP MCP connections accept JSON and streaming SSE responses, apply configured headers to initialization and subsequent requests, and retain the negotiated protocol version and session ID. See HTTP MCP configuration for authentication, headers, and session recovery.
| Category | Tools | Tier |
|---|---|---|
fs |
read, list, grep, write, edit | 0–2 |
bash |
spawn, status, output, kill, list | 4 |
term |
spawn, input, capture, resize, kill, list | 4 |
web |
fetch, search | 3 |
git |
diff, show, log, status (0), add, commit, branch (2), push (3) | 0–3 |
test |
run | 2 |
hunk |
review (0), apply (1), plan_edit (2) | 0–2 |
memory |
todo.list, goal.get/pause/resume, recent_turns, history, fetch_confessions, spec.status/read (0), todo.set/done/cancel/delete, goal.set/clear, confess, spec.update/deviate/materialize/review (1) | 0–1 |
plan |
read (0), write, tick (1) | 0–1 |
agent |
spawn | 2 |
form |
ask | 0 |
preview |
push | 1 |
session |
push | 0 |
sleep |
— | 0 |
Every tool declares a tier. Flow contract.scope statically validates all tool references at load time — a flow that tries to bash.spawn without capabilities.shell: true is rejected before it runs.
| Tier | Scope | Rollback |
|---|---|---|
| 0 | Pure read | Abort-safe |
| 1 | Project write | Pre-image (undo) |
| 2 | Git local | Reflog |
| 3 | Remote / irreversible | Requires confirm |
| 4 | Shell escape | Requires capabilities.shell: true + confirm |
atman runs proactive auto-compaction before an LLM call would overflow, generates a structured handoff summary, and holds a compact_lock so parallel workflow branches never race the compactor. A failed anchored summary leaves its selected history range intact and reports a failed compaction instead of replacing that range with a placeholder. Compaction is a first-class event in the transcript — you see it start, spin, and finish.
Three memory layers:
| Layer | Scope | Lifetime |
|---|---|---|
Todo (memory.todo.*) |
Current plan step | Session |
Plan (plan.*) |
High-level route across turns | Injected into every LLM call |
Confession (memory.confess) |
Project rule violations | Permanent, append-only |
atman # REPL (TUI)
atman run <file.at> [--flow <name>] [--reasoning <level>] [--image <path>]... [--mock] [--ephemeral]
atman logs tail [session] [--follow]
atman session list | show | search | sanitize
atman cost [session] [--all]
atman upgrade [--yes] [--verbose] [--no-modify-path]
atman monitor [--port 65098] # event monitor
atman preview serve [--port 65097] # artifact preview workbench
atman daemon start | stop | status | run [--reasoning <level>] [--image <path>]...
atman flow run <name> --revision <id-or-hash> [--mock] [--ephemeral]
atman flow snapshot | versions | diff | rollback | lint | test
atman sync init | push | pull # git-based cross-machine memory sync
atman migrate list | import [--from opencode|kiro-cli]
atman doctor [--fix]
REPL builtins: :help, :cost, :goal, :suggest, :compact, :copy, :attach, …
atman daemon stop allows five seconds for the auth
8BD0
enticated shutdown request, including the response body, then waits up to ten seconds for process exit. A failed request uses SIGTERM on Unix and reports an error on Windows.
Managed agents continue across turns while their goal is active. Root and child agents share revision-checked pause and resume controls; parent pauses preserve each child's own state. The TUI shows clickable Pause / Resume buttons, with Ctrl+Y for the focused agent and :goal for details. See Goal controls.
In the TUI, :panel opens the same command palette as Ctrl+P, including when the terminal intercepts that shortcut. Every palette action has a colon command shown beside it. Direct panel commands include :providers, :models, :aliases, :mcp, :memory, :history, :formula, and :keybindings. Panel commands open immediately during a running flow and preserve pending quotes and attachments. Enter accepts a command completion first; press Enter again to execute it.
Ctrl+K or :history searches committed conversations and retained legacy indexes. Enter or search runs the query; Tab or scope selects the current Session or its project. Selecting a result with the keyboard or mouse updates its context preview. Main and floating conversations retain separate queries and results.
~/.config/atman/config.toml:
[providers.openai-compatible]
kind = "openai-compat"
base_url = "https://gateway.example/v1"
api = "chat-completions"
# Applies to models using Chat Completions.
reasoning_format = "reasoning-effort"
# Enable only when the gateway accepts OpenAI's prompt_cache_key field.
# prompt_cache_key = true
[models.reasoning]
provider = "openai-compatible"
model = "vendor/reasoning-model"
api = "responses"
context_budget = 128000
max_tokens = 16384
reasoning = "high"
input_modalities = ["text", "image"]
image_detail = "auto"
[models.fast]
provider = "openai-compatible"
model = "vendor/fast-model"
context_budget = 64000
[alias.smart]
model = "reasoning"
[alias.cheap]
model = "fast"
[compaction]
review = "manual-only" # always | manual-only | never
[sandbox]
enabled = true
strict = false
[theme]
mode = "auto" # auto | dark | light | wuxia
[diff]
layout = "split" # split | unified
[render]
# math = false # Show formulas as raw Markdown text.
# metrics_animation = false # Update workflow counters without easing.Formula rendering is enabled by default. Set render.math = false and restart Atman to display $...$ and $$...$$ as plain text.
Ctrl+P → Formula Rendering, or :formula, changes the same setting from the TUI; restart Atman to apply it.
Workflow headers and footers share compact usage and edit counters. Increases ease over 320 ms in fixed-width fields; Metrics shows exact values immediately. Set render.metrics_animation = false to disable counter easing.
Tool calls from one assistant dispatch are grouped into an ordered working · N block. Each intent opens from a one-line summary to a bounded preview and then the complete auditable output. When a managed agent starts its final response, preceding thinking, tools, and workflow activity fold into a five-row work summary containing completed progress, edit metrics, and an activity description; click anywhere in the summary or press Alt+O to expand it with the same animation. Diff output uses a two-column layout by default, falls back to unified rendering in narrow inline views, and keeps the configured layout in larger views.
Provider env vars: ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL / OPENAI_API_KEY / OPENAI_BASE_URL.
Reasoning values include default, off, auto, minimal, low, medium, high, xhigh, max, ultra, and persistent. Provider and model capability checks reject unsupported efforts or execution modes before the request is sent. Anthropic models with explicit thinking budgets can use reasoning_budget_tokens = 4096. The legacy thinking = true|false setting is still accepted.
OpenAI and OpenAI-compatible providers accept api = "chat-completions" or api = "responses". Models inherit the provider API unless their own api overrides it. Omitting both fields preserves Chat Completions. Set base_url to the connection root, such as https://gateway.example/v1; the selected API determines the endpoint. Anthropic connections use Messages, and Codex login uses Responses.
For Chat Completions, OpenAI-compatible providers default to reasoning_format = "thinking-toggle", which represents default/off/auto. Select reasoning-effort when the gateway accepts exact effort values. Responses encodes effort and execution mode using its own protocol and does not send the Chat thinking toggle. Values such as high@pro remain subject to the model's capabilities, including when resolved from auto. Changing API does not lower the selected effort; unsupported combinations produce a configuration error.
Provider max_tokens controls the request's output limit. Model max_tokens reserves output capacity for context planning; it does not override that request limit. Explicit thinking budgets must fit both limits when configured.
The provider manager separates API from Chat reasoning format. Model settings expose Inherit, Chat Completions, and Responses. Test connection checks discovery and authentication; Test model sends a small request with the draft API, reasoning selection, and a tool definition. It does not execute an external tool. Editing the draft clears previous test feedback; Hide preserves a running test, and Stop test cancels it explicitly.
Provider Manager supports local search, connection details, and actions based on Config, OAuth, or Environment sources. Enter or a record click opens details. Ctrl+S saves a provider form; Esc cancels or asks how to handle unsaved changes. Hiding a pending operation preserves its draft and result. Connection tests retain their result and do not enable a disabled saved provider.
Click the composer's model label to search the compact selector by typing or pasting a model, alias or provider name. Arrow keys select a result; Enter or a result click requests the switch. No matches leaves selection disabled. ⋯ or Tab opens the full selector with the same query; Ctrl+U clears it and Esc closes it. Search preserves the conversation draft and waits for the original model-switch acknowledgement.
Model Manager groups models under provider headings with display names and model counts. Search keeps these groups within All providers or the selected provider, including empty providers when applicable. Continuation pages retain the provider heading. Configured models are editable; Catalog entries are read-only. Cached catalogs remain visible for disabled providers. Ctrl+S saves a model form; Esc cancels or opens the unsaved-changes prompt. Delete requires confirmation and blocks while aliases reference the model. Browsing, editing, and testing do not switch the current session model.
Alias model selection also groups models by provider and searches model names, API IDs, and provider names. Tab switches between the alias name and model list; / in the list focuses Search. Arrow buttons or ← / → change the provider scope. Filtering preserves the bound target until a model is explicitly selected. Ctrl+S or Save commits the target; Enter in the model list selects its focused model and saves.
The TUI imports a clipboard image with Cmd+V, Ctrl+V, or Alt+V. Pending images appear above the input and as stable [image N] references in the editor. Clipboard reading, PNG encoding and attachment storage run in bounded background workers; the input border shows progress while typing and window navigation remain available. Sending waits for the referenced images to finish and retains the draft. Completion stays with the original view and reference; deleting a reference cancels preparation, while Ctrl+U removes the latest image when no quote is pending. Images are copied into the session attachment store by content digest before the user turn is written. The lower input border shows the effective reasoning depth, and Ctrl+T selects the effort captured with the next submission. CLI and daemon runs accept repeatable --image arguments and the same --reasoning values. The selected value is invocation-local. llm.call, llm.extract, llm.classify, and llm.generate_branches consume it only when their own call explicitly passes effort: env("effort"); inheriting the invocation environment alone does not change a request. The managed agent's primary call opts in.
Flows can also use a fixed selection with llm.call(reasoning: "high@pro") or
llm.call(reasoning_budget: 4096).
Drag across transcript text, including line-end space and short gaps between Markdown blocks, to open Copy, Rich Copy, Quote, and Cancel actions. Holding the pointer beyond the visible document edge scrolls the selection. Quote keeps the selected text separate from the editable prompt and sends it as a Markdown blockquote. Click the quote card or press F4 to expand it, then use PgUp/PgDn or the mouse wheel to scroll; click [x] or press Ctrl+U to remove it. When the terminal is too short for the card, the input border shows the pending quote count. Pending text tasks can be inserted into the current flow from the Next queue with i or its mouse action. The task appears in the transcript only when an LLM call includes it; otherwise it returns to Next when the turn ends.
atman/
crates/
atman-macros/ # Compile-time bindings for Rust host APIs
atman-rt/ # Complete .at language VM: syntax, linking, validation, values, flow execution
atman-runtime/ # Atman host: effects, executor, tools, providers, sessions, memory, MCP
atman-cli/ # Binary, REPL, slash commands, monitor, daemon client
atman-client/ # Typed native and authenticated HTTP clients
atman-proto/ # JSON-RPC 2.0 envelope + daemon request/response types
atman-daemon/ # Daemon binary, Unix socket, HTTP+SSE, session pool
atman-tui/ # Terminal UI — themes, workflow panel, diff preview, input
examples/ # canonical .at flow examples
fixtures/atman-rt-embed/ # standalone runtime embedding check
fixtures/atman-rt-host-demo/ # portable owner-thread host binding check
fixtures/atman-rt-mirui/ # scripted mirui SDL demo + headless binding check
docs/ # Quickstart, context strategy, list combinators
atman-rt is the complete Atman language VM. Vm::compile(Source, &resolver) parses and links .at source, including use and pub flows. #[atman_rt::value] generates codecs and portable type descriptions for named-field structs and fieldless enums, while #[atman_rt::resource] exposes opaque typed generational handles. #[atman_rt::tools(namespace = "...")] on a concrete host impl generates stateful tools plus <namespace>.release; bindings mounted through one ToolRouter clone lineage share a resource registry, so one binding can borrow or release a resource created by another. ToolRouter::mount installs the generated handler and catalog batch atomically, ToolRouter::catalog projects its signatures, and Vm::validate_tools optionally checks linked .at calls before execution. A host can also register handlers manually with ToolRouter and compose authorization, observation, cancellation, flow lifecycle, and language-control callbacks with VmDelegates. Atman's tools, providers, sessions, and storage are supplied by atman-runtime; another host can use atman-rt without that crate. #[atman_runtime::tools] generates tool schemas and registration with an explicit Tier through the existing approval and event path; ToolRegistry::register_fn remains available for manual bindings.
Thread-affine UI or graphics objects remain on their owner thread by storing only a command proxy and opaque lease in the VM-side resource registry. A successful generated release invalidates every handle copy and drops that lease, allowing destruction to return through the owner-thread bridge; an active shared borrow reports the resource as busy.
#[atman_runtime::tools]
mod host_tools {
/// Double an integer.
#[tool(name = "math.double", tier = 0)]
pub async fn double(value: i64) -> i64 { value * 2 }
}
host_tools::register(®istry)?;For generated bindings, a Rust fn returns its .at value immediately. A Rust async fn returns a cold value; use math.double(value: 3).await or place calls in fanout [...] to execute them. Approval and tool events begin when the call is driven. Manual Tool implementations can declare the same behavior with call_mode(), and ToolDefinition::call_mode sets it for register_fn bindings.
Product bindings require tier on every #[tool]. Tiers 1–4 also require a cancel value such as #[tool(tier = 2, cancel = "atomic")]; accepted values are abort_safe, revertible, atomic, and irreversible. #[tool(scheduling_claims = path)] binds a function with the signature fn(&ToolArgs, &ToolCtx) -> Result<SchedulingClaims, RuntimeError>; undeclared tools form an opaque scheduling barrier. Dynamic approval, preview, and provenance behavior remain on the existing Tool trait.
cargo run --manifest-path fixtures/atman-rt-embed/Cargo.toml --locked checks portable flow behavior with only atman-rt as an Atman dependency. cargo run --manifest-path fixtures/atman-rt-embed/Cargo.toml --locked -- --demo 6 compiles .at source, imports a public flow, invokes a host effect, and prints result: 18. Omit 6 to enter an integer interactively. The CI workflow runs the fixture on Linux, macOS, and Windows, runs it on Wasm/WASI, and checks the no_std core on wasm32-unknown-unknown.
The portable fake graphics fixture and the mirui SDL fixture use atman-rt as their only Atman crate dependency. Both run the VM on a worker while UI state, rendering, and destruction remain on the owner thread. The mirui demo lets structured .at data control the visible title, metrics, stage content, palette phase, loop, conditional branch, yield, deferred present barrier, and resource release; --no-default-features runs its display-independent framebuffer checks.
env CARGO_TARGET_DIR=target cargo run --manifest-path fixtures/atman-rt-host-demo/Cargo.toml --locked
env CARGO_TARGET_DIR=target cargo run --manifest-path fixtures/atman-rt-mirui/Cargo.toml --locked
env CARGO_TARGET_DIR=target cargo test --manifest-path fixtures/atman-rt-mirui/Cargo.toml --no-default-features --lockedThe default syntax feature enables source compilation. With default-features = false, the VM executes a program built from Atman AST without the parser dependency. Both modes require an allocator, pointer-width atomics for Arc-backed environments and lambda captures, and a host that polls returned futures. riscv32imc-unknown-none-elf lacks pointer-width atomics and is not currently supported.
The atman-rt embedding guide describes the VM API, generated host bindings, resource lifecycle, validation, and fixtures.
Language: Rust (edition 2024, MSRV 1.85). License: MIT OR Apache-2.0.
Is atman an IDE? No. atman is a runtime + CLI for coding-agent workflows. It runs in your terminal, as a daemon behind an HTTP API, or embedded.
Is atman tied to one model provider? No. Anthropic, OpenAI, and any OpenAI-compatible endpoint (Ollama, DeepSeek, GLM, …) work through provider adapters. Mix models in a single flow.
Can atman edit my files?
Yes, when configured with file-editing tools. Use contract.scope to statically limit which paths each flow can read/write. Hunk review lets you approve edits before they land.
How is atman different from Aider / Claude Code / Cline? Those are LLM-driven chat-first agents. atman is orchestration-driven: you write the flow, the flow decides what happens next, the LLM executes what it's assigned. This makes runs reproducible, auditable, and scriptable.
What is MCP?
Model Context Protocol. atman is an MCP consumer — any MCP server you configure in mcp_servers.json is auto-connected at boot and its tools appear alongside the built-in ones. The TUI MCP panel supports adding and editing local server configurations with keyboard or mouse controls.
How are confessions and rules managed? Open Manage Memory & Rules from the TUI command palette (Ctrl+P). Action labels show their keys, including [E]dit and [X] Archive. In the editor, click to place the cursor, use Tab or Shift+Tab to change fields, Shift+Enter for a newline, Enter to save, or Esc to cancel. Search confessions and the rules loaded by the current agent, edit confession fields, and inspect revision history; original records remain intact. Archiving a confession requires confirmation, removes it from active memory and search, and retains its revision history. Organize generates category and related-record suggestions with the active model and shows progress or errors in the Suggestions pane; a fresh session uses the configured smart model. Review the suggestions, select individual rows or Select All, then apply the chosen categories. Rules are read-only in this panel; Reload refreshes their source files.
Records and action buttons have padded mouse targets and subdued hover. Use PgUp / PgDn to page through records. In a narrow window, click › or press Enter to expand the selected record's details; ↑ / ↓, PgUp / PgDn, or the wheel scrolls the details, and Esc or ‹ List returns to the list. The editor keeps the focused field and Save / Cancel controls visible as its fields wrap.
PRs welcome. Run cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace before submitting.
Dual-licensed under MIT or Apache-2.0, at your option.