테마: 터미널에 색 입히기

테마는 대화형 화면과 HTML 내보내기에 쓰이는 색을 제어합니다. 내장 테마는 system, dark, light 세 개입니다.

기본값인 system은 터미널의 테마에서 Pi 색을 만듭니다. 터미널의 기본 전경/배경색과 16 ANSI 색을 조회하고, 각 Pi 색을 대응하는 ANSI 색의 색상으로 배치합니다(예: 오류는 빨강 계열, 링크는 파랑 계열). 명도는 배경 대비가 충분하도록 조정되어 본문 텍스트는 배경과 모든 패널에서 WCAG 대비 4.5:1 이상을 유지합니다. 터미널이 밝기/어두움을 바꾸면 Pi는 다시 색을 조회해 테마를 재구성합니다.

선택

/settings → Theme에서 고릅니다. 저장되는 theme 설정 모양은 이렇습니다.

{ "theme": "dark" }

밝기 자동 추종을 쓰려면 첫 번째가 light, 두 번째가 dark인 짝을 저장합니다.

{ "theme": "light/dark" }

한 번의 실행에만 적용할 때는 pi --use-theme light처럼 --use-theme를 씁니다.

직접 만들기

<agent-dir>/themes/my-theme.json에 스키마(pi.dev/schemas/theme.schema.json)에 맞는 JSON을 두고 name을 my-theme로 설정한 뒤 /settings에서 선택합니다. 내장 테마를 복사해서 쓰는 것이 가장 빠릅니다. 핵심 필드는 name(필수), vars(재사용 색상 변수), colors(터미널 UI 역할별 색, 필수), export(HTML 내보내기 배경 덮어쓰기)입니다. 색은 여섯 가지 표기를 지원합니다.

표기	예
16진수 RGB	"#0af", "#00aaff"
OKLCH	"oklch(62% 0.1 200)"
OKHSL	"okhsl(250 60% 55%)"
256색 인덱스	39
변수 참조	"primary"
터미널 기본색	""

색 이름은 개별 컴포넌트가 아니라 인터페이스 역할을 서술합니다. 일반 인터페이스(accent, text, muted, error, warning), 메시지(userMessage*, thinkingText), 도구 실행(toolPendingBg, toolDiff*), markdown(md*), 문법 강조(syntax*) 같은 묶음에서 필요한 역할을 찾으면 됩니다. 테마 이름에는 /를 쓸 수 없고(자동 모드 구분자 예약) system은 예약어입니다. 프로젝트 테마는 .pi/themes/(신뢰 허용 후)에 둡니다.

Pi 패키지: 자원을 한 단위로 배포하기

확장·스킬·프롬프트 템플릿·테마를 npm이나 git으로 함께 설치·공유하는 단위가 Pi 패키지입니다.

설치와 관리

pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools@v1
pi install ./local-package
pi list
pi remove <source>
pi update --extensions

개인 설치는 ~/.pi/agent/settings.json에 기록되고, --local(-l)을 붙이면 .pi/settings.json에 씁니다(프로젝트 신뢰 후 로드). 한 번만 써보려면 pi -e npm:@example/pi-tools로 설정 없이 시도할 수 있습니다. 설정된 패키지 설치가 실패해도 Pi는 경고 후 해당 패키지 자원을 건너뛰고 계속 실행합니다.

만들기

가장 단순한 패키지는 관례 디렉터리만 갖춥니다.

my-pi-package/
├── package.json
├── extensions/
├── skills/
├── prompts/
└── themes/

pi 매니페스트가 없으면 이 디렉터리에서 확장(TS/JS), 스킬 디렉터리, markdown 프롬프트, JSON 테마를 자동으로 찾습니다. 자원이 다른 곳에 있거나 필터가 필요하면 package.json의 pi 키에 명시합니다.

{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./src/extension.ts"],
    "skills": ["./resources/skills"],
    "prompts": ["./resources/prompts/*.md"],
    "themes": ["./resources/themes/*.json"]
  }
}

pi-package 키워드를 붙이면 pi.dev 패키지 갤러리에 노출될 자격이 생깁니다. 확장 코드가 import하는 런타임 패키지는 dependencies에, Pi가 호스트에서 제공하는 패키지(@earendil-works/pi-ai, pi-agent-core, pi-coding-agent, pi-tui, typebox)는 peerDependencies에 "*" 범위로 선언하고 동봉하지 않습니다. 물리 사본을 두면 중복 클래스와 등록부 문제가 생깁니다.

선택과 범위

설정에서 객체 형태로 패키지를 좁힐 수 있습니다. 속성을 생략하면 패키지 허락 범위 전체를, []면 해당 유형을 로드하지 않고, !패턴, +경로, -경로로 정밀 조절합니다. 필터는 패키지 매니페스트를 좁힐 뿐 패키지 자체가 선언하지 않은 자원을 노출하지는 않습니다. pi config로 발견된 자원과 내장 확장 활성화·비활성화를 조절할 수 있습니다.

같은 패키지가 개인과 프로젝트 설정에 모두 있으면 보통 프로젝트 항목이 개인 항목을 대체합니다. npm 패키지는 이름, git 패키지는 ref를 뺀 저장소 URL, 로컬 패키지는 절대경로로 동일성을 판별해 같은 패키지의 이중 로드를 막습니다.

마지막으로 안전 안내: 패키지는 확장 코드를 실행할 수 있고 스킬을 통해 프로그램 실행을 지시할 수도 있습니다. 서third-party 패키지는 설치 전 소스를, 프로젝트 신뢰를 주기 전에는 프로젝트 패키지 선언을 검토하세요.