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:
/feedbackThe 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.
Share a trace as a link
fx.sh/share turns a trace into a link that shows it the way fx does:
- Open fx.sh/share and paste the
/traceoutput, or drop the.jsonlfile onto the page. On macOS,/tracecopies the file itself, so drop it or open it and copy its text. Traces up to 1.4 MB are supported, and the.mdtraces that earlier fx versions wrote up to 1 MB. If the page says the trace is incomplete, run/traceagain. - 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.
- 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:
| Records | What they hold |
|---|---|
summary, current_state | The platform, model, permission mode, and workspace; the session, token totals, process, worker, stream, and terminal state |
problems, problem | The 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_call | Recent 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_call | Recent 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_event | The 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_event | Context compaction decisions and failures, and the session's newest 32 failed compaction events |
last_shutdown, interrupted_turn, session_title | How the last run ended, a turn you interrupted, and how the session got its title |
subagents, subagent, subagent_turn | The subagents the session started, each with its name, session ID, state, and task, and their recent turns |
permissions, permission_grant | The permissions granted in this session |
auto_reviews, held_auto_review, auto_review | Auto-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 |
git | The workspace's branch, status, last 5 commits, and diff stats |
settings, setting, unknown_setting | What each settings file and FX_* variable sets, with masked values, and the keys fx doesn't know |
skills, skill, skill_problem | The skills fx found with their source, and the skills it couldn't load with the cause |
runtime_context, mcp_server | Terminal settings and the state of each MCP server |
shell | How fx starts shell commands and which common commands your shell startup files redefine |
renderer_state, renderer_events, renderer_event | Renderer diagnostics |
transcript, transcript_entry | The transcript, one record for each entry, with its kind and text |
trace_log, trace_log_line | The 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 fxfx 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 fxAdd 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.fxtapeTurn on a debug log
Start fx with FX_TRACE=1 to write a debug log to ~/.fx/logs/trace.log:
FX_TRACE=1 fxTo 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 doctorWhen fx can recover a session problem, the output includes the command to run. Troubleshooting covers the problems it reports most often.