diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..821854b --- /dev/null +++ b/docs/index.html @@ -0,0 +1,1707 @@ + + + + + + Wisp — Local Coding Agent Orchestrator + + + + + + + + +
+ +
+ +

Wisp

+

+ A local coding agent orchestrator.
+ Claude implements. Codex ships. You stay in control. +

+

+ 로컬 코딩 에이전트 오케스트레이터.
+ Claude가 구현하고, Codex가 배포한다. 결정권은 당신에게 있다. +

+ +
+ CI + npm + MIT + Platform +
+ +
+ Get Started + 시작하기 + GitHub ↗ + npm ↗ +
+ +
+
+ ┌─ + [1/4] + Claude + implement + writes the solution솔루션 작성 +
+
+     + [2/4] + Codex   + patch     + reviews diff, applies fixesdiff 검토 후 수정 적용 +
+
+     + [3/4] + Claude + review    + APPROVED / CHANGES_REQUESTEDAPPROVED / CHANGES_REQUESTED +
+
+ └─ + [4/4] + Codex   + ship      + suggests commit message커밋 메시지 제안 +
+
+
+ +
+ + +
+

Why Wisp

+

왜 Wisp인가

+

Agents should suggest, not decide.

+

에이전트는 제안하고, 결정은 사람이 한다.

+ +
+
+
+ AI edits your files while you look away +
+
Everything is dry-run by default
+
+
+
+ Can't tell what the agent actually did +
+
+ Full session log — prompts, diffs, timing, policy results +
+
+
+
One agent makes one big messy change
+
+ Four-role pipeline: implement → patch → review → ship +
+
+
+
AI pushes commits you didn't approve
+
Hard policy block on commit and push
+
+
+
+ Agents ignore your project conventions +
+
+ Load .wisp/instructions.md into every prompt +
+
+
+
+ Korean task input breaks English-only tools +
+
+ Auto-detects Korean, responds in Korean +
+
+
+ +
+
+
+ AI가 내가 모르는 사이에 파일을 수정한다 +
+
+ 기본값은 dry-run — 내가 명시적으로 허용해야 변경된다 +
+
+
+
+ 에이전트가 실제로 뭘 했는지 알 수 없다 +
+
+ 세션 전체 로그 — 프롬프트, diff, 실행 시간, 정책 검사 결과 +
+
+
+
+ 에이전트 하나가 한 번에 너무 많이 바꾼다 +
+
4단계 파이프라인으로 각 역할을 분리
+
+
+
에이전트가 커밋을 마음대로 올린다
+
커밋과 푸시는 정책으로 차단
+
+
+
에이전트가 프로젝트 규칙을 무시한다
+
+ .wisp/instructions.md를 모든 프롬프트에 주입 +
+
+
+
+ 한국어 입력이 영어 전용 툴에서 제대로 안 된다 +
+
한국어 자동 감지, 한국어로 응답
+
+
+
+ +
+ + +
+

Quick Start

+

빠른 시작

+

Up and running in 30 seconds.

+

30초 안에 바로 시작.

+ +
+
+ sh + +
+ 
# Install — binary auto-downloaded from GitHub Releases# 설치 — GitHub Releases에서 바이너리 자동 다운로드
+npm install -g @lka09/wisp
+
+# Initialize your project# 프로젝트 초기화
+cd your-project
+wisp init
+
+# Preview what agents would do — no files changed# 에이전트가 뭘 할지 미리보기 — 파일 변경 없음
+wisp summon "add rate limiting to the API endpoints"
+
+# Actually run it# 실제로 실행
+wisp summon "add rate limiting to the API endpoints" --execute-agents
+
+ +
+ Prerequisite: + Claude CLI + and/or + Codex CLI + installed and authenticated. Dry-run works without them. +
+
+ 사전 조건: + Claude CLI + 또는 + Codex CLI + 설치 및 인증 필요. dry-run은 에이전트 없이도 동작한다. +
+
+ +
+ + +
+

How It Works

+

동작 방식

+

A structured 4-step pipeline.

+

구조화된 4단계 파이프라인.

+ +
+
+
①
+

implement

+

+ Claude reads your task and project instructions, writes the + solution. +

+

+ Claude가 작업과 프로젝트 지시사항을 읽고 솔루션을 작성한다. +

+
+
+
②
+

patch

+

+ Codex reviews the diff and applies fixes. Repeats up to + max_review_rounds. +

+

+ Codex가 diff를 검토하고 수정 사항을 적용한다. 최대 + max_review_rounds회 반복. +

+
+
+
③
+

review

+

+ Claude reviews the final diff and outputs APPROVED, + CHANGES_REQUESTED, or + NEEDS_USER_DECISION. +

+

+ Claude가 최종 diff를 리뷰하고 APPROVED, + CHANGES_REQUESTED, + NEEDS_USER_DECISION 중 하나를 출력한다. +

+
+
+
④
+

ship

+

+ Codex prepares a commit message suggestion. You decide whether to + commit. +

+

+ Codex가 커밋 메시지 초안을 제안한다. 커밋 여부는 내가 결정한다. +

+
+
+ +

Session audit trail

+

세션 감사 기록

+

+ Every run writes a timestamped session under + .wisp/sessions/: +

+

+ 모든 실행마다 .wisp/sessions/ 아래에 타임스탬프 + 디렉터리가 생성된다: +

+ +
+
+ text +
+ 
.wisp/sessions/20260619-143022-p4801/
+  task.original.txt          what you typed내가 입력한 원본 작업
+  task.normalized.en.md      English translation for agents에이전트용 영어 번역
+  instructions.loaded.md     all project instruction files merged불러온 프로젝트 지시사항 전체
+  prompts/
+    implementer.en.md        prompt sent to ClaudeClaude에게 보낸 프롬프트
+    patcher.en.md
+    reviewer.en.md
+    shipper.en.md
+  outputs/
+    implement.out.md         stdout + stderrstdout + stderr
+    implement.meta.txt       timing, exit code, git delta, policy checks실행 시간, 종료 코드, git 변경사항, 정책 검사
+    implement.diff.*.patch   git state before/after this step이 단계 실행 전/후 git 상태
+  summary.md
+
+
+ +
+ + +
+

Installation

+

설치

+

npm or build from source.

+

npm 또는 소스 빌드.

+ +

Option 1 — npm (recommended)

+

방법 1 — npm (권장)

+ +
+
+ sh + +
+ 
npm install -g @lka09/wisp
+
+ +

+ The postinstall script downloads the pre-built binary for your + platform from GitHub Releases. If the download fails, it prints exact + build-from-source instructions. +

+

+ postinstall 스크립트가 GitHub Releases에서 플랫폼에 맞는 바이너리를 + 자동으로 다운로드한다. 다운로드에 실패하면 소스 빌드 방법을 정확하게 + 출력해준다. +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OSOSArchitecture아키텍처Asset릴리스 에셋
Windowsx86_64wisp-windows-x86_64.exe
WindowsARM64wisp-windows-aarch64.exe
Linuxx86_64wisp-linux-x86_64
LinuxARM64wisp-linux-aarch64
macOSx86_64 (Intel)wisp-darwin-x86_64
macOSApple Siliconwisp-darwin-aarch64
+
+ +

Option 2 — Build from source

+

방법 2 — 소스 빌드

+ +
+
+ sh — Linux / macOS + +
+ 
+git clone https://github.com/LKA09/Wisp
+cd Wisp/wisp
+cargo build --release
+mkdir -p ../npm/dist
+cp target/release/wisp ../npm/dist/wisp
+cd ../npm && npm link
+
+ +
+
+ powershell — Windows + +
+ 
+git clone https://github.com/LKA09/Wisp
+cd Wisp\wisp
+cargo build --release
+New-Item -ItemType Directory -Force -Path ..\npm\dist | Out-Null
+Copy-Item target\release\wisp.exe ..\npm\dist\wisp.exe
+cd ..\npm; npm link
+
+ +

Prerequisites

+

사전 요구사항

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Tool도구When needed필요 시점Install설치
Node.js ≥ 16Always항상 + nodejs.org +
GitAlways항상 + git-scm.com +
Rust + CargoSource build only소스 빌드 시 + rustup.rs +
Claude CLI--execute-agentsnpm i -g @anthropic-ai/claude-code
Codex CLI--execute-agentsnpm i -g @openai/codex
+
+
+ +
+ + +
+

TUI

+

Interactive terminal UI.

+

인터랙티브 터미널 UI.

+ +

+ Run wisp with no arguments to open the full-screen + interactive REPL. +

+

+ wisp를 인수 없이 실행하면 전체 화면 TUI가 열린다. +

+ +
+
+ terminal +
+ 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✦  Wisp  —  implement · patch · review · shipimplement · patch · review · ship
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Type a task and press Enter — default is dry-run preview.작업을 입력하고 Enter를 누르세요 — 기본값은 dry-run 미리보기.
+
+  › /
+  ╭────────────────────────────────────────────────────╮
+  │ /run    execute workflow interactively워크플로우 실행            │
+  │ /auto   execute workflow (auto-approve)워크플로우 실행 (자동 승인)     │
+  │ /claude run Claude directlyClaude 단독 실행                    │
+  │ /codex  run Codex directlyCodex 단독 실행                     │
+  │ /paste  enter multi-line paste mode여러 줄 붙여넣기 모드              │
+  ╰────────────────────────────────────────────────────╯
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Input입력Action동작
<task>Dry-run preview (no files changed)Dry-run 미리보기 (파일 변경 없음)
/run <task>Execute full workflow interactively전체 워크플로우 실행
/auto <task>Execute full workflow (auto-approve)전체 워크플로우 실행 (자동 승인)
/claude <task>Run Claude as single agentClaude 단독 에이전트 실행
/codex <task>Run Codex as single agentCodex 단독 에이전트 실행
/pasteMulti-line paste mode여러 줄 붙여넣기 모드
exit / Ctrl+CExit종료
+
+
+ +
+ + +
+

CLI Reference

+

CLI 레퍼런스

+

All commands at a glance.

+

전체 명령어 한눈에.

+ +
+
+ sh + +
+ 
# Project setup# 프로젝트 설정
+wisp init                                     # create wisp.toml + .wisp/# wisp.toml + .wisp/ 생성
+wisp doctor                                   # check git, agents, config# git, 에이전트, 설정 확인
+
+# 4-step workflow: implement → patch → review → ship# 4단계 워크플로우: implement → patch → review → ship
+wisp summon "<task>"                         # dry-run preview# dry-run 미리보기
+wisp summon "<task>" --execute-agents          # execute# 실행
+wisp summon "<task>" --execute-agents --allow-dirty
+wisp summon "<task>" --execute-agents --permission auto
+
+# Single agent# 단일 에이전트
+wisp ask claude "<task>"                     # dry-run# dry-run
+wisp ask claude "<task>" --execute-agents     # execute# 실행
+wisp ask codex  "<task>" --permission auto
+
+# Info# 정보
+wisp --help
+wisp --version
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Flag플래그Default기본값Description설명
--execute-agentsoff꺼짐Actually invoke agent CLIs에이전트 CLI 실제 실행
--allow-dirtyoff꺼짐Skip uncommitted-changes check커밋되지 않은 변경사항 허용
--permission interactive✓Agent prompts user for approval에이전트가 사용자에게 승인 요청
--permission autoPass auto-approve flags to agent자동 승인 플래그 전달
--permission skipSkip permission-gated steps권한 필요 단계 건너뜀
+
+
+ +
+ + +
+

Safety Model

+

안전 모델

+

Built-in guardrails, not an afterthought.

+

처음부터 설계된 안전장치.

+ +
+
+
+
+ No changes without consent +
+

+ Dry-run is the default. --execute-agents must be + explicit. +

+
+
+
+
+ Protected branches +
+

+ Execution blocked on main, + master (configurable). +

+
+
+
+
+ Dirty tree protection +
+

Blocked unless --allow-dirty is set.

+
+
+
+
+ No surprise commits +
+

Agents are instructed never to git commit.

+
+
+
+
+ No surprise pushes +
+

+ push approval is deny by default in + policy. +

+
+
+
+
+ Protected files +
+

+ deny_commands and protected_paths in + wisp.toml. +

+
+
+
+
+ Dependency changes flagged +
+

add_dependency triggers an approval gate.

+
+
+
+
+ Full audit trail +
+

Every session logged to .wisp/sessions/.

+
+
+ +
+
+
+
+ 동의 없이 변경 없음 +
+

+ dry-run이 기본값. --execute-agents는 명시적으로 + 설정해야 한다. +

+
+
+
+
+ protected 브랜치 보호 +
+

+ main, master에서 실행 차단 (설정 가능). +

+
+
+
+
+ dirty tree 보호 +
+

--allow-dirty 없으면 차단.

+
+
+
+
+ 깜짝 커밋 없음 +
+

에이전트는 git commit 금지 지시를 받는다.

+
+
+
+
+ 깜짝 푸시 없음 +
+

정책에서 push의 기본값은 deny.

+
+
+
+
+ 보호된 파일 안전 +
+

+ deny_commands와 protected_paths로 차단. +

+
+
+
+
+ 의존성 변경 알림 +
+

add_dependency는 승인 게이트를 통과해야 한다.

+
+
+
+
+ 완전한 감사 기록 +
+

모든 세션이 .wisp/sessions/에 기록된다.

+
+
+ +
+ Note: Wisp is not a security sandbox. Agents run with + your full user permissions. The policy layer blocks specific commands + and paths, but cannot prevent every possible unsafe action. Always + review agent output before approving commits. +
+
+ 주의: Wisp는 보안 샌드박스가 아니다. 에이전트는 내 + 사용자 권한으로 실행된다. 정책 레이어가 특정 명령어와 경로를 + 차단하지만 모든 위험한 동작을 막을 수는 없다. 커밋을 승인하기 전에 + 에이전트 출력을 반드시 검토하자. +
+
+ +
+ + +
+

Configuration

+

설정

+

+ Fully customizable via + wisp.toml. +

+

+ wisp.toml로 전부 설정. +

+ +

+ wisp init creates wisp.toml in your project + root. Edit it to customize agents, workflow, and policy. +

+

+ wisp init이 프로젝트 루트에 wisp.toml을 + 자동으로 생성한다. +

+ +
+
+ toml — wisp.toml + +
+ 
[language]
+ui       = "auto"   # auto-detects Korean input# 한국어 입력 자동 감지
+fallback = "en"
+
+[agents.claude]
+cmd  = "claude"
+args = ["-p", "{prompt}"]
+
+[agents.codex]
+cmd  = "codex"
+args = ["exec", "-s", "workspace-write", "{prompt}"]
+
+[workflow]
+implementer       = "claude"
+patcher           = "codex"
+reviewer          = "claude"
+shipper           = "codex"
+max_review_rounds = 2
+
+[approval]
+push                  = "deny"  # always block# 항상 차단
+commit                = "ask"
+add_dependency        = "ask"
+delete_file           = "ask"
+modify_protected_file = "deny"
+
+[policy]
+protected_branches = ["main", "master"]
+protected_paths    = [".env", ".git", "credentials.json"]
+deny_commands      = ["git push --force", "rm -rf /"]
+
+[instructions]
+files = [".wisp/instructions.md", "AGENTS.md", "CLAUDE.md"]
+
+ +

Project instructions

+

프로젝트 지시사항

+

+ Create .wisp/instructions.md to inject project context + into every agent prompt: +

+

+ .wisp/instructions.md를 만들면 모든 에이전트 프롬프트에 + 프로젝트 맥락이 자동으로 주입된다: +

+ +
+
+ markdown — .wisp/instructions.md +
+ 
+# Project Instructions
+
+- TypeScript + React 18. Use functional components and hooks only.
+- Run `npm test` before considering any task complete.
+- Never modify files under `src/generated/`.
+- Commit messages must follow Conventional Commits.
+ 
+# 프로젝트 지시사항
+
+- TypeScript + React 18 프로젝트다. 함수형 컴포넌트와 훅만 사용한다.
+- 작업 완료 전 반드시 `npm test`를 실행한다.
+- `src/generated/` 안의 파일은 수정하지 않는다.
+- 커밋 메시지는 Conventional Commits 형식을 따른다.
+
+
+ +
+ + + +
+ + + +