Share Thread with Support

We may ask you to share your thread with authorized Sourcegraph staff members to help diagnose quality issues:

1. In the Amp sidebar in VS Code or when viewing the thread on ampcode.com, open the sharing menu.
2. Select Share Thread with Support.

You can also share your thread via the CLI:

$amp threads share--support<thread-id>

This will allow authorized Sourcegraph staff members to view your thread for debugging purposes.

Support Bundles

We may ask you to generate a support bundle and share it directly with authorized Sourcegraph staff members to help diagnose quality issues. You can email support bundles toamp-devs@sourcegraph.com.

To generate a support bundle:

1. Open your terminal
2. Runamp doctor ornpx @sourcegraph/amp doctor
3. The bundle will be saved as a timestamped.json.gz file in your current directory

What’s included in a support bundle:

• System Information: Operating system, hardware specs, Node.js version, available memory and disk space
• Amp Installation: Version detection, installation method (npm/pnpm/yarn), package manager, recent logs (last 1000 entries)
• Network Diagnostics: Connectivity tests to Amp services, DNS resolution, proxy configuration detection
• SSL Analysis: Certificate chains, trusted root certificates, TLS configuration for corporate environments
• Environment Variables: Only variables with theAMP_ prefix

Support bundles are automatically redacted using Amp’sbuilt-in secret detection patterns but we recommend manually reviewing the information before sharing support bundles as log files gathered may contain sensitive information.

Visual Studio Code Developer Console

We may ask you to share information from your Visual Studio Code Developer Console.

To open the Developer Console:

macOS/Windows/Linux:

• PressCtrl/Cmd+Shift+P to open the Command Palette
• Type “Developer: Toggle Developer Tools” and press Enter

Or:

• Use the keyboard shortcut:Ctrl/Cmd+Option/Alt+I

The Developer Console will open as a separate window or panel, showing the Console, Network, and other debugging tabs that can help authorized Sourcegraph staff members diagnose quality issues.

Service Status

Checkampcodestatus.com for service status and to sign up for alerts via email, RSS, Slack. Alternatively, follow@ampcodestatus on X.

News

Follow Amp'sNews for the changelog and other updates from the Amp team.

Frequently Ignored Feedback

See Amp'sFrequently Ignored Feedback for the most common valid feedback that we've chosen to not address.

Permissions Reference

Amp’s permission system controlsevery tool invocation before execution. The system uses a single, ordered list of rules that are evaluated sequentially until the first match is found.

How Permissions Work

Before running any tool, Amp evaluates permissions through these steps:

1. Find matching rule: The first rule that matches the tooland its arguments wins
2. Determine action: The matching rule tells Amp to:
   • allow - run the tool silently
   • reject - block the call (optionally with custom message)
   • ask - prompt the operator for approval
   • delegate - delegate decision to an external program
3. Examine builtin rules: If no user rule matches, Amp falls back to built-in rules (e.g., allowingls via Bash)
4. Default Behavior: If no matching entry is found at all:
   • Main thread: Amp asks the operator
   • Sub-agent: Amp rejects the tool call

Configuration

Rules are defined in theamp.permissions setting. Each rule is a JSON object with these properties:

Match Conditions

Eachmatches key corresponds to a tool argument. Values can be:

• string – glob pattern (* = any characters) or regex pattern (/pattern/)
• array – OR of each entry (["rm -rf *", "git commit *"])
• boolean/number/null/undefined – literal value match
• object – nested structure matching

Regular Expression Patterns

Strings that start and end with/ are treated as regular expressions:

{  "tool": "Bash",  "matches": { "cmd": "/^git (status|log|diff)$/" },  "action": "allow"}

This matches exactlygit status,git log, orgit diff but notgit commit.

Value Type Matching

• String patterns only match string values using glob syntax
• Literal values (boolean, number, null, undefined) require exact matches
• Array conditions provide OR logic across multiple patterns
• Nested objects enable deep property matching with dot notation for objects and numeric strings for array indices

Examples

Basic Permission Rules

Allow all Bash commands in main thread, but restrict sub-agents:

{  "tool": "Bash",  "action": "allow",  "context": "thread"},{  "tool": "Bash",  "matches": { "cmd": ["rm -rf *", "find *", "git commit *"] },  "action": "reject",  "context": "subagent"}// In text form:// allow --context thread Bash// reject --context subagent Bash --cmd "rm -rf *" --cmd "find *" --cmd "git commit *"

Ask before grepping in the home directory:

{  "tool": "Grep",  "matches": { "path": "$HOME/*" },  "action": "ask"}// In text form:// ask Grep --path '$HOME/*'

Forbid editing dotfiles:

{  "tool": "edit_file",  "matches": { "path": ".*" },  "action": "reject"}// In text form:// reject edit_file --path '.*'

Delegation

Delegate GitHub CLI calls to external validator:

{  "tool": "Bash",  "matches": { "cmd": "gh *" },  "action": "delegate",  "to": "my-gh-permission-helper"}// In text form:// delegate --to my-gh-permission-helper Bash --cmd "gh *"

When instructed to delegate, Amp will:

• Execute the program named into (must be on$PATH, or an absolute path)
• ExportAMP_THREAD_ID,AGENT_TOOL_NAME=nameOfInvokedTool andAGENT=amp environment variables
• Pipe tool parameters tostdin as JSON
• Interpret exit status:
  • 0 → allow
  • 1 → ask operator
  • ≥ 2 → reject (stderr is surfaced to the model)

Text Format

For editing many rules conveniently, you can use the text format withamp permissions commands:

<action> [--<action-arg> ...] <tool> [--<match-key>[:<op>] <value>] ...

The text format is designed to be compatible with UNIX shell syntax,allowing you to copy/paste rules from and to the command line without further editing.

# Basic allow/reject rulesallow Bash--cmd'git *'reject Bash--cmd'python *'# Multiple conditionsallow Bash--cmd'git diff*'--cmd'git commit*'# Delegationdelegate--to amp-git-permissions Bash--cmd'*'

• Single- and double-quoted strings are supported
• unquoted true, false, null and numeric words are interpreted as JSON literals
• Any value containing* must be quoted

Listing Rules

amp permissions list# Show user rulesamp permissions list--builtin# Only built-in rules

Testing Rules

For example, testing if it would ask on a git commit:

$amp permissionstest Bash--cmd"git commit -m 'test'"tool: Basharguments: {"cmd":"git commit -m 'test'"}action: askmatched-rule: 12source: builtin

or testing if it would ask to edit .env in the current directory

$amp permissionstest edit_file--path"$PWD/README.md"tool: edit_filearguments: {"path":"/Users/your/project/README.md"}action: allowmatched-rule: 29source: builtin

The test subcommand allows you to test permission rules without actually running any toolsor hoping that the agent will generate the right parameters.

Editing Rules

You can use$EDITOR to edit rules interactively in the text format:

$amp permissions edit

And you can edit from STDIN:

$amp permissions edit<<'EOF'# Ask before every tool useask '*'EOF

Add Rules

For example, reject all mermaid diagrams:

$amp permissionsadd reject mermaid

or ask before searching about node.js or npm packages:

$amp permissionsadd ask web_search--query"*node*"--query"*npm*"

Matching multiple tools with a single rule

Tool names support glob patterns for managing groups of tools:

• Bash - matches only the Bash tool
• mcp__playwright__* - matches all Playwright MCP tools

Context Restrictions

Use thecontext field to restrict rules to the main agent or subagents

• "context": "thread" - only applies in main conversation thread
• "context": "subagent" - only applies to sub-agent tool calls
• Omitcontext - applies everywhere

Stream JSON Output

Amp’s CLI supports Claude Code compatible stream JSON output format for programmatic integration and real-time conversation monitoring.

Usage

Use the--stream-json flag with--execute mode to output in stream JSON format instead of plain text:

Basic usage with argument:

$amp--execute"what is 3 + 5?" --stream-json

With stdin input:

$echo"analyze this code"| amp--execute --stream-json

Streaming JSON input mode (see below for more information):

$echo'{"type":"user","message":{"role":"user","content":[{"type":"text","text":"what is 2+2?"}]}}'| amp--execute --stream-json --stream-json-input

Note: The--stream-json flag requires--execute mode. It cannot be used standalone.

Each conversation begins with an initialinit system message, followed by a list of user and assistant messages, followed by a finalresult system message with stats. Each message is emitted as a separate JSON object.

Message Schema

Messages returned from the stream JSON API are strictly typed according to the following schema:

typeStreamJSONMessage=// An assistant message|{      type:"assistant";      message:{        type:"message";        role:"assistant";        content:Array<{          type:"text";          text:string;}|{          type:"tool_use";          id:string;          name:string;          input: Record<string,unknown>;}>;        stop_reason:"end_turn"|"tool_use"|"max_tokens"|null;        usage?:{          input_tokens:number;  max_tokens:number;          cache_creation_input_tokens?:number;          cache_read_input_tokens?:number;          output_tokens:number;          service_tier?:string;};};      parent_tool_use_id:string|null;      session_id:string;}// A user message (tool results)|{      type:"user";      message:{        role:"user";        content:Array<{          type:"tool_result";          tool_use_id:string;          content:string;          is_error:boolean;}>;};      parent_tool_use_id:string|null;      session_id:string;}// Emitted as the last message on success|{      type:"result";      subtype:"success";      duration_ms:number;      is_error:false;      num_turns:number;      result:string;      session_id:string;      usage?:{        input_tokens:number;max_tokens:number;        cache_creation_input_tokens?:number;        cache_read_input_tokens?:number;        output_tokens:number;        service_tier?:string;};      permission_denials?:string[];}// Emitted as the last message on error|{      type:"result";      subtype:"error_during_execution"|"error_max_turns";      duration_ms:number;      is_error:true;      num_turns:number;      error:string;      session_id:string;      usage?:{        input_tokens:number;max_tokens:number;        cache_creation_input_tokens?:number;        cache_read_input_tokens?:number;        output_tokens:number;        service_tier?:string;};      permission_denials?:string[];}// Emitted as the first message at the start of a conversation|{      type:"system";      subtype:"init";      cwd:string;      session_id:string;      tools:string[];      mcp_servers:{ name:string; status:"connected"|"connecting"|"connection-failed"|"disabled"}[];};

Example Output

Simple math query:

$amp--execute"what is 3 + 5?" --stream-json{"type":"system","subtype":"init","cwd":"/Users/orb","session_id":"T-f9941a55-3765-421e-972f-05dc1138c3a3","tools":["Bash","finder","create_file","edit_file","glob","Grep","mcp__postgres__query","mermaid","oracle","Read","read_mcp_resource","read_web_page","Task","todo_read","todo_write","undo_edit","web_search"],"mcp_servers":[{"name":"postgres","status":"connected"}]}{"type":"user","message":{"role":"user","content":[{"type":"text","text":"what is 3 + 5?"}]},"parent_tool_use_id":null,"session_id":"T-f9941a55-3765-421e-972f-05dc1138c3a3"}{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"8"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"cache_creation_input_tokens":16256,"cache_read_input_tokens":0,"output_tokens":99,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-f9941a55-3765-421e-972f-05dc1138c3a3"}{"type":"result","subtype":"success","duration_ms":5400,"is_error":false,"num_turns":1,"result":"8","session_id":"T-f9941a55-3765-421e-972f-05dc1138c3a3"}

Tool usage example:

$amp--execute"list files using a tool" --stream-json{"type":"system","subtype":"init","cwd":"/Users/orb/project","session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95","tools":["Bash","finder" ,"create_file","edit_file","glob","Grep","mcp__postgres__query","mermaid","oracle","Read","read_mcp_resource","read_web_page","Task","todo_rea d","todo_write","undo_edit","web_search"],"mcp_servers":[{"name":"postgres","status":"connected"}]}{"type":"user","message":{"role":"user","content":[{"type":"text","text":"list files using a tool"}]},"parent_tool_use_id":null,"session_id":"T-d2fc4acc-dd1d-4 97f-9609-ed0da22a7c95"}{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_019cyniPYrSgaJitUSMyxyNV","name": "read", "input":{"path":"/Users/orb/project"}}],"stop_reason":"tool_use","usage":{"input_tokens":10,"cache_creation_input_tokens":13150,"cache_read_input_tokens": 0,"output_tokens":111,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95"}{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_019cyniPYrSgaJitUSMyxyNV","content":"["index.js","README.md"] ","is_error":false}]},"parent_tool_use_id":null,"session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95"}{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"Two files: index.js and README.md"}],"stop_reason":"end_tu rn","usage":{"input_tokens":7,"cache_creation_input_tokens":133,"cache_read_input_tokens":13150,"output_tokens":13,"max_tokens":968000,"service_tier":"standard "}},"parent_tool_use_id":null,"session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95"}{"type":"result","subtype":"success","duration_ms":7363,"is_error":false,"num_turns":2,"result":"Two files: index.js and README.md","session_id":"T-d2fc4acc-dd1d-497f-9609-ed0da22a7c95"}

Streaming JSON Input (--stream-json-input)

The--stream-json-input flag enablesstreaming input where Amp reads messages from stdin until it’s closed.

Each message should be a valid JSON object on a single line:

{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Your message here"}]}}

When using--stream-json-input, the behavior of--execute changes in that Amp will only exit once both the assistant is doneand stdin has been closed.

This allows for programmatic use of the Amp CLI to have conversations with multiple user messages.

Example:

#!/bin/bashsend_message(){localtext="$1"echo'{"type":"user","message":{"role":"user","content":[{"type":"text","text":"'$text'"}]}}'}{  send_message"what's 2+2?"sleep10  send_message"now add 8 to that"sleep10  send_message"now add 5 to that"}| amp--execute --stream-json --stream-json-input

This script produces the following output:

$./script.sh{"type":"system","subtype":"init","cwd":"/Users/orb","session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a","tools":["Bash","finder","create_file","edit_file","glob","Grep","mcp__postgres__query","mermaid","oracle","Read","read_mcp_resource","read_web_page","Task","todo_read","todo_write","undo_edit","web_search"],"mcp_servers":[{"name":"postgres","status":"connected"}]}{"type":"user","message":{"role":"user","content":[{"type":"text","text":"what's 2+2?"}]},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"4"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"cache_creation_input_tokens":13993,"cache_read_input_tokens":0,"output_tokens":67,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}{"type":"user","message":{"role":"user","content":[{"type":"text","text":"now add 8 to that"}]},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"12"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"cache_creation_input_tokens":36,"cache_read_input_tokens":13993,"output_tokens":76,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}{"type":"user","message":{"role":"user","content":[{"type":"text","text":"now add 5 to that"}]},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}{"type":"assistant","message":{"type":"message","role":"assistant","content":[{"type":"text","text":"17"}],"stop_reason":"end_turn","usage":{"input_tokens":10,"cache_creation_input_tokens":36,"cache_read_input_tokens":14029,"output_tokens":43,"max_tokens":968000,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}{"type":"result","subtype":"success","duration_ms":21639,"is_error":false,"num_turns":3,"result":"17","session_id":"T-addfb7a4-61d9-41e1-890b-7330aa54087a"}

Subagent Support

Stream JSON mode fully supports subagents created by the Task tool:

• Subagent messages have theirparent_tool_use_id field set to the Task tool’s ID
• Main agent messages haveparent_tool_use_id set tonull
• Completion logic waits for all subagents to finish before emitting the final result

Example with subagents:

$amp--execute"use Task tool to calculate 4+7" --stream-json{"type":"system","subtype":"init",...}{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_123","name":"Task",...}]},"parent_tool_use_id":null,...}{"type":"assistant","message":{"content":[{"type":"text","text":"11"}]},"parent_tool_use_id":"toolu_123",...}{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"toolu_123",...}]},"parent_tool_use_id":null,...}{"type":"result","subtype":"success",...}

Claude Code Compatibility

Amp’s stream JSON output tries to be compatible with Claude Code’s format as much as possible.

Workspace thread visibility controls

By default, threads created by workspace members areshared with the workspace.

Enterprise workspaces can configure additional options for thread visibility in theworkspace settings page.The currently supported options include:

• Disabling public threads
• Disabling private threads
• Private-by-default threads

Upon request, Enterprise workspaces can also enable user groups and per-group thread visibility.

Learn more thread visibility inPrivacy & Permissions.