Build on AdaL

AdaL runs everywhere your work runs — and unlike most agents, it stays one agent everywhere: same tools, same models, same capabilities whether a person is typing, a CI job is running, or your application is driving. Automate once, benefit everywhere.

Surface	Interface	Lifetime	Use it when
Interactive	Terminal UI	Until the user exits	A person is working with AdaL directly
Headless (-q)	Final text or JSON on stdout	One invocation	A script, pipeline, or CI job needs the final answer
Event stream (-o stream-json)	NDJSON events on stdout	One invocation	A process needs live progress from a single run
Python SDK	Client library → subprocess	Persistent, multi-query	A Python application needs bidirectional control: streaming, tool approvals, session resume

All CLI flags that select the working directory, model, tools, and session persistence work the same way on every surface.

Choosing a surface

• "I just want the answer in my shell script." → Headless mode with the default text output. adal -q "what does main.py do?" | pbcopy.
• "I need to parse the result programmatically." → Headless mode with -o json — you get the answer, every tool call, the model, and a session ID in one object.
• "I want to show live progress while AdaL works." → -o stream-json — newline-delimited events (tool calls, results, final answer) as they happen.
• "I'm building an app around AdaL, not a one-shot script." → The Python SDK. It keeps a session open, streams events, lets you approve or deny tool calls in code, and resumes conversations across client instances.

What you control on every surface

• Tool approval — decide up front with --permission-mode (CLI) or handle each call with a callback (SDK). See Headless → Tool Approval and SDK → Permissions.
• Tool visibility — grant only the tools a task needs via --enabled-default-tools / --disabled-default-tools.
• Model selection — -m (CLI) or model (SDK).
• Sessions — resume any conversation with -r <session-id> (CLI) or resume() (SDK).
• Exit codes — scripts can branch on 0 (success), 1 (failure), 2 (a tool call needed approval that nobody could give).

Extending the agent

If you want to change what the agent can do rather than how you invoke it, see Building on the Ecosystem: custom tools, plugins and skills, custom system prompts, and lifecycle hooks.

Where to start

1. Headless Mode — the fastest path from interactive user to automation
2. Event Stream Reference — the NDJSON protocol for live integrations
3. SDK Overview — embedding AdaL in a Python application