When facts are missing, Sopify stops and asks. When a decision needs your approval, it waits. When work is interrupted, it resumes from the last stopping point — even across different AI hosts.
After install, use ~go to start a managed workflow. See Installation for other targets, platforms, and verification.
Already in a Sopify-managed repo? Open any AI host and continue the unfinished task — it picks up from where you left off. Full walkthrough →
| Step | What happens |
|------|-------------|
| Start | Ask the host to begin or continue a task |
| Pause | Sopify stops when facts are missing or a decision needs you |
| Resume | Work picks up from project state — even on a different host |
Why Sopify?
As repositories grow, AI-assisted development runs into a hidden problem: decision context stays trapped in chat history, each new session re-derives the project state, and the user's mental model, the AI's understanding, and the codebase start to drift apart.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
First-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
Sopify uses project-level conventions to make critical steps visible. The basic process record is generated automatically, but the long-term compounding value still depends on consistently closing out work and maintaining project knowledge.
| Gap | Sopify's answer |
|-----|-----------------|
| State is trapped in a single host's chat session | Portable project state — switch hosts mid-task |
| No independent quality gate | An isolated, independent review pass before execution |
| Decisions are invisible and non-auditable | Plan changes force re-confirmation — the AI cannot silently proceed |
| Each session's learning is disposable | Plans, decisions, and reviews persist as reusable project assets |
Installation
Two-step install (recommended for first-time review):
The protocol works with any host. Verified runtime integrations today:
| Host | Install target | Availability | Validation coverage | Notes |
|------|----------------|--------------|---------------------|-------|
| codex | codex:zh-CN / codex:en-US | Deep verified | Host install flow, workspace bootstrap, and runtime package smoke are verified | Suitable for daily use |
| claude | claude:zh-CN / claude:en-US | Deep verified | Host install flow, workspace bootstrap, and runtime package smoke are verified | Suitable for daily use |
Notes:
Use sopify status / sopify doctor for detailed capability claims and live diagnostics
Availability expresses the current delivery tier, while Validation coverage describes what has already been validated
Installer behavior:
Installs the selected host prompt layer and the Sopify payload
A standard install makes your host ready to run Sopify; most users do not need --workspace
--workspace is an advanced prewarm path for maintainers, CI, or explicit repository setup
After Install
Use ~go when you want Sopify to manage the full task workflow for you.
Interrupt anytime — come back (even in a different tool) and resume from where you left off.
Complex changes can get an independent review before execution starts.
Run status to see current progress, doctor to troubleshoot.
Verify Your Install
python3 scripts/sopify_status.py --format text
python3 scripts/sopify_doctor.py --format text
will bootstrap on first project trigger: the host install is ready and the project-local runtime has not been prepared yet
workspace outcome: stub_selected [continue]: the workspace runtime entry is healthy
Payload or bundle corruption errors (for example global_bundle_missing, global_bundle_incompatible, or global_index_corrupted): repair the install and retry
First Use
After install, open your selected host inside a repository and paste one of the prompts below.
# Simple task
"Fix the typo on line 42 in src/utils.ts"
# Medium task
"Add error handling to login, signup, and password reset"
# Complex task
"~go Add user authentication with JWT"
# Plan only
"~go plan Refactor the database layer"
This is only a placeholder example of the pacing and format, not a fixed output contract; simple tasks are shorter, and complex tasks pause at checkpoints for confirmation.
For the full workflow, checkpoints, and plan lifecycle details, see How Sopify Works.
plan.directory only affects newly created knowledge and plan directories
Command Reference
| Command | Description |
|---------|-------------|
| ~go | Automatically route and run the full workflow |
| ~go plan | Plan only |
| ~go exec | Advanced restore/debug entry, not the default user path |
| ~go finalize | Close out the current metadata-managed plan |
Most users only need ~go and ~go plan; maintainer validation commands live in CONTRIBUTING.md.
This is a simplified view of the core layout. See docs/how-sopify-works.en.md for the full workflow, checkpoints, and knowledge layout.
FAQ
Q: How do I switch language?
Update sopify.config.yaml:
language: zh-CN # or en-US
Q: Where are plan packages stored?
By default they live under .sopify-skills/ in the project root. To change that:
plan:
directory: .my-custom-dir
This only affects newly created directories; existing history is not migrated automatically.
Q: When should I use --workspace prewarm?
Most users do not need it. A default install is already complete; Sopify bootstraps the project-local runtime automatically on the first trigger.
Use --workspace only for maintainer validation, CI, or when you explicitly want to prewarm a specific repository ahead of time. For this advanced path, use the repo-local installer:
Delete or clear .sopify-skills/user/preferences.md; keep feedback.jsonl only if you still want the audit trail.
Q: When should I run sync scripts?
When you change Codex/Skills/{CN,EN}, the mirrored Claude/Skills/{CN,EN} content, or runtime/builtin_skill_packages/*/skill.yaml, follow the validation steps in CONTRIBUTING.md.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
