Claude Code에게 "이런 그림 만들어서 여기에 넣어줘"라고 말하면, 그림이 만들어지고 문서의 정한 자리에 들어갑니다. 이미지 생성 사이트를 따로 열지 않습니다. Claude Code가 브라우저를 대신 움직여 처리합니다. 준비부터 첫 결과까지 그대로 따라 합니다.
이 작업은 세 쪽이 협업하는 구조입니다. 이 구조를 알면 중간에 막혀도 어디가 문제인지 바로 짚을 수 있습니다.
당신의 말을 받아 나머지 둘을 부립니다. 당신은 여기에만 말을 겁니다.
지휘자가 직접 못 만지는 브라우저를 대신 움직입니다. 로그인된 상태 그대로 씁니다.
실제로 그림을 그립니다. 브라우저 안에서 이미지를 만들어 냅니다.
당신이 지휘자에게 "이런 그림을 만들어 여기 넣어줘"라고 말하면, 지휘자가 손(Aside)을 써서 화가(ChatGPT)에게 주문하고, 다 그린 그림을 받아 당신의 문서에 붙입니다.
이 가이드는 Claude Code를 이미 설치해 써 본 분을 위한 것입니다. 화면은 Windows 기준입니다. 코드를 읽을 줄 몰라도 됩니다.
Claude Code가 아직 없다면 먼저 설치가 필요합니다. 설치가 끝난 뒤 이 가이드로 돌아오세요. 여기서부터는 Claude Code가 이미 있다고 보고 진행합니다.
그림을 그릴 손이 되는 프로그램입니다. 공식 사이트에서 받습니다.
브라우저에서 aside.com에 들어갑니다. 오른쪽 위 또는 가운데의 다운로드 버튼을 누릅니다. 내 컴퓨터에 맞는 버튼(Windows면 "Download for Windows")이 자동으로 표시됩니다.
버튼을 누르면 다운로드가 시작됩니다. 다운로드가 끝나면 안내대로 받은 설치 파일(Aside.exe)을 열고, 설치 창의 다음 버튼을 따라 끝까지 진행합니다.
여기까지 확인. 설치가 끝나면 Aside가 하나의 프로그램으로 실행됩니다. Aside 창이 열리면 다음으로 갑니다.
화가에게 그림을 시키려면 먼저 화가와 연결되어 있어야 합니다. 그 연결이 ChatGPT 로그인입니다.
Aside는 그 자체가 브라우저입니다. Aside의 주소창에 chatgpt.com을 입력해 들어간 뒤, 본인 ChatGPT 계정으로 로그인합니다. 로그인은 직접 하셔야 합니다.
중요. Aside 안에서 ChatGPT에 로그인만 되어 있으면 됩니다. 무료 계정도 하루 몇 장까지 그림을 만들 수 있습니다(품질은 유료와 같고 하루 만들 수 있는 수량만 적습니다). 자주 많이 만들려면 유료 플랜(Plus 등)이 편합니다. 그리고 로그아웃되지 않게 유지하세요. 로그아웃되면 그림이 안 만들어집니다.
여기까지 확인. Aside 안에서 ChatGPT 화면이 로그인된 상태로 보이면 됩니다. 새 대화를 시작할 수 있으면 로그인된 것입니다.
Claude Code가 Aside를 부르려면 둘을 잇는 얇은 연결선이 필요합니다. Aside 안에서 그 연결선을 한 번 켜 둡니다.
Aside 창에서 설정(Settings) 메뉴로 들어갑니다. 그 안의 Developers 항목을 엽니다. 거기에 연결용 명령줄 도구(CLI)를 설치하는 버튼이 있습니다. 그 버튼을 눌러 설치합니다.
설치가 끝나면 이 도구가 아래 경로에 생깁니다. 다음 단계에서 이 경로를 씁니다. <사용자이름> 부분은 본인 Windows 사용자 이름으로 바뀝니다.
C:\Users\<사용자이름>\AppData\Local\Aside\CLI\current\aside.exe
여기까지 확인. Settings의 Developers 화면에서 CLI가 "설치됨" 상태로 보이면 됩니다.
이제 지휘자(Claude Code)에게 "너는 이 손을 쓸 수 있다"고 알려 줍니다. 설정 파일에 짧은 블록 하나를 넣는 일입니다.
Claude Code의 설정 파일을 엽니다. 사용자 폴더 안의 .claude.json 파일입니다. 아래 경로에 있습니다.
C:\Users\<사용자이름>\.claude.json
이 파일을 열어, 가장 바깥 괄호 안에 mcpServers 항목을 아래처럼 추가합니다. 이미 mcpServers 항목이 있다면 그 안에 "aside" 한 덩어리만 더합니다. 경로의 <사용자이름>은 본인 것으로 바꿉니다.
{
"mcpServers": {
"aside": {
"command": "C:/Users/<사용자이름>/AppData/Local/Aside/CLI/current/aside.exe",
"args": ["mcp"]
}
}
}
경로 표기 주의. 설정 파일 안에서는 폴더 구분에 슬래시(/)를 씁니다. 위 블록을 그대로 쓰되 사용자 이름만 바꾸면 됩니다.
여기까지 확인. 파일을 저장했을 때 오류 표시가 없으면 됩니다. 괄호와 쉼표가 위 모양 그대로여야 합니다.
매번 긴 설명을 하지 않도록, 그림 만드는 절차를 Claude Code에 스킬로 한 번 넣어 둡니다. 이걸 넣어 두면 이다음부터는 "그려서 넣어줘" 한마디로 끝납니다. 파일은 Claude Code가 대신 만들어 줍니다.
Claude Code에게 아래 문장을 그대로 말합니다. 그리고 바로 이어서, 그 아래 "스킬 전문"의 복사 버튼을 눌러 내용을 붙여넣습니다.
아래 내용으로 ~/.claude/skills/aside-image/SKILL.md 파일을 만들어줘.
---
name: aside-image
description: >-
Use when the user wants to actually GENERATE an image through Aside (ChatGPT's
built-in GPT Image 2.5) and optionally INSERT it into a document. Korean
triggers - "aside로 이미지 만들어", "그림 그려줘", "이미지 생성해서 문서에 넣어줘",
"이미지 만들어서 삽입", "히어로 이미지 넣어줘", "aside 이미지". English -
"generate an image with aside", "make an image and insert it". Drives the
logged-in ChatGPT web session through mcp__aside__repl: opens chatgpt.com,
sends a NO-TEXT prompt, polls until the picture is done, downloads the original
file, saves it, and (if asked) inserts it into an HTML or markdown file at a
named spot. For photorealistic prompts, read the photoreal skill first to
design the prompt. Do NOT use for prompt-only design (that is photoreal) or for
code/API batch generation (that is gen_image.py). Requires the Aside MCP to be
connected and ChatGPT to be logged in inside Aside.
---
# aside-image
Aside가 모는 로그인된 ChatGPT 웹 세션으로 GPT Image 2.5 이미지를 실제로 생성하고, 원하면 산출물(HTML·마크다운)의 지정 위치에 삽입한다. 매번 긴 절차를 받아쓰지 않고 이 스킬이 전 과정을 수행한다.
## 전제 (없으면 먼저 안내)
- `mcp__aside__repl` 도구가 있어야 한다(Aside MCP 연결됨). 없으면 사용자에게 Aside 앱 설치 + CLI(Settings > Developers) + `~/.claude.json`의 `mcpServers.aside` 등록 + 재시작이 필요하다고 알린다.
- Aside 브라우저에서 ChatGPT에 로그인돼 있어야 한다(무료 계정도 하루 소량 생성 가능, 자주 많이 만들면 유료 플랜 권장). 실행 중 로그인 화면이 뜨면 멈추고 사용자에게 직접 로그인을 요청한다(비밀번호를 대신 입력하지 않는다). 비로그인 상태는 로그인 유도 화면만 뜨고 생성이 안 된다.
## 입력에서 확정할 것
- 무엇을 그릴지(장면·소재). 애매하면 한 줄로 되묻는다.
- 스타일. 기본은 요청 톤을 따른다. 실사 요청이면 먼저 photoreal 스킬로 프롬프트를 설계한다.
- 저장 경로. 삽입이면 대상 문서와 같은 폴더에 저장하고 상대경로로 넣는다.
- 삽입 여부와 위치(자리표시자·문단 기준). 삽입이 아니면 생성만 하고 파일 경로를 알린다.
## 프롬프트 원칙
- 맨 앞에 대문자로 금지문을 둔다: `NO TEXT, NO LETTERS, NO WORDS, NO NUMBERS`. 필요한 글자는 나중에 이미지 위에 얹는다.
- 장면을 구체적으로(무엇이·어디에·어떤 빛), 팔레트를 한 줄로 고정, 비율을 명시(예: 16:9 landscape).
- 실사면 photoreal 원칙(자연광, 과한 보정 없음, 살짝 치우친 구도, 미세한 비대칭)을 반영한다.
- 유명 IP 캐릭터는 ChatGPT가 거부한다. 걸리면 소재 변경을 사용자에게 확인한다. 우회하지 않는다.
## 절차 (mcp__aside__repl로 수행)
REPL은 하나의 영속 스코프를 공유하므로 호출마다 변수명을 새로 쓴다. `page.$`·`page.waitForTimeout`은 없다. 대기는 `await new Promise(r => setTimeout(r, ms))`.
### 1. 탭 열기
```js
await openTab('https://chatgpt.com/');
await new Promise(r => setTimeout(r, 4500));
const ready = await page.evaluate(() => !!document.querySelector('#prompt-textarea'));
```
`ready`가 false면 로그인 화면일 수 있다. 본문에 로그인/회원가입 버튼이 보이면 멈추고 사용자에게 로그인을 요청한다.
### 2. 프롬프트 입력·전송
```js
const prompt = "NO TEXT, NO LETTERS, NO WORDS, NO NUMBERS. <장면> <팔레트> centered composition, 16:9 landscape.";
await page.click('#prompt-textarea');
await new Promise(r => setTimeout(r, 400));
await page.keyboard.insertText(prompt); // fill 아님, contenteditable
await new Promise(r => setTimeout(r, 500));
await page.keyboard.press('Enter');
```
전송 뒤 `#prompt-textarea`의 길이가 0이면 전송된 것이다. 이미 다른 이미지가 대화에 있으면 그 파일 id를 기억해 3단계에서 제외한다.
### 3. 완성 폴링 (짧게 나눠서)
긴 루프 하나로 오래 돌리면 데몬 연결이 끊긴다. 한 호출당 약 40초로 끊어 새 `id=file_...`가 뜰 때까지 확인한다. GPT Image 2.5는 보통 15~120초.
```js
let done = null;
for (let i = 0; i < 10; i++) {
await new Promise(r => setTimeout(r, 5000));
const s = await page.evaluate((excl) => {
const main = document.querySelector('main');
const ids = Array.from(main.querySelectorAll('img')).map(im => im.src)
.filter(x => x.includes('estuary/content?id=file'));
const fresh = ids.filter(x => !excl.some(e => x.includes(e)));
const block = (main.innerText.match(/방지 조치를 위반|위반할 수 있습니다|생성할 수 없/gi) || []).length;
return { url: fresh[0] || null, block };
}, PREV_IDS /* 이전 이미지 file id 배열, 없으면 [] */);
if (s.url) { done = s; break; }
if (s.block >= 1) { done = s; break; } // 거부: 소재 변경 확인
}
```
한 이미지는 `<img>` 여러 개로 렌더되니 개수가 아니라 새 `id=file_...`로 완성을 판정한다.
### 4. 원본 반출 (display 경로)
화면의 것은 썸네일일 수 있다. 원본(`estuary/content?id=file...`)을 페이지 안에서 직접 받아 base64로 넘긴다. `public_content`는 쓰지 않는다.
```js
const out = await page.evaluate(async (u) => {
const res = await fetch(u, { credentials: 'include' });
const bytes = new Uint8Array(await res.arrayBuffer());
let bin = ''; const CH = 8192;
for (let i = 0; i < bytes.length; i += CH) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + CH));
return { b64: btoa(bin), size: bytes.length, ct: res.headers.get('content-type') };
}, done.url);
display('data:' + out.ct + ';base64,' + out.b64);
```
`display()`는 리사이즈 안 한 원본을 로컬 tmp에 저장하고 `Displayed image saved to: <절대경로>`로 경로를 반환한다. 그 경로를 복사 원본으로 쓴다(경로 하드코딩 금지, 반환값을 읽는다).
### 5. 저장
tmp 경로를 저장 위치로 복사한다. Windows는 `Copy-Item`, 맥은 `cp`.
## 삽입 (삽입 요청일 때)
- 마크다운(.md): 지정 위치에 ``. Obsidian 볼트면 `![[파일명.png]]`.
- HTML(.html): 자리표시자를 `<img src="파일명.png" alt="설명">`으로 교체.
- 이미지는 대상 문서와 같은 폴더에 두고 상대경로로 넣는다. alt(설명)를 반드시 채운다.
## 연결 끊김 복구
폴링 중 `page`가 null이거나 "not a function" 에러면 데몬 연결이 끊긴 것이다.
```js
const tabs = await listBrowserTabs();
const cg = tabs.find(t => t.url.includes('chatgpt.com'));
if (cg) { await attachBrowserTab(cg.targetId); } else { await openTab('https://chatgpt.com/'); }
```
이미 tmp에 받아 둔 파일은 남아 있으니 재연결 후 이어 간다.
## 마치며
생성만이면 저장 경로를, 삽입이면 삽입된 위치를 사용자에게 알린다. 프롬프트가 곧 자산이므로, 재사용 가치가 있으면 프롬프트 원문을 결과 옆에 짝으로 남긴다(볼트에서 작업 중이면 도메인 규약을 따른다).
여기까지 확인. Claude Code가 ~/.claude/skills/aside-image/SKILL.md 파일을 만들었다고 하면 됩니다.
연결 설정과 스킬은 프로그램을 다시 켜야 적용됩니다. 껐다 켠 뒤 준비가 됐는지 물어봅니다.
Claude Code를 완전히 종료했다가 다시 켭니다. 그런 다음 아래 문장을 그대로 물어봅니다.
aside 도구와 aside-image 스킬을 지금 쓸 수 있어? 되면 "준비됨"이라고만 답해줘.
준비됐다고 답하면 처음 한 번의 준비가 모두 끝난 것입니다. 이다음부터는 그냥 말만 걸면 됩니다.
여기까지 확인. "준비됨"이라고 답하면 됩니다. 안 된다고 하면 아래 "막히면"의 첫 항목을 봅니다.
준비가 끝났으니 첫 그림을 만듭니다. 스킬을 심어 뒀으니 긴 설명은 필요 없습니다. Claude Code에게 그리듯 말하면 됩니다. 괄호 안만 내 상황으로 바꿉니다.
(무엇을 그릴지)를 그려서 (저장할 폴더 경로)에 저장해줘. 예: 창가에 김이 오르는 가을 라떼, 낙엽과 니트 스카프, 따뜻한 분위기의 사진으로 그려줘.
스킬이 알아서 Aside로 ChatGPT를 열고, 그림 안에 글자가 들어가지 않게 주문하고, 완성된 원본을 받아 저장합니다. 당신은 무엇을 그릴지만 말하면 됩니다.
말하면 스킬이 ChatGPT에 주문을 넣고, ChatGPT 화면에 그림이 그려지기 시작합니다.
잠시 뒤 그림이 완성됩니다. 에이전트는 이 그림의 원본 파일을 받아 당신이 지정한 폴더에 저장합니다.
여기까지 확인. 에이전트가 알려 준 폴더에 그림 파일(그림.png)이 실제로 생겨 있으면 됩니다.
그림을 만드는 것과, 그 그림을 문서의 알맞은 자리에 넣는 것은 다른 동작입니다. 이제 넣는 동작을 시킵니다.
먼저 그림이 들어갈 문서를 준비합니다. 아래는 그림 자리를 비워 둔 소개 카드입니다. 위쪽 빗금 칸이 그림이 들어올 자리입니다.
이어서 이렇게 말하면 됩니다. 어디에 넣을지만 알려 주면 됩니다.
방금 만든 그림을 (문서 경로)의 (넣을 자리)에 넣어줘. 예: 방금 만든 그림을 소개.html 맨 위 이미지 자리에 넣어줘.
스킬이 문서의 빈 자리를 그림으로 바꿉니다. 비어 있던 카드가 완성된 문서가 됩니다.
아래는 정지 화면이 아니라 위에서 만든 실제 완성 문서입니다. 직접 스크롤해 보세요. 이 카드의 사진이 스킬로 만들어 넣은 그림입니다.
여기까지 확인. 문서를 브라우저로 열었을 때 빈 자리에 그림이 채워져 보이면 끝난 것입니다. 사람이 한 일은 말 몇 마디뿐입니다.
생성과 삽입을 한 번에 시켜도 됩니다. "가을 라떼 사진 그려서 소개.html 맨 위에 넣어줘"처럼 한 문장으로 말하면 스킬이 만들고 바로 넣습니다. 위 카페 카드에 실린 사진도 이 방식으로 스킬을 한마디로 발화시켜 실제로 만들어 넣은 결과입니다.
같은 도구라도 어떻게 말하느냐에 따라 결과가 달라집니다. 세 가지만 기억하면 됩니다.
무엇이, 어디에, 어떤 분위기인지 적습니다
"카페 사진"보다 "창가 나무 테이블 위 김이 오르는 라떼, 낙엽과 니트 스카프, 따뜻한 오후 햇살"이 훨씬 낫습니다. 장면을 구체적으로 그려 줍니다.
그림 안에 글자를 넣지 말라고 합니다
글자는 자주 뭉개집니다. 제목이나 이름은 그림 위에 나중에 따로 얹습니다.
여러 장을 만들어 고릅니다
같은 주문도 만들 때마다 조금씩 다릅니다. "각도와 거리를 바꿔서 세 장 만들어줘"라고 하면 그중 마음에 드는 것을 고를 수 있습니다.
실제로 자주 걸리는 것만 모았습니다.
에이전트가 aside 도구를 못 쓴다고 합니다
설정이 아직 적용되지 않은 것입니다. Claude Code를 완전히 종료했다가 다시 켭니다. 그래도 안 되면 .claude.json의 aside 블록에서 경로와 사용자 이름, 괄호 모양을 다시 확인합니다.
그림이 안 만들어지고 로그인 화면이 뜹니다
Aside 안의 ChatGPT가 로그아웃된 것입니다. Aside에서 chatgpt.com에 다시 로그인합니다. 로그인은 직접 하셔야 합니다.
특정 캐릭터가 계속 거부됩니다
유명 만화나 게임 캐릭터는 저작권 때문에 거부됩니다. 그 특징이 강하면 비슷하게 바꿔도 계속 걸립니다. 소재를 다른 것으로 바꿉니다.
그림 안 글자가 깨져 나옵니다
주문에 "그림 안에 글자를 넣지 마"라고 넣습니다. 필요한 글자는 완성된 그림 위에 따로 얹습니다.
그림이 마음에 안 듭니다
"조금 더 따뜻하게" "각도를 바꿔서 다시" 처럼 고칠 점만 말해 다시 시킵니다. 한 번에 안 나오는 것이 정상이니 몇 장 더 만들어 고릅니다.