VibeLign Manual

This manual explains how to use VibeLign before, during, and after AI-assisted edits.

The primary CLI command is vib. The legacy vibelign command is also supported as a backward-compatible wrapper.

1. What VibeLign is for

VibeLign is a safety layer for AI coding workflows.

It does not replace your AI tool. It helps you keep the project stable while using tools like:

Claude Code
OpenCode
Cursor
Antigravity
general GPT-based coding workflows

The core idea is simple:

Let AI generate code, but do not let it freely destroy project structure. And always make it easy to save and undo.

2. The safest workflow

New project or first time using VibeLign

vib start

프로젝트에 필요한 모든 파일 생성, 훅 설정, 상태 점검을 한 번에 처리합니다.

Reinstall VibeLign after source changes

vib init

VibeLign 소스를 수정한 후 재설치할 때 사용합니다.

Ongoing workflow

Use this loop whenever you ask AI to change code:

vib checkpoint "before your task"
vib doctor --strict
vib anchor
vib patch "your request here"
# ask AI using the generated patch request
vib explain --write-report
vib guard --strict --write-report

# if all good:
vib checkpoint "done: your task"

# if something broke:
vib undo

3. Command reference

VibeLign policy card

This card explains the rules that keep AI edits safe and predictable.

Policy	What it means
Request decomposition	AI should split each request into `intent / source / destination / behavior_constraint`.
Narrow scope first	Prefer one file, one anchor, one clear change. Do not let AI spread edits across unrelated code.
No out-of-bound edits	Only `target_file` and `target_anchor` are allowed. Everything else stays untouched.
Move/delete preservation	If `delete` and `move` are both present, treat it as move + preservation unless the user explicitly wants removal.
Source/destination by role	Resolve source and destination independently based on their roles.
Strict patch + guard	Build safe patch plans, then verify and checkpoint after applying.
Contract changes require tests/docs	If patch contract or CodeSpeak shape changes, update tests and docs together.
Protected files stay protected	Respect `protect`-ed files and other sensitive files like `.env` or config files.

See also: AGENTS.md, README.md VibeLign patch rules, PROJECT_CONTEXT.md, AI_DEV_SYSTEM_SINGLE_FILE.md, VIBELIGN_PATCH_REQUEST.md, VIBELIGN_GUARD.md.

`vib init`

VibeLign 소스를 수정한 후 재설치할 때 사용합니다.

vib init
vib init --force

What it does:

Python 버전, pip, uv 환경을 확인합니다
로컬 소스가 감지되면 네트워크 없이 직접 복사해 재설치합니다
로컬 소스가 없으면 uv 또는 pip으로 최신 버전을 재설치합니다

Use vib init after modifying VibeLign source code or when you need to reinstall.

`vib start`

프로젝트에서 VibeLign을 처음 쓸 때 가장 먼저 실행하는 명령어예요. 쉽게 말하면 “AI한테 코딩 맡기기 전에 안전장치부터 켜는 준비 버튼”이에요.

vib start

What it does:

AGENTS.md, AI_DEV_SYSTEM_SINGLE_FILE.md 같은 필요한 파일을 자동으로 만들어줘요 (이미 있으면 최대한 유지해요)
.vibelign/ 폴더와 config.yaml, state.json, project_map.json을 준비해줘요
.gitignore에 VibeLign 관련 항목을 넣어 로컬 파일이 Git에 덜 섞이게 해줘요
AI 도구 설정 파일도 준비해줘요 (Claude Code, Cursor 등)
Git 저장소라면 커밋 전에 비밀정보를 검사하는 보호도 자동으로 연결해줘요 (vib secrets --staged + vib guard --strict)
마지막에는 지금 프로젝트가 얼마나 준비됐는지 점검해서 다음에 뭘 하면 되는지도 알려줘요

자주 쓰는 플래그:

vib start --all-tools
vib start --tools claude,cursor
vib start --quickstart
vib start --force

--all-tools = Claude, Antigravity, OpenCode, Cursor, Codex를 한 번에 준비
--tools = 원하는 도구만 골라서 준비
--quickstart = start 뒤에 vib anchor --auto까지 바로 실행
--force = 기존 설정도 다시 생성

초보자 기준으로는 새 프로젝트든 기존 프로젝트든, AI 작업 시작 전에 vib start 한 번만 하면 된다고 생각하면 쉬워요. 참고로 vib start는 프로젝트 준비용이고, vib init은 VibeLign 자체를 다시 설치할 때 쓰는 명령어예요. When Cursor is included, vib start also creates or updates .cursor/mcp.json and appends the vibelign MCP server without overwriting other configured servers.

Typical Cursor layout after setup:

your-project/
  .cursor/
    mcp.json
  .cursorrules
  vibelign_exports/
    cursor/
      RULES.md
      SETUP.md
      PROMPT_TEMPLATE.md

.cursor/mcp.json — runtime MCP registration used by Cursor
.cursorrules — project rules file read by Cursor
vibelign_exports/cursor/ — generated reference templates and setup guides

`vib checkpoint`

Saves the current project state as a restore point (uses Git under the hood).

vib checkpoint "before login feature"
vib checkpoint "added signup validation"
vib checkpoint

If no message is given, a timestamp is used automatically.
Shows a list of changed files before saving.
Displays the total number of checkpoints saved.

Think of it as a game save point for your code.

`vib undo`

Restores the project to the last checkpoint.

vib undo
vib undo --list

Behavior:

If there are unsaved changes → restores to the last commit (like pressing “undo” in a game)
If the working tree is already clean → rolls back to the previous checkpoint commit
--list → shows the list of available checkpoints to choose from

Use this when AI broke something and you want to go back.

`vib history`

Shows all saved checkpoints.

vib history

Displays:

checkpoint number
when it was saved (e.g. “2 hours ago”)
the message you gave it

Also shows:

total checkpoint count
most recent save time
reminder of how to undo or save a new checkpoint

`vib docs-build`

문서 다이어그램이나 요약이 이상할 때 다시 만드는 명령어예요. 쉽게 말하면 “문서용 캐시를 다시 만들기” 버튼 같은 거예요.

vib docs-build
vib docs-build PROJECT_CONTEXT.md
vib docs-build docs/wiki/index.md

어떨 때 쓰면 되나요?

Docs Viewer에서 다이어그램이 예전 내용처럼 보일 때
문서를 방금 수정했는데 오른쪽 요약이 안 바뀔 때
특정 문서만 다시 만들고 싶을 때

What it does:

markdown 문서를 다시 읽어요
그 문서의 요약/다이어그램용 docs_visual 파일을 다시 만들어요
다음에 Docs Viewer가 열릴 때 새 결과를 읽을 수 있게 해줘요

정리하면:

vib docs-build = 전체 문서를 다시 만들기
vib docs-build 파일경로 = 그 문서 하나만 다시 만들기

`vib docs-index`

Docs Viewer가 어떤 문서를 보여줄지 목록을 만드는 명령어예요. 쉽게 말하면 “문서 리스트와 약속(schema) 확인용 명령어” 예요.

vib docs-index
vib docs-index /path/to/project
vib docs-index --visual-contract

What it does:

프로젝트 안의 markdown 문서 목록을 JSON으로 보여줘요
Docs Viewer가 쓸 제목, 경로, 카테고리 정보를 정리해줘요
--visual-contract를 쓰면 docs visual artifact의 schema/generator 약속도 보여줘요

이 명령어는 보통 사람이 매일 직접 쓰는 명령어라기보다, GUI나 디버깅할 때 도움이 되는 명령어라고 생각하면 쉬워요.

`vib protect`

Locks important files so AI cannot accidentally modify them.

vib protect main.py
vib protect src/config.py
vib protect --list
vib protect --remove main.py

Protected files are tracked in .vibelign_protected
guard and watch will warn you if a protected file was changed
Use this for files that must never be touched by AI

`vib config`

Sets API keys and Gemini model preferences.

vib config

What it does:

Guides you through saving API keys to your shell profile or current session
If Gemini is selected, shows available Gemini model IDs
Saves GEMINI_MODEL when you choose a Gemini model

Notes:

When a Gemini API key is available, VibeLign tries to fetch the current official model list from Google AI Studio
If the live model list cannot be fetched, VibeLign falls back to a built-in recommended Gemini model list
Press Enter or choose 0 to keep the current Gemini model setting unchanged

`vib secrets`

실수로 API 키나 비밀번호 같은 비밀정보를 Git에 올리기 전에 막아주는 명령어예요. 쉽게 말하면 “커밋 직전 마지막 안전검사”예요.

vib secrets --staged
vib secrets --install-hook
vib secrets --uninstall-hook

vib secrets --staged = 지금 한 번 직접 검사
vib secrets --install-hook = 앞으로 커밋할 때마다 자동 검사
vib secrets --uninstall-hook = 그 자동 검사 끄기

What it does:

커밋하기 전에 지금 올리려는 내용만 검사해요
API 키, 토큰, 개인키, .env 같은 비밀정보가 있는지 찾아봐요
Git 저장소라면 보통 vib start가 이 검사를 자동으로 연결해줘요
자동 hook을 켜면 vib guard --strict도 같이 돌아가서 구조 문제까지 한 번 더 확인해줘요
이미 다른 자동 실행 설정이 있으면 마음대로 덮어쓰지 않아요

커밋이 막히면 “중요한 정보가 들어있을 수 있으니 다시 봐달라”는 뜻이에요. 만약 진짜 비밀정보가 아닌데도 잘못 잡혔다면, 그 줄 끝에 vibelign: allow-secret를 붙여서 예외 처리할 수 있어요.

`vib ask`

Generates a plain-language explanation prompt for a file.

vib ask login.py
vib ask login.py "what does the validate function do?"
vib ask login.py --write
GEMINI_MODEL=gemini-2.5-flash-lite vib ask login.py

What it does:

Reads the file
Builds a prompt asking an AI to explain it in plain Korean
With --write: saves the prompt to VIBELIGN_ASK.md
Without --write: prints the prompt so you can copy it

Use this when you do not understand a file and want to ask AI to explain it before editing.

Notes:

Files over 300 lines are truncated to the first 300 lines
The prompt includes the filename, line count, and file content
If Gemini is the provider that runs, it uses gemini-3-flash-preview by default
You can override the Gemini model for one command by setting GEMINI_MODEL

`vib doctor`

Checks structural issues.

vib doctor
vib doctor --strict
vib doctor --json

Looks for:

oversized entry files
huge files (300+ warning, 500+ strong warning, 800+ critical)
catch-all files
missing anchors
UI + business logic mixing
too many definitions in one file
circular imports and missing internal module targets

Use --strict when you want earlier warnings.

`vib anchor`

Adds module-level anchors to source files that do not have them yet.

vib anchor
vib anchor --dry-run
vib anchor --only-ext .py,.js

Important behavior:

skips docs, tests, GitHub workflow folders, virtualenvs, and dependency folders by default
does not rewrite files that already contain anchors

Example anchor:

# === ANCHOR: BACKUP_WORKER_START ===
# code
# === ANCHOR: BACKUP_WORKER_END ===

Why this matters: AI can be instructed to edit only inside an anchor instead of rewriting the full file.

Anchor intent metadata

You can attach intent descriptions to anchors in .vibelign/anchor_meta.json. This improves patch suggestion accuracy when using vib patch.

Format:

{
  "LOGIN_FORM": {
    "intent": "이메일/비밀번호 입력받아 로그인 처리",
    "connects": ["AUTH_API"],
    "warning": "수정 시 AUTH_API에 영향"
  }
}

This file is written programmatically via the Python API (set_anchor_intent) or edited manually.

`vib scan`

Runs anchor scan + anchor index update + project map refresh in a single command.

vib scan
vib scan --auto

What it does:

Runs vib anchor --suggest (or --auto if flag given)
Rebuilds .vibelign/anchor_index.json
Regenerates .vibelign/project_map.json with the latest anchor index

Use vib scan instead of running vib anchor and vib start separately. This is the recommended way to keep the project map fresh after adding anchors.

`vib patch`

Builds a safer AI prompt.

vib patch "로그인 버튼 추가해줘"
vib patch "add progress indicator to backup worker"
vib patch "add progress indicator to backup worker" --json

Outputs:

suggested target file and anchor (CodeSpeak + 앵커 위치 요약)
confidence
rationale

Korean requests are fully supported:

vib patch "로그인 버튼 크기 키워줘"
vib patch "장바구니 삭제 버튼 추가해줘"
vib patch "비밀번호 버그 고쳐줘"

Notes:

files like __init__.py, tests, docs, and cache folders are strongly deprioritized
if the project has no useful source files yet, confidence becomes low
if anchor intent metadata exists in .vibelign/anchor_meta.json, it is used to improve anchor matching accuracy

`vib explain`

Explains recent changes in human language.

vib explain
vib explain --write-report
vib explain --json
vib explain --since-minutes 30

Primary mode:

uses Git status if available

Fallback mode:

uses recently modified files
intentionally avoids overreacting on freshly created repos

Output includes:

summary
what changed
why it matters
risk level
rollback hint

When --write-report is used, this is saved:

VIBELIGN_EXPLAIN.md

`vib guard`

doctor + explain + 구조 계획/앵커 검사까지 한 번에 보는 종합 검사예요.

vib guard
vib guard --strict
vib guard --json
vib guard --write-report

This answers:

“Is it safe to continue with another AI edit right now?”

Output includes:

overall level
whether the session should be considered blocked
recommendations
doctor findings
recent changed files
protected file violations (if any)
planning 상태 (planning_required, planning_exempt, plan_exists_but_deviated)
새 source 파일 앵커 누락 여부

자주 쓰는 플래그:

vib guard --strict
vib guard --since-minutes 30
vib guard --write-report
vib guard --json

--strict = warn도 fail처럼 강하게 본다
--since-minutes = 최근 몇 분 변경만 본다
--write-report = 결과를 파일로 저장한다
--json = 개발자용 JSON 출력

`vib plan-structure`

큰 기능을 만들기 전에 어느 파일을 고치고 어느 파일을 새로 만들지 먼저 정하는 명령어예요. 쉽게 말하면 “코딩 시작 전에 설계도 한 장 먼저 만드는 버튼”이에요.

보통은 이렇게 생각하면 쉬워요.

먼저 plan-structure로 작업 설계도를 만들고
그다음 patch나 AI 작업으로 실제 구현을 하고
마지막에 guard --strict로 계획대로 잘 됐는지 확인하는 거예요.

vib plan-structure "OAuth 인증 추가"
vib plan-structure --scope vibelign/core/ "watch 기능 확장"
vib plan-structure --ai "mcp handler 수정"

큰 기능이라 여러 파일이 바뀔 것 같을 때 좋아요
새 production 파일을 만들기 전에 쓰면 guard와 pre-check가 이 계획을 보고 검사할 수 있어요
결과는 .vibelign/plans/ 아래에 저장돼요

`vib claude-hook`

Claude Code가 파일을 쓰기 전에 VibeLign 검사를 먼저 하게 만드는 스위치예요.

vib claude-hook status
vib claude-hook enable
vib claude-hook disable

status = 지금 켜져 있는지 확인
enable = Claude가 Write 전에 pre-check 실행
disable = 검사만 끄고 hook 자리는 남김

보통은 vib start가 설치를 도와주고, 이 명령어는 상태를 보거나 잠깐 켜고 끌 때 쓰면 돼요.

Saved report:

VIBELIGN_GUARD.md

`vib export`

Creates helper files for tool-specific workflows.

vib export claude
vib export opencode
vib export cursor
vib export antigravity

This creates:

vibelign_exports/<tool>/

Also creates in the project root:

AI_DEV_SYSTEM_SINGLE_FILE.md — the full ruleset
AGENTS.md — auto-read by Claude Code, OpenCode, and other AI tools
.cursorrules — Cursor rules file when exporting for cursor

Examples:

Claude → RULES.md, SETUP.md, PROMPT_TEMPLATE.md
OpenCode → RULES.md, SETUP.md, PROMPT_TEMPLATE.md
Cursor → RULES.md (.cursorrules format), SETUP.md, PROMPT_TEMPLATE.md
Antigravity → TASK_ARTIFACT.md, VERIFICATION_CHECKLIST.md, SETUP.md

For Cursor, vib export cursor prepares rules/templates, while vib start --tools cursor handles runtime MCP registration in .cursor/mcp.json.

Example Cursor file layout:

your-project/
  .cursor/
    mcp.json
  .cursorrules
  vibelign_exports/
    cursor/
      RULES.md
      SETUP.md
      PROMPT_TEMPLATE.md

`vib watch`

Real-time monitor while AI or you edit files.

vib watch
vib watch --strict
vib watch --auto-fix
vib watch --write-log
vib watch --json
vib watch --debounce-ms 800

Extra dependency required:

pip install watchdog

uv add watchdog

Watch detects:

entry files growing too large
catch-all filenames
larger files with no anchors
likely UI + business logic mixing
likely business logic inside entry files
changes to protected files

추가 동작:

--auto-fix를 붙이면 새 .py/.ts/.tsx/.js/.jsx 파일에 앵커가 없을 때 저장 직후 자동으로 앵커를 넣어줘요
--write-log를 붙이면 .vibelign/watch.log에 감시 기록을 저장해요

Auto project map refresh: When files change, vib watch automatically refreshes .vibelign/project_map.json after a debounce period (default 800ms). The map update uses a temp-file swap to avoid partial reads. Status messages are printed:

⏳ 코드맵 갱신 중... (파일 3개 변경)
✅ 파일 3개 변경 감지 → 코드맵 자동 갱신 완료

Log file if enabled:

.vibelign/watch.log

State file:

.vibelign/watch_state.json

If watchdog is missing, only the watch command fails gracefully. All other commands continue to work.

`vib transfer`

Generates PROJECT_CONTEXT.md — a single file that lets another AI tool immediately understand your project.

vib transfer              # generate PROJECT_CONTEXT.md
vib transfer --compact    # smaller version (saves tokens)
vib transfer --full       # includes deeper file tree

Switching AI tools or hitting a token limit?

Use --handoff to add a short Session Handoff block at the top of PROJECT_CONTEXT.md. The new AI reads the handoff block first and continues work immediately.

vib transfer --handoff             # interactive: asks what the next AI should do first
vib transfer --handoff --no-prompt # automatic: fills what it can from repo signals
vib transfer --handoff --print     # also prints a short summary to the console
vib transfer --handoff --session-summary "current session work"
vib transfer --handoff --first-next-action "next action"
vib transfer --handoff --dry-run   # preview without writing PROJECT_CONTEXT.md
vib transfer --out ctx.md          # write to a different filename

Handoff-specific flags:

--session-summary "..." — directly sets the current-session summary in the Session Handoff block.
--first-next-action "..." — directly sets what the next AI should do first.
--dry-run — previews the generated handoff content without saving it.
--print — saves the file and also prints the handoff summary to the console.
--no-prompt — skips interactive questions and uses recorded project/session signals where possible.

Compatibility:

--handoff cannot be used together with --compact or --full.

checkpoint vs transfer --handoff — what’s the difference?

	`vib checkpoint`	`vib transfer --handoff`
Purpose	Save current state (restore point)	Pass context to next AI tool
Output	Compressed snapshot in `.vibelign/`	Session Handoff block in `PROJECT_CONTEXT.md`
Use when	Before AI edits anything	Before switching AI tools or hitting a token limit
Undoable	Yes — `vib undo` restores it	No — it is a context file, not a save

Flow when hitting a token limit:

# Current session is about to run out of tokens
vib transfer --handoff     # generates handoff (you enter one-line next action)

# Open a new AI chat or switch tools
# Tell the new AI: "Read PROJECT_CONTEXT.md first — especially the Session Handoff block at the top"
# The new AI reads the handoff block and continues immediately

Note: Running vib checkpoint after vib transfer --handoff will overwrite the handoff block, because checkpoint regenerates PROJECT_CONTEXT.md. Run vib transfer --handoff right before switching to a new AI session.

4. Recommended project rules

Best results come from these conventions:

run vib start when starting a new project or using VibeLign for the first time
save a vib checkpoint before every AI edit
use vib undo immediately if something looks wrong
vib protect files that must never change
keep entry files tiny
split large files before AI keeps growing them
run vib scan after adding anchors to keep the project map fresh
prefer patch requests over vague instructions (Korean is supported)
run vib guard before another large AI change

VibeLign patch rules

Split composite requests into intent / source / destination / behavior_constraint.
If delete and move appear together, treat it as move + preservation unless the user clearly wants removal.
Resolve source and destination by role, not with the same rule.
If patch contract or codespeak shape changes, update tests and docs together.
Keep terminology aligned with the shared glossary and project docs.

5. Suggested installation strategy

Recommended:

Python package use: uv
JS helper ecosystem: pnpm

Still supported:

pip
npm

Good future distribution option on macOS:

Homebrew

6. Troubleshooting

`watch` says watchdog is missing

Install it:

pip install watchdog

`patch` suggested the wrong file

Use the JSON output, inspect the rationale, then manually edit the generated markdown request.

`guard` seems too noisy

Prefer Git repositories. Fallback mtime mode is intentionally conservative, but calmer than before.

`anchor` touched files you did not want

Use:

vib anchor --dry-run
vib anchor --only-ext .py

`undo` says there are no checkpoints

Run vib checkpoint "initial" first to create your first save point.

`protect` list is empty

Run vib protect <filename> to add files to the protected list.

7. Typical initial setup

New project or first time using VibeLign:

vib start

That’s it. Everything else is set up automatically.

Existing project (VibeLign already configured):

vib doctor
vib anchor --dry-run
vib anchor
vib export opencode
vib checkpoint "vibelign added"

To reinstall VibeLign after source changes:

vib init

8. Backward compatibility

The legacy vibelign command is maintained as a wrapper that delegates to vib. All commands work with both:

vib doctor        # primary
vibelign doctor   # also works (backward-compatible wrapper)

9. Final advice

The safest pattern is:

checkpoint first, AI second, guard always

That is exactly what VibeLign is for.

VibeLign Manual

1. What VibeLign is for

2. The safest workflow

New project or first time using VibeLign

Reinstall VibeLign after source changes

Ongoing workflow

3. Command reference

VibeLign policy card

vib init

vib start

vib checkpoint

vib undo

vib history

vib docs-build

vib docs-index

vib protect

vib config

vib secrets

vib ask

vib doctor

vib anchor

Anchor intent metadata

vib scan

vib patch

vib explain

vib guard

vib plan-structure

vib claude-hook

vib export

vib watch

vib transfer

4. Recommended project rules

VibeLign patch rules

5. Suggested installation strategy

6. Troubleshooting

watch says watchdog is missing

patch suggested the wrong file

guard seems too noisy

anchor touched files you did not want

undo says there are no checkpoints

protect list is empty

7. Typical initial setup

8. Backward compatibility

9. Final advice

`vib init`

`vib start`

`vib checkpoint`

`vib undo`

`vib history`

`vib docs-build`

`vib docs-index`

`vib protect`

`vib config`

`vib secrets`

`vib ask`

`vib doctor`

`vib anchor`

`vib scan`

`vib patch`

`vib explain`

`vib guard`

`vib plan-structure`

`vib claude-hook`

`vib export`

`vib watch`

`vib transfer`

`watch` says watchdog is missing

`patch` suggested the wrong file

`guard` seems too noisy

`anchor` touched files you did not want

`undo` says there are no checkpoints

`protect` list is empty