aaw-core 0.1.0__tar.gz

aaw_core-0.1.0/.dockerignore

@@ -0,0 +1,10 @@
+.git
+.venv
+.github
+.pytest_cache
+.ruff_cache
+**/__pycache__
+tests
+docs
+docker
+*.sqlite

aaw_core-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## What this changes
+
+<!-- One or two sentences. Link the issue or discussion if there is one. -->
+
+## Checklist
+
+- [ ] Every commit is signed off (`git commit -s`), per the DCO in CONTRIBUTING.md.
+- [ ] No secrets, tokens, or hosted-project defaults were added; config comes from env or `~/.aaw/config.json`.
+- [ ] Tests pass locally (`pytest`) and lint is clean (`ruff check .`).
+- [ ] If this touches encryption, pairing, `aaw_core/transport/`, or `relay/`: the event/command shapes and the encryption envelope stay compatible with the phone apps (see `docs/protocol.contract.md`).

aaw_core-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+# Build, lint, test, and scan for secrets. Never deploys anything.
+# Fork pull requests get no repository secrets.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: tmux (the end-to-end host test needs it)
+        run: |
+          if [ "$RUNNER_OS" = "Linux" ]; then sudo apt-get update -q && sudo apt-get install -y -q tmux; fi
+          if [ "$RUNNER_OS" = "macOS" ]; then brew list tmux >/dev/null 2>&1 || brew install -q tmux; fi
+          tmux -V
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev,relay]"
+      - run: ruff check .
+      - run: pytest -q
+      - run: aaw --version
+
+  secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

aaw_core-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Local config, state, logs
+.env
+.env.*
+*.log
+*.jsonl
+.aaw/
+locks/
+*.pid
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+
+# Belt and braces: secrets never belong here
+*.p8
+*.p12
+*.cer
+*.provisionprofile
+*service-account*.json
+*secrets*.env

aaw_core-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful and constructive, assume good faith, and keep discussions about the work. Harassment, personal attacks, and discriminatory language are not tolerated anywhere this project happens: issues, pull requests, discussions, and any linked channels.
+
+## Enforcement
+
+Report unacceptable behavior to **hello@agentsatwork.app**. Reports are handled privately and confidentially. Maintainers may edit, remove, or reject contributions and comments that violate this code, and may temporarily or permanently ban contributors for repeated or severe violations.

aaw_core-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to Agents At Work Core
+
+Thanks for helping. This is the open-source engine behind Agents At Work; the apps are closed, but everything that runs on your computer lives here.
+
+## Developer Certificate of Origin (DCO)
+
+Every commit must be signed off:
+
+```bash
+git commit -s -m "your message"
+```
+
+That adds a `Signed-off-by: Your Name <you@example.com>` trailer, certifying you have the right to contribute the change under the MIT license (the [DCO 1.1](https://developercertificate.org/)). A DCO check runs on every pull request; unsigned commits fail it. There is no CLA.
+
+## Development setup
+
+```bash
+git clone https://github.com/sergenes/aaw-core
+cd aaw-core
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,relay]"
+pytest
+ruff check .
+```
+
+Python 3.11+. The host runs on Linux and macOS; the relay runs anywhere Python does.
+
+## What gets extra scrutiny
+
+Changes to these paths are reviewed more slowly and carefully, because they affect security or compatibility with the closed phone apps:
+
+- `aaw_core/encryption.py`: the AES-256-GCM envelope must stay byte-compatible with the apps.
+- Pairing and the QR payload.
+- `aaw_core/transport/` and `relay/`: event and command shapes are a contract with the apps (see `docs/protocol.contract.md`).
+
+## Before opening a pull request
+
+- For anything non-trivial, open an issue or discussion first so you do not spend a weekend on something that conflicts with the roadmap.
+- CI must be green: build, tests, lint, and the secret scanner.
+- Never commit secrets, keys, tokens, or anything pointing at a specific hosted project. Configuration comes from environment variables and `~/.aaw/config.json`; the code has no hosted defaults.
+
+## How this project is developed
+
+The engine is developed here, in the open. It was assembled by porting the host from the maintainer's product, Agents At Work, and it is now the engine that product runs: the Mac app bundles it, and the hosted relay is this relay. Good contributions here reach both.

aaw_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergey Nes
+
+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.

aaw_core-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: aaw-core
+Version: 0.1.0
+Summary: Agents At Work Core: the open-source engine behind Agents At Work. Run Claude Code, Codex, Gemini CLI, Grok, Cursor, and Scoot on your own Mac or Linux box and control them from your phone.
+Project-URL: Homepage, https://agentsatwork.app
+Project-URL: Repository, https://github.com/sergenes/aaw-core
+Project-URL: Issues, https://github.com/sergenes/aaw-core/issues
+Project-URL: Changelog, https://github.com/sergenes/aaw-core/releases
+Author: Sergey Nes
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,codex,gemini-cli,remote-control,tmux
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42
+Requires-Dist: qrcode>=7
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: httpx2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: relay
+Requires-Dist: aiosqlite>=0.20; extra == 'relay'
+Requires-Dist: starlette>=0.37; extra == 'relay'
+Requires-Dist: uvicorn>=0.29; extra == 'relay'
+Description-Content-Type: text/markdown
+
+# Agents At Work Core
+
+[![PyPI](https://img.shields.io/pypi/v/aaw-core.svg?label=PyPI)](https://pypi.org/project/aaw-core/)
+[![tests](https://github.com/sergenes/aaw-core/actions/workflows/ci.yml/badge.svg)](https://github.com/sergenes/aaw-core/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)](#install)
+[![Agents](https://img.shields.io/badge/agents-Claude%20Code%20%7C%20Codex%20%7C%20Gemini%20%7C%20Grok%20%7C%20Cursor%20%7C%20scoot-orange.svg)](#supported-agents)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+**The open-source engine behind [Agents At Work](https://agentsatwork.app).**
+Run Claude Code, Codex, Gemini CLI, Grok, Cursor, and scoot on your own Mac or Linux box, and follow them from your phone: approve tool calls, answer questions, send prompts, and schedule prompts for later, end-to-end encrypted.
+
+> **Status: alpha.**
+> This is the engine the Agents At Work Mac app bundles and the hosted relay runs, so it is in daily use, but the command line and the config keys can still change between 0.x releases.
+
+## What is open and what is not
+
+`aaw-core` is everything that runs on *your* computer: the daemon that watches your agents in `tmux`, the hooks that report what they do, and the `aaw` command line.
+It also contains the relay server that connects your computer to your phone.
+All of it is MIT licensed.
+
+The phone apps (iPhone, iPad, Android) and the Mac menu-bar app are not in this repository.
+The Mac app is a free download that runs this same engine.
+The phone apps are free for one computer on our hosted relay; the Personal and Pro plans raise that to 3 and 15 computers.
+Computers on a relay you host yourself never count toward a plan.
+
+## How it works
+
+```
+your computer                                          your phone
+  agent in tmux  <->  aaw daemon  <->  local store        store app
+                          |                                  ^
+                          | one outbound WebSocket           |
+                          v                                  |
+                     the relay (tiny; ciphertext + routing only) -> push (FCM/APNs)
+```
+
+- Your **local store** on the computer is the source of truth for the conversation history.
+- The daemon keeps **one outbound WebSocket** to a relay, so it works behind any home router or cellular NAT with **no ports, no tunnel, no VPN, no Firebase project**.
+- The relay buffers what is in flight while the phone is asleep and triggers a wake-up push. It only ever sees **ciphertext and routing metadata**: prompts, answers, and content are AES-256-GCM encrypted with a key that only your computer and your phone hold, exchanged once by QR.
+- We host a relay for free users; self-hosters run the same server with `docker compose`.
+
+## Install
+
+On Linux, one command installs or updates everything: its own virtualenv, the `aaw` command, the shell integration, the link with your phone (a QR code), and the always-on service.
+It also removes the earlier Agents At Work Linux host if it finds one.
+
+```bash
+curl -fsSL https://agentsatwork.app/install-linux.sh | bash    # the same script as scripts/install.sh
+```
+
+Or by hand, on Linux or macOS (on a Mac, the free Agents At Work app does all of this for you):
+
+```bash
+pipx install aaw-core                      # Python 3.11+, and tmux
+aaw link                                   # asks which relay (ours, or your own), prints a QR code to scan
+aaw service install                        # the always-on part: runs in the background and starts at every login
+aaw shell-integration on                   # typing claude, codex, ... in a folder starts a bridged session
+```
+
+Then start an agent the way you always do (`cd ~/my-project && claude`), or start one from the phone.
+
+## Everyday commands
+
+```bash
+aaw status                          # the computer, the relay, and every session
+aaw start ~/my-project              # start a session (--agent codex, gemini, grok, cursor, scoot)
+aaw stop my-project                 # stop one session
+aaw feed my-project                 # the conversation, paged; -f follows it live
+aaw send my-project "run the tests" # send a prompt
+aaw schedule my-project --at 2am "continue with the refactor"   # a prompt for later
+aaw mobile-mode on                  # permission prompts go to the phone
+aaw quit                            # stop everything; the next login (or aaw service start) brings it back
+aaw uninstall                       # remove the service, the hooks, the shell line, and ~/.aaw
+```
+
+`aaw --help` lists every command, and `aaw <command> --help` its options.
+
+## Hosting the relay yourself
+
+The relay is a small server in this repository (`aaw_core/relay/`): run it with `docker compose` from `relay/`, or with `pip install "aaw-core[relay]"` and `python -m aaw_core.relay`, behind a TLS proxy.
+Point your computer at it with `aaw link --relay wss://your.host/v1/ws`.
+It sees only ciphertext and routing metadata, the same as ours.
+One difference: waking the phone with a push notification needs the app's own push credentials, so on your own relay the phone gets updates while the app is open, not in the background.
+`relay/README.md` has the details.
+
+## Desktop notifications
+
+The phone is the primary channel, and the computer itself also gets a banner when a turn finishes, an error happens, or the agent waits for input: `osascript` on macOS, `notify-send` on a Linux desktop (GNOME, KDE, and the rest). A server or a box without a desktop simply has no `notify-send` and shows nothing. On macOS, while any Focus is on (Do Not Disturb included), banners from scripts go to Notification Center silently unless Agents At Work is allowed under System Settings > Focus > Allowed Apps; `aaw status` reminds you. Two keys in `~/.aaw/config.json`: `local_notifications` (default `true`; a GUI that shows its own banners turns it off) and `waiting_alert_seconds` (default `0`, off; the seconds a question may sit unanswered before a "waiting for your answer" banner, for when the push is muted while you are at the desk).
+
+## Supported agents
+
+Claude Code, Codex CLI, Gemini CLI, Grok CLI, Cursor, and [Scoot](https://github.com/sergenes/scootcli) (local models with Ollama, plus cloud models). Not affiliated with Anthropic, OpenAI, Google, xAI, Anysphere, or Ollama.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions use the DCO (`git commit -s`). Security reports: see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

aaw_core-0.1.0/README.md

@@ -0,0 +1,101 @@
+# Agents At Work Core
+
+[![PyPI](https://img.shields.io/pypi/v/aaw-core.svg?label=PyPI)](https://pypi.org/project/aaw-core/)
+[![tests](https://github.com/sergenes/aaw-core/actions/workflows/ci.yml/badge.svg)](https://github.com/sergenes/aaw-core/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey.svg)](#install)
+[![Agents](https://img.shields.io/badge/agents-Claude%20Code%20%7C%20Codex%20%7C%20Gemini%20%7C%20Grok%20%7C%20Cursor%20%7C%20scoot-orange.svg)](#supported-agents)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+**The open-source engine behind [Agents At Work](https://agentsatwork.app).**
+Run Claude Code, Codex, Gemini CLI, Grok, Cursor, and scoot on your own Mac or Linux box, and follow them from your phone: approve tool calls, answer questions, send prompts, and schedule prompts for later, end-to-end encrypted.
+
+> **Status: alpha.**
+> This is the engine the Agents At Work Mac app bundles and the hosted relay runs, so it is in daily use, but the command line and the config keys can still change between 0.x releases.
+
+## What is open and what is not
+
+`aaw-core` is everything that runs on *your* computer: the daemon that watches your agents in `tmux`, the hooks that report what they do, and the `aaw` command line.
+It also contains the relay server that connects your computer to your phone.
+All of it is MIT licensed.
+
+The phone apps (iPhone, iPad, Android) and the Mac menu-bar app are not in this repository.
+The Mac app is a free download that runs this same engine.
+The phone apps are free for one computer on our hosted relay; the Personal and Pro plans raise that to 3 and 15 computers.
+Computers on a relay you host yourself never count toward a plan.
+
+## How it works
+
+```
+your computer                                          your phone
+  agent in tmux  <->  aaw daemon  <->  local store        store app
+                          |                                  ^
+                          | one outbound WebSocket           |
+                          v                                  |
+                     the relay (tiny; ciphertext + routing only) -> push (FCM/APNs)
+```
+
+- Your **local store** on the computer is the source of truth for the conversation history.
+- The daemon keeps **one outbound WebSocket** to a relay, so it works behind any home router or cellular NAT with **no ports, no tunnel, no VPN, no Firebase project**.
+- The relay buffers what is in flight while the phone is asleep and triggers a wake-up push. It only ever sees **ciphertext and routing metadata**: prompts, answers, and content are AES-256-GCM encrypted with a key that only your computer and your phone hold, exchanged once by QR.
+- We host a relay for free users; self-hosters run the same server with `docker compose`.
+
+## Install
+
+On Linux, one command installs or updates everything: its own virtualenv, the `aaw` command, the shell integration, the link with your phone (a QR code), and the always-on service.
+It also removes the earlier Agents At Work Linux host if it finds one.
+
+```bash
+curl -fsSL https://agentsatwork.app/install-linux.sh | bash    # the same script as scripts/install.sh
+```
+
+Or by hand, on Linux or macOS (on a Mac, the free Agents At Work app does all of this for you):
+
+```bash
+pipx install aaw-core                      # Python 3.11+, and tmux
+aaw link                                   # asks which relay (ours, or your own), prints a QR code to scan
+aaw service install                        # the always-on part: runs in the background and starts at every login
+aaw shell-integration on                   # typing claude, codex, ... in a folder starts a bridged session
+```
+
+Then start an agent the way you always do (`cd ~/my-project && claude`), or start one from the phone.
+
+## Everyday commands
+
+```bash
+aaw status                          # the computer, the relay, and every session
+aaw start ~/my-project              # start a session (--agent codex, gemini, grok, cursor, scoot)
+aaw stop my-project                 # stop one session
+aaw feed my-project                 # the conversation, paged; -f follows it live
+aaw send my-project "run the tests" # send a prompt
+aaw schedule my-project --at 2am "continue with the refactor"   # a prompt for later
+aaw mobile-mode on                  # permission prompts go to the phone
+aaw quit                            # stop everything; the next login (or aaw service start) brings it back
+aaw uninstall                       # remove the service, the hooks, the shell line, and ~/.aaw
+```
+
+`aaw --help` lists every command, and `aaw <command> --help` its options.
+
+## Hosting the relay yourself
+
+The relay is a small server in this repository (`aaw_core/relay/`): run it with `docker compose` from `relay/`, or with `pip install "aaw-core[relay]"` and `python -m aaw_core.relay`, behind a TLS proxy.
+Point your computer at it with `aaw link --relay wss://your.host/v1/ws`.
+It sees only ciphertext and routing metadata, the same as ours.
+One difference: waking the phone with a push notification needs the app's own push credentials, so on your own relay the phone gets updates while the app is open, not in the background.
+`relay/README.md` has the details.
+
+## Desktop notifications
+
+The phone is the primary channel, and the computer itself also gets a banner when a turn finishes, an error happens, or the agent waits for input: `osascript` on macOS, `notify-send` on a Linux desktop (GNOME, KDE, and the rest). A server or a box without a desktop simply has no `notify-send` and shows nothing. On macOS, while any Focus is on (Do Not Disturb included), banners from scripts go to Notification Center silently unless Agents At Work is allowed under System Settings > Focus > Allowed Apps; `aaw status` reminds you. Two keys in `~/.aaw/config.json`: `local_notifications` (default `true`; a GUI that shows its own banners turns it off) and `waiting_alert_seconds` (default `0`, off; the seconds a question may sit unanswered before a "waiting for your answer" banner, for when the push is muted while you are at the desk).
+
+## Supported agents
+
+Claude Code, Codex CLI, Gemini CLI, Grok CLI, Cursor, and [Scoot](https://github.com/sergenes/scootcli) (local models with Ollama, plus cloud models). Not affiliated with Anthropic, OpenAI, Google, xAI, Anysphere, or Ollama.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions use the DCO (`git commit -s`). Security reports: see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

aaw_core-0.1.0/SECURITY.md

@@ -0,0 +1,18 @@
+# Security policy
+
+This project handles end-to-end encryption and remote control of coding agents. Please report vulnerabilities privately, not in the public issue tracker.
+
+## Reporting
+
+- Preferred: open a private report through **GitHub Security Advisories** on this repository ("Report a vulnerability").
+- Or email **hello@agentsatwork.app** with the details.
+
+Include what you found, how to reproduce it, and the impact you believe it has. You will get an acknowledgement, and a fix or a mitigation plan, before any public disclosure.
+
+## Scope
+
+- The host (`aaw_core/`): the daemon, hooks, pairing, and the `aaw` command.
+- The relay (`relay/`).
+- The encryption envelope and key handling.
+
+The closed phone and macOS apps are out of scope here; report those to the same email.

aaw_core-0.1.0/aaw_core/__init__.py

@@ -0,0 +1,7 @@
+"""Agents At Work Core: the open-source engine behind Agents At Work.
+
+The headless host (daemon, hooks, ``aaw`` CLI) that watches coding agents in tmux
+on your own computer, plus the relay transport that connects it to your phone.
+"""
+
+__version__ = "0.1.0"

aaw_core-0.1.0/aaw_core/config.py

@@ -0,0 +1,151 @@
+"""Configuration for the aaw-core host.
+
+Config-first by construction: everything comes from environment variables or
+``~/.aaw/config.json``. There are no defaults that point at any hosted project,
+which is what makes this repository safe to publish without a secrets audit.
+
+Precedence: environment variable > config file > built-in default.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+# A distinct state directory so aaw-core can coexist on one machine with the
+# commercial Agents At Work host, which uses ~/.agent-bridge.
+DEFAULT_STATE_DIR = Path.home() / ".aaw"
+
+# The relay we host for free users. A public endpoint, not a secret, and never a
+# silent default: `aaw link` offers it and writes the choice to config.json.
+HOSTED_RELAY_URL = "wss://relay.agentsatwork.app/v1/ws"
+
+
+def default_computer_name() -> str:
+    """The name a person knows this computer by.
+
+    On macOS that is the Computer Name from System Settings ("Sergey's MacBook Pro"),
+    not the network hostname ("Sergeys-MacBook-Pro.local"). Elsewhere the hostname,
+    without a trailing ".local".
+    """
+    if sys.platform == "darwin":
+        try:
+            out = subprocess.run(["scutil", "--get", "ComputerName"], capture_output=True, text=True,
+                                 timeout=2, check=False).stdout.strip()
+            if out:
+                return out
+        except (OSError, subprocess.SubprocessError):
+            pass
+    name = os.uname().nodename
+    return name.removesuffix(".local")
+
+
+def _config_file(state_dir: Path) -> dict:
+    path = state_dir / "config.json"
+    try:
+        return json.loads(path.read_text()) if path.exists() else {}
+    except (OSError, ValueError):
+        return {}
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Resolved settings for one host process."""
+
+    state_dir: Path
+    relay_url: str | None  # wss://... ; required to bridge to a phone, None = local only
+    computer_name: str
+    keep_awake: bool
+    browse_roots: tuple[str, ...] = ("~",)  # folders the phone may browse and start sessions in
+    local_notifications: bool = True  # desktop banners (osascript / notify-send)
+    waiting_alert_seconds: int = 0  # 0 = no "waiting for your answer" desktop alert
+
+    @property
+    def sessions_dir(self) -> Path:
+        return self.state_dir / "sessions"
+
+    @property
+    def run_dir(self) -> Path:
+        """Pid files of the daemons and the keep-awake helper."""
+        return self.state_dir / "run"
+
+    def daemon_pid_file(self, project_id: str) -> Path:
+        return self.run_dir / f"daemon.{project_id}.pid"
+
+    def daemon_log_file(self, project_id: str) -> Path:
+        return self.logs_dir / f"daemon.{project_id}.log"
+
+    @property
+    def keep_awake_pid_file(self) -> Path:
+        return self.run_dir / "keep-awake.pid"
+
+    @property
+    def supervisor_log_file(self) -> Path:
+        return self.logs_dir / "supervisor.log"
+
+    @property
+    def session_key_file(self) -> Path:
+        return self.state_dir / "session.key"
+
+    @property
+    def enabled_flag(self) -> Path:
+        return self.state_dir / "enabled"
+
+    @property
+    def mobile_mode_file(self) -> Path:
+        """Holds "manual" or a timestamp while permission prompts should go to the phone."""
+        return self.state_dir / "mobile_mode"
+
+    @property
+    def host_file(self) -> Path:
+        """The persisted host identity (computer id + relay routing token)."""
+        return self.state_dir / "host.json"
+
+    @property
+    def logs_dir(self) -> Path:
+        return self.state_dir / "logs"
+
+
+def save_config(state_dir: Path, **fields) -> Path:
+    """Merge fields into <state dir>/config.json (created if missing)."""
+    path = state_dir / "config.json"
+    current = _config_file(state_dir)
+    current.update(fields)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(current, indent=2) + "\n")
+    return path
+
+
+def load_settings() -> Settings:
+    state_dir = Path(os.environ.get("AAW_STATE_DIR") or DEFAULT_STATE_DIR).expanduser()
+    cfg = _config_file(state_dir)
+
+    def pick(env: str, key: str, default):
+        value = os.environ.get(env)
+        if value is not None and value != "":
+            return value
+        return cfg.get(key, default)
+
+    def flag(env: str, key: str, default: str) -> bool:
+        return str(pick(env, key, default)).lower() in ("1", "true", "yes")
+
+    roots = pick("AAW_BROWSE_ROOTS", "browse_roots", "~")
+    if isinstance(roots, str):
+        roots = [r for r in roots.split(os.pathsep) if r]
+    try:
+        waiting = int(pick("AAW_WAITING_ALERT_SECONDS", "waiting_alert_seconds", 0))
+    except (TypeError, ValueError):
+        waiting = 0
+    return Settings(
+        state_dir=state_dir,
+        relay_url=pick("AAW_RELAY_URL", "relay_url", None),
+        computer_name=pick("AAW_COMPUTER_NAME", "computer_name", None) or default_computer_name(),
+        keep_awake=flag("AAW_KEEP_AWAKE", "keep_awake", "true"),
+        browse_roots=tuple(str(r) for r in roots) or ("~",),
+        local_notifications=flag("AAW_LOCAL_NOTIFICATIONS", "local_notifications", "true"),
+        waiting_alert_seconds=max(0, waiting),
+    )