fix: opt-in --debug flag and README security warning

README.md

@@ -62,6 +62,11 @@ python app.py --port 8080 --host 0.0.0.0
 python app.py --base-dir /path/to/claude/projects
 ```
 
+> **Security warning:** Do not use `--host 0.0.0.0` together with `--debug` on untrusted networks.
+> That combination exposes Werkzeug's interactive debugger, which allows arbitrary code execution
+> from any browser that can reach the server. For typical local browsing, keep the default
+> `--host 127.0.0.1` and omit `--debug`.
+
 ### CLI Export
 
 ```bash

app.py

@@ -41,6 +41,12 @@ def index():
     parser = argparse.ArgumentParser(description="Claude Code Chat Browser")
     parser.add_argument("--port", type=int, default=5000)
     parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        default=False,
+        help="Enable Flask/Werkzeug debug mode (never use with --host 0.0.0.0 on untrusted networks).",
+    )
     parser.add_argument("--base-dir", default=None, help="Override Claude projects dir")
     parser.add_argument(
         "--exclude-rules", "-e",
@@ -56,6 +62,6 @@ def index():
     app.run(
         host=args.host,
         port=args.port,
-        debug=True,
+        debug=args.debug,
         use_reloader=(sys.platform != "win32"),
     )

tests/test_cli_args.py

@@ -221,6 +221,7 @@ def _build_parser(self) -> argparse.ArgumentParser:
         parser = argparse.ArgumentParser(description="Claude Code Chat Browser")
         parser.add_argument("--port", type=int, default=5000)
         parser.add_argument("--host", default="127.0.0.1")
+        parser.add_argument("--debug", action="store_true", default=False)
         parser.add_argument("--base-dir", default=None)
         parser.add_argument("--exclude-rules", "-e", default=None,
                             metavar="PATH", dest="exclude_rules")
@@ -237,6 +238,26 @@ def test_host_override(self):
         args = parser.parse_args(["--host", "127.0.0.1"])
         assert args.host == "127.0.0.1"
 
+    def test_debug_default_is_false(self):
+        parser = self._build_parser()
+        args = parser.parse_args([])
+        assert args.debug is False
+
+    def test_debug_explicit_true(self):
+        parser = self._build_parser()
+        args = parser.parse_args(["--debug"])
+        assert args.debug is True
+
+    def test_app_py_debug_not_hardcoded_true(self):
+        """app.run() must not pass debug=True unconditionally."""
+        app_path = os.path.join(REPO_ROOT, "app.py")
+        with open(app_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        run_block_start = src.find("app.run(")
+        assert run_block_start != -1
+        run_block = src[run_block_start : src.find(")", run_block_start) + 1]
+        assert "debug=True" not in run_block
+
     def test_port_default(self):
         parser = self._build_parser()
         args = parser.parse_args([])