시작하기

아무것도 없는 상태에서 동작하는 HarneesLab 설정까지 필요한 모든 것을 다룹니다. Web UI를 선호하든 CLI를 선호하든 이 문서에서 시작할 수 있습니다.

HarneesLab은 HarneesLab fork를 바탕으로 반복 가능한 AI coding workflow harness와 학습 가능한 에이전트 워크플로를 실험하기 위한 문서 사이트입니다. public brand, package scope, CLI binary는 HarneesLab 기준으로 전환되었고, repo-local .harneeslab/ directory와 harneeslab-* workflow/command namespace는 호환성을 위해 유지합니다.

---

사전 준비

시작하기 전에 다음이 준비되어 있는지 확인하세요.

요구 사항	확인 방법	설치 방법
Git	git --version	git-scm.com
Bun (Node.js + npm 대체)	bun --version	Linux/macOS: curl -fsSL https://bun.sh/install | bash — Windows: powershell -c "irm bun.sh/install.ps1 | iex"
Claude Code CLI	claude --version	docs.claude.com/claude-code/installation — compiled HarneesLab binaries에서는 CLAUDE_BIN_PATH도 설정하세요(자세히 보기)
GitHub account	—	github.com

root로 실행하지 마세요. HarneesLab과 HarneesLab이 의존하는 Claude Code CLI는 root 사용자로 실행할 때 동작하지 않습니다. VPS나 서버에 root만 있다면 먼저 일반 사용자를 만드세요.

adduser harneeslab          # create user (Debian/Ubuntu)
usermod -aG sudo harneeslab # give sudo access
su - harneeslab             # switch to the new user

그런 다음 새 사용자 세션 안에서 이 가이드를 이어가세요.

Windows 사용자: HarneesLab은 Windows에서 네이티브로 실행됩니다. WSL2는 필요하지 않습니다. Git Bash가 포함된 Git for Windows와 Bun for Windows를 설치하세요. 한 가지 주의할 점은 DAG workflow의 bash: 노드에는 bash 실행 파일이 필요하다는 것입니다. Git Bash가 이를 자동으로 제공합니다.

Bun은 Node.js를 대체합니다. Node.js나 npm을 별도로 설치할 필요가 없습니다. 이 프로젝트에서 Bun은 런타임, 패키지 매니저, 테스트 러너 역할을 모두 합니다. 이미 Node.js가 있어도 괜찮지만 HarneesLab은 사용하지 않습니다.

---

1단계: clone 및 설치

먼저 HarneesLab 서버 코드를 둘 위치를 선택합니다.

옵션 A: Home directory (개인 사용, 단일 사용자)

Linux/macOS:

cd ~  # 또는 원하는 directory
git clone https://github.com/NewTurn2017/HarneesLab
cd HarneesLab

Windows (PowerShell):

cd $HOME  # 또는 원하는 directory
git clone https://github.com/NewTurn2017/HarneesLab
cd HarneesLab

옵션 B: /opt (Linux/macOS 서버 설치 — 디렉터리를 깔끔하게 유지)

sudo mkdir -p /opt/harneeslab
sudo chown $USER:$USER /opt/harneeslab
git clone https://github.com/NewTurn2017/HarneesLab /opt/harneeslab
cd /opt/harneeslab

그런 다음 의존성을 설치합니다.

bun install

monorepo 전체의 의존성이 설치됩니다. 보통 약 30초가 걸립니다.

---

2단계: 인증 설정

GitHub token(저장소 clone용)과 Claude authentication(AI assistant용) 두 가지가 필요합니다.

GitHub Token

1. github.com/settings/tokens로 이동합니다.
2. **“Generate new token (classic)“**을 클릭합니다.
3. scope로 **repo**를 선택합니다.
4. token을 복사합니다(ghp_...로 시작).

Claude 인증

이미 Claude Code를 사용하고 있다면 대부분 인증이 끝난 상태입니다. 다음으로 확인하세요.

claude --version

인증되어 있지 않다면:

claude /login

브라우저 흐름을 따라 로그인하세요. 자격 증명은 전역으로 저장되므로 API key가 필요하지 않습니다.

---

3단계: .env 파일 만들기

Web UI / server mode에서는 필수, CLI-only 사용에서는 선택 사항입니다. CLI는 기본적으로 기존 Claude authentication을 사용합니다.

cp .env.example .env

에디터에서 .env를 열고 다음 두 값을 설정합니다.

# Paste your GitHub token in both (they serve different parts of the system)
GH_TOKEN=ghp_your_token_here
GITHUB_TOKEN=ghp_your_token_here

# Use your existing Claude Code login
CLAUDE_USE_GLOBAL_AUTH=true

여기까지면 충분합니다. 나머지는 합리적인 기본값이 있습니다.

• Database: ~/.harneeslab/harneeslab.db의 SQLite(자동 생성, 추가 설정 없음)
• Port: API server는 3090, Web UI dev server는 5173
• AI assistant: Claude(기본값)

GitHub token 변수가 왜 두 개인가요? GH_TOKEN은 GitHub CLI(gh)가 사용하고, GITHUB_TOKEN은 HarneesLab의 GitHub adapter가 사용합니다. 둘 다 같은 값으로 설정하세요.

---

실행 방식 선택

경로 A: Web UI (Server)

4단계: server 시작

bun run dev

이 명령은 두 가지를 동시에 시작합니다.

• Backend API server: http://localhost:3090
• Web UI: http://localhost:5173

다음과 비슷한 출력이 보여야 합니다.

[server] Hono server listening on port 3090
[web] VITE ready in Xms
[web] Local: http://localhost:5173/

Homelab / remote server인가요? backend API는 기본적으로 이미 0.0.0.0에 bind되므로 다른 머신에서 접근할 수 있습니다. 하지만 Vite dev server(Web UI)는 localhost에서만 listen합니다. 네트워크에서 Web UI를 노출하려면:

bun run dev:web -- --host 0.0.0.0

그런 다음 bun run dev:server로 backend를 별도로 시작하세요. Web UI는 http://<server-ip>:5173에서 접근할 수 있습니다. 방화벽에서 5173과 3090 포트를 허용했는지 확인하세요.

5단계: 동작 확인

브라우저에서 **http://localhost:5173**을 엽니다. HarneesLab Web UI가 보여야 합니다.

빠른 검증 체크리스트:

1. Health check — 새 터미널에서:

   curl http://localhost:3090/health
   # 예상 응답: {"status":"ok"}

2. Database 확인:

   curl http://localhost:3090/health/db
   # 예상 응답: {"status":"ok","database":"connected"}

3. 테스트 메시지 보내기 — Web UI에서 새 conversation을 만들고 다음을 입력합니다.

   /status

   platform type과 session info가 포함된 status response가 보여야 합니다.

세 가지가 모두 동작하면 실행 준비가 끝난 것입니다.

6단계: repository clone 후 coding 시작

Web UI chat에서 작업할 repo를 clone합니다.

/clone https://github.com/user/your-repo

그다음 AI에게 자연어로 말하면 됩니다.

What's the structure of this repo?

AI가 codebase를 분석하고 응답합니다. workflow도 사용할 수 있습니다.

/workflow list

사용 가능한 모든 workflow가 표시됩니다. 하나를 시도해 보세요.

Help me understand the authentication module

AI router가 메시지에 맞는 workflow를 자동으로 선택합니다.

---

경로 B: CLI (No Server)

4단계: CLI를 전역 설치

cd packages/cli && bun link && cd ../..

이 명령은 어느 repository에서나 실행할 수 있도록 hlab 명령을 전역 등록합니다.

Success! Registered "@harneeslab/cli" 출력 뒤에 bun link @harneeslab/cli에 관한 메시지가 보일 수 있습니다. 그 두 번째 부분은 무시하세요. 다른 프로젝트에서 HarneesLab을 dependency로 추가할 때 쓰는 안내입니다.

Bun은 linked binary를 ~/.bun/bin/에 설치합니다. hlab 명령을 찾을 수 없다면 아직 그 디렉터리가 PATH에 없는 것입니다. 다음처럼 고치세요.

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

동작을 확인합니다.

hlab version

5단계: repository에서 workflow 실행

cd /path/to/your/repository

# 사용 가능한 workflow 목록
hlab workflow list

# codebase에 대해 질문
hlab workflow run harneeslab-assist "How does the auth module work?"

# isolated branch에서 feature 계획
hlab workflow run harneeslab-feature-development --branch feat/dark-mode "Add dark mode"

# GitHub issue 수정
hlab workflow run harneeslab-fix-github-issue --branch fix/issue-42 "Fix issue #42"

여기까지입니다. CLI는 git repo를 자동 감지하고, 상태 추적에는 SQLite(~/.harneeslab/harneeslab.db)를 사용하며, 출력은 stdout으로 streaming합니다.

대상 디렉터리는 git repository여야 합니다. HarneesLab은 격리를 위해 git worktree를 사용하므로 .git 폴더가 필요합니다. 프로젝트가 아직 git repo가 아니라면 먼저 git init && git add . && git commit -m "initial commit"을 실행하세요.

---

CLI 참고 자료

workflow 실행 예

# 사용 가능한 workflow 목록
hlab workflow list

# workflow 실행
hlab workflow run <name> "<message>"

# worktree isolation 사용(코드 변경에 권장)
hlab workflow run <name> --branch <branch-name> "<message>"

# isolation 없이 live checkout에서 직접 실행
hlab workflow run <name> --no-worktree "<message>"

# 다른 directory를 대상으로 실행
hlab workflow run <name> --cwd /path/to/repo "<message>"

CLI 명령

명령	기능
hlab chat <message>	orchestrator에 message를 보냅니다
hlab setup	credentials와 config를 위한 interactive setup wizard를 실행합니다
hlab workflow list	사용 가능한 workflow 목록을 표시합니다
hlab workflow run <name> [msg]	workflow를 실행합니다
hlab workflow status	실행 중인 workflow를 표시합니다
hlab workflow resume <id>	실패한 workflow를 재개합니다
hlab workflow abandon <id>	terminal 상태가 아닌 run을 abandon합니다
hlab workflow approve <id> [comment]	interactive loop gate를 승인합니다
hlab workflow reject <id> [--reason "..."]	approval gate를 거절합니다
hlab workflow cleanup [days]	오래된 run record를 삭제합니다(기본: 7일)
hlab workflow event emit	workflow event를 emit합니다
hlab isolation list	active worktree 목록을 표시합니다
hlab isolation cleanup [days]	stale environment를 제거합니다
hlab isolation cleanup --merged	merge된 branch를 제거합니다
hlab isolation cleanup --merged --include-closed	closed(abandoned) PR branch도 함께 제거합니다
hlab complete <branch>	branch lifecycle을 완료합니다
hlab validate workflows [name]	workflow definition을 검증합니다
hlab validate commands [name]	command file을 검증합니다
hlab version	version info를 표시합니다

Worktree 관리

hlab isolation list                         # active worktree 표시
hlab isolation cleanup                      # stale worktree 제거(7일 초과)
hlab isolation cleanup 14                   # custom staleness threshold
hlab isolation cleanup --merged             # merge된 branch 제거(remote도 삭제)
hlab isolation cleanup --merged --include-closed  # closed/abandoned PR branch도 제거
hlab complete <branch>                      # branch lifecycle 완료(worktree + branch)
hlab complete <branch> --force              # uncommitted-changes check 건너뛰기

사용 가능한 Workflows

Workflow	기능
harneeslab-assist	일반 Q&A, debugging, 탐색, CI failure 등을 처리하는 범용 workflow
harneeslab-fix-github-issue	조사, root cause analysis, fix 구현, validation, PR 생성
harneeslab-idea-to-pr	feature idea를 plan, implement, validate하고 PR과 parallel review, self-fix까지 수행
harneeslab-plan-to-pr	기존 plan을 실행하고 implement, validate, PR, review까지 진행
harneeslab-feature-development	plan에서 feature를 구현하고 validate한 뒤 PR 생성
harneeslab-comprehensive-pr-review	automatic fix를 포함한 multi-agent PR review(5개 parallel reviewer)
harneeslab-smart-pr-review	복잡도에 맞춰 관련 agent만 route하는 PR review
harneeslab-create-issue	문제를 classify하고 context 수집, investigate 후 GitHub issue 생성
harneeslab-validate-pr	main과 feature branch 양쪽을 테스트하는 철저한 PR validation
harneeslab-resolve-conflicts	PR의 merge conflict를 detect, analyze, resolve
harneeslab-refactor-safely	type-check hook과 behavior verification을 포함한 안전한 refactoring
harneeslab-architect	architecture sweep, complexity reduction, codebase health 점검
harneeslab-ralph-dag	PRD implementation loop(story가 끝날 때까지 반복)
harneeslab-issue-review-full	GitHub issue를 위한 comprehensive fix와 full multi-agent review
harneeslab-test-loop-dag	모든 test가 통과할 때까지 반복하는 test-fix cycle
harneeslab-remotion-generate	AI로 Remotion video composition 생성 또는 수정
harneeslab-interactive-prd	guided conversation을 통해 PRD 생성
harneeslab-piv-loop	human-in-the-loop 방식의 guided Plan-Implement-Validate development
harneeslab-adversarial-dev	adversarial development로 완전한 application을 처음부터 구축

이 bundled workflow들은 대부분의 프로젝트에서 바로 사용할 수 있습니다. 커스터마이즈하려면 .harneeslab/workflows/defaults/에서 하나를 .harneeslab/workflows/로 복사해 수정하세요. 같은 이름의 파일은 기본값을 override합니다.

자동 선택: workflow 이름을 외울 필요가 없습니다. 원하는 일을 설명하기만 하면 router가 모든 workflow description을 읽고 가장 적합한 것을 선택합니다. 예를 들어 “fix issue #42”는 harneeslab-fix-github-issue로 route되고, “review this PR”은 harneeslab-smart-pr-review로 route됩니다. 명확히 맞는 것이 없으면 harneeslab-assist로 fallback합니다.

---

대상 repo 커스터마이즈

대상 repo에 .harneeslab/ 디렉터리를 추가해 repo-specific 동작을 정의할 수 있습니다.

your-repo/
└── .harneeslab/
    ├── config.yaml         # AI assistant, worktree copy rule
    ├── commands/            # custom command(.md files)
    └── workflows/           # custom multi-step workflow(.yaml files)

예시 .harneeslab/config.yaml:

assistant: claude
commands:
  folder: .claude/commands/harneeslab    # 추가 command search path
worktree:
  copyFiles:
    - .env.example                   # worktree에 같은 이름으로 복사
    - .env

.harneeslab/ config가 없어도 platform은 합리적인 기본값(bundled commands와 workflows)을 사용합니다.

custom command 만들기

repo의 .harneeslab/commands/에 .md 파일을 두세요.

---
description: 전체 test suite 실행
argument-hint: <module>
---

# Test Runner

다음 대상을 테스트하세요: $ARGUMENTS

사용 가능한 변수: $1, $2, $3(positional), $ARGUMENTS(전체 args), $ARTIFACTS_DIR(workflow artifacts directory), $WORKFLOW_ID(run ID), $BASE_BRANCH(base branch), $nodeId.output(DAG node output).

custom workflow 만들기

repo의 .harneeslab/workflows/에 .yaml 파일을 두세요.

name: my-workflow
description: feature를 계획한 뒤 구현
model: sonnet

nodes:
  - id: plan
    command: plan

  - id: implement
    command: implement
    depends_on: [plan]
    context: fresh

workflow는 여러 command를 DAG node로 연결하고, parallel execution과 conditional branching을 지원하며, $nodeId.output substitution으로 node 간 context를 전달합니다.

commands와 workflows는 어디에서 load되나요?

commands와 workflows는 runtime에 현재 working directory에서 load됩니다. 고정된 global location에서 load되지 않습니다.

• CLI: hlab 명령을 실행한 위치에서 읽습니다. local repo에서 실행하면 uncommitted change도 즉시 반영됩니다.
• Server (Telegram/Slack/GitHub): ~/.harneeslab/workspaces/owner/repo/의 workspace clone에서 읽습니다. 이 clone은 worktree 생성 전에만 remote에서 sync되므로 server가 변경 사항을 보려면 commit and push가 필요합니다.

요약하면 CLI는 local files를 보고, server는 push된 내용을 봅니다.

---

격리 (Worktrees)

--branch flag를 사용하면 CLI가 git worktree를 만들어 격리된 디렉터리에서 작업합니다. 이렇게 하면 parallel task끼리 또는 main branch와 충돌하지 않습니다.

~/.harneeslab/
├── harneeslab.db              # SQLite database(자동 생성)
└── workspaces/            # project 중심 layout
    └── owner/repo/
        ├── source/        # clone 또는 local path symlink
        ├── worktrees/     # task별 격리 worktree
        │   ├── fix/issue-42/
        │   └── feat/dark-mode/
        ├── artifacts/     # workflow artifact(git에 넣지 않음)
        └── logs/          # workflow execution log

---

Claude Code와 함께 사용하기 (Skill)

Claude Code가 대신 HarneesLab workflow를 호출할 수 있게 하려면 프로젝트에 HarneesLab skill을 설치하세요. setup wizard가 이를 자동으로 처리합니다. hlab setup을 실행하고 skill installation prompt를 승인하면 됩니다.

수동으로 설치하려면:

cp -r HarneesLab/.claude/skills/hlab /path/to/your/repo/.claude/skills/

그런 다음 Claude Code에서 “use hlab to fix issue #42”처럼 말하면 적절한 workflow를 호출합니다.

---

전체 platform 실행 (Server + Chat Adapters)

CLI는 standalone으로 동작하지만 Telegram, Slack, Discord, GitHub webhooks로도 상호작용하고 싶다면 README의 시작하기를 보거나, HarneesLab repo에서 Claude Code를 열고 “Set up HarneesLab”이라고 말해 setup wizard를 실행하세요.

---

문제 해결

”Cannot create worktree: not in a git repository” (but the repo exists)

실제 원인은 보통 이전 HarneesLab run에서 다른 path를 사용해 생긴 stale symlink입니다. error output에서 다음 내용을 찾아보세요.

Source symlink at ~/.harneeslab/workspaces/.../source already points to <old-path>, expected <new-path>

~/.harneeslab/workspaces/<github-user>/<repo-name>의 stale workspace folder를 수동으로 삭제한 뒤 명령을 다시 실행하면 해결됩니다.

앞으로는 hlab isolation cleanup이 이를 자동으로 처리할 예정입니다.

---

”command not found: bun”

Bun을 설치하세요: curl -fsSL https://bun.sh/install | bash. 그런 다음 터미널을 재시작하거나 source ~/.bashrc를 실행하세요.

”command not found: claude”

Claude Code CLI를 설치하세요. docs.claude.com/claude-code/installation을 참고하세요.

Port 3090 already in use

다른 프로세스가 포트를 사용 중입니다. 해당 프로세스를 중지하거나 port를 override하세요.

PORT=4000 bun run dev

Web UI shows “disconnected”

backend가 실행 중인지 확인하세요(bun run dev는 backend와 frontend를 모두 시작합니다). terminal에서 error를 확인하고, browser를 새로고침해 보세요.

Clone command fails with 401/403

GitHub token이 없거나 유효하지 않습니다. 다음을 확인하세요.

# Test your token
curl -H "Authorization: token $(grep GH_TOKEN .env | cut -d= -f2)" https://api.github.com/user

GitHub profile이 반환되면 token이 동작하는 것입니다. 아니라면 새로 발급하세요.

AI doesn’t respond

Claude authentication이 동작하는지 확인하세요.

claude --version   # version이 보여야 함
claude /login      # 필요하면 다시 인증

”Cannot find module” or dependency errors

bun install

그래도 해결되지 않으면 node_modules 폴더를 삭제한 뒤 다시 설치하세요.

bun install

---

빠른 참고표

작업	명령
전체 시작	bun run dev
backend만 시작	bun run dev:server
frontend만 시작	bun run dev:web
test 실행	bun run test
type check	bun run type-check
전체 validation	bun run validate
Web UI	http://localhost:5173
API server	http://localhost:3090
Health check	curl http://localhost:3090/health

---

다음 단계

chat platform 추가 (선택)

휴대폰에서 HarneesLab에 message를 보내고 싶다면 다음 중 하나를 선택하세요.

플랫폼	난이도	가이드
Telegram	쉬움(5분)	adapter 설정
Discord	쉬움(5분)	adapter 설정
Slack	중간(15분)	adapter 설정
GitHub Webhooks	중간(15분)	adapter 설정

custom command와 workflow 만들기

HarneesLab이 실행할 수 있는 AI prompt를 repo에 추가하세요.

your-repo/
└── .harneeslab/
    ├── commands/        # AI instruction을 담은 Markdown file
    └── workflows/       # command를 연결하는 YAML workflow

workflow 작성과 command 작성을 참고하세요.

server에 배포

어느 device에서나 항상 접근하려면 Docker 배포 가이드를 참고하세요.

---

더 읽을거리

• 설정 — 모든 configuration option
• AI 어시스턴트 — Claude와 Codex setup 상세
• CLI 참고 자료 — 전체 CLI documentation
• workflow 작성 — custom workflow 만들기