Sopify: resumable AI coding with plans tracked in .sopify/
Resumable, traceable AI coding — plans, handoffs, and evidence stay with the repo across hosts.
At a glance
- What is it?
- Sopify is a development process protocol layer for AI coding hosts such as Codex and Claude. It stores plans and verification receipts in .sopify/ as git-tracked files, so a workflow can be paused and picked up again across supported hosts.
- Who is it for?
- Adopt Sopify if you already work inside Codex, Claude, Qoder, Copilot or Cursor and you want plans, decisions and verification receipts to live in the repository rather than in chat history. Skip it if you want a new editor or CLI, or if you need a documented rollback path: the README does not document one.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 16 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Sopify actually solves for AI coding sessions
The problem Sopify targets is premature coding. The README describes the failure mode directly: when an AI coding tool jumps to code before the facts are clear, speed turns into rework. Sopify is not a model and not an editor. It is a process protocol layer that sits in front of whichever host you already use.
Who it is for: teams and individuals already running Codex, Claude, Qoder, Copilot or Cursor who keep losing context between sessions, machines or teammates. The README lists three things it prevents. Premature coding, where the AI starts changing code before missing facts or decisions are resolved. Lost context, where switching hosts or teammates forces the work to be re-explained. Forgotten decisions, where tradeoffs disappear into chat history instead of becoming project artifacts.
The intended user is therefore someone who already accepts that an AI assistant will write code in their repository, and who wants a checkpoint between the request and the diff. If you are happy letting the assistant edit files immediately and reviewing the result, Sopify adds a step you did not ask for.
The mechanism: a protocol layer with .sopify/ as the record
The architecture described in the README separates execution from record keeping. The host LLM executes. Sopify supplies shared workflow rules and preserves plans, decisions and verification evidence as project files under `.sopify/`. Local resume pointers stay on the machine and are the only part not tracked by git.
The README states that each adapter delivers the same protocol through the host surfaces it supports, and that entry mode and verification level remain explicit. That qualifier matters more than the marketing line above it: continuation support is a property of the host, not of Sopify in general. The README points to a host support matrix for entry shape and verification level, and states that hosts with continuation support can pick up where you left off. It does not claim every listed host resumes.
A concrete example of the record layout is linked from the README. An archived July 2026 workflow sits at `.sopify/history/2026-07/20260718_evidentloop_optional_audit_integration/`, with a `plan.md`, a `receipts/verify_001.json` and a `receipts/final.json`. The README says the second audit found no open risk and that 5 protocol checks and 55 targeted tests with 48 subtests were recorded before archive. Those numbers come from the project's own write-up of that run, not from an independent measurement.
The README also describes live plan storage at `.sopify/plan/`. So the layout has at least two zones: an active plan area and a history area for archived work with its receipts.
Installing Sopify via install.sh and starting a first ~go workflow
The Quick Start gives a single command. It targets one host at a time, and the README states the installer checks for Python 3.11 or newer before downloading. The command installs Sopify only.
curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target codex:en-USAfter a successful install, the README says to use `~go` to start a managed workflow. That is the entry point for a new managed session in the host you targeted.
~goIf you are already inside a Sopify-managed repository, the README gives a specific instruction: explicitly ask to continue, or use `~go` to resume the current plan. It also states that ordinary questions and small fixes are handled directly, without automatically re-entering the previous plan workflow. That is a deliberate design choice, and it means `~go` is the deliberate act of resuming rather than a default behaviour.
The same install command accepts an optional flag. Appending `--with-evidentloop` installs EvidentLoop alongside Sopify; the README links to the Installation section for details.
curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target codex:en-US --with-evidentloopTwo other entry points exist in the repository root: `install.ps1` for Windows and `bootstrap.sh`. The README says the Installation section covers other hosts, Windows, and how to review the installer before running it. Piping a remote script into a shell is the kind of step worth reading before you run it, and the project at least points at that review path. There is also an example configuration file at `examples/sopify.config.yaml` and an example directory at `examples/external-repo-quickstart/`.
Cross-host resume and the limits of the host support matrix
The README's headline scenario: you start a feature in Codex, finish the design, implement two of four tasks. Next week a teammate opens the same repo in Claude and types `~go`. Sopify reads the checkpoint and continues from task 3.
That scenario depends on git-tracked state, which is the strongest part of the design. Plans and receipts are project files, so they travel with a clone. A teammate does not need a handoff document because the plan is already in the tree. The local resume pointers stay out of git, which is consistent: machine-specific paths should not be committed.
The limitation is the phrase the README keeps repeating. Continuation is available on hosts with continuation support, and entry mode and verification level remain explicit per host. Read that as: the cross-host story is real where the matrix says it is real, and the matrix is the document that decides. A reader who assumes every badge in the header behaves identically will be disappointed, and the README does not let you make that assumption in good faith.
The second limitation is verification depth. The README says the protocol checks and test counts recorded in the archived example were recorded for that task. Sopify records evidence; it does not decide what evidence is sufficient for your project. If your definition of done is a specific CI job, the receipt format is something you have to reconcile with it.
Where Sopify is the wrong tool
Sopify is a poor fit for throwaway work. A one-line fix, a scratch script, a quick experiment: the README itself says ordinary questions and small fixes are handled directly rather than entering the plan workflow, which acknowledges that the managed path has a cost. If most of your sessions look like that, you are installing a protocol layer you will rarely invoke.
It is also the wrong tool if you want a new interface. The README is explicit that there is no new editor and no new CLI, and that you install into the host you already use. Anyone hoping Sopify replaces their coding environment is looking at the wrong project.
The third case is the one the README does not address. There is no documented rollback or uninstall path in the README. If your team needs a written removal procedure before adopting a tool that writes into your repository, that procedure is not documented here. The `.sopify/` directory is plain files under git, so removal is at least inspectable, but inspectable is not the same as documented.
Finally, the repository is not archived, but the last push was on 2026-08-30. That is recent enough that the project is not dormant, and the release list shows three releases in roughly six weeks, ending with 2026-08-30.001152. Still, a protocol that other tools must adopt is only as useful as its host coverage, and coverage is the thing to check against your own host before committing.
How Sopify differs from a plain AGENTS.md or CLAUDE.md file
The obvious alternative is a static instruction file in the repository root, the kind hosts like Codex and Claude already read. The difference in approach is state versus instructions.
A static instruction file describes how you want the assistant to behave. It has no notion of a current task, no checkpoint, and no record of what was decided last week. Its content is the same on day one and day thirty unless a human edits it.
Sopify keeps a mutable record instead. `.sopify/plan/` holds the active plan; `.sopify/history/` holds archived work with receipts. Resuming means reading that state and continuing from a specific task index, which is what the README's task 3 example describes. The instruction file tells the assistant what rules to follow; Sopify tells it where the work currently stands.
The trade-off is weight. A markdown file costs nothing to add and nothing to maintain. Sopify adds a directory, a protocol, an installer and a per-host support matrix that you have to consult. If your assistant sessions are short and self-contained, the static file gets you most of the way. If they routinely span days, machines or people, the static file is exactly the thing that fails, because nothing in it remembers that you finished task 2.
Licence, releases and upgrade cost
Sopify is Apache-2.0, and the repository carries a separate `LICENSE-docs` file. The README badges the docs under CC BY 4.0. That split is worth noticing: code and documentation are licensed differently, so if you plan to reuse the docs in your own material, check `LICENSE-docs` rather than assuming the Apache-2.0 terms cover everything in the tree. This is not legal advice; read both files.
On upgrades, the release naming is date-based: 2026-07-21, 2026-08-22.134737, 2026-08-30.001152. The Quick Start pins nothing. It downloads `releases/latest/download/install.sh`, so re-running the install command pulls the newest installer, and the version badge in the README moves with it. There is no documented version pinning flag in the README, and no documented upgrade or downgrade procedure. A team that needs reproducible tool versions across machines should treat that as an open question to resolve before rollout.
The recurring cost is not the install. It is the record. Every managed workflow leaves files under `.sopify/`, and those files are committed. Over months, `.sopify/history/` becomes part of your repository's size and review surface. The archived example includes JSON receipts and a plan, which is small, but nothing in the README describes a retention or pruning policy. If your team is sensitive to repository growth, decide on a policy before the history directory gets large.
Editorial conclusion
Adopt Sopify if you already work inside Codex, Claude, Qoder, Copilot or Cursor and you want plans, decisions and verification receipts to live in the repository rather than in chat history. Skip it if you want a new editor or CLI, or if you need a documented rollback path: the README does not document one. Before installing, read install.sh in the repository, confirm your Python is 3.11 or newer, and check the host support matrix for the verification level your host actually provides.
Frequently asked questions
Does Sopify work with Claude and Codex, or only one host?
The README lists Codex, Claude, Qoder, Copilot and Cursor as hosts, and the install command takes a --target flag such as codex:en-US. Entry mode and verification level stay explicit in a host support matrix, so behaviour differs by host.
What Python version does Sopify require?
The README states Sopify requires Python 3.11 or newer, and that the installer checks the version before downloading.
How do I resume a Sopify plan after switching machines?
The README says plans and verification receipts are tracked in .sopify/, while only local resume pointers stay out of git. In a Sopify-managed repo, explicitly ask to continue or use ~go to resume the current plan on a host with continuation support.
Community notes