agnview 0.1.0__tar.gz

agnview-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taher Laskar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agnview-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: agnview
+Version: 0.1.0
+Summary: One screen for the coding agents already running on your machine.
+Author: tlaskar-git
+License: MIT
+Project-URL: Homepage, https://github.com/tlaskar-git/AgnView
+Project-URL: Repository, https://github.com/tlaskar-git/AgnView
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi==0.141.1
+Requires-Dist: uvicorn[standard]==0.52.4
+Requires-Dist: pydantic==2.13.5
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: httpx==0.28.1
+Requires-Dist: rich==15.0.0
+Requires-Dist: sse-starlette==3.4.11
+Requires-Dist: qrcode==8.2
+Requires-Dist: iroh==1.1.0
+Provides-Extra: dev
+Requires-Dist: pytest==9.1.1; extra == "dev"
+Requires-Dist: ruff==0.15.4; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+  <img src="docs/agnview_logo.png" alt="AgnView" width="140" />
+  <h1>AgnView</h1>
+  <p><strong>One screen for the coding agents already running on your machine.</strong></p>
+</div>
+
+---
+
+## What AgnView is
+
+AgnView is a local dashboard and coordination hub for the agent CLIs you have
+installed: Claude Code, Codex, AntiGravity, DeepSeek, and any local model you
+run yourself. There are five known agent roles a task can be assigned to:
+`claude_code`, `codex`, `antigravity`, `deepseek` and `custom`. It does three
+things.
+
+**Watch.** Every agent's output streams into one console, colour-coded by
+agent, instead of being scattered across terminal tabs.
+
+**Coordinate.** Describe a job as a set of tasks with dependencies. A task
+stays blocked until the tasks it depends on complete, and when it starts, the
+agent picks it up with the upstream summaries and artefacts attached. If one
+agent finds a defect in another's work, it can send the task back for revision,
+or mark it failed, which blocks everything downstream.
+
+**Keep an eye on quotas.** Session and weekly limits for your Claude, ChatGPT
+and Gemini subscriptions, in one place.
+
+AgnView runs entirely on your own machine. It is free, and there is nothing to
+sign up for.
+
+## Screenshots
+
+| | Light | Dark |
+|---|---|---|
+| **Console** | ![Console, light](docs/screenshots/console-light.png) | ![Console, dark](docs/screenshots/console-dark.png) |
+| **Pipelines** | ![Pipelines, light](docs/screenshots/pipelines-light.png) | ![Pipelines, dark](docs/screenshots/pipelines-dark.png) |
+| **Usage** | ![Usage, light](docs/screenshots/usage-light.png) | ![Usage, dark](docs/screenshots/usage-dark.png) |
+
+## Supported platforms
+
+| | |
+|---|---|
+| Windows | 10 and 11 |
+| macOS | 12 Monterey and later, Intel and Apple silicon |
+| Linux | any distribution with Python 3.10 or newer |
+| Python | 3.10 or newer |
+| Browser | any current Chrome, Edge, Firefox or Safari |
+
+The companion mobile client is iOS and iPadOS.
+
+## Clients
+
+The AgnView hub in this repo covers Windows, macOS and Linux.
+
+- **iOS and iPadOS**: [github.com/tlaskar-git/AgnView-iOS](https://github.com/tlaskar-git/AgnView-iOS)
+  holds the design prototype and mobile spec for the iOS and iPadOS client.
+- **Android**: an Android client will live at
+  [github.com/tlaskar-git/AgnView-Android](https://github.com/tlaskar-git/AgnView-Android)
+  (reference only, not yet created).
+
+AgnView does not install any coding agent for you. It watches and dispatches to
+the CLIs already on your machine: Claude Code, Codex, AntiGravity or any other
+tool you add as an adapter. Install the CLIs you want to use yourself, before
+or after installing AgnView.
+
+## Install
+
+The quickest way is not to install at all. [uv](https://docs.astral.sh/uv/)
+fetches and runs AgnView in one command, with no clone and no virtualenv:
+
+```bash
+uvx agnview serve
+```
+
+To keep it around permanently:
+
+```bash
+uv tool install agnview      # or: pipx install agnview / pip install agnview
+```
+
+Working on AgnView itself? Install from source:
+
+```bash
+git clone https://github.com/tlaskar-git/AgnView.git
+cd AgnView
+pip install -e .
+```
+
+`agent-relay` is supported as an alias for the `agnview` command.
+
+## Start
+
+```bash
+agnview serve
+```
+
+The dashboard is then at <http://127.0.0.1:8765>.
+
+By default AgnView binds `127.0.0.1`, so only your own machine can reach it. To
+let your phone or another computer on the same network connect, opt in
+explicitly:
+
+```bash
+agnview serve --listen-lan
+```
+
+Choose a different port with `--port`, and require a token from connecting
+clients with `--token`.
+
+## Pair a phone
+
+1. Start the hub with `agnview serve --listen-lan`.
+2. Open the dashboard and choose the mobile option in the header to show the
+   pairing QR code.
+3. Scan it with the AgnView app on a device on the same network.
+
+The QR code carries the hub's LAN address, its certificate fingerprint, and a
+pairing key. Regenerating the code invalidates every device already paired.
+`docs/PAIRING.md` is the full contract.
+
+**Treat the pairing QR code like a password.** Anyone who can read it can reach
+the hub, and the hub can run commands on this machine. See `SECURITY.md`.
+
+## LAN pairing, plus a remote path if you want it
+
+On your own local network, your machine and your phone talk to each other
+directly. Nothing goes through anybody else's infrastructure, and no account
+or setup is needed.
+
+If your phone is off your home or office Wi-Fi, LAN pairing alone cannot reach
+it. AgnView also accepts connections over iroh, which can carry the pairing QR
+code and the console beyond the LAN without a VPN. See "Remote access" below
+for what that depends on and how to opt out of it.
+
+## Remote access
+
+`docs/REMOTE-ACCESS.md` covers every path in order: LAN, bundled iroh, what
+iroh depends on, running your own relay, and the overlay alternatives
+(Tailscale, NetBird, an SSH local port forward, or an existing WireGuard
+tunnel) via `--listen-overlay`.
+
+Remote access uses iroh's free public relays. Most connections are direct and never touch a relay. Relayed connections are rate limited and carry no uptime guarantee. You can point AgnView at your own relay in Settings.
+
+## Docker, and what a container cannot do
+
+```bash
+docker compose up -d
+```
+
+The hub is then at <http://localhost:8765>. The image runs as an unprivileged
+`agnview` user and carries a `HEALTHCHECK` against the dashboard root, and the
+compose file keeps `~/.agnview` (pairing token, adapters, notification config)
+in a named volume so it survives rebuilds and restarts.
+
+**A containerised hub cannot dispatch to CLI agents.** AgnView dispatches work
+by executing the agent binaries on the host: `claude`, `codex`, `antigravity`
+and the rest, with their own credentials, config and your working tree. A
+container sees none of that.
+
+- Docker suits watching and managing a pipeline: the dashboard, the REST and
+  SSE API, job and dependency state, web-LLM prompt generation, quota
+  monitoring, and mobile pairing, with remote worker daemons doing the actual
+  execution.
+- A native install suits dispatch. If you want AgnView to run Claude Code,
+  Codex or AntiGravity for you, install it on the machine where those CLIs
+  live.
+
+## Command line
+
+`agnview serve` runs the hub. The rest of the commands drive it, so an agent
+can take part in a pipeline from a script:
+
+| Command | Purpose |
+|---|---|
+| `create-job` | Create a job from a YAML or JSON pipeline file |
+| `status` | Show job and task status |
+| `wait` | Block until a task's dependencies are satisfied |
+| `claim` | Claim a task and begin work |
+| `complete` | Mark a task complete with a summary |
+| `reject` | Send a task back to its agent for revision |
+| `my-tasks` | List tasks assigned to an agent |
+| `nodes` | List connected agent instances |
+| `worker` | Poll for assigned tasks as a daemon |
+| `export-prompt` | Build a context prompt for a web LLM |
+| `usage` | Show live subscription quotas |
+
+Run any of them with `--help` for the full set of options.
+
+## How a pipeline runs
+
+1. Create a job whose tasks name their dependencies. Tasks with no unmet
+   dependencies start ready; the rest start pending.
+2. An agent claims a ready task, which moves it to in progress.
+3. Completing a task records its summary and artefacts, and unlocks every task
+   whose dependencies are now met.
+4. An agent that finds a defect upstream requests a revision. The upstream task
+   reopens and its dependents go back to pending until it is fixed.
+5. A task that cannot be finished is marked failed, which blocks everything
+   downstream of it and fails the job.
+
+Every one of these changes is pushed to open dashboards over Server-Sent
+Events, so a second tab or a paired phone follows along without a reload.
+
+## Licence
+
+MIT, as declared in `pyproject.toml`. The repository does not yet carry a
+`LICENSE` file; one should be added before public release.

agnview-0.1.0/README.md

@@ -0,0 +1,208 @@
+<div align="center">
+  <img src="docs/agnview_logo.png" alt="AgnView" width="140" />
+  <h1>AgnView</h1>
+  <p><strong>One screen for the coding agents already running on your machine.</strong></p>
+</div>
+
+---
+
+## What AgnView is
+
+AgnView is a local dashboard and coordination hub for the agent CLIs you have
+installed: Claude Code, Codex, AntiGravity, DeepSeek, and any local model you
+run yourself. There are five known agent roles a task can be assigned to:
+`claude_code`, `codex`, `antigravity`, `deepseek` and `custom`. It does three
+things.
+
+**Watch.** Every agent's output streams into one console, colour-coded by
+agent, instead of being scattered across terminal tabs.
+
+**Coordinate.** Describe a job as a set of tasks with dependencies. A task
+stays blocked until the tasks it depends on complete, and when it starts, the
+agent picks it up with the upstream summaries and artefacts attached. If one
+agent finds a defect in another's work, it can send the task back for revision,
+or mark it failed, which blocks everything downstream.
+
+**Keep an eye on quotas.** Session and weekly limits for your Claude, ChatGPT
+and Gemini subscriptions, in one place.
+
+AgnView runs entirely on your own machine. It is free, and there is nothing to
+sign up for.
+
+## Screenshots
+
+| | Light | Dark |
+|---|---|---|
+| **Console** | ![Console, light](docs/screenshots/console-light.png) | ![Console, dark](docs/screenshots/console-dark.png) |
+| **Pipelines** | ![Pipelines, light](docs/screenshots/pipelines-light.png) | ![Pipelines, dark](docs/screenshots/pipelines-dark.png) |
+| **Usage** | ![Usage, light](docs/screenshots/usage-light.png) | ![Usage, dark](docs/screenshots/usage-dark.png) |
+
+## Supported platforms
+
+| | |
+|---|---|
+| Windows | 10 and 11 |
+| macOS | 12 Monterey and later, Intel and Apple silicon |
+| Linux | any distribution with Python 3.10 or newer |
+| Python | 3.10 or newer |
+| Browser | any current Chrome, Edge, Firefox or Safari |
+
+The companion mobile client is iOS and iPadOS.
+
+## Clients
+
+The AgnView hub in this repo covers Windows, macOS and Linux.
+
+- **iOS and iPadOS**: [github.com/tlaskar-git/AgnView-iOS](https://github.com/tlaskar-git/AgnView-iOS)
+  holds the design prototype and mobile spec for the iOS and iPadOS client.
+- **Android**: an Android client will live at
+  [github.com/tlaskar-git/AgnView-Android](https://github.com/tlaskar-git/AgnView-Android)
+  (reference only, not yet created).
+
+AgnView does not install any coding agent for you. It watches and dispatches to
+the CLIs already on your machine: Claude Code, Codex, AntiGravity or any other
+tool you add as an adapter. Install the CLIs you want to use yourself, before
+or after installing AgnView.
+
+## Install
+
+The quickest way is not to install at all. [uv](https://docs.astral.sh/uv/)
+fetches and runs AgnView in one command, with no clone and no virtualenv:
+
+```bash
+uvx agnview serve
+```
+
+To keep it around permanently:
+
+```bash
+uv tool install agnview      # or: pipx install agnview / pip install agnview
+```
+
+Working on AgnView itself? Install from source:
+
+```bash
+git clone https://github.com/tlaskar-git/AgnView.git
+cd AgnView
+pip install -e .
+```
+
+`agent-relay` is supported as an alias for the `agnview` command.
+
+## Start
+
+```bash
+agnview serve
+```
+
+The dashboard is then at <http://127.0.0.1:8765>.
+
+By default AgnView binds `127.0.0.1`, so only your own machine can reach it. To
+let your phone or another computer on the same network connect, opt in
+explicitly:
+
+```bash
+agnview serve --listen-lan
+```
+
+Choose a different port with `--port`, and require a token from connecting
+clients with `--token`.
+
+## Pair a phone
+
+1. Start the hub with `agnview serve --listen-lan`.
+2. Open the dashboard and choose the mobile option in the header to show the
+   pairing QR code.
+3. Scan it with the AgnView app on a device on the same network.
+
+The QR code carries the hub's LAN address, its certificate fingerprint, and a
+pairing key. Regenerating the code invalidates every device already paired.
+`docs/PAIRING.md` is the full contract.
+
+**Treat the pairing QR code like a password.** Anyone who can read it can reach
+the hub, and the hub can run commands on this machine. See `SECURITY.md`.
+
+## LAN pairing, plus a remote path if you want it
+
+On your own local network, your machine and your phone talk to each other
+directly. Nothing goes through anybody else's infrastructure, and no account
+or setup is needed.
+
+If your phone is off your home or office Wi-Fi, LAN pairing alone cannot reach
+it. AgnView also accepts connections over iroh, which can carry the pairing QR
+code and the console beyond the LAN without a VPN. See "Remote access" below
+for what that depends on and how to opt out of it.
+
+## Remote access
+
+`docs/REMOTE-ACCESS.md` covers every path in order: LAN, bundled iroh, what
+iroh depends on, running your own relay, and the overlay alternatives
+(Tailscale, NetBird, an SSH local port forward, or an existing WireGuard
+tunnel) via `--listen-overlay`.
+
+Remote access uses iroh's free public relays. Most connections are direct and never touch a relay. Relayed connections are rate limited and carry no uptime guarantee. You can point AgnView at your own relay in Settings.
+
+## Docker, and what a container cannot do
+
+```bash
+docker compose up -d
+```
+
+The hub is then at <http://localhost:8765>. The image runs as an unprivileged
+`agnview` user and carries a `HEALTHCHECK` against the dashboard root, and the
+compose file keeps `~/.agnview` (pairing token, adapters, notification config)
+in a named volume so it survives rebuilds and restarts.
+
+**A containerised hub cannot dispatch to CLI agents.** AgnView dispatches work
+by executing the agent binaries on the host: `claude`, `codex`, `antigravity`
+and the rest, with their own credentials, config and your working tree. A
+container sees none of that.
+
+- Docker suits watching and managing a pipeline: the dashboard, the REST and
+  SSE API, job and dependency state, web-LLM prompt generation, quota
+  monitoring, and mobile pairing, with remote worker daemons doing the actual
+  execution.
+- A native install suits dispatch. If you want AgnView to run Claude Code,
+  Codex or AntiGravity for you, install it on the machine where those CLIs
+  live.
+
+## Command line
+
+`agnview serve` runs the hub. The rest of the commands drive it, so an agent
+can take part in a pipeline from a script:
+
+| Command | Purpose |
+|---|---|
+| `create-job` | Create a job from a YAML or JSON pipeline file |
+| `status` | Show job and task status |
+| `wait` | Block until a task's dependencies are satisfied |
+| `claim` | Claim a task and begin work |
+| `complete` | Mark a task complete with a summary |
+| `reject` | Send a task back to its agent for revision |
+| `my-tasks` | List tasks assigned to an agent |
+| `nodes` | List connected agent instances |
+| `worker` | Poll for assigned tasks as a daemon |
+| `export-prompt` | Build a context prompt for a web LLM |
+| `usage` | Show live subscription quotas |
+
+Run any of them with `--help` for the full set of options.
+
+## How a pipeline runs
+
+1. Create a job whose tasks name their dependencies. Tasks with no unmet
+   dependencies start ready; the rest start pending.
+2. An agent claims a ready task, which moves it to in progress.
+3. Completing a task records its summary and artefacts, and unlocks every task
+   whose dependencies are now met.
+4. An agent that finds a defect upstream requests a revision. The upstream task
+   reopens and its dependents go back to pending until it is fixed.
+5. A task that cannot be finished is marked failed, which blocks everything
+   downstream of it and fails the job.
+
+Every one of these changes is pushed to open dashboards over Server-Sent
+Events, so a second tab or a paired phone follows along without a reload.
+
+## Licence
+
+MIT, as declared in `pyproject.toml`. The repository does not yet carry a
+`LICENSE` file; one should be added before public release.

agnview-0.1.0/agent_relay/__init__.py

@@ -0,0 +1,3 @@
+"""AgentRelay: Cross-Agent Orchestration & Status Synchronization Hub."""
+
+__version__ = "0.1.0"

agnview-0.1.0/agent_relay/api/app.py

@@ -0,0 +1,161 @@
+import asyncio
+import os
+from pathlib import Path
+from typing import Optional
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse, JSONResponse
+
+from .routes import router as api_router
+from ..core.engine import RelayEngine
+from ..core.db import Database
+from ..core.config import load_config
+from ..core.iroh_transport import IrohTransport
+
+
+# Set AGNVIEW_IROH=0 to keep the hub LAN only. The default is on, because the
+# whole point of the iroh transport is that the user never sets anything up.
+IROH_ENV = "AGNVIEW_IROH"
+
+
+def _iroh_enabled_from_env() -> bool:
+    value = os.environ.get(IROH_ENV)
+    if value is None:
+        return True
+    return value.strip().lower() not in ("0", "false", "no", "off")
+
+
+def create_app(db_path: Optional[str] = None, auth_token: Optional[str] = None, port: int = 8765) -> FastAPI:
+    token = auth_token or os.environ.get("AGENT_RELAY_TOKEN")
+
+    app = FastAPI(
+        title="AgnView API",
+        description="Cross-Agent Coordination Hub & Live Console for Claude Code, Codex, AntiGravity, and Web LLMs",
+        version="0.1.0"
+    )
+
+    # Enable CORS for external tools, mobile apps, and browser extensions
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Token Authentication Middleware for distributed multi-computer and mobile setups
+    if token:
+        @app.middleware("http")
+        async def verify_token_middleware(request: Request, call_next):
+            # Only authenticate API endpoints; allow static dashboard index and docs
+            path = request.url.path
+            if path.startswith("/api") and not path.startswith("/api/mobile/pairing"):
+                client_ip = request.client.host if request.client else "127.0.0.1"
+                # Allow unauthenticated access only for local browser same-origin sessions (not programmatic API clients/tests)
+                is_local_browser = (
+                    client_ip in ("127.0.0.1", "::1", "localhost")
+                    and (
+                        request.headers.get("Sec-Fetch-Site") == "same-origin"
+                        or request.headers.get("Referer", "").startswith(("http://localhost:", "http://127.0.0.1:", "http://[::1]:"))
+                    )
+                )
+                if not is_local_browser:
+                    from ..core.pairing import check_auth_rate_limit, record_failed_auth, reset_auth_rate_limit
+
+                    # Check rate limiting for failed auth attempts
+                    if not check_auth_rate_limit(client_ip):
+                        return JSONResponse(
+                            status_code=429,
+                            content={"detail": "Too many failed authentication attempts. Please try again later."}
+                        )
+
+                    auth_header = (
+                        request.headers.get("X-AgnView-Token") or
+                        request.headers.get("X-Agent-Relay-Token") or
+                        request.headers.get("Authorization")
+                    )
+                    token_param = request.query_params.get("token")
+
+                    provided = None
+                    if auth_header:
+                        if auth_header.startswith("Bearer "):
+                            provided = auth_header[7:].strip()
+                        else:
+                            provided = auth_header.strip()
+                    elif token_param:
+                        provided = token_param.strip()
+
+                    expected = request.app.state.auth_token or token
+                    if not provided or provided != expected:
+                        record_failed_auth(client_ip)
+                        return JSONResponse(
+                            status_code=401,
+                            content={"detail": "Unauthorized: Invalid or missing AgnView authentication token."}
+                        )
+
+                    reset_auth_rate_limit(client_ip)
+
+            return await call_next(request)
+
+    db = Database(db_path)
+    engine = RelayEngine(db, port=port)
+    app.state.db = db
+    app.state.engine = engine
+    app.state.auth_token = token
+
+    config = load_config()
+    app.state.config = config
+
+    # A configuration the hub cannot act on stops iroh and nothing else. The
+    # reason is already in the log and travels to the API in the status.
+    if not _iroh_enabled_from_env():
+        iroh_enabled, disabled_reason = False, f"{IROH_ENV} is set to off"
+    elif not config.iroh_enabled:
+        iroh_enabled, disabled_reason = False, f"iroh_enabled is false in {config.path}"
+    elif not config.is_valid:
+        iroh_enabled, disabled_reason = False, "; ".join(config.errors)
+    else:
+        iroh_enabled, disabled_reason = True, ""
+
+    iroh_transport = IrohTransport(
+        db=db,
+        token_provider=lambda: app.state.auth_token,
+        relay_url=config.relay_url,
+        enabled=iroh_enabled,
+        disabled_reason=disabled_reason,
+    )
+    app.state.iroh = iroh_transport
+
+    @app.on_event("startup")
+    async def _bind_event_loop():
+        # Job and task routes are sync, so they execute on worker threads.
+        # Remember the serving loop so their broadcasts still reach SSE clients.
+        engine.bind_loop(asyncio.get_running_loop())
+
+    @app.on_event("startup")
+    async def _start_iroh_transport():
+        # start() schedules the bind and returns. Startup never waits on the
+        # network, so a hub with no route out still comes up and serves the
+        # dashboard.
+        iroh_transport.start()
+
+    @app.on_event("shutdown")
+    async def _stop_iroh_transport():
+        await iroh_transport.stop()
+
+    app.include_router(api_router)
+
+    # Web Dashboard Static UI & Assets
+    web_dir = Path(__file__).parent.parent / "web"
+    static_dir = web_dir / "static"
+    if static_dir.exists():
+        app.mount("/static", StaticFiles(directory=str(static_dir)), name="static")
+
+    index_file = web_dir / "templates" / "index.html"
+    if index_file.exists():
+        @app.get("/", include_in_schema=False)
+        async def serve_index():
+            return FileResponse(str(index_file))
+
+    return app