mosa

# MOSA MOSA is a local-first creative memory library for Codex and Cowart. It keeps reusable visuals together with their complete prompts, generation context, and provenance, then makes them searchable, editable, and reusable in one local Web app. > **Every visual, in context.** > Codex images and Cowart canvas images are both monitored locally and remain traceable. **OpenAI Build Week demo:** [Watch the 2:21 English walkthrough on YouTube](https://youtu.be/RdRtq4xfqhI). ## Built with Codex and GPT-5.6 MOSA was built through iterative Codex sessions using GPT-5.6-terra. GPT-5.6 shaped the local-first product boundary, provenance model, end-to-end demo path, and successive interface and reliability refinements. Codex then turned those decisions into the Node service, MCP tools, web interface, Codex image archiver, and Cowart bridge; it also ran focused tests and verification passes that informed follow-up fixes. The Build Week implementation history is visible in the repository's dated commits: Codex image provenance, the MCP workflow, Cowart synchronization, source-aware metadata, hard-link archival, and UI refinements were developed as separate, reviewable changes. A real Codex image-generation run was used to verify that MOSA preserves the generated image, complete prompt, task context, `imagegen` tool attribution, and `gpt-5.6-terra` model metadata. The resulting product closes the loop for visual work: create in Codex or Cowart, preserve the image with its prompt and provenance, find it again in MOSA, and reuse it on the Cowart canvas without duplicating its record. ## Build Week setup and judging guide MOSA is a local-first developer tool. The complete library can be evaluated from the tracked sample records without an OpenAI account, Codex image credits, Cowart, or access to the author's local files. ### Supported platform - Tested platform: macOS with Node.js and npm. - The core Node.js service and browser UI use standard filesystem and HTTP APIs, but Windows and Linux have not been verified for this submission. - Codex automatic archiving requires Codex Desktop and access to its standard local `~/.codex/generated_images/` and session directories. - Cowart automatic archiving is optional and requires the separately installed Cowart plugin plus a configured local canvas directory. ### Install and run ```bash git clone https://github.com/fengseekling-coder/mosa.git cd mosa npm ci npm test npm start ``` Open <http://127.0.0.1:43517>. The repository includes sample records, so the gallery, search, filters, asset detail view, prompt provenance, and source metadata can be inspected immediately. No build step, test account, API key, or external database is required. ### MOSA 2.0 Core migration (SQLite + derivatives) MOSA leaves the current JSON library untouched until a verified migration succeeds. The production library is independent from this Git checkout and defaults to `~/MOSA Library`; it contains `mosa.db`, immutable originals, generated WebP previews and thumbnails, plus a read-only JSON backup from the migration. ```bash # Inspect the legacy JSON library without writing anything. npm exec mosa -- migrate --dry-run # Migrate into ~/MOSA Library and verify every imported original by SHA-256. npm exec mosa -- migrate npm exec mosa -- verify # Rebuild or repair resumable preview and thumbnail jobs. npm exec mosa -- thumbnails rebuild ``` Use `--library /absolute/path/to/library` to choose another location. Corrupt JSON, corrupt collection data, missing originals, or hash mismatches leave SQLite inactive and report the exact paths. Empty collections are preserved. After a successful migration, `npm start` automatically selects the completed SQLite library; use `MOSA_LIBRARY_DIR` only when choosing a non-default location. SQLite adds FTS5 search and cursor pagination (`limit` up to 250) without changing existing REST fields or MCP v1 tool names. The gallery requests 100 thumbnails at a time, the inspector uses a 1600px preview when ready, and `/library/<project>/images/<file>` still serves the original asset. The UI follows the system language by default. To inspect the English interface, open **Settings → Language → English** after starting MOSA. For a quick bridge health check while the service is running: ```bash curl -sS http://127.0.0.1:43517/api/codex-bridge curl -sS http://127.0.0.1:43517/api/cowart-bridge ``` The optional integrations become active when their local source directories are available. They are not required to inspect or test the tracked Build Week sample data. ### What judges can verify 1. Browse and search the included visual records in the Web app. 2. Open an asset to inspect its full prompt, source type, Codex task ID, original path, dimensions, and provenance status. 3. Run `npm test` to verify JSON compatibility, SQLite migration, derivative jobs, route behavior, accessibility contracts, Codex reconciliation, and Cowart deduplication. Run `npm run test:performance` separately for the 50,000-asset benchmark. 4. Review the dated Git history and the `Built with Codex and GPT-5.6` section above for the Build Week implementation record. ## Technical documentation ### Connect Codex MCP Register MCP in the terminal. Replace the path with your absolute path: ```bash codex mcp add mosa \ --env MOSA_PROJECT_DIR=/absolute/path/to/your/workspace \ -- node /absolute/path/to/mosa/mcp/server.mjs ``` After registration, open a new Codex task to load the MCP tool. The image generation should call `asset_create` and pass the actual `imagePath` returned by the image tool; the same call can also pass the complete `prompt`, `generation_tool`, `model`, and `codex_session_id`. `asset_create` will copy the file to the library and save: - The original image path and Codex task directory ID; - The complete Prompt and recipe fields; - `generation_tool`, `model`, `codex_session_id`, and other available generation contexts; - A library copy to prevent loss of assets due to changes in the Codex temporary runtime directory. The default allowed source directory for Codex is: ```text ~/.codex/generated_images/<task-id>/<image>.png ``` The service will verify the directory at startup and continuously monitor new images. For each image, the bridge will match the output file path with the `image_generation_end.revised_prompt` in the local Codex session and save the actual prompt executed by the image tool; if the record is not available, it will fallback to the task user instruction and explicitly mark the status. When the Codex image and MOSA library directories are on the same filesystem, MOSA uses hard links, so the two paths are available but the disk only occupies one copy of the image data; when they are across disks, it automatically degrades to a copy. When manually saving through `asset_create`, you can supplement the complete model, recipe, and revised prompt. Existing copied Codex assets can be safely migrated: the script will first verify the hash consistency of both ends and then atomically replace it with a hard link, without deleting the Codex original path. ```bash node scripts/migrate-codex-hardlinks.mjs ``` ### Cowart automatic archiving After starting the library manager, the built-in bridge will continuously monitor the MOSA-specific canvas: ```text ~/.codex/cowart-data/mosa/pages/ ``` After Cowart saves the canvas, the newly generated images, AI image replacement results, and annotation editing results will be automatically archived. The bridge will deduplicate based on the page asset path in the Cowart canvas snapshot; images inserted back into the canvas from the library will carry the source ID, and the bridge will skip it to avoid duplicate archiving. When opening the Cowart canvas of other projects, MOSA will automatically identify the project root directory from the local Codex task record `render_cowart_canvas_widget` or Cowart local startup call, verify that the project indeed exists a Cowart canvas marker, and then immediately monitor `<project>/canvas/`. Each project still maintains its own canvas; the automatic discovery list is saved in `~/.codex/mosa/cowart-projects.json` and will take effect after the service restarts. This process is based on real startup events and will not scan any project directory on the machine. The Cowart snapshot only provides canvas description (alt text) and does not save the complete generation prompt. Therefore, the assets automatically archived from Cowart will be explicitly marked as `canvas-alt-text-only`; if you need a complete prompt, you can supplement it on the details page or record it from the original generation task. Common Codex workflow: - **“Start MOSA”**: Run the local library and open the Web App. - **“Start canvas”**: Open the native Codex canvas of Cowart. - **“Insert current asset into canvas”**: Read the asset through `asset_get`, insert it into Cowart, and carry the MOSA source ID to prevent duplication. The asset details page also provides the **“Insert into Cowart”** button. MOSA will call the `insert_cowart_image` tool of the Cowart plugin installed on the local machine, put the asset into the current Cowart page, and write `mosaAssetId` to prevent the bridge from archiving the same asset again. The button requires the Cowart plugin to be installed and the target canvas to have been saved at least once; if the plugin is not available, the button will be explicitly disabled. Cowart is an external Codex plugin, and its running data is intentionally saved outside the repository and will not be copied or submitted into this project. After installing or upgrading Cowart, please open a new Codex task to load its MCP tool. #### Configure MOSA-specific canvas By default, the MOSA-specific canvas directory name is `mosa`. If you want to use another external directory for this specific canvas, please explicitly specify it when starting the service: ```bash COWART_MOSA_CANVAS_DIR=/absolute/path/to/cowart-data/my-project npm start ``` This environment variable only changes the MOSA-specific canvas. Other project canvases will be automatically discovered after Cowart is actually opened. ### Quick end-to-end verification 1. Run `npm start` and open the Web App. 2. Open any Codex task (no need to associate with MOSA project). 3. Generate an image; wait up to 3 seconds in the Web and confirm that a new asset with **Codex** source, task ID, original path, and prompt status appears. 4. Open the Cowart canvas of any project, generate, replace, or annotate and edit an image and save it; MOSA will automatically discover and monitor this project canvas. 5. Wait up to 2 seconds and go back to the Web to view the new asset with **Cowart** source mark; you can also visit `/api/cowart-bridge` to view the synchronization status. 6. Insert a library asset back into the canvas and confirm that the asset count does not increase due to the same file again. ## Changelog Build Week release notes are in [CHANGELOG.md](CHANGELOG.md). ### Configurable Items | Environment Variable | Default Value | Purpose | | --- | --- | --- | | `MOSA_PROJECT_DIR` | Parent directory of MOSA | Workspace root directory, used to determine project context | | `MOSA_PORT` | `43517` | Local port for Web service | | `MOSA_LIBRARY_DIR` | `~/MOSA Library` | Root directory of migrated SQLite asset library; falls back to JSON if not migrated | | `CODEX_GENERATED_IMAGES_DIR` | `~/.codex/generated_images` | Root directory of Codex image sources that `asset_create` can read | | `CODEX_SESSIONS_DIR` | `~/.codex/sessions` | Root directory for session records used to read corresponding Codex task prompts | | `COWART_MOSA_CANVAS_DIR` | `~/.codex/cowart-data/mosa` | MOSA-specific Cowart canvas data directory | | `MOSA_COWART_REGISTRY_PATH` | `~/.codex/mosa/cowart-projects.json` | List of automatically discovered project canvases; only listens to `<project>/canvas/` | | `COWART_MCP_SERVER_PATH` | `~/plugins/cowart/mcp/server.mjs` | Optional Cowart MCP service entry for one-click insertion in Web | ### Local Data Structure ```text mosa/ ├── assets/ │ └── default/ │ ├── images/ # Asset library image copies │ ├── prompts/ # Editable Prompt text │ └── metadata/ # JSON metadata and source information ├── app/ # Local Web UI ├── lib/ # Asset storage and Cowart bridge └── mcp/ # Codex MCP service ``` After completing the migration, personal assets are located outside the repository: ```text ~/MOSA Library/ ├── mosa.db # SQLite runtime authoritative data ├── assets/<project>/ │ ├── original/ # Unmodified original images │ ├── previews/ # WebP previews with longest side 1600px │ └── thumbnails/ # WebP thumbnails with longest side 400px └── legacy-json-backup/ # JSON/Prompt backups saved during migration ``` Cowart runtime data is not in the repository: ```text ~/.codex/cowart-data/mosa/ # MOSA-specific canvas ~/.codex/mosa/cowart-projects.json # Automatically discovered project root directory ``` #### Git and Local Assets Runtime images, Prompts, and metadata for the asset library are saved locally under `assets/<project>/`, but new archive records are ignored by `.gitignore` by default to avoid polluting the workspace with every generated image from Codex or Cowart. Assets tracked in the repository are only used as demonstration samples; if you want to submit a new asset as an official sample, make sure it does not contain sensitive content and then explicitly run: ```bash git add -f assets/default/images/<asset>.png \ assets/default/prompts/<asset>.md \ assets/default/metadata/<asset>.json ``` The local HTTP service only accepts same-origin browser requests and should not be exposed through remote web pages, reverse proxies, or public ports. ### MCP Tools - `asset_create` - `asset_list` - `asset_get` - `asset_update_metadata` - `asset_attach_prompt` - `asset_archive` - `asset_duplicate` You can run the MCP service directly in the repository parent directory for local debugging: ```bash cd /absolute/path/to/your/workspace node mosa/mcp/server.mjs ``` ### Current Boundaries - Unmigrated data is saved as local JSON files; after verification, SQLite is the only runtime metadata authority. JSON is only retained for compatibility fallback and migration backup, without dual writing. - Codex image archiving automatically listens to the standard generation directory when the asset manager service is running; MCP `asset_create` can be used to explicitly save and supplement generated metadata. - Cowart automatic archiving relies on the asset manager service running and only covers MOSA-specific canvases and project canvases discovered from real Cowart startup events. - Cowart automatic archiving retains canvas descriptions but does not have complete Prompts; original Prompts need to be supplemented from generated tasks. - "Re-generation with the same recipe" currently copies Codex instructions without directly calling the image model. ### Build Week Demonstration List 1. Show a real Codex `image_generation_end` record and the listener automatically archives complete Prompts and sources without needing to click Import. 2. Show that generated or edited images in Cowart appear in the asset library without additional入库 instructions. 3. Search for assets in the Web interface, open the details page to show Prompts, recipes, and sources. 4. Insert library assets into Cowart, showing deduplication protection and reusability. 5. Submit evidence: the commit records from 2026-07-17 to 2026-07-19 in this repository can track the incremental build of Codex/GPT-5.6; the GitHub project description and this section explain the closed loop. 6. `/feedback` has been executed in the main build Codex task, and the returned Session ID is recorded in the submission materials. ## License MOSA is available under the [MIT License](LICENSE).