Skip to content

FAQ & Troubleshooting

Jump to bottom
Phi Trần tuấn edited this page Jun 30, 2026 · 1 revision

FAQ & Troubleshooting — Title: FAQ & Troubleshooting (trang cuối cùng)

# FAQ & Troubleshooting

## `FileNotFoundError: Khong tim thay .fw_data/src/`

`fw.py` auto-detects the module directory in 3 candidate locations:

1. Same directory as `fw.py` → `.fw_data/src/`
2. `sys.prefix/.fw_data/src/` (when installed via pip)
3. Two parent levels above `fw.py` → `.fw_data/src/`

If none is found, check whether you're running `fw.py` from the original cloned directory, or whether `pip install .` completed successfully. See [[Installation]].

## `NameError` that only shows up while the agent is running, not at startup

This is almost certainly caused by a change to the module load order in `_MODULES` (in `fw.py`), or a newly split-out module reading a global defined in a module that loads **later**, but reading it **at import-time** instead of **at runtime**. See the full explanation in [[Architecture]] § "Why order matters" before making changes.

## `pip install` fails on Termux

Add the `--break-system-packages` flag:

```bash
pip install . --break-system-packages

Termux has no sudo — don't use apt/systemctl or anything requiring root, including when letting the agent run the bash tool.

/mcp doesn't work / no servers show up

MCP only activates when the selected provider is commandcode (currently the only provider with the mcp_capable flag). Switch providers with /model, then verify with /mcp list. See MCP Integration.

Agent refuses to write/edit files even in build mode

Check:

  1. /perms — is the relevant tool's permission (write/edit/apply_patch) set to deny?
  2. /sandbox — is the file path outside the session's sandboxed project_dir? (After the first write, the sandbox is fully enforced — no reads/writes outside it.)
  3. /agent — are you accidentally in plan mode (read-only)?

See the full mechanism in Permissions & Sandbox.

!`shell` in a custom command doesn't run

This is intentional default behavior — the !`shell` syntax in .fw_data/commands/*.md files is disabled to prevent custom commands from silently executing system commands. Run the command manually if you trust it, or use the bash tool directly in conversation (still subject to its default ask permission). See Custom Commands.

UI has no gradient/spinner, just plain text

rich isn't installed. This isn't a bug — the app falls back to plain ANSI when rich is missing (HAS_RICH guard). Install rich if you want the full UI.

Lost progress after Ctrl+C mid-turn

Nothing is lost — the system automatically creates a checkpoint the moment a KeyboardInterrupt happens mid-turn, labeled "interrupted". Review it with /checkpoint. See Configuration.

Where can I contribute / report a bug?

This project is exclusively owned by Trần Tuấn Phi — it doesn't use a standard open-source license. Contact before any public sharing or commercial use: phihhhhhhhhhh@gmail.com. Report security issues privately before public disclosure. See the License and Security & Terms of Use sections in the README.

Clone this wiki locally