Bun + TypeScript runtime and CLI stack

AdaptiveAgent

AdaptiveAgent is the operating layer for reliable AI agents.

Run goal-oriented agents with typed tools, structured events, approvals, resumable runs, retries, child-run delegation, and multi-model support.

Start in 60 secs Read the overview
Typed tools and structured events Approvals and controlled execution Resumable runs with retries Child-run delegation and multi-model support

What is AdaptiveAgent?

From fragile agent demos to controlled production workflows.

AdaptiveAgent is the operating layer for reliable AI agents.

It is a Bun + TypeScript runtime and CLI stack for running goal-oriented agents with typed tools, structured events, approvals, resumable runs, retries, child-run delegation, and multi-model support.

It helps teams move from fragile agent demos to controlled, inspectable, recoverable production workflows.

Typed tools Keep executable primitives explicit and inspectable.
Structured events Make runtime history legible for teams and systems.
Approvals Put human and policy gates around sensitive actions.
Resumable runs Recover work without losing execution context.
Retries Handle transient model and tool failures deliberately.
Multi-model support Route work across providers that match the task.

Runtime shape

A local stack for goals, tools, history, and recovery.

AdaptiveAgent runs goals as durable sessions: tools stay explicit, events record each step, approvals gate sensitive actions, and runtime history supports inspection, retries, and recovery.

Inspectable agent execution loop
Goal-oriented agents Begin with a top-level objective and run through the CLI. adaptive-agent run
Typed tools Use explicit capabilities instead of hidden side effects. Tool
Structured events Trace approvals, retries, child runs, and model activity. event log
Recoverable history Resume, inspect, and reason about production workflows. runtime history

Getting Started in 60secs

Install, add a key, then run your first local agent.

These commands are the complete README quickstart, with code blocks styled for scanning and terminal use.

1

Install

Use the platform installer for macOS, Linux, or Windows PowerShell.
macOS
curl -fsSL https://github.com/ugmurthy/adaptiveAgent/releases/latest/download/install.sh | sh
Linux
curl -fsSL https://github.com/ugmurthy/adaptiveAgent/releases/latest/download/install.sh | sh
Windows PowerShell
irm https://github.com/ugmurthy/adaptiveAgent/releases/latest/download/install.ps1 | iex

If the installer says adaptive-agent is not on your PATH, run the exact PATH command it prints.

2

Add an API key

The default hosted quickstart uses OpenRouter.
bash
export OPENROUTER_API_KEY="<your-key>"
Windows PowerShell
$env:OPENROUTER_API_KEY = "<your-key>"

Other supported providers use their own keys:

  • OpenRouter: OPENROUTER_API_KEY Get key
  • Mistral: MISTRAL_API_KEY Get key
  • Mesh: MESH_API_KEY Get key
  • Ollama: no API key, but Ollama must be running locally
3

Init and run

Create local config, check the provider, and confirm the agent is working.
terminal
adaptive-agent init
adaptive-agent doctor --provider-check
adaptive-agent run "Hello, confirm you are working"

That is it. You now have a configured local agent that can run goals, use tools, and produce inspectable runtime history.

Examples

Start with one command, then grow into reusable agent workflows.

Use these examples after the quickstart has created local config and your provider API key is available in the shell.

  • Simple
  • Default agent
  • Read-only goal

Run one local goal

Use the generated default agent for a small, safe task. Add --progress and --events when you want to see the execution loop.

terminal
adaptive-agent run \
  --progress \
  --events \
  "Summarize this repository in five bullets."
  • Intermediate
  • Scripted prompt
  • Article output

Generate an article from a topic

The examples/writing-adaptive-agent.sh script builds a dated writing prompt, chooses the installed CLI when available, and runs with automatic approvals.

terminal
chmod +x ./examples/writing-adaptive-agent.sh

./examples/writing-adaptive-agent.sh \
  "The impact of Grok 4 on open source AI"
  • Complex
  • STORM methodology
  • Deep research

Use the STORM researcher agent

Run the bundled storm-researcher profile for a long-form, citation-heavy article that discovers perspectives, outlines first, then writes.

terminal
export MESH_API_KEY="<your-key>"

adaptive-agent run \
  --agent ./packages/agent-sdk/bundled/agents/storm-researcher.json \
  --approval auto \
  --events \
  --progress \
  "Write a cited STORM-style article about agent reliability patterns in 2026."

Docs

How to use AdaptiveAgent from install to repeatable runs.

AdaptiveAgent is a CLI-facing shell workflow backed by a typed runtime. The normal path is initialize config, choose an agent profile, run a goal, and inspect or retry the result.

1. Initialize your local agent home

Run adaptive-agent init once to create ~/.adaptiveAgent, install bundled agents and skills, and write default settings.

  • Health check: adaptive-agent doctor --provider-check
  • Inventory: adaptive-agent catalog
  • Resolved config: adaptive-agent config

2. Run goals with the right agent

The default command is adaptive-agent run "goal". Pass --agent to use a specific JSON profile by path or by a name found in your configured agent directories.

  • Provider: override with --provider and --model.
  • Runtime: use --runtime memory locally or --runtime postgres for durable history.
  • Safety: choose --approval manual, auto, or reject.

3. Inspect, automate, and recover

Use runtime output modes and event flags to make runs easy to debug locally or consume from scripts.

  • Readable runs: add --progress, --events, and --inspect.
  • Automation: use --output json or --output jsonl.
  • Recovery: use adaptive-agent retry --run-id <runId> for failed retryable runs.

Pick the workflow that matches the job

Try one task adaptive-agent run "goal" for a quick local run.
Make it visible Add --progress --events --inspect to watch the loop and review the result.
Keep it safe Use --approval reject for read-only audits, manual for prompts, or auto for trusted automation.
Automate it Use --output json or --output jsonl from scripts, CI, and benchmark runs.
Make it durable Use --runtime postgres when a run needs history, retry, or restart-safe execution.

Useful things to try first

Map a repository Ask for packages, entrypoints, architecture, tests, and risky areas before changing code.
Review a pull request Run a reviewer profile with --approval reject so it can inspect but not mutate.
Write a research brief Use the STORM researcher for cited reports, market scans, or technical comparisons.
Generate release notes Turn commits, docs, or changelog fragments into user-facing summaries.
Run private local analysis Switch to --provider ollama when data should stay on your machine.
Evaluate agents Use JSONL input and output to compare providers, models, prompts, and agent profiles.

Create your own reusable agent profile

An agent profile is a portable JSON workflow: model, instructions, tools, defaults, and optional delegates. Save named profiles such as reviewer.json, researcher.json, or release-manager.json, then run them with --agent.

Start with a read-only reviewer that can inspect files and web pages but cannot write or run shell commands.

agents/reviewer.json
{
  "version": 1,
  "id": "reviewer",
  "name": "Repository Reviewer",
  "invocationModes": ["run"],
  "defaultInvocationMode": "run",
  "model": {
    "provider": "openrouter",
    "model": "qwen/qwen3.5-27b",
    "apiKeyEnv": "OPENROUTER_API_KEY"
  },
  "workspaceRoot": ".",
  "systemInstructions": "Review code for correctness, safety, tests, and maintainability. Return prioritized findings with file references.",
  "tools": ["read_file", "list_directory", "web_search", "read_web_page"],
  "defaults": {
    "maxSteps": 30,
    "capture": "summary"
  }
}

Use the profile by path, or place it in one of your configured agent directories and use the short name.

terminal
adaptive-agent run \
  --agent ./agents/reviewer.json \
  --approval reject \
  --progress \
  --inspect \
  "Review the current repository changes for risky runtime behavior."

adaptive-agent catalog

Recipes for real work

Understand a codebase

terminal
adaptive-agent run \
  --progress \
  --events \
  "Map this repository: packages, entrypoints, data flow, tests, and risky areas."

Create structured automation

terminal
adaptive-agent run \
  --input-json '{"topic":"agent reliability","audience":"engineering leaders"}' \
  --output json \
  "Create a concise research brief."

Run with a local model

terminal
adaptive-agent run \
  --provider ollama \
  --model llama3.2 \
  --runtime memory \
  "Summarize this document without using a hosted provider."

Persist and retry long-running work

terminal
adaptive-agent run \
  --runtime postgres \
  --events \
  --inspect \
  "Audit these logs and summarize likely root causes."

adaptive-agent retry --run-id <runId> --runtime postgres

Run evaluations

Use eval commands when you want repeatable model or agent-profile comparisons over JSONL cases.

terminal
adaptive-agent eval cases \
  --input ./data/tasks.jsonl \
  --out ./runs/results.jsonl \
  --runtime postgres \
  --output jsonl

Coordinate specialists

For bigger objectives, use a coordinator profile and a worker catalog so research, writing, review, and synthesis can be separated.

terminal
adaptive-agent swarm-run \
  --agent coordinator \
  --worker-catalog researcher,writer,reviewer \
  --runtime postgres \
  --events \
  "Produce a launch strategy."

Beyond the terminal

AdaptiveAgent is technical today, but the same runtime can be packaged for non-technical users.

  • Desktop app: guided setup, saved profiles, run history, and approval prompts.
  • Team workspace: shared templates, durable runs, human review, and audit trails.
  • Hosted forms: turn common workflows into simple inputs such as topic, files, and desired output.