Merge pull request #28 from HarnessLab/update_17_4

Update 17 4

Author: abdoelsayed2016

PARITY_CHECKLIST.md

@@ -822,6 +822,7 @@ Mirrored / scaffold areas needing real implementation:
 - [ ] Token budget calculations
 
 ### Tier 3 — Nice-to-Have Features
+- [x] Local web GUI (FastAPI + vanilla JS SPA) → `src/gui/__main__.py`, `src/gui/server.py`, `src/gui/static/*`; launch with `python -m src.gui` or `claw-code-gui`
 - [ ] TUI/Ink component library
 - [ ] Voice mode
 - [ ] VIM mode and keybinding system

README.md

@@ -56,6 +56,7 @@
 | 🆕 | **Tokenizer-Aware Context** | Cached tokenizer backends with heuristic fallback for `/context`, `/status`, and compaction |
 | 🆕 | **Prompt Budget Preflight** | Preflight prompt-length validation, token-budget reporting, and auto-compact/context collapse before backend failures |
 | 🆕 | **LSP Runtime** | Local LSP-style code intelligence for definitions, references, hover, symbols, call hierarchy, and diagnostics |
+| 🆕 | **Local Web GUI** | Browser-based chat UI via `python -m src.gui` — modern dark theme, slash command palette, session browser, settings panel |
 | 🆕 | **Daemon Commands** | Local `daemon start/ps/logs/attach/kill` wrapper over background agent sessions |
 | 🆕 | **Background Sessions** | Local `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, and `agent-kill` flows |
 | 🆕 | **Testing Guide** | Comprehensive [TESTING_GUIDE.md](TESTING_GUIDE.md) with commands for every feature |
@@ -85,6 +86,7 @@ Built on the public porting workspace from [instructkr/claw-code](https://github
 |---------|-------------|
 | 🤖 **Agent Loop** | Full agentic coding loop with tool calling and iterative reasoning |
 | 💬 **Interactive Chat** | Multi-turn REPL via `agent-chat` with session continuity |
+| 🖥️ **Local Web GUI** | Browser-based chat UI launched with `python -m src.gui` — sessions browser, slash command palette, live settings |
 | 🧰 **Core Tools** | File read / write / edit, glob search, grep search, shell execution |
 | 🔌 **Plugin Runtime** | Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking |
 | 🪆 **Nested Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
@@ -169,6 +171,7 @@ Built on the public porting workspace from [instructkr/claw-code](https://github
 - [x] Local workflow runtime with workflow list/get/run tools and CLI/slash flows
 - [x] Local remote trigger runtime with create/update/run flows and CLI/slash inspection
 - [x] Local managed git worktree runtime with live cwd switching and worktree CLI/slash flows
+- [x] Local web GUI (FastAPI + vanilla JS SPA) with chat, sessions browser, slash command palette, and live settings (`python -m src.gui`)
 - [x] Tokenizer-aware context accounting with cached tokenizer backends and heuristic fallback
 - [x] Plugin runtime: manifest discovery, hooks, aliases, virtual tools, tool blocking
 - [x] Plugin lifecycle hooks: resume, persist, delegate phases
@@ -245,7 +248,11 @@ claw-code/
 │   ├── commands.py               # Mirrored command inventory
 │   ├── tools.py                  # Mirrored tool inventory
 │   ├── runtime.py                # Mirrored runtime facade
-│   └── reference_data/           # Mirrored inventory snapshots
+│   ├── reference_data/           # Mirrored inventory snapshots
+│   └── gui/                      # Local web GUI (FastAPI + vanilla JS SPA)
+│       ├── __main__.py           # `python -m src.gui` entry point
+│       ├── server.py             # FastAPI app and JSON endpoints
+│       └── static/               # index.html, app.css, app.js
 └── tests/                        # Unit tests
     ├── test_agent_runtime.py
     ├── test_agent_context.py
@@ -712,6 +719,41 @@ Features:
 
 ---
 
+## 🖥️ Local Web GUI
+
+If the terminal isn't your thing, launch the bundled browser GUI:
+
+```bash
+python3 -m src.gui --cwd . --allow-write --allow-shell
+```
+
+Your default browser opens to `http://127.0.0.1:8765` with a modern dark-themed chat UI.
+
+| Flag | Description |
+|------|-------------|
+| `--host <addr>` | Bind address (default `127.0.0.1`) |
+| `--port <n>` | Port to listen on (default `8765`) |
+| `--cwd <path>` | Workspace directory the agent operates in |
+| `--model <name>` | Override the model name |
+| `--base-url <url>` | Override the OpenAI-compatible API base URL |
+| `--api-key <key>` | API key for the model server |
+| `--session-dir <path>` | Where saved sessions live |
+| `--allow-write` | Allow file write/edit tools |
+| `--allow-shell` | Allow shell execution |
+| `--no-browser` | Don't auto-open a browser tab |
+
+The GUI surfaces:
+
+- multi-turn chat with tool-call cards (collapsible JSON args + results)
+- saved sessions sidebar with one-click resume
+- slash command and skill pickers (`/` and `★` buttons, or `Cmd/Ctrl+K`)
+- live settings panel (model, base URL, working dir, permissions)
+- usage / cost meta in the composer footer
+
+> **Note:** The GUI uses [FastAPI](https://fastapi.tiangolo.com/) and [Uvicorn](https://www.uvicorn.org/) under the hood. These get installed automatically if you install the package via `pip install -e .`. The core Python agent runtime itself remains dependency-free.
+
+---
+
 ## 🔄 Session Persistence
 
 Each `agent` run automatically saves a resumable session:

pyproject.toml

@@ -32,14 +32,19 @@ classifiers = [
   "Topic :: Software Development",
   "Topic :: Software Development :: Build Tools",
 ]
-dependencies = []
+dependencies = [
+  "fastapi>=0.110",
+  "uvicorn>=0.27",
+  "pydantic>=2.5",
+]
 
 [project.urls]
 Homepage = "https://github.com/HarnessLab/claw-code-agent"
 Repository = "https://github.com/HarnessLab/claw-code-agent"
 
 [project.scripts]
 claw-code-agent = "src.main:main"
+claw-code-gui = "src.gui.__main__:main"
 
 [tool.setuptools]
 include-package-data = true
@@ -51,4 +56,5 @@ include = ["src*"]
 [tool.setuptools.package-data]
 src = [
   "reference_data/*.json",
+  "gui/static/*",
 ]

src/gui/__init__.py

@@ -0,0 +1,4 @@
+"""Local web GUI for the claw-code agent.
+
+Run with: ``python -m src.gui`` or ``python -m src.gui --port 8765``.
+"""

src/gui/__main__.py

@@ -0,0 +1,85 @@
+"""GUI entry point: ``python -m src.gui [--port N] [--cwd PATH] ...``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import webbrowser
+from pathlib import Path
+
+import uvicorn
+
+from ..session_store import DEFAULT_AGENT_SESSION_DIR
+from .server import AgentState, create_app
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog='claw-code-gui',
+        description='Launch the local web GUI for the claw-code agent.',
+    )
+    parser.add_argument('--host', default='127.0.0.1')
+    parser.add_argument('--port', type=int, default=8765)
+    parser.add_argument(
+        '--cwd',
+        default='.',
+        help='Working directory that the agent operates in (default: current dir).',
+    )
+    parser.add_argument(
+        '--model',
+        default=os.environ.get('OPENAI_MODEL', 'Qwen/Qwen3-Coder-30B-A3B-Instruct'),
+    )
+    parser.add_argument(
+        '--base-url',
+        default=os.environ.get('OPENAI_BASE_URL', 'http://127.0.0.1:8000/v1'),
+    )
+    parser.add_argument(
+        '--api-key',
+        default=os.environ.get('OPENAI_API_KEY', 'local-token'),
+    )
+    parser.add_argument(
+        '--session-dir',
+        default=str(DEFAULT_AGENT_SESSION_DIR),
+        help='Directory where agent sessions are saved (default: .port_sessions/agent).',
+    )
+    parser.add_argument('--allow-shell', action='store_true')
+    parser.add_argument('--allow-write', action='store_true')
+    parser.add_argument(
+        '--no-browser',
+        action='store_true',
+        help='Do not auto-open a browser tab on launch.',
+    )
+
+    args = parser.parse_args()
+
+    state = AgentState(
+        cwd=Path(args.cwd),
+        model=args.model,
+        base_url=args.base_url,
+        api_key=args.api_key,
+        allow_shell=args.allow_shell,
+        allow_write=args.allow_write,
+        session_directory=Path(args.session_dir),
+    )
+    app = create_app(state)
+
+    url = f'http://{args.host}:{args.port}'
+    print(f'Claw Code GUI listening on {url}')
+    print(f'  cwd       : {state.cwd}')
+    print(f'  model     : {state.model}')
+    print(f'  base-url  : {state.base_url}')
+    print(f'  sessions  : {state.session_directory}')
+    print(f'  shell     : {"on" if state.allow_shell else "off"}')
+    print(f'  write     : {"on" if state.allow_write else "off"}')
+
+    if not args.no_browser:
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+
+    uvicorn.run(app, host=args.host, port=args.port, log_level='info')
+
+
+if __name__ == '__main__':
+    main()