Power Tools 파워 툴즈

● WebFetch

URL → Markdown conversion tool for agents. Fetches any URL, converts HTML to clean Markdown using Mozilla Readability + Turndown, and caches results for fast repeated access. 에이전트를 위한 URL → Markdown 변환 도구. 모든 URL을 가져와 Mozilla Readability + Turndown으로 HTML을 깔끔한 Markdown으로 변환하고, 빠른 반복 접근을 위해 결과를 캐시합니다.

Tool Parameters 도구 파라미터

Parameter파라미터	Type타입	Required필수	Default기본값
url	string	Yes예	—
raw	boolean	No아니오	false
includeScripts	boolean	No아니오	false
maxLength	number	No아니오	—

Cache 캐시

In-memory LRU cache. 100 entries max, 15-minute TTL. Cache key is derived from JSON.stringify({url, mode, scripts}) where mode is "full" (default) or "full" when raw is true. 인메모리 LRU 캐시. 최대 100개 항목, 15분 TTL. 캐시 키는 JSON.stringify({url, mode, scripts})에서 파생됩니다. 여기서 mode는 기본값 "auto" 또는 raw가 true일 때 "full"입니다.

Limits 제한

• MAX_CONTENT_SIZE = 10 MB — checked via content-length header and actual byte count content-length 헤더와 실제 바이트 수로 확인
• FETCH_TIMEOUT_MS = 30 s — hard abort via AbortController AbortController를 통한 강제 중단

User Agent 사용자 에이전트

Extraction Modes 추출 모드

Mode모드	Trigger트리거	Behavior동작
full	raw: false (default)	Readable content — Mozilla Readability + Turndown + GFM읽을 수 있는 콘텐츠 — Mozilla Readability + Turndown + GFM
raw	raw: true	Full HTML converted to Markdown via Turndown (no Readability filter)전체 HTML을 Turndown으로 Markdown 변환 (Readability 필터 없음)

Truncation 자르기

When maxLength is set and content exceeds it, the returned copy is sliced and suffixed with: maxLength가 설정되고 콘텐츠가 초과하면 반환된 사본은 잘리고 다음 접미사가 붙습니다:

The original content stored in cache is not truncated. 캐시에 저장된 원본 콘텐츠는 자르지 않습니다.

■ Editor Stash

Session-scoped single-slot stash for editor text. Save a snippet, clear the editor, restore it later — all without leaving the editor. 에디터 텍스트를 위한 세션 범위의 단일 슬롯 스태시. 스니펫을 저장하고, 에디터를 지우고, 나중에 복원 — 에디터를 떠나지 않고 모두 가능합니다.

Slash Commands 슬래시 명령

Command명령	Action동작
/stash-save	Copy current editor text into the stash slot현재 에디터 텍스트를 스태시 슬롯에 복사
/stash-clear	Clear the stash slot contents스태시 슬롯 내용 지우기
/stash-restore	Replace editor text with stashed content에디터 텍스트를 스태시된 내용으로 교체

Keyboard Shortcuts 키보드 단축키

Shortcut단축키	Byte바이트	Action동작
Ctrl+S	\x13	Save to stash스태시에 저장
Ctrl+R	\x12	Restore from stash스태시에서 복원
Ctrl+K	\x0b	Clear stash스태시 지우기

Status Indicator 상태 표시기

An editor decorator appends a status line at the bottom of the editor showing stash size and shortcut hints. 에디터 데코레이터가 에디터 하단에 스태시 크기와 단축키 힌트를 보여주는 상태 줄을 추가합니다.

★ Artifacts

Structured per-run artifact directories for subagent outputs. Each subagent invocation gets an isolated directory tree for its output, progress, and declared read files. 서브에이전트 출력을 위한 구조화된 실행별 아티팩트 디렉토리. 각 서브에이전트 호출은 출력, 진행, 선언된 읽기 파일을 위한 격리된 디렉토리 트리를 가져옵니다.

Directory Layout 디렉토리 레이아웃

Base Directory 기본 디렉토리

run.json Schema run.json 스키마

Field	Type타입	Description설명
agentName	string	Subagent identifier서브에이전트 식별자
runId	string	Unique run identifier고유 실행 식별자
rootRunId	string	Parent session run identifier부모 세션 실행 식별자
cwd	string	Working directory at creation time생성 시점의 작업 디렉토리
outputFile	string?	Resolved output path해결된 출력 경로
progressFile	string?	Resolved progress path해결된 진행 경로
readFiles	string[]	Declared read file paths선언된 읽기 파일 경로
createdAt	string	ISO 8601 timestampISO 8601 타임스탬프

Path Guards 경로 가드

All user-supplied paths are validated before resolution: 모든 사용자 제공 경로는 해결 전에 검증됩니다:

• Rejects absolute paths (/etc/passwd) 절대 경로 거부 (/etc/passwd)
• Rejects home shortcuts (~, ~/...) 홈 단축키 거부 (~, ~/...)
• Rejects paths that escape the run directory (../../etc) 런 디렉토리를 벗어나는 경로 거부 (../../etc)
• Rejects paths that escape the workspace (for declared reads) 워크스페이스를 벗어나는 경로 거부 (선언된 읽기용)

Segment Sanitization 세그먼트 정화

sanitizeSegment() replaces non-alphanumeric characters (except ., _, -) with -, then strips leading and trailing dashes. Falls back to "run" if the result is empty. sanitizeSegment()은 영숫자가 아닌 문자(., _, - 제외)를 -로 교체하고, 선행 및 후행 대시를 제거합니다. 결과가 비어있으면 "run"을 사용합니다.

◆ Lore Commits

Structured git trailers that embed decision context directly into commit messages. Future agents and developers can query project knowledge via git log. 커밋 메시지에 결정 컨텍스트를 직접 삽입하는 구조화된 git 트레일러. 미래의 에이전트와 개발자가 git log를 통해 프로젝트 지식을 조회할 수 있습니다.

Trailer Vocabulary 트레일러 어휘

Trailer트레일러	Format형식	Example예시
Constraint:	Free text자유 텍스트	Constraint: must support Node 18+
Rejected:	<alt> | <reason>	Rejected: SQLite | adds native dependency
Confidence:	high / medium / lowhigh / medium / low	Confidence: high
Scope-risk:	narrow / moderate / broadnarrow / moderate / broad	Scope-risk: narrow
Reversibility:	clean / moderate / difficultclean / moderate / difficult	Reversibility: clean
Directive:	Free text자유 텍스트	Directive: keep backwards compat
Tested:	Free text자유 텍스트	Tested: manual verification on macOS
Not-tested:	Free text자유 텍스트	Not-tested: Windows path handling
Related:	Free text자유 텍스트	Related: #42

Querying Lore Lore 조회

Filter commits by any trailer key: 모든 트레일러 키로 커밋 필터링:

Setup 설정

The lore-setup skill writes Lore commit format rules to AGENTS.md or CLAUDE.md so all agents automatically use structured git trailers in commit messages. lore-setup 스킬이 AGENTS.md 또는 CLAUDE.md에 Lore 커밋 형식 규칙을 작성하여 모든 에이전트가 커밋 메시지에 자동으로 구조화된 git 트레일러를 사용하도록 합니다.

▶ Welcome Banner

ROACH PI branded header that replaces the generic pi startup listing. Shows the ASCII art logo and quick-start hints when the session begins. 일반적인 pi 시작 목록을 대체하는 ROACH PI 브랜디드 헤더. 세션 시작 시 ASCII 아트 로고와 빠른 시작 힌트를 표시합니다.

/welcome Command /welcome 명령

Input입력	Effect효과
off, hide, dismiss	Hide the banner배너 숨기기
on, show, restore	Show the banner배너 표시
(bare) /welcome	Toggle visibility가시성 토글

Interaction with /setup /setup과의 상호작용

/setup sets quietStartup: true so the pi agent's generic startup listing is suppressed, making the ROACH PI banner the main startup surface. /setup이 quietStartup: true를 설정하여 pi 에이전트의 일반적인 시작 목록이 억제되고, ROACH PI 배너가 주 시작 화면이 됩니다.

Interaction with /init /init과의 상호작용

/init also configures banner visibility as part of the initial project setup flow. /init도 초기 프로젝트 설정 흐름의 일부로 배너 가시성을 구성합니다.

◐ Plan Progress & Milestone TUI

Real-time plan and milestone progress displayed in the TUI footer. Shows task completion, running state, and milestone lifecycle at a glance. TUI 푸터에 표시되는 실시간 계획 및 마일스톤 진행 상황. 작업 완료, 실행 상태, 마일스톤 수명 주기를 한눈에 보여줍니다.

Task Statuses 작업 상태

Status상태	Meaning의미
pending	Not yet started아직 시작 안 됨
running	Currently executing현재 실행 중
completed	Finished successfully성공적으로 완료
failed	Finished with error오류로 완료

Milestone Statuses 마일스톤 상태

Status상태	Meaning의미
pending	Waiting to start시작 대기 중
planning	Plan being drafted계획 작성 중
executing	Tasks running작업 실행 중
validating	Review underway리뷰 진행 중
completed	All tasks passed모든 작업 통과
failed	Validation failed검증 실패
skipped	Explicitly skipped명시적으로 건너뜀

Spinner 스피너

A 400ms interval spinner (PLAN_PROGRESS_SPINNER_MS) runs only while tasks are in the running state. Frames cycle through ◐ ◓ ◑ ◒. 작업이 running 상태인 동안만 400ms 간격 스피너(PLAN_PROGRESS_SPINNER_MS)가 실행됩니다. 프레임은 ◐ ◓ ◑ ◒을 순환합니다.

Milestone File Detection 마일스톤 파일 감지

File Type파일 유형	Pattern패턴
Milestone file마일스톤 파일	/(M\d+)-([^/\s]+)\.md$/i
State table상태 테이블	/state.md$/
Todo할 일	/todo.md$/
Completion완료	/completion.md$/

/reset-phase Command /reset-phase 명령

Clears all plan and milestone state from the tracker, returning to a clean slate. 트래커에서 모든 계획 및 마일스톤 상태를 지우고 깨끗한 상태로 돌아갑니다.

Footer Integration 푸터 통합

The footer subscribes to PlanProgressTracker change notifications via setOnChange(). When progress changes, the footer calls tui.requestRender(true) to update the display. The spinner timer is started on demand and cleaned up in dispose(). 푸터는 setOnChange()을 통해 PlanProgressTracker 변경 알림을 구독합니다. 진행 상황이 변경되면 푸터는 tui.requestRender(true)를 호출하여 표시를 업데이트합니다. 스피너 타이머는 필요할 때 시작되고 dispose()에서 정리됩니다.