patch.moi/docs/pages/index.md

title	description
patch.moi	Git-first maintenance for custom patches on top of upstream open source software.

patch.moi

patch.moi watches upstream projects and keeps the operational record for maintained forks. It does not replace Git, CI, or release tooling. It records what upstream did, starts or resumes the right maintenance work, and preserves enough state to inspect, retry, replay, and review the result.

The patch stack remains ordinary Git:

• upstream movement comes from feeds, remotes, tags, branches, and commits
• maintained forks live in fork repositories and patch branches
• patch commits stay in the maintained repository
• candidate outputs are branches, tags, pull requests, checks, or artifacts
• internal build and public release channels consume candidate refs separately

flowchart LR
  Upstream["upstream feed or ref"] --> Patch["patch.moi intake"]
  Patch --> Event["durable update event"]
  Event --> Attempt["maintenance attempt"]
  Attempt --> Workspace["local workspace or forge runner"]
  Git["upstream and fork Git refs"] --> Workspace
  Workspace --> Candidate["candidate ref or artifact"]
  Candidate --> Internal["internal channel"]
  Candidate --> Public["public release"]

Ownership

patch.moi owns product state around the patch stack:

• feed cursors and normalized update signals
• deterministic flow events
• workspace dispatch, retry, and replay records
• maintenance attempts, candidate refs, outcomes, and intervention state
• admin inspection APIs for that state

Execution surfaces own the work itself:

• codex-flow packages match events and run portable Bun or Code Mode steps
• Codex workspace backends provide app-server, delegation, and flow transport
• local workspaces and forge runners fetch, rebase, verify, and push candidates
• release channels publish or deploy after review and policy gates

.codex/workspace.toml is repo-native operator automation. In this repo it exposes the harness fixture through codex-flows workspace doctor|tick|run. That state lives under .codex/workspace/<mode> and does not replace patch.moi-owned DATA_DIR records.

Fastest Path

Install and run the checks:

bun install
bun run check

Run the harness directly:

CODEX_FLOW_FETCH=0 CODEX_FLOW_PUSH=0 bun run harness:flow

Run the same harness through the patch.moi CLI and record DATA_DIR state:

CODEX_FLOW_FETCH=0 CODEX_FLOW_PUSH=0 bun run patch.moi -- run harness
bun run patch.moi -- status

Run the same harness through repo-native workspace autonomy:

bun run workspace:doctor
CODEX_FLOW_FETCH=0 CODEX_FLOW_PUSH=0 bun run workspace:run:harness

Run the manual workspace-owned flow smoke task only when a Codex workspace backend is running:

CODEX_WORKSPACE_BACKEND_WS_URL=ws://127.0.0.1:3586 \
CODEX_FLOW_FETCH=0 CODEX_FLOW_PUSH=0 \
bun run workspace:run:harness-flow

Start the Patch service when you want feed intake and admin state:

DATA_DIR=./data FEED_SOURCES_PATH=./feed-sources.json bun run --filter @peezy.tech/patch dev

Read Next

• First harness run: Run the harness maintenance flow.
• Feed intake: Watch an upstream release.
• CLI operations: CLI.
• System model: Architecture.
• Durable state: JSONL state.
• Retry and replay: Flow event retry and replay.
• Codex-specific model: Codex fork model.
• Service runner shape: Forge service mode.

Repository Layout

• apps/patch: Patch service, feed poller, JSONL store, admin API, Discord output, and workspace backend adapter.
• flows/patch-moi-harness: executable maintenance flow for the harness repos.
• .codex/flows: installed external flow capabilities, currently the Codex release maintenance flows from the neighboring ../codex-flows pack.
• harness: upstream and maintained fork repositories used for rehearsal.
• .codex/workspace.toml: optional repo-native workspace automation config.
• docs: this Tome documentation site.