Share feedback

Report a problem with /feedback. For rendering or interaction bugs, you can include a trace or terminal recording to help reproduce it.

Report a problem

Inside the interactive shell:

$/feedback

The command opens fx.sh/feedback, which goes to the fx issue form on GitHub. If fx can't open a browser, open that address yourself. Include what happened, what you expected, and the steps to reproduce the problem.

Create a private diagnostic trace

Inside the interactive shell:

$/trace

/trace writes the trace to an fx-trace-*.jsonl file in your temporary directory, readable only by you. The file is in JSON Lines format, one JSON object per line, so a program can read the trace. It includes the fx version and platform, the model, permission mode, workspace path, session ID, recent tool calls, network and renderer diagnostics, and the transcript with obvious secrets masked. It keeps up to 32 failed network calls, 32 failed model catalog events, and 32 failed context compaction events from the session as their own failed_network_call, failed_model_catalog_event, and failed_compaction_event records, so later entries that did not fail can't push them out of the trace. Its problem records name the newest three of each kind. When a debug log is on, the trace also includes the log's most recent lines.

The trace keeps the 32 most recent failed tool calls in failed_tool_call records, so later successful calls don't push them out. Each one has up to 8 KiB of its arguments and 8 KiB of its result, taken from the start and the end, and, for a call that ran, its default working folder. Tool call records also have the call's call_id, which the session log uses for the same call. A shell record shows how fx starts shell commands and which common commands, such as ls, your shell startup files redefine.

On macOS, /trace copies the file itself to the clipboard; on other platforms, it prints the saved path. To add the trace to a report, share it as a link from fx.sh/share, which hides private data before upload, and put the link in the issue form's Trace field. Or zip the trace file and attach the .zip; GitHub doesn't accept .jsonl files.

Traces, debug logs, and recordings stay local until you share them. They can contain prompts, code, paths, and secrets, so remove anything private before you share them.

The trace also describes your setup. In auto mode, its auto_review records show what the safety reviewer decided for each recent action it reviewed, and its held_auto_review records keep the last 32 actions it held, each with the reason or the reviewer's rationale. Its git record shows the workspace's branch, changed files, and recent commits. Its setting records show the values your settings files and FX_* variables set, as fx config list --show-origin prints them. Its skill and skill_problem records list the skills fx found and any it couldn't load. File names, commit messages, and setting values can be private too, so check these records before you share a trace.

fx.sh/share turns a trace into a link that shows it the way fx does:

  1. Open fx.sh/share and paste the /trace output, or drop the .jsonl file onto the page. On macOS, /trace copies the file itself, so drop it or open it and copy its text. Traces up to 1.4 MB are supported, and the .md traces that earlier fx versions wrote up to 1 MB. If the page says the trace is incomplete, run /trace again.
  2. Review the highlighted redactions. The page replaces home directory names, known credential formats, sensitive URL parameters, long random-looking tokens, email addresses, IP addresses, phone numbers, and card and social security numbers with placeholders. Keep any value you want to show.
  3. Choose create secret link, then put the link in your report.

Your browser encrypts the redacted text before uploading it. The decryption key is the part of the link after #, which your browser never sends to fx.sh, so a lost link can't be recovered. Anyone with the link can read the redacted trace, and the link expires 7 days after you create it.

Read a trace with a program

Each line of a trace is a record: a JSON object whose type field names what it holds. The first line is an fx_trace header with the trace's format_version, the fx_version and git_commit of the fx that wrote it, and written_at. The last line is an end record whose records field counts the records before it, so a trace without one was cut off while fx wrote it.

Information that has a list comes as a summary record followed by one record for each item:

RecordsWhat they hold
summary, current_stateThe platform, model, permission mode, and workspace; the session, token totals, process, worker, stream, and terminal state
problems, problemThe problems fx found, each with a kind such as network_call, tool_call, compaction, mcp_server, or model_catalog
tool_calls, tool_call, web_search_call, failed_tool_callRecent tool calls with their outcome, duration, source, call ID, and masked arguments and results, and the most recent failed calls, kept apart
network, network_turn, network_call, failed_network_callRecent model requests with their status, duration, tokens, stop reasons, and gateway diagnostics, plus session totals and the session's newest 32 failed requests
model_catalog, model_catalog_event, failed_model_catalog_eventThe model catalog's state, the selected model's capabilities, recent catalog events, and the session's newest 32 failed catalog events
compaction, compaction_event, failed_compaction_eventContext compaction decisions and failures, and the session's newest 32 failed compaction events
last_shutdown, interrupted_turn, session_titleHow the last run ended, a turn you interrupted, and how the session got its title
subagents, subagent, subagent_turnThe subagents the session started, each with its name, session ID, state, and task, and their recent turns
permissions, permission_grantThe permissions granted in this session
auto_reviews, held_auto_review, auto_reviewAuto-mode safety reviews counted by result, the newest that didn't clear, and the newest of all, each with its action, risk or reason, rationale, and call ID
gitThe workspace's branch, status, last 5 commits, and diff stats
settings, setting, unknown_settingWhat each settings file and FX_* variable sets, with masked values, and the keys fx doesn't know
skills, skill, skill_problemThe skills fx found with their source, and the skills it couldn't load with the cause
runtime_context, mcp_serverTerminal settings and the state of each MCP server
shellHow fx starts shell commands and which common commands your shell startup files redefine
renderer_state, renderer_events, renderer_eventRenderer diagnostics
transcript, transcript_entryThe transcript, one record for each entry, with its kind and text
trace_log, trace_log_lineThe debug log's most recent lines, when a log is on

When the session started subagents, a tool call or network call that a subagent made has source set to subagent and a subagent_id. Each subagent record is followed by its newest 8 turns, newest first, as subagent_turn records, and counts the rest in turns_omitted. When the trace still has the turn, the subagent_turn record with that subagent_id is among them, and both records carry that subagent's session_id. The subagents record lists in unmatched_subagent_ids the subagent_id of each recent tool call whose turn fx no longer keeps.

A time is an ISO 8601 UTC string with a matching field that ends in _ms and holds Unix milliseconds. A field without a value is left out. Text that can hold prompts, output, or secrets has obvious secrets masked. Skip record types and fields you don't recognize, because fx can add them without changing format_version.

For example, this jq command lists the tool calls that didn't succeed:

jq -c 'select(.type == "tool_call" and .outcome != "succeeded") | {name, outcome, duration_ms}' fx-trace-*.jsonl

Record a terminal issue

Start fx with recording enabled, then reproduce the problem:

$FX_DEBUG_RECORD=1 fx

fx shows the recording path in the transcript and writes a private .fxtape file under ~/.fx/recordings/. Choose an explicit path with FX_RECORD, which overwrites any file already at that path:

$FX_RECORD=./repro.fxtape fx

Add FX_DEBUG_RECORD_SILENT_BANNER=1 to keep the recording notice out of the inline transcript during a screen share. Recording stays on, and the notice still appears in Full detail, which ctrl+o opens.

Recordings capture everything fx draws on screen, including the prompt text you type, plus resizes, interrupts, and markers. Set FX_RECORD_INPUT=1 only when the fx team needs raw terminal input to reproduce the issue.

Replay a recording

Exit fx, then replay the recording to confirm that it captures the issue:

$fx replay ./repro.fxtape

Turn on a debug log

Start fx with FX_TRACE=1 to write a debug log to ~/.fx/logs/trace.log:

$FX_TRACE=1 fx

To choose the file, set FX_TRACE_LOG to its path instead. A relative path is relative to the workspace. While a log is on, /trace includes its most recent lines.

Check your setup first

For startup or session problems, run:

$fx doctor

When fx can recover a session problem, the output includes the command to run. Troubleshooting covers the problems it reports most often.