Examples

Copy Markdown View Source

Runnable examples demonstrating every public function of the Amp SDK for Elixir.

Prerequisite: The Amp CLI must be installed and authenticated (amp login).

Behavior note: Some examples are optional and return exit code 20 (skip) when prerequisites are missing. run_all.sh reports these as skipped instead of passed/failed.

  • tools_make.exs: skips automatically if the installed Amp CLI requires interactive input
  • threads_handoff_replay.exs: set AMP_RUN_REPLAY=1 to run replay
  • mcp_oauth.exs: set AMP_MCP_OAUTH_SERVER and AMP_MCP_OAUTH_SERVER_URL to run status/logout; set AMP_MCP_OAUTH_RUN_LOGIN=1 to run login too

Run All

./examples/run_all.sh
./examples/run_all.sh --ssh-host example.internal
./examples/run_all.sh --ssh-host example.internal --danger-full-access

Or run individually:

mix run examples/<name>.exs
mix run examples/run_simple.exs -- --ssh-host example.internal
mix run examples/run_simple.exs -- --ssh-host example.internal --danger-full-access

Shared SSH Flags

Every example in this directory accepts the same optional SSH transport flags:

  • --cwd <path> passes an explicit working directory to the example
  • --danger-full-access maps the example to dangerously_allow_all: true
  • --ssh-host <host> switches the example to execution_surface: :ssh_exec
  • --ssh-user <user> overrides the SSH user
  • --ssh-port <port> overrides the SSH port
  • --ssh-identity-file <path> sets the SSH identity file

If you omit the SSH flags, the examples keep the existing local subprocess default unchanged.

For Amp, --danger-full-access keeps the same transport placement and opts the example into the permissive runtime flag that the Amp CLI already exposes.

Execute

ExampleDescription
basic_execute.exsStream all message types with pattern matching
run_simple.exsBlocking run/2 returning final result
create_user_message.exsMulti-turn via create_user_message/1
thinking.exsThinking blocks via --stream-json-thinking
no_ide_mode.exsHeadless flags: --no-ide, --no-notifications, --no-color
continue_thread.exsMulti-turn conversation with thread continuation
with_permissions.exsFine-grained tool permissions via create_permission/3

Management

ExampleDescription
usage.exsCredit balance and usage info
tools_list.exsList all available tools
tools_show.exsShow tool schema (e.g., Read)
tools_use.exsInvoke a tool directly
tools_make.exsCreate a new tool (auto-skips if CLI requires interactive input)
skills_list.exsList installed skills
skills_manage.exsSkill lifecycle: add, info, remove
permissions_list.exsList permission rules
permissions_manage.exsTest and add permissions
tasks_list.exsList tasks
tasks_import.exsImport tasks from JSON
review.exsCode review with summary

Threads

ExampleDescription
threads.exsCreate thread + export as Markdown
thread_lifecycle.exsFull lifecycle: create, rename, share, archive, delete
threads_list.exsList all threads
threads_search.exsSearch threads by query
threads_handoff_replay.exsThread handoff and replay

MCP

ExampleDescription
mcp_list.exsList configured MCP servers
mcp_doctor.exsCheck MCP server health
mcp_manage.exsMCP lifecycle: add, approve, remove
mcp_oauth.exsOAuth: status, login, logout

Adding New Examples

  1. Create a .exs file in this directory
  2. End with System.halt(0) to prevent the BEAM from hanging
  3. Add a run_example call in run_all.sh
  4. Use %Options{dangerously_allow_all: true} for non-interactive execution
  5. Require examples/support/example_helper.exs, call Support.init!(), and apply Support.with_execution_surface/1 or Support.command_opts/1 so the shared SSH and --danger-full-access flags work consistently

Recovery-Oriented Examples

For the emergency hardening lane, the most relevant existing examples are:

  • examples/continue_thread.exs
  • examples/threads.exs
  • examples/thread_lifecycle.exs

examples/run_all.sh already includes the continuation and thread-management demos in its standard execution sequence.