Tips & Tricks — zero to coding agent Tips & Tricks — 코딩 에이전트 0에서 시작하기

You need one Z.ai GLM key. Two ways to get it: 필요한 것은 딱 하나, Z.ai GLM 키다. 받는 방법은 두 가지다:

• Shared key from this console (recommended): log in to the ZAI Plan Console → 「API 키 금고」 → tap 「관리자에게 키 열람 요청」. Once the admin approves, the key appears in the vault — press 열람 to copy it. 이 콘솔에서 공유받기(권장): ZAI Plan Console에 Google 로그인 → 「API 키 금고」 화면 → 「관리자에게 키 열람 요청」 버튼 누르기. 관리자가 승인하면 금고에 공유 키가 나타나고, 「열람」 버튼으로 복사할 수 있다.
• Your own subscription: subscribe to the GLM Coding Plan at z.ai and issue an API key from your dashboard. 직접 구독: z.ai에서 GLM Coding Plan을 구독하고, 대시보드에서 API 키를 발급받는다.

⚠ Treat the key like a password. Never paste it in chats or screenshots. If it leaks, ask for rotation immediately. ⚠ 키는 비밀번호다. 채팅·스크린샷에 절대 붙여넣지 말고, 유출되면 즉시 관리자에게 회전(교체)을 요청하라.

macOS: press ⌘+Space, type 터미널 (or Terminal), Enter. Windows: press the Start key, type PowerShell, Enter. macOS: ⌘+스페이스를 누르고 터미널(또는 Terminal) 입력 후 엔터. Windows: 시작 버튼 → PowerShell 검색 → 엔터. 이후 모든 명령은 이 창에 입력한다.

pi itself and every pi package come through npm. Check Node first: pi 본체도, pi 패키지도 전부 npm을 거친다. 먼저 확인:

If the version is older or the command is not found, install Node 22: 버전이 더 낮거나 명령이 없다고 나오면 Node 22을 설치한다:

The npm package is @earendil-works/pi-coding-agent and the command it installs is pi. --ignore-scripts skips dependency lifecycle scripts — pi does not need them: npm 패키지 이름은 @earendil-works/pi-coding-agent이고, 설치되는 명령 이름은 pi다. --ignore-scripts는 의존성 설치 스크립트를 건너뛰는 옵션이며, pi는 그 스크립트가 필요 없다:

Two routes. Inside pi, run /login and pick ZAI Coding Plan (Global) — the key is saved to ~/.pi/agent/auth.json under the zai entry and reused from then on. Or set the environment variable before launching: 두 가지 길이 있다. pi 안에서 /login을 실행하고 ZAI Coding Plan (Global)을 고르면 키가 ~/.pi/agent/auth.json의 zai 항목에 저장되고 다음부터 자동으로 쓰인다. 아니면 실행 전에 환경변수로 넣는다:

Then confirm the subscription actually unlocked the models: 그다음 구독으로 모델이 실제로 열렸는지 확인한다:

The same /login screen also takes a Claude Pro/Max, ChatGPT Plus/Pro (Codex), or GitHub Copilot subscription, so one pi install can hold several providers side by side — this guide stays on the single GLM key. 같은 /login 화면에서 Claude Pro/Max, ChatGPT Plus/Pro(Codex), GitHub Copilot 구독도 붙일 수 있어서, pi 하나에 여러 공급자를 동시에 둘 수 있다. 이 문서는 GLM 키 하나만으로 진행한다.

pi reads ~/.pi/agent/settings.json. Pin the provider, the model, and the thinking level once so every new session starts there. The snippet merges into the existing file, so nothing already in it is lost: pi는 ~/.pi/agent/settings.json을 읽는다. 공급자·모델·사고 수준을 한 번 고정해 두면 새 세션이 항상 그 상태로 시작한다. 아래 스크립트는 기존 파일에 합치는 방식이라 이미 있는 값은 그대로 살아 있다:

Switch mid-session with /model (or Ctrl+L). GLM-5.3-Flash maps low, high, and max; max is simply the top setting. 세션 도중 바꾸려면 /model(또는 Ctrl+L). GLM-5.3-Flash의 사고 수준은 low·high·max이고, max는 그 척도의 맨 위다.

GLM-5.3-Flash is the first natively multimodal GLM-5 model. When pi's model declaration includes ["text", "image"], the normal read tool passes images directly to the active model. GLM-5.3-Flash는 GLM-5 계열 최초의 네이티브 멀티모달 모델이다. pi 모델 선언이 ["text", "image"]를 포함하면 기본 read 도구가 이미지를 활성 모델에 직접 넘긴다.

⚠ A multimodal model name alone is not enough: models.json must declare the image input. The default pi-setup repository does this for GLM-5.3-Flash. ⚠ 모델 이름만 멀티모달이어서는 부족하다. models.json이 이미지 입력을 선언해야 한다. 기본 pi-setup 저장소가 GLM-5.3-Flash에 이 선언을 제공한다.

pi ships deliberately bare — four tools: read, write, edit, bash. Everything else is a package you opt into. This is the exact set behind this site's default setup. pi install accepts one source per call, so this loops (verified — passing several at once errors with Unexpected argument): pi는 일부러 헐겁게 나온다 — 도구는 read·write·edit·bash 넷뿐이다. 나머지는 전부 직접 골라 붙이는 패키지다. 아래가 이 사이트 기본 구성의 실제 한 벌이다. pi install은 한 번에 하나씩만 받으므로 반복문을 쓴다(실측 — 여러 개를 한 줄에 넣으면 Unexpected argument 오류가 난다):

⚠ pi packages run with your full local permissions — extensions are executable TypeScript and skills can direct the model to run commands. Install only what you can inspect. pi-subagents + pi-lens is already a useful minimal extension set. ⚠ pi 패키지는 당신의 로컬 권한으로 실행된다. 확장은 실제 TypeScript 코드이고, 스킬은 모델에게 명령 실행을 지시할 수 있다. 읽고 납득한 것만 설치하라. pi-subagents + pi-lens만으로도 쓸 만한 최소 확장 세트다.

With pi-subagents installed, the main agent can hand work to child agents that each start with a clean context. Pinning every gate to zai/glm-5.3-flash at thinking max keeps the whole pipeline on one subscription; skills define the role differences: pi-subagents를 깔면 주 에이전트가 깨끗한 컨텍스트의 자식 에이전트에게 일을 넘길 수 있다. 모든 관문을 zai/glm-5.3-flash · 사고 max로 고정하고, 역할 차이는 붙인 스킬로 만든다:

The six gates are specifier → coder → cleaner → sw-architect ∥ hardender → qa. Then just say it in plain language: "use reviewer to review this diff". If you later add a Claude or ChatGPT subscription, change one model line per gate — the rest of the config stays. 여섯 관문은 specifier → coder → cleaner → sw-architect ∥ hardender → qa 순이다. 쓸 때는 그냥 말로 시키면 된다 — "reviewer로 이 diff 리뷰해줘". 나중에 Claude나 ChatGPT 구독을 붙이면 관문마다 model 한 줄만 바꾸면 되고 나머지 설정은 그대로다.

The permission package from STEP 7 reads ~/.pi/agent/extensions/pi-permission-system/config.json. This policy lets ordinary work run uninterrupted, still asks before rm or sudo, hard-denies rm -rf, and blocks reads of .env files and ~/.ssh across every tool at once: STEP 7의 권한 패키지는 ~/.pi/agent/extensions/pi-permission-system/config.json을 읽는다. 아래 정책은 평범한 작업은 끊김 없이 통과시키되, rm·sudo는 물어보고, rm -rf는 아예 막고, .env 파일과 ~/.ssh 읽기를 모든 도구에서 한꺼번에 차단한다:

Separately, pi asks whether to trust a project folder before it loads that project's settings, extensions, or skills. Set the fallback once, along with the interface options this setup uses: 이와 별개로, pi는 프로젝트 폴더의 설정·확장·스킬을 읽기 전에 그 폴더를 신뢰할지 물어본다. 그 기본 동작과 이 구성이 쓰는 화면 설정을 한 번에 정한다:

⚠ defaultProjectTrust: "always" means a repository you clone can load its own pi settings and run its own extensions without asking you first. That is fine for your own code; leave it at the "ask" default if you open other people's repositories. pi has no sandbox — every tool runs as your user account. ⚠ defaultProjectTrust: "always"는 새로 클론한 저장소가 자기 pi 설정을 읽고 자기 확장을 실행하는 것을 묻지 않고 허용한다는 뜻이다. 내 코드만 다룬다면 괜찮지만, 남의 저장소를 자주 연다면 기본값 "ask"로 두라. pi에는 샌드박스가 없다 — 모든 도구는 당신 계정 권한으로 실행된다.

You are talking to the agent directly. Just write what you want, in Korean: 대화 상대는 에이전트 본인이다. 하고 싶은 일을 한국어로 그대로 쓰면 된다:

• /model — switch model mid-session. Drop to glm-5-turbo for cheap bulk work./model — 세션 도중 모델 변경. 양 많고 단순한 일은 값싼 glm-5-turbo로.
• pi -c resumes the last session, pi -r picks one from a list.pi -c는 직전 세션 이어가기, pi -r는 목록에서 골라 이어가기.
• pi -p "…" runs one prompt and exits — useful in scripts.pi -p "…"는 프롬프트 하나만 처리하고 종료한다 — 스크립트에 쓰기 좋다.
• Put an AGENTS.md in the project root and pi loads it at startup as your standing project instructions.프로젝트 루트에 AGENTS.md를 두면 시작할 때 자동으로 읽어 프로젝트 상시 지시사항으로 삼는다.

Want to try a risky config without touching your real one? Point pi at a throwaway directory: 지금 설정을 건드리지 않고 위험한 실험을 해보고 싶다면, pi가 볼 디렉터리 자체를 바꿔치면 된다:

cskwork/pi-setup-public is the source of truth for settings, agents, skills, model declarations, and packages. Clone it once; later runs fast-forward the same checkout and rerun the idempotent installer. cskwork/pi-setup-public이 설정·에이전트·스킬·모델 선언·패키지의 정본이다. 한 번 클론한 뒤에는 같은 체크아웃을 fast-forward하고 멱등 설치기를 다시 실행하면 된다.

Prefer an agent to do this safely? Use the one-shot pi setup prompt. It preserves local changes, checks native image input, and reports anything that still needs a human. 에이전트에게 안전하게 맡기려면 pi 온보딩 한 방 설치 프롬프트를 쓴다. 로컬 수정을 보존하고, 네이티브 이미지 입력을 확인하며, 사람 손이 필요한 항목만 보고한다.

Why this setup? 왜 이 구성인가?

pi ships no model and only four built-in tools. That is the point: every extra capability remains a decision you can inspect, change, or remove. GLM-5.3-Flash combines a 1,000,000-token context with native image input, so one Z.ai model handles repository-scale code and screenshots without a second vision path. pi는 모델 없이 기본 도구 넷만 들고 나온다. 그래서 추가 기능이 전부 사용자가 읽고 바꾸고 뺄 수 있는 결정으로 남는다. GLM-5.3-Flash는 100만 토큰 컨텍스트와 네이티브 이미지 입력을 함께 제공해, 저장소 규모의 코드와 스크린샷을 별도 비전 경로 없이 한 모델로 다룬다.

pi 상세 → · pi-setup 상세 →

Other harnesses 다른 하네스

• OpenCode 2 (opencode2) — full walkthrough: the previous default. Same Z.ai key, LSP-aware editing, vision through Z.ai's MCP server instead of a pi package. OpenCode 2(opencode2) — 전체 안내: 직전까지의 기본 구성. 같은 Z.ai 키를 쓰고, LSP로 코드를 이해하며, 이미지는 pi 패키지 대신 Z.ai의 MCP 서버로 읽는다.
• Prime Agent: a pi fork whose only tool is a persistent IPython kernel, so Python variables survive across turns. macOS/Linux first. Prime Agent: pi를 포크한 하네스로, 도구가 영구 IPython 커널 하나뿐이라 파이썬 변수가 턴을 넘어 살아남는다. macOS·Linux 우선.
• More in the harnesses catalog. 나머지는 harnesses 카탈로그에서.