Threads

Threads provide conversation continuity across multiple Amp executions. Each execution creates a thread, and you can continue threads to build multi-step workflows.

Creating Threads

{:ok, thread_id} = AmpSdk.threads_new(visibility: :private)
# => {:ok, "T-a1b2c3d4-..."}

Visibility Options

• :private — only you can see it
• :public — anyone with the link
• :workspace — workspace members
• :group — group members

Continuing Threads

Continue Most Recent Thread

alias AmpSdk.Types.Options

AmpSdk.run("Follow up on the last task", %Options{continue_thread: true})

Continue a Specific Thread

AmpSdk.run("Continue this work", %Options{continue_thread: "T-abc123-def456"})

Listing Threads

{:ok, threads} = AmpSdk.threads_list()

Enum.each(threads, fn thread ->
  IO.puts("#{thread.id} #{thread.visibility} #{thread.messages} #{thread.title}")
end)

Searching Threads

# Basic search
{:ok, results} = AmpSdk.threads_search("auth refactor")

# With pagination
{:ok, results} = AmpSdk.threads_search("auth", limit: 10, offset: 0)

# JSON output for programmatic use
{:ok, json} = AmpSdk.threads_search("auth", json: true)

Sharing Threads

Change visibility or share with Amp support:

# Change thread visibility
{:ok, output} = AmpSdk.threads_share("T-abc123-def456", visibility: :public)
IO.puts(output)

# Share with Amp support for debugging
{:ok, output} = AmpSdk.threads_share("T-abc123-def456", support: true)
IO.puts(output)

Renaming Threads

{:ok, _} = AmpSdk.threads_rename("T-abc123-def456", "Auth module refactor")

Archiving Threads

Soft-delete a thread (can be restored):

{:ok, _} = AmpSdk.threads_archive("T-abc123-def456")

Deleting Threads

Permanently delete a thread:

{:ok, _} = AmpSdk.threads_delete("T-abc123-def456")

Handoff Threads

Create a handoff thread from an existing thread for multi-agent workflows:

{:ok, new_thread_id} = AmpSdk.threads_handoff("T-abc123-def456",
  goal: "Continue with the auth refactor and summarize next steps",
  print: true
)

Replaying Threads

Re-run a thread with its original history:

{:ok, output} = AmpSdk.threads_replay("T-abc123-def456",
  no_typing: true,
  no_indicator: true,
  exit_delay: 0
)

threads_replay is terminal-driven by the Amp CLI; in some non-interactive/headless environments the CLI may return an internal error.

Exporting Threads

Get a thread's conversation as Markdown:

{:ok, markdown} = AmpSdk.threads_markdown("T-abc123-def456")
File.write!("thread_export.md", markdown)

Multi-Step Workflow

alias AmpSdk.Types.Options

opts = %Options{visibility: "private", dangerously_allow_all: true}

# Step 1: Analyze
{:ok, analysis} = AmpSdk.run("Analyze lib/auth.ex for improvements", opts)

# Step 2: Implement (continues the thread)
{:ok, changes} = AmpSdk.run(
  "Implement the improvements you identified",
  %Options{opts | continue_thread: true}
)

# Step 3: Test (continues again)
{:ok, tests} = AmpSdk.run(
  "Write tests for the changes",
  %Options{opts | continue_thread: true}
)

Session ID

Each execution's SystemMessage includes a session_id (the thread ID). You can capture it from the stream:

thread_id =
  AmpSdk.execute("Hello")
  # Drain the stream fully so the thread is persisted before follow-up commands.
  |> Enum.reduce(nil, fn
    %AmpSdk.Types.SystemMessage{session_id: id}, _acc -> id
    _msg, acc -> acc
  end)

All Thread Functions

Standardized Thread Projection

The native Amp thread model is still the source of truth, but the runtime layer now offers a standardized projection for upper orchestration repos:

• AmpSdk.Runtime.CLI.capabilities/0
• AmpSdk.Runtime.CLI.list_provider_sessions/1

That projection is deliberately history-focused. It lets the caller list and resume known Amp threads without pretending that Amp shares the exact same prompt/control semantics as the other providers.