Skip to content

openlogos sync

Bring every OpenLogos-managed file in the project up to date with the installed CLI and the current logos/logos.config.json. Run it after upgrading the CLI, after editing the config, or after changing the AI tool.

Terminal window
openlogos sync

No arguments or options. Must be run from the project root (where logos/logos.config.json exists).

AreaWhat sync does
Guard scripts and post-check engineRewrites the managed guard assets from the bytes bundled with the CLI: .claude/openlogos/bin/guard-check and guard-post-check.cjs for Claude Code, .cursor/hooks/openlogos-runtime.cjs and openlogos-guard-post.cjs for Cursor, plus the hook runtimes inside the ZCode / Qoder / WorkBuddy plugins
Claude Code hooksMerges SessionStart, PreToolUse, PostToolUse, PostToolUseFailure, and Stop into .claude/settings.json; older OpenLogos hook entries are migrated in place, other hooks are untouched
Reply languageSets the top-level language in .claude/settings.json from the project locale ("english" / "chinese"); a custom value you set is kept and reported
SkillsRe-deploys Skills to every configured host target (see table below)
Host pluginsRe-deploys OpenCode, Codex, Cursor, ZCode, Qoder, and WorkBuddy assets for every configured tool
.gitignore managed blockRe-renders the # >>> openlogos managed >>> block from guard.unversioned (always including logos/.openlogos-runtime/); content outside the block is untouched
.gitattributes managed blockKeeps line endings byte-stable for logos/** and managed hook files; files already converted to CRLF are restored from the git index and reported
Instruction filesRegenerates the OpenLogos managed block in AGENTS.md and CLAUDE.md for the current locale, tools, and lifecycle
SpecsCopies the bundled methodology specs to logos/spec/
Project dataSyncs the project name into logos-project.yaml, backfills missing scenarios[].module fields, adds missing resource_index entries, and backfills documents.changes, sourceRoots, and verify.pre_run_command in logos.config.json

On success it writes logos/.openlogos-sync.json, recording which bundled asset manifest the project is synced to.

aiTool may be a single value, an array, or all. sync expands it and refreshes every concrete target:

ToolSkills targetOther assets
Claude Codelogos/skills/.claude/commands/openlogos/, .claude/agents/, .claude/openlogos/bin/, .claude/settings.json
OpenCodelogos/skills/.opencode/plugins/openlogos.js, .opencode/commands/, opencode.json
Codex.agents/plugins/openlogos/skills/.agents/plugins/openlogos/, .agents/plugins/marketplace.json, .codex/config.toml
Cursor.cursor/skills/.cursor/agents/, .cursor/hooks.json (managed entries only), .cursor/hooks/
ZCode.zcode/plugins/openlogos/skills/.zcode/plugins/openlogos/
Qoder.qoder/plugins/openlogos/skills/.qoder/plugins/openlogos/
WorkBuddy.workbuddy/plugins/openlogos/skills/.workbuddy/plugins/openlogos/
Otherlogos/skills/none

When more than one tool is configured, AGENTS.md and CLAUDE.md are generated with multi-tool Skill paths so that their Active Skills section matches what was deployed.

Notes per host:

  • Codex: Skills are rewritten with the YAML frontmatter Codex requires (name, description). Only the openlogos entry in .agents/plugins/marketplace.json is touched. Codex may still ask for a one-time /hooks review of .agents/plugins/openlogos/hooks/session-start.sh.
  • Cursor: sync adds any missing managed hook entry (for example afterShellExecution on projects created before it existed). Running it again produces no diff.
  • ZCode / Qoder / WorkBuddy: the plugin directory is replaced in one step and rolled back on failure. Files you added inside the plugin directory are kept. Start a new host session to load the refreshed plugin.

If the project was set up with an older OpenLogos version, sync also performs these one-time migrations. You do not need to run anything else.

  • Cursor rules → Skills: OpenLogos-managed rule files under .cursor/rules/ (one <skill>.mdc per OpenLogos Skill plus openlogos-policy.mdc) are migrated to .cursor/skills/<name>/SKILL.md. Only those exact file names are removed, and only after the new Skills and hook entries are written successfully. Your own files in .cursor/rules/ are never touched. The CLI lists what was removed and what was kept.
  • Old guard → current guard: guard scripts and hook registrations from the old guard are replaced, and the post-check hooks (PostToolUse / PostToolUseFailure / Stop for Claude Code, afterShellExecution for Cursor) are added.
  • Project lifecycle: an old project-level lifecycle: "active" is migrated to a per-module launched lifecycle.

Run this after upgrading in each existing project. See Upgrading from 0.13.x for the full upgrade steps.

Syncing project files... (openlogos v0.16.0)
✓ logos-project.yaml resource_index is already up to date
✓ AGENTS.md updated
✓ CLAUDE.md updated
✓ <n> skills synced to logos/skills/
✓ Claude Code plugin synced: <n> commands, <n> agents → .claude/
✓ <n> specs synced to logos/spec/
✓ .gitignore OpenLogos managed block updated
Sync complete.

The exact lines depend on the configured tools and on what actually changed. Lines such as scenario(s) backfilled with module field appear only when there is something to backfill.

  • After upgrading the openlogos CLI, once in every existing project
  • After editing logos/logos.config.json (name, locale, AI tool, guard.unversioned)
  • When switching AI tools mid-project, or after changing aiTool to an array or all
  • After running openlogos launch if you need to force-regenerate files
ErrorCauseFix
logos/logos.config.json not foundNot in project root, or project not initializedcd to the project root, or run openlogos init first
未知的 AI Adapter id:<value>aiTool in the config contains an unsupported valueFix aiTool to one of claude-code, opencode, codex, cursor, zcode, qoder, workbuddy, other, all; nothing was written
baseline_commit_in_progressA baseline-seed commit is in progress for a moduleWait for it to finish and rerun openlogos sync; nothing was written
Sync partially completed: .gitignore managed block was not updated. (exit code 1)The .gitignore managed block is corrupted, or guard.unversioned has an invalid entryFix the markers or the entry as the message says and rerun; everything else was synced
Bundled guard post-check engine missingThe installed package is incompleteReinstall openlogos, then rerun openlogos sync
  • init: First-time project setup, or adding a target tool with --ai-tool
  • launch: Activate change management (also regenerates files internally)
  • ignore / exempt: Change the entries rendered into the .gitignore managed block