codex-autorunner 0.1.0__tar.gz

codex_autorunner-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Zhang
+
+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.

codex_autorunner-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: codex-autorunner
+Version: 0.1.0
+Summary: Codex autorunner CLI per DESIGN-V1
+Author: Codex
+License: MIT License
+        
+        Copyright (c) 2025 David Zhang
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/Git-on-my-level/codex-autorunner
+Project-URL: Repository, https://github.com/Git-on-my-level/codex-autorunner
+Project-URL: Issues, https://github.com/Git-on-my-level/codex-autorunner/issues
+Keywords: codex,automation,agent,cli,fastapi
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9
+Requires-Dist: click<8.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: ptyprocess>=0.7
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Provides-Extra: telegram
+Requires-Dist: httpx>=0.27; extra == "telegram"
+Provides-Extra: voice
+Requires-Dist: httpx>=0.27; extra == "voice"
+Requires-Dist: python-multipart>=0.0.9; extra == "voice"
+Provides-Extra: github
+Dynamic: license-file
+
+# codex-autorunner
+
+An opinionated autorunner that uses the Codex CLI to work on large tasks via a simple loop. On each loop we feed the Codex instance the last one's final output along with core documents.
+1. TODO - Tracks long-horizon tasks
+2. PROGRESS - High level overview of what's been done already that may be relevant for future agents
+3. OPINIONS - Guidelines for how we should approach implementation
+4. SPEC - Source-of-truth requirements and scope for large features/projects
+
+## Sneak Peak
+Run multiple agents on many repositories, with git worktree support
+![Desktop hub](docs/screenshots/car-desktop-hub.png)
+
+See the progress of your long running tasks with a high level overview
+![Desktop repo dashboard](docs/screenshots/car-desktop-repo-dashboard.png)
+
+Dive deep into specific agent execution with a rich but readable log
+![Desktop logs](docs/screenshots/car-desktop-logs.png)
+
+All memory and opinions are markdown files! Edit them directly or chat with the document!
+![Desktop TODO](docs/screenshots/car-desktop-todo.png)
+
+Use codex CLI directly for multi-shot problem solving or `/review`
+![Desktop terminal](docs/screenshots/car-desktop-terminal.png)
+
+Mobile-first experience, code on the go with Whisper support (BYOK)
+![Mobile terminal](docs/screenshots/car-mobile-terminal.png)
+
+## What it does
+- Initializes a repo with Codex-friendly docs and config.
+- Runs Codex in a loop against the repo, streaming logs.
+- Tracks state, logs, and config under `.codex-autorunner/`.
+- Exposes a power-user HTTP API and web UI for docs, logs, runner control, and a Codex TUI terminal.
+- Optionally runs a Telegram bot for interactive, user-in-the-loop Codex sessions.
+- Generates a pasteable repo snapshot (`.codex-autorunner/SNAPSHOT.md`) for sharing with other LLM chats.
+
+CLI commands are available as `codex-autorunner` or the shorter `car`.
+
+## Install
+PyPI (pipx):
+```
+pipx install codex-autorunner
+```
+
+GitHub (pipx, dev):
+```
+pipx install git+https://github.com/Git-on-my-level/codex-autorunner.git
+```
+
+From source (editable):
+```
+git clone https://github.com/Git-on-my-level/codex-autorunner.git
+cd codex-autorunner
+pip install -e .
+```
+
+### Optional extras
+- Telegram bot support: `pip install codex-autorunner[telegram]`
+- Voice transcription support: `pip install codex-autorunner[voice]`
+- Dev tools (lint/test): `pip install codex-autorunner[dev]`
+- Local dev alternative: `pip install -e .[extra]`
+
+## Dev setup
+- `make setup` creates `.venv`, installs `.[dev]`, runs `npm install`, and sets `core.hooksPath` to `.githooks`.
+
+### Opinionated setup (macOS headless hub at `~/car-workspace`)
+- One-shot setup (user scope): `scripts/install-local-mac-hub.sh`. It pipx-installs this repo, creates/initializes `~/car-workspace` as a hub, writes a launchd agent plist, and loads it. Defaults: host `127.0.0.1`, port `4173`, label `com.codex.autorunner`. Override via env (`WORKSPACE`, `HOST`, `PORT`, `LABEL`, `PLIST_PATH`, `PACKAGE_SRC`). For remote access, prefer a VPN like Tailscale and keep the hub bound to loopback; if you bind to a non-loopback host, the script configures `server.auth_token_env` + a token in `.codex-autorunner/.env`.
+- Create/update the launchd agent plist and (re)load it: `scripts/launchd-hub.sh` (or `make launchd-hub`).
+- Linux users: see `docs/ops/systemd.md` for systemd hub/Telegram setup.
+- Manual path if you prefer:
+  - `pipx install .`
+  - `car init --mode hub --path ~/car-workspace`
+  - Copy `docs/ops/launchd-hub-example.plist` to `~/Library/LaunchAgents/com.codex.autorunner.plist`, replace `/Users/you` with your home, adjust host/port if desired, then `launchctl load -w ~/Library/LaunchAgents/com.codex.autorunner.plist`.
+- The hub serves the UI/API from `http://<host>:<port>` and writes logs to `~/car-workspace/.codex-autorunner/codex-autorunner-hub.log`. Each repo under `~/car-workspace` should be a git repo with its own `.codex-autorunner/` (run `car init` in each).
+
+#### Refresh a launchd hub to the current branch
+When you change code in this repo and want the launchd-managed hub to run it:
+1) Recommended: run the safe refresher, which installs into a new venv, flips `~/.local/pipx/venvs/codex-autorunner.current`, restarts launchd, health-checks, and auto-rolls back on failure:
+```
+make refresh-launchd
+```
+
+Important: avoid in-place pip/pipx installs against the live venv. During uninstall/reinstall, packaged static assets disappear and the UI can break while the server keeps running. Use the safe refresher or stop the service before manual installs.
+
+2) Manual path (offline only; no rollback): stop launchd first, then reinstall into the launchd venv (pipx default paths shown; adjust if your label/paths differ):
+```
+$HOME/.local/pipx/venvs/codex-autorunner/bin/python -m pip install --force-reinstall /path/to/your/codex-autorunner
+```
+3) Restart the agent so it picks up the new bits (default label is `com.codex.autorunner`; default plist `~/Library/LaunchAgents/com.codex.autorunner.plist`):
+```
+launchctl unload ~/Library/LaunchAgents/com.codex.autorunner.plist 2>/dev/null || true
+launchctl load -w ~/Library/LaunchAgents/com.codex.autorunner.plist
+launchctl kickstart -k gui/$(id -u)/com.codex.autorunner
+```
+4) Tail the hub log to confirm it booted: `tail -n 50 ~/car-workspace/.codex-autorunner/codex-autorunner-hub.log`.
+
+#### Health checks (recommended)
+- `GET /health` returns 200 (verifies static assets are present).
+- `GET /static/app.js` returns 200.
+- Optional: `GET /` returns HTML (not a JSON error).
+If you set a base path, prefix all checks with it.
+
+## Quick start
+1) Install (editable): `pip install -e .`
+2) Initialize (per repo): `codex-autorunner init --git-init` (or `car init --git-init` if you prefer short). This creates `.codex-autorunner/config.yml`, state/log files, and the docs under `.codex-autorunner/`.
+3) Run once: `codex-autorunner once` / `car once`
+4) Continuous loop: `codex-autorunner run` / `car run`
+5) If stuck: `codex-autorunner kill` then `codex-autorunner resume` (or the `car` equivalents)
+6) Check status/logs: `codex-autorunner status`, `codex-autorunner log --tail 200` (or `car ...`)
+
+## Configuration
+- Root defaults live in `codex-autorunner.yml` (committed). These defaults are used when CAR generates `.codex-autorunner/config.yml`.
+- Local overrides live in `codex-autorunner.override.yml` (gitignored). Use it for machine-specific tweaks; keep secrets in env vars.
+- Repo config lives at `.codex-autorunner/config.yml` (generated). Edit it for repo-specific changes.
+
+## Interfaces
+
+CAR supports two interfaces with the same core engine. The web UI is the power
+user control plane for multi-repo visibility and system control. The Telegram
+bot is optimized for interactive back-and-forth, mirroring the Codex TUI
+experience inside Telegram with user-in-the-loop approvals.
+
+### Web UI (control plane)
+1) Ensure the repo is initialized (`codex-autorunner init`) so `.codex-autorunner/config.yml` exists.
+2) Start the API/UI backend: `codex-autorunner serve` (or `car serve`) — defaults to `127.0.0.1:4173`; override via `server.host`/`server.port` in `.codex-autorunner/config.yml`.
+3) Open `http://127.0.0.1:4173` to use the UI, or call the FastAPI endpoints under `/api/*`.
+   - The Terminal tab launches the configured Codex binary inside a PTY via websocket; it uses `codex.terminal_args` (defaults empty, so it runs `codex` bare unless you override). xterm.js assets are vendored under `static/vendor`.
+   - If you need to serve under a proxy prefix (e.g., `/car`), set `server.base_path` in `.codex-autorunner/config.yml` or pass `--base-path` to `car serve/hub serve`; all HTTP/WS endpoints will be reachable under that prefix. Proxy must forward that prefix (e.g., Caddy `handle /car/* { reverse_proxy ... }` with a 404 fallback for everything else).
+   - Chat composer shortcuts: desktop uses Cmd+Enter (or Ctrl+Enter) to send and Shift+Enter for newline; mobile uses Enter to send and Shift+Enter for newline.
+
+### Telegram bot (interactive sessions)
+- The interactive Telegram bot is separate from `notifications.telegram` (which is one-way notifications).
+- Each operator should create their own Telegram bot token. Multi-user use requires explicit allowlists.
+- Quickstart:
+  1) Set env vars: `CAR_TELEGRAM_BOT_TOKEN` (and optionally `CAR_TELEGRAM_CHAT_ID`).
+  2) In config, set `telegram_bot.enabled: true` and fill `allowed_user_ids` + `allowed_chat_ids`.
+  3) Run `car telegram start --path <repo_or_hub>`.
+  4) Use `/bind` (hub mode) and `/new` or `/resume` in Telegram.
+- How it works (high level):
+  - The bot polls the Telegram Bot API, allowlists chat/user IDs, and routes each topic to a workspace + Codex thread.
+  - Messages and media are forwarded to the Codex app-server, streaming responses back to Telegram.
+  - Approvals can be requested inline, giving a hands-on, TUI-like workflow without leaving Telegram.
+- Details: `docs/telegram/architecture.md`, `docs/ops/telegram-bot-runbook.md`, and `docs/telegram/security.md`.
+
+## Security and remote access
+- The UI/API are effectively privileged access and can execute code on your machine (terminal + runner).
+- Keep the server bound to `127.0.0.1` and use Tailscale (or another VPN) for remote access.
+- If you must expose it, set `server.auth_token_env` and also put it behind an auth-enforcing reverse proxy (basic auth/SSO).
+- Do not expose it publicly without protections. See `docs/web/security.md` for details.
+
+### Auth token (optional)
+If you set `server.auth_token_env`, the API requires `Authorization: Bearer <token>` on every request.
+- Set the config: `server.auth_token_env: CAR_SERVER_TOKEN`.
+- Export the token before starting the server: `export CAR_SERVER_TOKEN="..."`.
+- Browser UI: visit `http://host:port/?token=...` once. The UI stores it in `sessionStorage` and removes it from the URL; WebSocket connections send the token via `Sec-WebSocket-Protocol: car-token-b64.<base64url(token)>`.
+- CLI: requests automatically attach the token from `server.auth_token_env`; if the env var is missing, CLI commands will error.
+
+## Git hooks
+- Install dev tools: `pip install -e .[dev]`
+- Point Git to the repo hooks: `git config core.hooksPath .githooks`
+- The `pre-commit` hook runs `scripts/check.sh` (Black formatting check + pytest). Run it manually with `./scripts/check.sh` before committing or in CI.
+
+## Commands (CLI)
+- `init` — seed config/state/docs.
+- `run` / `once` — run the loop (continuous or single iteration).
+- `resume` — clear stale lock/state and restart; `--once` for a single run.
+- `kill` — SIGTERM the running loop and mark state error.
+- `status` — show current state and outstanding TODO count.
+- `sessions` — list terminal sessions (server-backed when available).
+- `stop-session` — stop a terminal session by repo (`--repo`) or id (`--session`).
+- `log` — view logs (tail or specific run).
+- `edit` — open TODO/PROGRESS/OPINIONS/SPEC in `$EDITOR`.
+- `ingest-spec` — generate TODO/PROGRESS/OPINIONS from SPEC using Codex (use `--force` to overwrite).
+- `clear-docs` — reset TODO/PROGRESS/OPINIONS to empty templates (type CLEAR to confirm).
+- `snapshot` — generate/update `.codex-autorunner/SNAPSHOT.md` (incremental by default when one exists; use `--from-scratch` to regenerate).
+- `serve` — start the HTTP API (FastAPI) on host/port from config (defaults 127.0.0.1:4173).
+
+## Snapshot (repo briefing)
+- Web UI: open the Snapshot tab. If no snapshot exists, you’ll see “Generate snapshot”; otherwise you’ll see “Update snapshot (incremental)” and “Regenerate snapshot (from scratch)”, plus “Copy to clipboard”.
+- CLI: `codex-autorunner snapshot` (or `car snapshot`) writes `.codex-autorunner/SNAPSHOT.md` and `.codex-autorunner/snapshot_state.json`.

codex_autorunner-0.1.0/README.md

@@ -0,0 +1,179 @@
+# codex-autorunner
+
+An opinionated autorunner that uses the Codex CLI to work on large tasks via a simple loop. On each loop we feed the Codex instance the last one's final output along with core documents.
+1. TODO - Tracks long-horizon tasks
+2. PROGRESS - High level overview of what's been done already that may be relevant for future agents
+3. OPINIONS - Guidelines for how we should approach implementation
+4. SPEC - Source-of-truth requirements and scope for large features/projects
+
+## Sneak Peak
+Run multiple agents on many repositories, with git worktree support
+![Desktop hub](docs/screenshots/car-desktop-hub.png)
+
+See the progress of your long running tasks with a high level overview
+![Desktop repo dashboard](docs/screenshots/car-desktop-repo-dashboard.png)
+
+Dive deep into specific agent execution with a rich but readable log
+![Desktop logs](docs/screenshots/car-desktop-logs.png)
+
+All memory and opinions are markdown files! Edit them directly or chat with the document!
+![Desktop TODO](docs/screenshots/car-desktop-todo.png)
+
+Use codex CLI directly for multi-shot problem solving or `/review`
+![Desktop terminal](docs/screenshots/car-desktop-terminal.png)
+
+Mobile-first experience, code on the go with Whisper support (BYOK)
+![Mobile terminal](docs/screenshots/car-mobile-terminal.png)
+
+## What it does
+- Initializes a repo with Codex-friendly docs and config.
+- Runs Codex in a loop against the repo, streaming logs.
+- Tracks state, logs, and config under `.codex-autorunner/`.
+- Exposes a power-user HTTP API and web UI for docs, logs, runner control, and a Codex TUI terminal.
+- Optionally runs a Telegram bot for interactive, user-in-the-loop Codex sessions.
+- Generates a pasteable repo snapshot (`.codex-autorunner/SNAPSHOT.md`) for sharing with other LLM chats.
+
+CLI commands are available as `codex-autorunner` or the shorter `car`.
+
+## Install
+PyPI (pipx):
+```
+pipx install codex-autorunner
+```
+
+GitHub (pipx, dev):
+```
+pipx install git+https://github.com/Git-on-my-level/codex-autorunner.git
+```
+
+From source (editable):
+```
+git clone https://github.com/Git-on-my-level/codex-autorunner.git
+cd codex-autorunner
+pip install -e .
+```
+
+### Optional extras
+- Telegram bot support: `pip install codex-autorunner[telegram]`
+- Voice transcription support: `pip install codex-autorunner[voice]`
+- Dev tools (lint/test): `pip install codex-autorunner[dev]`
+- Local dev alternative: `pip install -e .[extra]`
+
+## Dev setup
+- `make setup` creates `.venv`, installs `.[dev]`, runs `npm install`, and sets `core.hooksPath` to `.githooks`.
+
+### Opinionated setup (macOS headless hub at `~/car-workspace`)
+- One-shot setup (user scope): `scripts/install-local-mac-hub.sh`. It pipx-installs this repo, creates/initializes `~/car-workspace` as a hub, writes a launchd agent plist, and loads it. Defaults: host `127.0.0.1`, port `4173`, label `com.codex.autorunner`. Override via env (`WORKSPACE`, `HOST`, `PORT`, `LABEL`, `PLIST_PATH`, `PACKAGE_SRC`). For remote access, prefer a VPN like Tailscale and keep the hub bound to loopback; if you bind to a non-loopback host, the script configures `server.auth_token_env` + a token in `.codex-autorunner/.env`.
+- Create/update the launchd agent plist and (re)load it: `scripts/launchd-hub.sh` (or `make launchd-hub`).
+- Linux users: see `docs/ops/systemd.md` for systemd hub/Telegram setup.
+- Manual path if you prefer:
+  - `pipx install .`
+  - `car init --mode hub --path ~/car-workspace`
+  - Copy `docs/ops/launchd-hub-example.plist` to `~/Library/LaunchAgents/com.codex.autorunner.plist`, replace `/Users/you` with your home, adjust host/port if desired, then `launchctl load -w ~/Library/LaunchAgents/com.codex.autorunner.plist`.
+- The hub serves the UI/API from `http://<host>:<port>` and writes logs to `~/car-workspace/.codex-autorunner/codex-autorunner-hub.log`. Each repo under `~/car-workspace` should be a git repo with its own `.codex-autorunner/` (run `car init` in each).
+
+#### Refresh a launchd hub to the current branch
+When you change code in this repo and want the launchd-managed hub to run it:
+1) Recommended: run the safe refresher, which installs into a new venv, flips `~/.local/pipx/venvs/codex-autorunner.current`, restarts launchd, health-checks, and auto-rolls back on failure:
+```
+make refresh-launchd
+```
+
+Important: avoid in-place pip/pipx installs against the live venv. During uninstall/reinstall, packaged static assets disappear and the UI can break while the server keeps running. Use the safe refresher or stop the service before manual installs.
+
+2) Manual path (offline only; no rollback): stop launchd first, then reinstall into the launchd venv (pipx default paths shown; adjust if your label/paths differ):
+```
+$HOME/.local/pipx/venvs/codex-autorunner/bin/python -m pip install --force-reinstall /path/to/your/codex-autorunner
+```
+3) Restart the agent so it picks up the new bits (default label is `com.codex.autorunner`; default plist `~/Library/LaunchAgents/com.codex.autorunner.plist`):
+```
+launchctl unload ~/Library/LaunchAgents/com.codex.autorunner.plist 2>/dev/null || true
+launchctl load -w ~/Library/LaunchAgents/com.codex.autorunner.plist
+launchctl kickstart -k gui/$(id -u)/com.codex.autorunner
+```
+4) Tail the hub log to confirm it booted: `tail -n 50 ~/car-workspace/.codex-autorunner/codex-autorunner-hub.log`.
+
+#### Health checks (recommended)
+- `GET /health` returns 200 (verifies static assets are present).
+- `GET /static/app.js` returns 200.
+- Optional: `GET /` returns HTML (not a JSON error).
+If you set a base path, prefix all checks with it.
+
+## Quick start
+1) Install (editable): `pip install -e .`
+2) Initialize (per repo): `codex-autorunner init --git-init` (or `car init --git-init` if you prefer short). This creates `.codex-autorunner/config.yml`, state/log files, and the docs under `.codex-autorunner/`.
+3) Run once: `codex-autorunner once` / `car once`
+4) Continuous loop: `codex-autorunner run` / `car run`
+5) If stuck: `codex-autorunner kill` then `codex-autorunner resume` (or the `car` equivalents)
+6) Check status/logs: `codex-autorunner status`, `codex-autorunner log --tail 200` (or `car ...`)
+
+## Configuration
+- Root defaults live in `codex-autorunner.yml` (committed). These defaults are used when CAR generates `.codex-autorunner/config.yml`.
+- Local overrides live in `codex-autorunner.override.yml` (gitignored). Use it for machine-specific tweaks; keep secrets in env vars.
+- Repo config lives at `.codex-autorunner/config.yml` (generated). Edit it for repo-specific changes.
+
+## Interfaces
+
+CAR supports two interfaces with the same core engine. The web UI is the power
+user control plane for multi-repo visibility and system control. The Telegram
+bot is optimized for interactive back-and-forth, mirroring the Codex TUI
+experience inside Telegram with user-in-the-loop approvals.
+
+### Web UI (control plane)
+1) Ensure the repo is initialized (`codex-autorunner init`) so `.codex-autorunner/config.yml` exists.
+2) Start the API/UI backend: `codex-autorunner serve` (or `car serve`) — defaults to `127.0.0.1:4173`; override via `server.host`/`server.port` in `.codex-autorunner/config.yml`.
+3) Open `http://127.0.0.1:4173` to use the UI, or call the FastAPI endpoints under `/api/*`.
+   - The Terminal tab launches the configured Codex binary inside a PTY via websocket; it uses `codex.terminal_args` (defaults empty, so it runs `codex` bare unless you override). xterm.js assets are vendored under `static/vendor`.
+   - If you need to serve under a proxy prefix (e.g., `/car`), set `server.base_path` in `.codex-autorunner/config.yml` or pass `--base-path` to `car serve/hub serve`; all HTTP/WS endpoints will be reachable under that prefix. Proxy must forward that prefix (e.g., Caddy `handle /car/* { reverse_proxy ... }` with a 404 fallback for everything else).
+   - Chat composer shortcuts: desktop uses Cmd+Enter (or Ctrl+Enter) to send and Shift+Enter for newline; mobile uses Enter to send and Shift+Enter for newline.
+
+### Telegram bot (interactive sessions)
+- The interactive Telegram bot is separate from `notifications.telegram` (which is one-way notifications).
+- Each operator should create their own Telegram bot token. Multi-user use requires explicit allowlists.
+- Quickstart:
+  1) Set env vars: `CAR_TELEGRAM_BOT_TOKEN` (and optionally `CAR_TELEGRAM_CHAT_ID`).
+  2) In config, set `telegram_bot.enabled: true` and fill `allowed_user_ids` + `allowed_chat_ids`.
+  3) Run `car telegram start --path <repo_or_hub>`.
+  4) Use `/bind` (hub mode) and `/new` or `/resume` in Telegram.
+- How it works (high level):
+  - The bot polls the Telegram Bot API, allowlists chat/user IDs, and routes each topic to a workspace + Codex thread.
+  - Messages and media are forwarded to the Codex app-server, streaming responses back to Telegram.
+  - Approvals can be requested inline, giving a hands-on, TUI-like workflow without leaving Telegram.
+- Details: `docs/telegram/architecture.md`, `docs/ops/telegram-bot-runbook.md`, and `docs/telegram/security.md`.
+
+## Security and remote access
+- The UI/API are effectively privileged access and can execute code on your machine (terminal + runner).
+- Keep the server bound to `127.0.0.1` and use Tailscale (or another VPN) for remote access.
+- If you must expose it, set `server.auth_token_env` and also put it behind an auth-enforcing reverse proxy (basic auth/SSO).
+- Do not expose it publicly without protections. See `docs/web/security.md` for details.
+
+### Auth token (optional)
+If you set `server.auth_token_env`, the API requires `Authorization: Bearer <token>` on every request.
+- Set the config: `server.auth_token_env: CAR_SERVER_TOKEN`.
+- Export the token before starting the server: `export CAR_SERVER_TOKEN="..."`.
+- Browser UI: visit `http://host:port/?token=...` once. The UI stores it in `sessionStorage` and removes it from the URL; WebSocket connections send the token via `Sec-WebSocket-Protocol: car-token-b64.<base64url(token)>`.
+- CLI: requests automatically attach the token from `server.auth_token_env`; if the env var is missing, CLI commands will error.
+
+## Git hooks
+- Install dev tools: `pip install -e .[dev]`
+- Point Git to the repo hooks: `git config core.hooksPath .githooks`
+- The `pre-commit` hook runs `scripts/check.sh` (Black formatting check + pytest). Run it manually with `./scripts/check.sh` before committing or in CI.
+
+## Commands (CLI)
+- `init` — seed config/state/docs.
+- `run` / `once` — run the loop (continuous or single iteration).
+- `resume` — clear stale lock/state and restart; `--once` for a single run.
+- `kill` — SIGTERM the running loop and mark state error.
+- `status` — show current state and outstanding TODO count.
+- `sessions` — list terminal sessions (server-backed when available).
+- `stop-session` — stop a terminal session by repo (`--repo`) or id (`--session`).
+- `log` — view logs (tail or specific run).
+- `edit` — open TODO/PROGRESS/OPINIONS/SPEC in `$EDITOR`.
+- `ingest-spec` — generate TODO/PROGRESS/OPINIONS from SPEC using Codex (use `--force` to overwrite).
+- `clear-docs` — reset TODO/PROGRESS/OPINIONS to empty templates (type CLEAR to confirm).
+- `snapshot` — generate/update `.codex-autorunner/SNAPSHOT.md` (incremental by default when one exists; use `--from-scratch` to regenerate).
+- `serve` — start the HTTP API (FastAPI) on host/port from config (defaults 127.0.0.1:4173).
+
+## Snapshot (repo briefing)
+- Web UI: open the Snapshot tab. If no snapshot exists, you’ll see “Generate snapshot”; otherwise you’ll see “Update snapshot (incremental)” and “Regenerate snapshot (from scratch)”, plus “Copy to clipboard”.
+- CLI: `codex-autorunner snapshot` (or `car snapshot`) writes `.codex-autorunner/SNAPSHOT.md` and `.codex-autorunner/snapshot_state.json`.

codex_autorunner-0.1.0/pyproject.toml

@@ -0,0 +1,105 @@
+[project]
+name = "codex-autorunner"
+version = "0.1.0"
+description = "Codex autorunner CLI per DESIGN-V1"
+readme = "README.md"
+license = {file = "LICENSE"}
+authors = [{name = "Codex"}]
+requires-python = ">=3.9"
+dependencies = [
+  "typer>=0.9",
+  "click<8.2",
+  "pyyaml>=6.0",
+  "fastapi>=0.111",
+  "uvicorn[standard]>=0.30",
+  "ptyprocess>=0.7",
+  "python-multipart>=0.0.9",
+  "python-dotenv>=1.0",
+  "httpx>=0.27",
+]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+]
+keywords = ["codex", "automation", "agent", "cli", "fastapi"]
+
+[project.urls]
+Homepage = "https://github.com/Git-on-my-level/codex-autorunner"
+Repository = "https://github.com/Git-on-my-level/codex-autorunner"
+Issues = "https://github.com/Git-on-my-level/codex-autorunner/issues"
+
+[project.optional-dependencies]
+dev = [
+  "black>=23.0",
+  "mypy>=1.10",
+  "pytest>=7.0",
+  "ruff>=0.5.0",
+  "types-PyYAML",
+]
+telegram = [
+  "httpx>=0.27",
+]
+voice = [
+  "httpx>=0.27",
+  "python-multipart>=0.0.9",
+]
+github = []
+
+[project.scripts]
+codex-autorunner = "codex_autorunner.cli:app"
+car = "codex_autorunner.cli:app"
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+codex_autorunner = ["static/*", "static/**/*"]
+
+[tool.typer]
+completions = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/codex_autorunner/logging_utils.py" = ["F403"]
+"src/codex_autorunner/pty_session.py" = ["F403"]
+"src/codex_autorunner/static_assets.py" = ["F403"]
+"src/codex_autorunner/cli.py" = ["B008"]
+"src/codex_autorunner/routes/terminal_images.py" = ["B008"]
+"src/codex_autorunner/routes/voice.py" = ["B008"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+no_implicit_optional = true
+ignore_missing_imports = true
+warn_unused_ignores = true
+files = [
+  "src/codex_autorunner",
+]
+
+[[tool.mypy.overrides]]
+module = ["codex_autorunner.core", "codex_autorunner.core.*"]
+ignore_errors = false
+
+[[tool.mypy.overrides]]
+module = [
+  "codex_autorunner.integrations.app_server",
+  "codex_autorunner.integrations.app_server.*",
+]
+ignore_errors = false

codex_autorunner-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codex_autorunner-0.1.0/src/codex_autorunner/__init__.py

@@ -0,0 +1,3 @@
+"""Codex autorunner package."""
+
+__all__ = ["cli", "core", "integrations", "routes", "server", "voice", "web"]