FlowAgent - Orquestrador de Fluxos de Trabalho Local
wndnjs3865/flowagent
Orquestrador de fluxos de trabalho local para PMEs coreanas - zero dados na nuvem
Ver no GitHubPlataforma local-first para automação de fluxos de trabalho de escritório em coreano, voltada para PMEs. Oferece 8 fluxos pré-construídos para equipes de administração, vendas e executivos, executados completamente no laptop sem enviar dados para nuvem. Funciona via YAML + Claude API, com interface web e execução em tempo real.
Instalação
npx convez-ai wndnjs3865/flowagent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de reuniões e relatórios semanais
- Triagem e resposta automática de emails de vendas
- Processamento de cotações e follow-ups para freelancers
- Geração diária de resumos de vendas para executivos
- Automação de respostas em redes sociais
Veredito

Projeto bem-pensado para o contexto coreano com foco em privacidade local e usabilidade sem código. Limitação: população de usuários restrita ao mercado coreano; arquitetura YAML é simples mas oferece pouca flexibilidade comparada a orquestradores enterprise como n8n.
README
A tradução para o português deste README ainda está na fila.
FlowAgent
A local-first Korean SMB workflow orchestrator — Run pre-built workflows for daily office work entirely on your laptop. Your company data never leaves the machine.
🌐 https://taskflow.kr — 다운로드 · 가격 · 문서 · 템플릿
회사 데이터는 노트북 안에만. 한국어 사무 자동화, 8 워크플로 · 3 페르소나 즉시 사용 가능.
🎉 2026-05-20 출시 — A 사무직 · B 1인 자영업·프리랜서 · D SMB 사장 3 페르소나 카드 모두 작동.
⬇ 다운로드 · 📖 문서 · 💰 가격 · 🎯 8 워크플로 · 📝 LICENSE · ™ TRADEMARK
한 화면 요약
페르소나별 진입
| 페르소나 | 진입 페이지 | 핵심 워크플로 |
|---|---|---|
| A 사무직 · 총무 · 운영팀 | /sumu | meeting-actions · weekly-report · approval-triage |
| B 1인 자영업 · 프리랜서 | /solo | quote-email · sales-followup · sns-replies |
| D SMB 사장 · 대표 | /executive | sales-summary (매일) · weekly-report (받는 입장) |
공통: sales-summary·inquiry-triage는 페르소나 비중만 다를 뿐 3 페르소나 모두 사용. 자세한 매핑은 Bundled workflows.
차별점 (한국 시장 유일)
- 회사 데이터가 노트북 밖으로 안 나감 (local-first) — Notion AI·ChatGPT·뤼튼은 클라우드 SaaS.
- 한국어 사무 워크플로 8종 번들 — n8n·Make·Zapier는 빈 페이지에서 시작.
start.bat더블클릭 진입 — 비개발자도 5분 안에 첫 결과.
반복 업무 스트레스를 줄이는 로컬 워크플로우 러너. LLM 호출과 셸 명령을 YAML 한 파일로 엮어 브라우저에서 실행하고, 결과를 SSE로 실시간 스트리밍합니다. 단일 사용자·단일 머신·DAG 없음·큐 없음.
빠른 시작
권장: taskflow.kr/download에서 zip 받기 → 압축 풀고 start.bat 더블클릭. Anthropic API 키만 입력하면 끝.
개발자: git clone https://github.com/wndnjs3865/flowagent.git && pnpm install && pnpm dev
도메인 용어 (Workflow, Step, Run, Runner, Agent) 는 CONTEXT.md 에 정의돼 있어요. 코드, 커밋, PR 제목에서 그대로 사용하세요.
어디부터 읽어야 하나요?
이 README는 두 종류의 독자를 위해 분리돼 있습니다. 본인 경로만 따라가시면 됩니다.
| 누구 | 시작 위치 | 목표 |
|---|---|---|
| 일반 사용자 (비개발자, 사무·총무·영업지원) — 노트북에서 8 워크플로 데모를 직접 돌려보고 싶음 | 바로 아래 일반 사용자용 5분 시작 가이드 | 설치 → 8 워크플로 데모 실행. customize는 미팅 신청으로 |
| 개발자 / Pilot 운영자 — 코드 수정, 새 워크플로우 작성, 미팅 시연·customize 진행 | Developer quickstart → Demo path (Pilot 운영자용) → Writing a workflow | 8 워크플로 외 사례를 yaml로, 4주 Pilot 진행, 코드 기여 |
위 두 경로 모두에 공통으로 유용한 섹션: 1분 데모 영상, Bundled workflows, Run logs, Limits.
일반 사용자 — 더블클릭 2번이면 끝
비개발자도 GitHub·PowerShell·터미널을 모르고 노트북에서 8 워크플로 데모를 직접 실행할 수 있게 만든 흐름.
1️⃣ 📦 flowagent ZIP 다운로드
위 큰 링크를 클릭하면 flowagent-main.zip 이 자동으로 받아집니다.
다운로드 폴더로 가서 zip 파일을 우클릭 → "모든 파일 압축 풀기" → 위치는 C:\flowagent 같이 한글·공백 없는 폴더 권장.
2️⃣ 압축 푼 폴더 안의 start.bat 더블클릭
다음 4단계가 자동으로 진행됩니다. 표 오른쪽 "본인이 할 일"만 해주시면 됩니다.
| 자동 진행 | 본인이 할 일 |
|---|---|
| Node.js 설치 여부 확인 | 없으면 nodejs.org가 자동으로 열림 → LTS 초록 버튼으로 설치한 뒤 start.bat 다시 더블클릭 |
| pnpm 자동 설치 (corepack 또는 npm) | (없음) |
메모장 자동 실행 → .env 파일 열림 | ANTHROPIC_API_KEY= 뒤에 본인 키 붙여넣고 Ctrl+S → 메모장 닫기 (키 발급 1분 — Create Key → sk-ant-… 복사) |
| 의존성 설치 + 서버 시작 + 브라우저 자동 열기 | 브라우저에 5장 카드 보이면 카드 1개 → Run |
검은 창은 닫지 마세요 — 서버가 꺼집니다.
(SmartScreen이 start.bat 실행 경고를 띄우면 추가 정보 → 실행.)
내 데이터 1개 넣어보기 (선택, 3분)
8 워크플로 모두 노트북 안 파일을 LLM 입력으로 씁니다. 그 파일을 본인 데이터로 같은 이름·같은 형식으로 덮어쓰면 본인 데이터 결과가 즉시 나옵니다.
| 워크플로우 | 바꿀 파일 | 형식 |
|---|---|---|
meeting-actions | workflows\fixtures\meeting-notes-2026-w19.md | 한국어 회의록 (.md) |
weekly-report | workflows\fixtures\weekly-progress-2026-w19.md | 한 주 진행 노트 (.md) |
sales-summary | workflows\fixtures\sales-2026-04.csv | CSV (Excel 저장 시 "CSV UTF-8") |
inquiry-triage | workflows\fixtures\inquiries-2026-05.csv | CSV — id,접수일시,고객명,문의내용 |
approval-triage | workflows\fixtures\inbox-approvals-2026-05.md | 결재 요청 (.md, ## REQ-001 형식) |
quote-email | workflows\fixtures\project-brief-2026-w20.md | 프로젝트 brief + 본인 단가 (.md) |
sales-followup | workflows\fixtures\client-meeting-2026-w22.md | 미팅 raw 노트 (.md) |
sns-replies | workflows\fixtures\sns-comments-2026-w23.md | SNS 댓글·DM raw export (.md) |
- 위 표에서 1개 선택 → Explorer에서 해당 파일 더블클릭해 열기
- 본인 데이터로 내용 바꾸고 저장
- 브라우저 새로고침 → 같은 카드 → Run
더 깊은 customize · 4주 Pilot
미팅 신청 → wndnjs3865@naver.com (또는 페이지 상단 Pilot 미팅 신청 배너). 30분 안에 귀사 데이터로 YAML 하나 함께 만들어 드립니다 — 회사 데이터는 노트북을 벗어나지 않습니다.
막힐 때
- "Node.js가 설치되지 않았습니다" → nodejs.org가 자동으로 열림. LTS 설치 후
start.bat다시 더블클릭. - 검은 창에 "API 키" 오류 → 폴더의
.env파일을 메모장으로 다시 열어ANTHROPIC_API_KEY=뒤 키 (앞뒤 공백·따옴표 없이) 확인 후 저장 →start.bat다시. - 브라우저 "사이트 연결 불가" → 검은 창에
FlowAgent listening on …줄 있는지 확인. 없으면start.bat다시 더블클릭. - 검은 창 닫혀버림 → 서버가 꺼졌습니다.
start.bat다시 더블클릭. - 한국어 깨짐 → 브라우저
Ctrl+R새로고침.
Developer quickstart
pnpm install
cp .env.example .env
# edit .env and put your Anthropic API key in ANTHROPIC_API_KEY=
pnpm dev
# open http://localhost:3000
.env is loaded automatically via tsx --env-file=.env — no dotenv dependency needed.
Required env:
| Var | Purpose |
|---|---|
ANTHROPIC_API_KEY | Used by llm steps. Without it, runs fail at the first llm step. |
PORT | HTTP port (default 3000). |
FLOWAGENT_WORKFLOWS_DIR | Directory scanned for *.yaml workflows (default workflows). |
FLOWAGENT_RUNS_DIR | Directory where per-run JSONL audit logs are written (default runs). Created on demand. |
FLOWAGENT_PILOT_CONTACT_EMAIL | Email used by the Listing page "Pilot 미팅 신청" CTA button. The server builds a mailto: link with a fixed Korean subject. Defaults to the FlowAgent official sales channel wndnjs3865@naver.com — override only if you fork for your own sales. |
FLOWAGENT_SHARE_SECRET | HMAC signing secret for /share/* URLs — used to send dashboard results to a phone (spec § 5 옵션 2). Must be at least 32 characters — shorter values throw at runtime. When unset, the share UI is hidden and /share/* routes return 503. Generate with openssl rand -base64 32 (or PowerShell [Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))) and keep it in .env, never commit. |
FLOWAGENT_PUBLIC_ORIGIN | Optional public origin (e.g. https://flowagent.example.com) used when building share URLs. Useful behind a reverse proxy where the Node server sees localhost but the user-facing URL is the public domain. When unset, x-forwarded-proto + x-forwarded-host headers are honored if both present, falling back to the request URL itself. |
1분 데모 영상
기본 5종 워크플로우 순회 데모. 노트북에서 5분 시작 → 실제 결과까지 한 화면. (B 페르소나 3종은 차기 영상에 포함 예정.)
영상 제작 가이드
영상은 직접 녹화·편집·업로드합니다. 절차는 다음 두 문서 따라가면 30분:
- Storyboard —
docs/sales/pilot-demo-storyboard.md— 초 단위 컷·내레이션·녹화 도구·편집 가이드·fallback. 사전 점검 60초 + 1분 분할 8단계. - Asset 호스팅 —
assets/README.md— GitHub Release 업로드 절차, 파일명 규약(pilot-demo-<용도>-<duration>.<ext>), 1MB 이상 바이너리는 repo commit 금지.
요약 흐름:
# 1. 사전 점검 (60초) — storyboard "사전 점검" 섹션 그대로
rm -f runs/*.jsonl && pnpm dev > /dev/null 2>&1 &
sleep 3 && curl -sf http://localhost:3000/ > /dev/null && echo OK
# 2. OBS / QuickTime으로 1920×1080 30fps 녹화 (storyboard 따라 75초 → 60초 컷 편집)
# 3. GitHub Release에 업로드
gh release create v0.1.0-demo --title "Pilot demo assets v0.1" \
--notes "1분 데모 영상" ./pilot-demo-1min.mp4
# 4. README 위 <video src="..."> 의 URL을 새 asset URL로 교체
gh release view v0.1.0-demo --json assets --jq '.assets[0].browser_download_url'
기본 5종 워크플로우 실시간 실행 검증 결과 (영상 storyboard 측정 기준): weekly-report 9초 / meeting-actions 10초 / sales-summary 15초 / inquiry-triage 24초 / approval-triage 17초 — 총 75초. 컷 편집으로 60초 압축. (B 페르소나 3종 timing은 차기 측정 시 추가.)
Demo path (Pilot 운영자용) — first run in 5 minutes
The fastest path from clone to a result you can show a Pilot stakeholder. Total: 5 minutes including prereqs, 3 minutes if Node/pnpm are already installed.
Prereqs (2 minutes)
- Node.js 20.6 or newer (
node --version) — needed fortsx --env-file. - pnpm (
npm i -g pnpmif missing). - Anthropic API key from https://console.anthropic.com/settings/keys.
Windows 사용자 안내 (PowerShell · cmd · Git Bash 모두 동일 동작)
이 프로젝트의 shell step은 OS-중립 node -e "..." 한 줄로 통일돼 있어 추가로 Git Bash·WSL 설치가 필요 없습니다. Windows 표준 PowerShell·cmd 어느 쪽에서도 8 워크플로 모두 그대로 동작합니다.
| 단계 | 명령 (PowerShell 또는 cmd) |
|---|---|
| 1. Node.js 설치 | https://nodejs.org/ "LTS" installer 또는 winget install OpenJS.NodeJS.LTS |
| 2. pnpm 설치 | npm i -g pnpm |
| 3. 프로젝트 받기 | git clone https://github.com/wndnjs3865/flowagent && cd flowagent |
| 4. 의존성 설치 | pnpm install |
5. .env 생성 | copy .env.example .env (cmd) 또는 Copy-Item .env.example .env (PowerShell) — 그 후 .env 열어 ANTHROPIC_API_KEY=sk-ant-... 붙여넣기 |
| 6. 서버 실행 | pnpm dev |
| 7. 브라우저 | http://localhost:3000 |
PowerShell 실행정책 이슈 시 — pnpm.ps1이 차단되면 한 번만:
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
이후 pnpm dev 정상. cmd에서는 이 문제 없음.
Steps (3 minutes)
git clone <this repo> && cd flowagentpnpm installcp .env.example .env, then open.envand paste your key intoANTHROPIC_API_KEY=sk-ant-...pnpm dev— you should seeFlowAgent listening on http://localhost:3000. Leave it running.- Open http://localhost:3000 in a browser. You'll see 5 bundled workflows in the list.
- Click
meeting-actions→ Run. Each step streams into the log box live (step-start→step-output→step-end). The full run takes ~20 seconds. - After the run finishes, open
runs/<runId>.jsonlin your editor. The exact events you just saw are on disk, one JSON object per line, ready to replay or share.
Try sales-summary for an executive-summary demo, inquiry-triage for a CS-desk demo, or
approval-triage for an office-manager demo. Each finishes in under 30 seconds.
What you should see at the end of step 6 (the Slack-format step of meeting-actions), in Korean,
ready to paste:
이번 주 액션 아이템 정리해드릴게요 👇
*이팀장*
• [5/16] 단골 고객 사은품 제공 방안 초안 작성
• [5/18] 쿠팡 광고비 재편성 안 회의 전 보고
*박매니저*
• [5/15] 마케팅 주니어 채용공고 초안 작성
...
Pilot meeting — pre-flight (30초 사전 점검)
미팅 30분 전, 화면 공유 시작 직전에 아래 4가지를 확인합니다. 라이브 시연이 끊기지 않게 하는 최소 가드.
# 1. API 키 동작 확인 — 빈 결과면 .env의 ANTHROPIC_API_KEY를 다시 확인
curl -s -o /dev/null -w "key=%{http_code}\n" -H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" https://api.anthropic.com/v1/models | grep -E "200|key="
# 2. 서버 살아있는지 — 200이어야 함
curl -s -o /dev/null -w "server=%{http_code}\n" http://localhost:3000/
# 3. runs/ 비어있는지 — 새 출력이 한눈에 보이게
ls runs/*.jsonl 2>/dev/null | wc -l # 0이면 OK, 아니면 mv runs runs.bak && mkdir runs
# 4. 브라우저 zoom 125%+ — 화면 공유 시 가독성
Pilot meeting — 3-minute live demo script (범용)
화면 공유하면서 아래 멘트를 순서대로 따라 읽으세요. 총 3분, 시연 3건.
(0:00, 인트로 — 20초) "FlowAgent는 노트북 한 대에서 도는 워크플로우 도우미예요. 회사 데이터를 외부 SaaS에 올리지 않습니다. 반복되는 사무 업무를 매일 같은 손으로 다시 하지 않게 만드는 게 목표예요."
(0:20, 시연 1 · meeting-actions — 50초) Run 누르며: "어제 회의록을 그대로 넣어 본 거예요. 단 몇 초 만에 담당자별 액션 아이템이 한국어로 정리되고, Slack에 그대로 붙여넣을 수 있는 형식까지 나옵니다."
(1:10, 시연 2 · sales-summary — 50초) Run 누르며: "이번엔 4월 매출 CSV예요. 채널별 이상치를 짚어주고, 경영진 보고용 3문장 요약이 자동으로 만들어집니다."
(2:00, 시연 3 · inquiry-triage — 50초) Run 누르며: "고객 문의 6건이에요. 카테고리·긴급도로 분류된 표가 먼저 나오고, 카테고리별 답변 초안까지 한 번에 만들어집니다. CS 담당자가 톤만 다듬으면 끝이에요."
(2:50, 클로징 — 30초)
runs/폴더 열며: "보시다시피 출력은 모두 자동으로 디스크에 저장됩니다. 한 달 뒤에 '이 자동화가 시간을 얼마나 아꼈는지' 리포트도 명령 한 줄로 뽑을 수 있어요. 다음 주에 귀사 데이터 1건으로 같이 만들어 보면 어떠세요?"
Persona-specific demo paths (시연 순서 갈아끼우기)
상대 회사가 어느 부서를 데려오는지 미리 알면 시연을 바꿔서 첫 임팩트를 최대화합니다.
| 상대 | 추천 시연 순서 (3분) | 클로징 강조점 |
|---|---|---|
| CS팀장 / 운영팀장 | inquiry-triage → meeting-actions → approval-triage | "매일 답변 톤 통일 + 우선순위 분류 + 결재 누락 방지" |
| 재무·총무·CFO | sales-summary → approval-triage → weekly-report | "월말 1-pager 자동화 + 결재 잔량 가시화 + 주간 보고 표준화" |
| 대표·실무 매니저 | weekly-report → meeting-actions → sales-summary | "보고 자동화 3종 세트 — 주간/회의/월간" |
| 잡탕(혼합) | 위 범용 스크립트 그대로 | 데이터 위치 + 5분 시작 + JSONL 감사 로그 |
장애 발생 시 30초 복구 (live 데모 도중)
| 증상 | 한 줄 복구 | 안 되면 |
|---|---|---|
step-end ... ok:false 첫 LLM 단계 실패 | "API 키 한도 초과예요" → weekly-report 대신 1단계만인 shell-only 사례로 우회 | runs/*.jsonl 미리 캡처해 둔 이전 성공 결과를 화면에 띄움 |
| 브라우저에 한국어 깨짐 | 새로고침 (Ctrl/Cmd+R) — Tailwind CDN 캐시 문제 90% | 다른 워크플로우로 즉시 전환, 깨짐은 미팅 후 처리 |
| SSE가 멈춤 (3초 이상 출력 없음) | "잠시 LLM 응답 대기 중입니다" 한 마디 + 우회로 다른 탭 열어 두 번째 워크플로우 Run | 첫 탭은 그대로 두고 두 번째 탭에서 진행 |
| 서버 자체 죽음 | 터미널 pnpm dev 재실행(2초) | "로컬 환경 변수가 꼬여서요" 솔직 + 캡처본으로 마무리 |
After demo — 30분 안에 보내는 leave-behind
- 이 README 링크 (
#demo-path-first-run-in-5-minutes로 anchor) docs/sales/pilot-onepager.md를 PDF로 변환해 첨부 — 한국어 폰트 포함:pandoc docs/sales/pilot-onepager.md -o docs/sales/pilot-onepager.pdf --pdf-engine=weasyprint --metadata title="FlowAgent — Pilot 1-pager"(사전 설치:apt-get install -y pandoc weasyprint)- 미팅 중 작성한 귀사 케이스 1건의 YAML 초안 (
workflows/<customer-slug>-draft.yaml형태로 첨부) - 다음 미팅 후보 일정 3개 (1주차 설치 미팅용)
- 다음 outreach·설치 미팅 제안 이메일 — 템플릿
docs/sales/pilot-outreach-email.md사용.{{회사명}}/{{담당자명}}/{{후보1·2·3}}/{{발신자명}}자리표시자만 치환하고 PDF 첨부 후 발송. Follow-up·Warm intro·설치 미팅 3가지 변형이 같은 파일 하단에 있음.
Bundled workflows
The workflows/ directory ships eight end-to-end workflows covering the most common Korean SMB
office tasks for all three target personas (A 사무직 · B 1인 자영업 · D 사장). All use Korean
fixtures under workflows/fixtures/ and English LLM prompts that emit Korean output
(see feedback_demo_fixture_language rule for why).
기본 5종 (A·D 페르소나 중심)
| Workflow | What it does | Persona (spec § 3) | 없애주는 반복 업무 스트레스 |
|---|---|---|---|
weekly-report | 한 주 진행 노트 → 4-section 구조화 → Slack 공유용 메시지 | 사무직 A ★★★ · 사장 D ★★ | 매주 같은 보고서를 처음부터 다시 쓰는 30분 |
meeting-actions | 회의록 → 담당자별 액션 표 → Slack 보고 포맷 | 사무직 A ★★★ · 사장 D ★★ | 회의 끝나고 회의록 다시 읽으며 액션을 추리는 인지 부하 |
sales-summary | 월간 매출 CSV → 채널·이상치 분석 → 경영진 3-문장 요약 | 사장 D ★★★ · 사무직 A ★★ · 자영업 B ★★ | 월말마다 이상치 찾고 1-pager 만드는 압박 |
inquiry-triage | 고객 문의 CSV → 카테고리·긴급도 분류 + 카테고리별 답변 초안 | 자영업 B ★★★ · 사무직 A ★★ | 매일 같은 톤으로 답변 쓰고 우선순위 매기는 피로 |
approval-triage | 결재 대기함 → 자동승인·검토·정보부족 분류 + 오늘의 brief | 사무직 A ★★★ · 사장 D ★★ | 결재함에 줄선 요청을 하나씩 읽고 판단하는 인지 부하 |
B 페르소나 신규 3종 — 출시 완료 (3/3)
| Workflow | What it does | Persona (spec § 3) | 없애주는 반복 업무 스트레스 |
|---|---|---|---|
quote-email | 프로젝트 brief + 본인 단가 가이드 → 견적 항목·금액 산정 → 고객 회신 메일 초안 | 자영업 B ★★★ | 매번 비슷한 견적 메일 다시 쓰며 단가·일정·세금 조건 빠뜨리는 불안 |
sales-followup | 고객 미팅·통화 raw 노트 → 다음 액션·약속·추가 견적 분리 + follow-up 메일 + 일정 제안 | 자영업 B ★★★ | 미팅 끝나고 머릿속 흩어진 액션·약속·다음 일정을 메모로 못 옮기는 부담 |
sns-replies | 인스타·블로그 한 주간 댓글·DM raw 목록 → 스팸 거름 + 카테고리별 답글 초안 + 협업·견적 lead 별도 추적 | 자영업 B ★★★ | 매일 들어오는 인스타 DM·블로그 댓글에 일일이 답글 톤 맞추고 스팸 거르고 진짜 lead 놓치지 않는 피로 |
To adapt one for a real Pilot case, edit the file in workflows/fixtures/ to the customer's own data —
the YAML prompts stay the same. The customer's data never leaves their machine.
Pilot 미팅 자리 customize 시드 (_pilot-draft-template.yaml) — 3분 가이드
귀사 사례 1건을 미팅 자리에서 같이 워크플로우로 만드는 시드. 비개발자도 운영자와 함께 3단계로 따라옵니다. 본인이 채우는 칸은 5개(한국어), 영문 LLM 프롬프트 4개는 운영자가 같이 채워줍니다.
1단계 — 복사 (PowerShell·터미널 한 줄, <회사> 자리에 본인 회사 영문 약어)
cp workflows/_pilot-draft-template.yaml workflows/acme-draft.yaml
2단계 — fixture 1건 두기
본인 데이터 파일(회의록 .md / 매출 .csv / 문의 .csv / 결재 .md 중 하나)을 아래 위치에 같은 이름으로 저장:
workflows/fixtures/acme-sample.md
3단계 — 자리표시자 채우기 (아래 표 참조)
| 채우는 사람 | placeholder | 예시 | 어디에 쓰임 |
|---|---|---|---|
| 본인 | {{customer-slug}} | acme | rename·fixture 파일명과 일치 (영문 소문자) |
| 본인 | {{확장자}} | md / csv | 위 fixture 확장자 |
| 본인 | {{담당자_페르소나}} | 운영 / 사무관리 | 카드 페르소나 필터 |
| 본인 | {{귀사가_겪는_반복_업무_한_줄}} | 매주 동일한 양식 보고서 다시 쓰기 | 카드 stressRelieved |
| 본인 | {{회사명}} | Acme | 결과 wrap 헤더 |
| 본인 | {{워크플로우_제목}} | 주간 액션 정리 | 결과 wrap 헤더 |
| 운영자 | {{입력_종류_영문}} | a Korean weekly meeting note | 2단계 LLM prompt |
| 운영자 | {{추출_목표_영문}} | every action item with owner and deadline | 2단계 LLM prompt |
| 운영자 | {{출력_형식_영문}} | Korean Markdown table | 2단계 LLM prompt |
| 운영자 | {{전달_채널_영문}} | Slack-ready Korean message | 4단계 LLM prompt |
완료 후 — 브라우저 listing(/) 새로고침 → 새 카드 자동 등장 → Run.
_ prefix 파일은 listing/route에서 자동 제외 (src/workflows-dir.ts). 시드 자체는 listing에 안 보이고 /workflows/_pilot-draft-template·/run 모두 404. 데모 중 미완성 placeholder가 고객에게 노출될 위험 없음. 별도 비공개 시드를 더 두려면 동일하게 _ prefix로 시작하는 파일명을 사용.
Writing a workflow
Drop a <name>.yaml file in workflows/. The filename (without extension) becomes the URL slug; the
name: field is the human-readable label shown in the UI. See
workflows/weekly-report.yaml for a working 3-step demo.
name: my-workflow
description: One-line summary shown on the list page.
steps:
- type: llm
name: draft # optional, used in event logs
prompt: |
Write a haiku about workflows.
- type: shell
name: wrap
command: |
node -e "process.stdout.write('=== Output ===\n' + {{prev}} + '\n')"
- type: llm
prompt: |
Translate to Korean:
{{prev}}
{{prev}} substitution rules
{{prev}} is replaced with the previous Step's output. Different rules per step type:
-
llmstep —{{prev}}is spliced into the prompt string verbatim. No escaping needed. -
shellstep —{{prev}}is replaced with the JS expressionprocess.env.FLOWAGENT_PREV, and the previous output is passed via the child process's environment. The shell command must be anode -e "..."one-liner — this makes commands cross-platform (PowerShell, cmd, Git Bash, sh, bash all execute identically) and neutralizes backticks,$(),$VAR, and semicolon chains inside untrusted LLM output because Node reads the value at runtime instead of the shell tokenizing it.# ✅ Recommended — Node one-liner reads prev as a JS expression command: | node -e "process.stdout.write({{prev}})" # ✅ Wrap with a banner command: | node -e "process.stdout.write('=== Header ===\n' + {{prev}} + '\n=== End ===\n')" # ✅ Load a fixture file (replaces `cat <path>` from sh-only workflows) command: | node -e "process.stdout.write(require('fs').readFileSync('workflows/fixtures/data.csv','utf8'))" # ❌ Avoid — sh-specific, fails on Windows PowerShell/cmd command: printf '%s' "{{prev}}" command: cat workflows/fixtures/data.csvPlace
{{prev}}unquoted as a bare token inside the Node expression — it expands to a JS variable, not a string literal.
Project layout
src/
spec.ts # Zod schema + loadWorkflow(filePath) — YAML → typed Workflow
runner.ts # runWorkflow() — sequential execution + SSE-style event callback
runners.ts # createDefaultRunners() — wires llm + shell step runners
workflows-dir.ts # listWorkflows(dir) — file scanner
server.ts # Hono app factory (env-driven)
main.ts # HTTP entry — @hono/node-server bind
routes/
workflows.ts # GET /, GET /workflows/:name, POST /workflows/:name/run (SSE)
steps/
llm.ts # Anthropic SDK call
shell.ts # child_process.exec with FLOWAGENT_PREV env-var injection
views/
layout.tsx # Tailwind CDN shell
index.tsx # workflow list page
run.tsx # workflow detail page + SSE client
error.tsx # 404 / 500 page
workflows/ # *.yaml — your workflows live here
runs/ # <runId>.jsonl — one line per SSE event, written live
docs/adr/ # architecture decisions
.claude/ # project skills, agents, commands (Claude Code config)
Run logs
Every workflow run streams its events live to runs/<runId>.jsonl as well as over SSE. One JSON object
per line, in event order: step-start, step-output, step-end (× number of steps), then done. The
file basename equals the runId reported in the done event.
# Replay the most recent run
tail -n +1 "$(ls -t runs/*.jsonl | head -1)" | jq .
# Show just the outputs for a given run
jq -r 'select(.kind=="step-output") | .output' runs/<runId>.jsonl
Disk writes happen before SSE writes, so the log stays complete even if the client disconnects mid-run.
Pilot use — turning run logs into a monthly automation report
Pilot customers often want proof that automation actually saved time. The JSONL format makes this a one-liner:
# How many runs this month, and which workflows?
ls runs/2026-05-*.jsonl | wc -l
jq -r '.step.name // empty' runs/*.jsonl | sort | uniq -c | sort -rn
# Pull every Slack-ready output from this month for archival
jq -r 'select(.kind=="step-output" and .index==3) | .output' runs/2026-05-*.jsonl
Pair this with a calendar reminder ("매월 1일 자동화 효과 리포트") and the customer has a recurring business-value artifact without touching the runner.
Development
pnpm test # vitest, one shot
pnpm test:watch # vitest watch
pnpm typecheck # tsc --noEmit
pnpm dev # tsx watch with .env autoload
pnpm start # production-ish single shot
Test layout mirrors source (*.test.ts next to the file). All step runners and routes have unit coverage;
the SSE route test exercises the full event sequence with fake runners.
Operating philosophy
See CLAUDE.md for the full agent-facing config. The short version:
- Align before you code —
/grillfor non-trivial requests. - Spec → Build → Review — one skill per lifecycle phase, see
.claude/skills/. - Maintainability first — code should be readable by a developer who lands on this repo cold. Prefer editing existing files; surface assumptions; sanitize at every trust boundary.
Limits (intentional, MVP scope)
- No DAG, no branching, no parallel steps. Linear only.
- No retry, no resume, no checkpointing.
- No auth — bind to localhost only.
- Run logs are not rotated or pruned — clean
runs/manually if it grows.