English · العربية · Español · Français · 日本語 · 한국어 · Tiếng Việt · 中文 (简体) · 中文（繁體） · Deutsch · Русский

Reusable scripts + guides for building apps step-by-step from screenshots/markdown with Codex as a non-interactive tool.

🎯 Mission: Make app-development pipelines deterministic, resumable, and artifact-driven.

🧩 Design principle: Plan -> Work -> Verify -> Summary -> Commit/Push.

• Updated: 2026-02-16T00:27:20Z
• Phase commit: Selfdev: 52 pwa_action_palette_dynamic_and_editable_blocks summary
• Progress: 51 / 55 tasks done
• Codex session: 019c6056-f33a-7f31-b08f-0ca40c365351
• Philosophy: Plan -> Work -> Verify -> Summary -> Commit/Push (linear, resumable)

This section is updated by scripts/auto-autoappdev-development.sh. Do not edit content between the markers.

• 🚀 Overview
• 🧭 Repository Snapshot
• 🧭 Philosophy
• ✨ Features
• 📌 At A Glance
• 🏗️ Architecture
• 📚 Contents
• 🗂️ Project Structure
• ✅ Prerequisites
• 🧩 Compatibility & Assumptions
• 🛠️ Installation
• ⚡ Quick Start
• ⚙️ Configuration
• ▶️ Usage
• 🧭 Operational Runbooks
• 📡 API Snapshot
• 🧪 Examples
• 🧱 Development Notes
• 🔐 Safety Notes
• 🔧 Troubleshooting
• 🌐 README & i18n Workflow
• 📘 Readme Generation Context
• ❓ FAQ
• 🗺️ Roadmap
• 🤝 Contributing
• ❤️ Support
• 📄 License

AutoAppDev is a controller project for long-running, resumable app-development pipelines. It combines:

1. A Tornado backend API with PostgreSQL-backed persistence (plus local JSON fallback behavior in storage code).
2. A Scratch-like static PWA controller UI.
3. Scripts and docs for pipeline authoring, deterministic code generation, self-development loops, and README automation.

The project is optimized for predictable agent execution with strict sequencing and artifact-oriented workflow history.

AutoAppDev treats agents as tools and keeps work stable via a strict, resumable loop:

1. Plan
2. Implement
3. Debug/verify (with timeouts)
4. Fix
5. Summarize + log
6. Commit + push

The controller app aims to embody the same concepts as Scratch-like blocks/actions (including a common update_readme action) so each workspace stays current and reproducible.

• Resumable pipeline lifecycle control: start, pause, resume, stop.
• Script library APIs for AAPS pipeline scripts (.aaps) and canonical IR (autoappdev_ir v1).
• Deterministic parser/import pipeline:
  • Parse formatted AAPS scripts.
  • Import annotated shell via # AAPS: comments.
  • Optional Codex-assisted parse fallback (AUTOAPPDEV_ENABLE_LLM_PARSE=1).
• Action registry with built-ins + editable/custom actions (clone/edit flow for readonly built-ins).
• Scratch-like PWA blocks and runtime-loaded action palette (GET /api/actions).
• Runtime messaging channels:
  • Inbox (/api/inbox) for operator -> pipeline guidance.
  • Outbox (/api/outbox) including file-queue ingestion from runtime/outbox.
• Incremental log streaming from backend and pipeline logs (/api/logs, /api/logs/tail).
• Deterministic runner codegen from canonical IR (scripts/pipeline_codegen/generate_runner_from_ir.py).
• Self-dev driver for iterative repository evolution (scripts/auto-autoappdev-development.sh).
• README automation pipeline with multilingual generation scaffolding under i18n/.

Operator / Developer
        |
        v
   PWA (static files, pwa/)
        |
        | HTTP JSON API
        v
Tornado backend (backend/app.py)
        |
        +--> Postgres (DATABASE_URL)
        +--> runtime/ (logs, outbox, llm_parse artifacts)
        +--> scripts/ (pipeline runner + codegen helpers)

• Expose controller APIs for scripts, actions, plan, pipeline lifecycle, logs, inbox/outbox, workspace config.
• Validate and persist pipeline script assets.
• Coordinate pipeline execution state and status transitions.
• Provide deterministic fallback behavior when DB pool is unavailable.

• Render Scratch-like block UI and pipeline editing flow.
• Load action palette dynamically from backend registry.
• Drive lifecycle controls and monitor status/logs/messages.

Reference map for the most commonly used docs, scripts, and examples:

• docs/auto-development-guide.md: Bilingual (EN/ZH) philosophy and requirements for a long-running, resumable auto-development agent.
• docs/ORDERING_RATIONALE.md: Example rationale for sequencing screenshot-driven steps.
• docs/controller-mvp-scope.md: Controller MVP scope (screens + minimal APIs).
• docs/end-to-end-demo-checklist.md: Deterministic manual end-to-end demo checklist (backend + PWA happy path).
• docs/env.md: Environment variables (.env) conventions.
• docs/api-contracts.md: API request/response contracts for the controller.
• docs/pipeline-formatted-script-spec.md: Standard pipeline script format (AAPS) and canonical IR schema (TASK -> STEP -> ACTION).
• docs/pipeline-runner-codegen.md: Deterministic generator for runnable bash pipeline runners from canonical IR.
• docs/common-actions.md: Common action contracts/specs (includes update_readme).
• docs/workspace-layout.md: Standard workspace folders + contracts (materials/interactions/outputs/docs/references/scripts/tools/logs/auto-apps).
• scripts/run_autoappdev_tmux.sh: Start the AutoAppDev app (backend + PWA) in tmux.
• scripts/run_autoappdev_selfdev_tmux.sh: Start the AutoAppDev self-dev driver in tmux.
• scripts/app-auto-development.sh: Linear pipeline driver (plan -> backend -> PWA -> Android -> iOS -> review -> summary) with resume/state support.
• scripts/generate_screenshot_docs.sh: Screenshot -> markdown description generator (Codex-driven).
• scripts/setup_autoappdev_env.sh: Main conda env bootstrap script for local runs.
• scripts/setup_backend_env.sh: Backend env helper script.
• examples/ralph-wiggum-example.sh: Example Codex CLI automation helper.

AutoAppDev/
├── README.md
├── .env.example
├── .github/
│   └── FUNDING.yml
├── backend/
│   ├── app.py
│   ├── storage.py
│   ├── schema.sql
│   ├── apply_schema.py
│   ├── db_smoketest.py
│   ├── action_registry.py
│   ├── builtin_actions.py
│   ├── update_readme_action.py
│   ├── pipeline_parser.py
│   ├── pipeline_shell_import.py
│   ├── llm_assisted_parse.py
│   ├── workspace_config.py
│   ├── requirements.txt
│   └── README.md
├── pwa/
│   ├── index.html
│   ├── app.js
│   ├── i18n.js
│   ├── api-client.js
│   ├── styles.css
│   ├── service-worker.js
│   ├── manifest.json
│   └── README.md
├── docs/
├── scripts/
│   └── pipeline_codegen/
├── prompt_tools/
├── examples/
├── references/
├── i18n/
└── .auto-readme-work/

• OS with bash.
• Python 3.11+.
• Conda (conda) for the provided setup scripts.
• tmux for one-command backend+PWA or self-dev sessions.
• PostgreSQL reachable by DATABASE_URL.
• Optional: codex CLI for Codex-powered flows (self-dev, parse-llm fallback, auto-readme pipeline).

Quick requirement matrix:

Assumptions used in this README:

• You run commands from repository root unless a section says otherwise.
• .env is configured before starting backend services.
• conda and tmux are available for the recommended one-command workflows.

git clone [email protected]:lachlanchen/AutoAppDev.git
cd AutoAppDev

cp .env.example .env

Edit .env and set at least:

• SECRET_KEY
• DATABASE_URL
• AUTOAPPDEV_HOST and AUTOAPPDEV_PORT (or PORT)

./scripts/setup_autoappdev_env.sh

conda run -n autoappdev python -m backend.apply_schema

conda run -n autoappdev python -m backend.db_smoketest

# from repo root
cp .env.example .env
./scripts/setup_autoappdev_env.sh
conda run -n autoappdev python -m backend.apply_schema
./scripts/run_autoappdev_tmux.sh --restart

Then open:

• PWA: http://127.0.0.1:5173/
• Backend API base: http://127.0.0.1:8788
• Health check: http://127.0.0.1:8788/api/health

Smoke-check with one command:

curl -sS http://127.0.0.1:8788/api/health | python3 -m json.tool

Quick endpoint map:

Primary file: .env (see docs/env.md and .env.example).

Validate .env quickly:

bash -lc 'set -euo pipefail; test -f .env; set -a; source .env; set +a; \
python3 - <<"PY"\
import os, sys\
req = ["SECRET_KEY", "DATABASE_URL"]\
missing = [k for k in req if not os.getenv(k)]\
port_ok = bool(os.getenv("AUTOAPPDEV_PORT") or os.getenv("PORT"))\
if not port_ok: missing.append("AUTOAPPDEV_PORT or PORT")\
if missing:\
  print("Missing env:", ", ".join(missing))\
  sys.exit(1)\
print("OK: env looks set")\
PY'

• ./scripts/run_autoappdev_tmux.sh --help
• ./scripts/run_autoappdev_tmux.sh --backend-port 8790 --pwa-port 5174
• ./scripts/run_autoappdev_tmux.sh --detached
• ./scripts/run_autoappdev_selfdev_tmux.sh --help
• ./scripts/run_autoappdev_selfdev_tmux.sh --start-at 14 --reasoning xhigh

• Parse AAPS via API: POST /api/scripts/parse
• Import annotated shell: POST /api/scripts/import-shell
• Optional LLM parse: POST /api/scripts/parse-llm (requires AUTOAPPDEV_ENABLE_LLM_PARSE=1)

• GET /api/pipeline
• GET /api/pipeline/status
• POST /api/pipeline/start
• POST /api/pipeline/pause
• POST /api/pipeline/resume
• POST /api/pipeline/stop

• Health/version/config: /api/health, /api/version, /api/config
• Plan/scripts: /api/plan, /api/scripts, /api/scripts/<id>
• Actions: /api/actions, /api/actions/<id>, /api/actions/<id>/clone, /api/actions/update-readme
• Messaging: /api/chat, /api/inbox, /api/outbox
• Logs: /api/logs, /api/logs/tail

See docs/api-contracts.md for request/response shapes.

cp .env.example .env
./scripts/setup_autoappdev_env.sh
conda run -n autoappdev python -m backend.apply_schema
./scripts/run_autoappdev_tmux.sh --restart

Validation checkpoints:

• curl -sS http://127.0.0.1:8788/api/health | python3 -m json.tool
• Open http://127.0.0.1:5173/ and confirm the UI can load /api/config.
• Optional: open /api/version and verify expected backend metadata is returned.

conda run -n autoappdev python -m backend.app
curl -sS http://127.0.0.1:8788/api/version
curl -sS http://127.0.0.1:8788/api/pipeline/status | python3 -m json.tool

python3 scripts/pipeline_codegen/generate_runner_from_ir.py \
  --in examples/pipeline_ir_codegen_demo_v0.json \
  --out /tmp/autoappdev_runner.sh

bash -n /tmp/autoappdev_runner.sh
scripts/pipeline_codegen/smoke_codegen.sh
scripts/pipeline_codegen/smoke_placeholders.sh
scripts/pipeline_codegen/smoke_conditional_steps.sh
scripts/pipeline_codegen/smoke_meta_round_v0.sh

Core API groups at a glance:

AUTOAPPDEV_PIPELINE 1

TASK  {"id":"t1","title":"Happy path demo"}
STEP  {"id":"s1","title":"Plan","block":"plan"}
ACTION {"id":"a1","kind":"note","params":{"text":"Read context and outline steps."}}

Full examples:

• examples/pipeline_formatted_script_v1.aaps
• examples/pipeline_ir_v1.json
• examples/pipeline_shell_annotated_v0.sh
• examples/pipeline_ir_codegen_demo_v0.json

python3 scripts/pipeline_codegen/generate_runner_from_ir.py \
  --in examples/pipeline_ir_codegen_demo_v0.json \
  --out /tmp/autoappdev_runner.sh

bash -n /tmp/autoappdev_runner.sh
scripts/pipeline_codegen/smoke_codegen.sh

export AUTOAPPDEV_PIPELINE_SCRIPT=scripts/pipeline_demo.sh
conda run -n autoappdev python -m backend.app

Then use the PWA Start/Pause/Resume/Stop controls and inspect /api/logs.

curl -sS -X POST http://127.0.0.1:8788/api/scripts/import-shell \
  -H 'Content-Type: application/json' \
  -d @- <<'JSON'
{
  "shell_text": "#!/usr/bin/env bash\n# AAPS: AUTOAPPDEV_PIPELINE 1\n# AAPS:\n# AAPS: TASK {\"id\":\"t1\",\"title\":\"Demo\"}\n# AAPS: STEP {\"id\":\"s1\",\"title\":\"Plan\",\"block\":\"plan\"}\n# AAPS: ACTION {\"id\":\"a1\",\"kind\":\"noop\"}\n"
}
JSON

• The backend is Tornado-based and designed for local dev ergonomics (including permissive CORS for localhost split ports).
• Storage is PostgreSQL-first with compatibility behavior in backend/storage.py.
• PWA block keys and script STEP.block values are intentionally aligned (plan, work, debug, fix, summary, commit_push).
• Built-in actions are readonly; clone before editing.
• update_readme action is path-safety constrained to workspace README targets under auto-apps/<workspace>/README.md.
• There are historical path/name references in some docs/scripts (HeyCyan, LightMind) inherited from project evolution. Current repo canonical path is this repository root.
• The root i18n/ directory exists. Language README files are expected there in multilingual runs.

• Runtime defaults to ./runtime unless overridden by AUTOAPPDEV_RUNTIME_DIR.
• Self-dev automation state/history is tracked under references/selfdev/.
• README pipeline artifacts are recorded under .auto-readme-work/<timestamp>/.

• Repository includes smoke checks and deterministic demo scripts.
• A full top-level automated test suite/CI manifest is not currently defined in root metadata.
• Assumption: validation is primarily script-driven for now (scripts/pipeline_codegen/smoke_*.sh, backend.db_smoketest, end-to-end checklist).

• update_readme action is intentionally constrained to workspace README targets (auto-apps/<workspace>/README.md) with path traversal protections.
• Action registry validation enforces normalized action spec fields and bounded values for supported reasoning levels.
• Repository scripts assume trusted local execution; review script bodies before running in shared or production-adjacent environments.
• .env may hold sensitive values (DATABASE_URL, API keys). Keep .env uncommitted and use environment-specific secret management outside local dev.

For a deterministic manual verification path, use docs/end-to-end-demo-checklist.md.

• Root README is the canonical source used by the README automation pipeline.
• Multilingual variants are expected under i18n/.
• i18n directory status: ✅ present in this repository.
• Current language set in this repository:
  • i18n/README.ar.md
  • i18n/README.de.md
  • i18n/README.es.md
  • i18n/README.fr.md
  • i18n/README.ja.md
  • i18n/README.ko.md
  • i18n/README.ru.md
  • i18n/README.vi.md
  • i18n/README.zh-Hans.md
  • i18n/README.zh-Hant.md
• Language navigation should stay as a single line at the top of each README variant (no duplicated language bars).
• README pipeline entrypoint: prompt_tools/auto-readme-pipeline.sh.

• Always process multilingual generation when updating canonical README content.
• Generate/update language files one-by-one (sequentially), not in bulk ambiguous batches.
• Keep exactly one language-options navigation line at the top of each variant.
• Do not duplicate language bars within the same file.
• Preserve canonical command snippets, links, API paths, and badge intent across translations.

Suggested one-by-one generation order:

1. i18n/README.ar.md
2. i18n/README.de.md
3. i18n/README.es.md
4. i18n/README.fr.md
5. i18n/README.ja.md
6. i18n/README.ko.md
7. i18n/README.ru.md
8. i18n/README.vi.md
9. i18n/README.zh-Hans.md
10. i18n/README.zh-Hant.md

Language coverage table:

Observed workspace note:

• i18n/README.zh-Hant.md.tmp may appear as a temporary translation artifact; keep final canonical files as README.<lang>.md.

• Pipeline run timestamp: 20260301_095119
• Trigger: ./README.md first complete draft generation (canonical-base incremental update)
• Input user prompt: Use current README as canonical base. No reduction: only increment and improve. Preserve existing content, links, badges, commands, and details. Always process multilingual generation (do not skip): ensure i18n exists and generate/update language files one-by-one with a single language-options line at the top and no duplicates.
• Goal: generate a complete, beautiful README draft with required sections and support information
• Source snapshot used:
  • ./.auto-readme-work/20260301_095119/pipeline-context.md
  • ./.auto-readme-work/20260301_095119/repo-structure-analysis.md
• This file was generated from repository contents and preserved as a canonical draft entry point.

Preferred and expected for normal operation. The storage layer contains fallback compatibility behavior, but production-like usage should assume PostgreSQL is available via DATABASE_URL.

AUTOAPPDEV_PORT is project-specific. PORT exists as a deployment-friendly alias. Keep them aligned unless you intentionally override behavior in your launch path.

Run backend-only (conda run -n autoappdev python -m backend.app) and use /api/health, /api/version, /api/config, then script/action endpoints listed in docs/api-contracts.md.

Yes. The repository includes prompt_tools/auto-readme-pipeline.sh, and language variants are maintained under i18n/ with one language-navigation line at the top of each variant.

• Complete remaining self-dev tasks beyond current 51 / 55 status.
• Expand workspace/materials/context tooling and stronger safe-path contracts.
• Continue improving action palette UX and editable action workflows.
• Deepen multilingual README/UI support across i18n/ and runtime language switching.
• Strengthen smoke/integration checks and CI coverage (currently script-driven smoke checks are present; no full CI manifest is documented at root).
• Continue hardening parser/import/codegen determinism around AAPS v1 and canonical IR.

Contributions are welcome via issues and pull requests.

Suggested workflow:

1. Fork and create a feature branch.
2. Keep changes focused and reproducible.
3. Prefer deterministic scripts/tests where possible.
4. Update docs when behavior/contracts change (docs/*, API contracts, examples).
5. Open a PR with context, validation steps, and any runtime assumptions.

Repository remotes currently include:

• origin: [email protected]:lachlanchen/AutoAppDev.git
• Additional remotes may be present in local clones for related repositories (example found in this workspace: novel).

Donate	PayPal	Stripe

No root LICENSE file was detected in this repository snapshot.

Assumption note:

• Until a license file is added, treat usage/redistribution terms as unspecified and confirm with the maintainer.