Claude Code HTTP Hooks: 웹앱으로 AI 에이전트 제어하기

안녕하세요, Tom입니다.

Claude Code 쓰면서 "이 작업 승인 여부를 웹 대시보드에서 관리할 수 있으면 좋겠는데..."라고 생각해본 적 있으세요?

이제 가능합니다. Claude Code에 HTTP Hook 기능이 추가되었습니다.

HTTP Hook이 뭔가요?

기존 커맨드 훅(Command Hook)은 강력하지만 복잡했습니다:

쉘 스크립트 작성 필요
보안 관리 까다로움
상태 공유 어려움

HTTP Hook은 이걸 완전히 바꿉니다:

Claude Code 이벤트 발생
 ↓
HTTP POST → 웹 서버 (localhost도 가능)
 ↓
웹 서버가 응답 (승인/거부/수정)
 ↓
Claude Code가 응답에 따라 행동

왜 이게 중요한가?

1. 웹앱으로 제어 가능

// Express.js 예시
app.post('/claude-hook', (req, res) => {
 const { event, context } = req.body;
 
 if (event.type === 'file_write') {
 // 파일 쓰기 승인 여부를 웹 대시보드에서 확인
 if (isDangerousPath(event.path)) {
 res.json({ approved: false, reason: 'Sensitive file' });
 } else {
 res.json({ approved: true });
 }
 }
});

이제 브라우저에서 실시간으로:

Claude Code가 뭘 하려는지 확인
승인/거부 버튼 클릭
로그 확인 및 저장

2. 팀 단위 권한 관리

데이터베이스 ←→ 웹 서버 ←→ Claude Code

중앙 DB로 권한 관리: 누가 어떤 작업을 승인했는지 추적
팀원과 공유: 같은 웹앱으로 여러 Claude Code 인스턴스 제어
감사 기록: 모든 이벤트를 DB에 저장

3. 복잡한 로직도 쉽게

쉘 스크립트로는 어려웠던 것들:

REST API 호출
데이터베이스 쿼리
복잡한 조건문
실시간 알림

웹 서버에서는:

모든 npm 패키지 사용 가능
Prisma, TypeORM 등으로 DB 연동
TypeScript로 타입 안전하게
Slack/Discord 웹훅 바로 연동

실전 활용 예시

예시 1: 민감한 파일 보호

// hooks/file-protection.ts
const PROTECTED_PATHS = [
 '.env',
 'secrets/',
 'config/production.yml'
];
 
app.post('/hook', async (req, res) => {
 if (req.body.event.type === 'file_write') {
 const path = req.body.event.path;
 
 if (PROTECTED_PATHS.some(p => path.includes(p))) {
 // Slack으로 알림 전송
 await slackNotify({
 text: ` Claude Code가 민감한 파일 수정 시도: ${path}`,
 channel: '#security'
 });
 
 return res.json({
 approved: false,
 message: '민감한 파일은 수동 승인이 필요합니다.'
 });
 }
 }
 
 res.json({ approved: true });
});

예시 2: 비용 관리

// hooks/cost-tracking.ts
app.post('/hook', async (req, res) => {
 const { event, context } = req.body;
 
 // API 호출 비용 추적
 if (event.type === 'api_call') {
 const cost = estimateCost(event.model, event.tokens);
 
 await db.usage.create({
 data: {
 userId: context.user,
 model: event.model,
 tokens: event.tokens,
 cost: cost
 }
 });
 
 // 일일 한도 체크
 const todayTotal = await db.usage.sum({ where: { 
 userId: context.user,
 date: new Date()
 }});
 
 if (todayTotal > DAILY_LIMIT) {
 return res.json({
 approved: false,
 message: '오늘 일일 한도를 초과했습니다.'
 });
 }
 }
 
 res.json({ approved: true });
});

예시 3: 작업 승인 대시보드

// 실시간 승인 대시보드
app.get('/dashboard', (req, res) => {
 res.render('dashboard', {
 pendingActions: await getPendingActions()
 });
});
 
// 웹소켓으로 실시간 이벤트 전송
io.on('connection', (socket) => {
 socket.on('approve', async (eventId) => {
 await approveEvent(eventId);
 io.emit('event_approved', eventId);
 });
});

로컬호스트도 가능!

가장 좋은 점:

# 1. 로컬에서 웹 서버 실행
npm run dev # http://localhost:3000
 
# 2. Claude Code 설정
claude-code --http-hook=http://localhost:3000/hook

외부 서버 필요 없음. 개발 머신에서 바로 테스트 가능합니다.

기존 커맨드 훅과 비교

기능	커맨드 훅	HTTP 훅
설정 난이도	높음 (스크립트)	낮음 (웹 API)
복잡한 로직	어려움	쉬움
팀 공유	어려움	쉬움
실시간 대시보드	불가능	가능
보안 관리	복잡함	명확함 (HTTP)
디버깅	어려움	쉬움 (로그/UI)

시작하기

공식 문서 확인 Claude Code Hooks Reference
간단한 서버로 시작

import express from 'express';
 
const app = express();
app.use(express.json());
 
app.post('/hook', (req, res) => {
console.log('Event:', req.body);
res.json({ approved: true });
});
 
app.listen(3000);

Claude Code 연결

claude-code --http-hook=http://localhost:3000/hook

마무리하며

HTTP Hook는 Claude Code를 "혼자 쓰는 도구"에서 "팀이 관리하는 인프라"로 바꿔줍니다.

특히:

민감한 작업이 많은 프로덕션 환경
여러 사람이 Claude Code를 쓰는 팀
승인 프로세스가 필요한 조직

에서 정말 유용할 것 같습니다.

여러분은 어떤 Hook을 만들어보고 싶으신가요?

이 글은 Geeknews에서 발견한 내용을 정리한 것입니다. 원본은 여기에서 확인할 수 있습니다.