워크플로우 허브는 코덱스 작업을 프로젝트별로 짧게 정리하는 로컬 우선 작업판입니다. 여러 저장소를 오가며 일할 때 지금 하는 일, 다음 행동, 끝낸 일, 보류한 판단, 실험 기록을 한곳에 남겨 다음 세션이 바로 이어받을 수 있게 합니다.
이 저장소는 파이썬 표준 라이브러리만 사용합니다. 기본 저장 위치는 ~/.codex/workflow-hub이며, 별도 서버나 데이터베이스 없이 파일로 상태를 보관합니다.
- 현재 폴더가 어떤 프로젝트인지 감지하고 프로젝트별 초점을 따로 유지합니다.
- 깃 작업, 배포 기준, 정책 변경, 장애 원인처럼 다음 세션에 꼭 필요한 일만 기록하도록 걸러줍니다.
- 완료 기록에는 다음 행동과 검증 근거를 같이 남기도록 유도합니다.
- 보류 아이디어, 실험 조건, 결정 기록을 현재 작업과 섞이지 않게 분리합니다.
- 웹 작업판을 띄워 프로젝트 목록, 작업 흐름, 패치노트, 실험, 검토할 판단을 빠르게 확인합니다.
- Workflow Hub: 현재 기준선, 실험 상태, 결정, 다음 행동의 운영 원본입니다.
- Git/Gitea: 코드, 설정, 산출물, 재현 가능한 이력의 원본입니다.
- 패치 노트: 세션에서 무엇을 했는지 남기는 상세 참고 기록입니다.
- Qdrant 기억: 원본 기록을 찾기 위한 검색 색인이며 최종 판정 원본이 아닙니다.
- 오라클 검토: 반론과 대안을 주는 자문 자료이며 단독으로 최종 결정을 만들지 않습니다.
- 대시보드: 위 기록을 읽기 위한 화면이며 원본 저장소가 아닙니다.
- 파이썬 3.11 이상
- 깃: 프로젝트 감지, 원격 저장소 연결, 완료 기록 링크 확인에 사용
- 지원 운영체제: macOS 또는 Linux (
fcntl파일 잠금 사용) - 선택 사항:
pytest,ruff(python -m pip install -e '.[dev]') - 선택 사항: Gitea 원격 동기화 환경변수
실행 시 추가로 설치해야 하는 의존성은 없습니다. 개발과 검증을 할 때만 pytest, ruff 같은 보조 도구가 필요합니다.
git clone <github-repository-url> workflow-hub
cd workflow-hub
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
wf init
wf dashboard네트워크가 막힌 환경에서 --no-build-isolation 옵션으로 설치해야 한다면 먼저 빌드 도구를 준비합니다.
python -m pip install setuptools wheel
python -m pip install --no-build-isolation -e .웹 작업판을 보고 싶다면 다음 명령을 실행합니다.
wf serve --host 127.0.0.1 --port 8787브라우저에서 http://127.0.0.1:8787/을 엽니다.
무인 상태 점검은 http://127.0.0.1:8787/healthz를 사용합니다. 응답에는 상태, 버전, 등록 프로젝트 수, 최근 초점 갱신 시각, 복구 대기 여부가 들어 있습니다. 정상은 ok, 이전 쓰기 작업이 비정상 종료된 상태는 recovery_pending, 상태 파일을 읽지 못하면 HTTP 503과 error를 반환합니다. 서비스는 포트를 열기 전에 복구 대기 상태를 자동 정리합니다. 화면 시간은 기본적으로 서울 시간이며 WORKFLOW_HUB_TIMEZONE으로 바꿀 수 있고, 잘못된 값은 서울 시간으로 안전하게 되돌아갑니다. 과거 주소 리다이렉트가 필요할 때만 WORKFLOW_HUB_LEGACY_HOSTS(쉼표 구분)와 WORKFLOW_HUB_REDIRECT_HOST를 함께 지정합니다.
저장소 안에서 바로 확인할 수도 있습니다.
./bin/wf init
./bin/wf dashboard
./bin/wf serve --host 127.0.0.1 --port 8787bin/wf는 현재 저장소 위치를 기준으로 파이썬 경로를 잡고, .venv, Homebrew, 시스템 순서로 Python 3.11 이상을 선택합니다. 서비스처럼 인터프리터를 고정하려면 WORKFLOW_HUB_PYTHON에 실행 파일 경로를 지정합니다. 따라서 /Users/kimrin/src/workflow-hub가 아닌 다른 폴더에 복제해도 그대로 실행됩니다.
wf init
wf detect --cwd "$PWD"
wf guard pre --cwd "$PWD" --intent "배포 전 설치 설명과 검증 절차를 정리"
wf set-focus --project workflow-hub --stage verification --reason "설치 검증 진행" --next-action "새 환경에서 설치 꾸러미 확인"
wf park --project workflow-hub --title "후속 아이디어" --summary "나중에 다시 볼 내용"
wf decision --project workflow-hub --decision "배포 문서는 한국어 README를 기준으로 둔다" --rationale "사용자가 바로 읽고 설치할 수 있어야 한다" --made-by user
wf experiment --project workflow-hub --title "요약 프롬프트 확인" --condition "같은 샘플에서 프롬프트 하나만 바꾼다" --criterion "핵심 누락이 줄어야 한다" --result "구조 검증은 통과" --status planned --execution-status generated --machine-verdict passed --human-verdict pending --disposition active --review-request-source user --baseline-ref "decision:baseline-1" --changed-axis prompt
wf review-pending --project workflow-hub
wf finish --project workflow-hub --summary "설치 설명과 검증을 정리했다" --next-action "원격 저장소에 올릴지 정한다"
wf migrate --project workflow-hub --dry-run
wf sync-gitea --project workflow-hub
wf audit continuity --cwd "$PWD"
wf dashboard
wf servewf audit continuity는 코덱스 작업기록의 최근 의도와 허브의 실제 기록을 비교해, 기록 대상인데 허브에 남지 않은 흐름을 드러냅니다. 사전 점검은 완료, 보류 아이디어, 결정, 실험 같은 실제 기록으로 세지 않습니다. 기본 작업기록 위치는 ~/.codex/worklog/projects이며, 다른 위치를 쓰려면 WORKFLOW_HUB_WORKLOG_DIR를 지정합니다.
실험 기록은 산출 완료와 사용자 판정을 분리합니다. 새 기록에서는 --execution-status, --machine-verdict, --human-verdict, --disposition을 함께 써서 실행 상태, 기계 검증, 사용자 판정, 처분을 따로 남깁니다. 사용자 결론이 아직 없으면 --status planned --execution-status generated --human-verdict pending --disposition active --review-request-source user처럼 검토 요청 출처까지 명시해야 wf review-pending에 판정 대기 실험으로 잡힙니다. 결과가 있다는 이유만으로는 판정 대기가 생기지 않습니다. --status done은 사용자가 accepted, rejected, inconclusive 중 하나로 결론을 낸 뒤에만 쓰며, --human-verdict-source user로 결론 출처를 함께 남깁니다.
wf finish는 완료 기록만 남기며 원격 저장소를 만들거나 푸시하지 않습니다. Gitea 반영은 wf sync-gitea --project <slug>로 명시 실행합니다. 이때 승인된 gitea-prmorx 원격과 코덱스가 만든 커밋 표식이 있어야 푸시합니다. 코덱스가 제안한 결정은 기본적으로 needs_user_review가 되며, 사용자가 승인한 결정은 --made-by user를 붙입니다.
wf migrate --project <slug> --dry-run은 과거 프로젝트 파일을 실제로 고치지 않고, 추가될 필드와 진단만 보여줍니다. 전체 데이터 마이그레이션은 사용자 확인 전에는 건식 실행만 허용합니다.
기본값은 다음과 같습니다.
~/.codex/workflow-hub/
active_focus.yaml
config.yaml
registry.yaml
recovery_state.yaml
recovery_pending.yaml # 쓰기 도중에만 존재하며 비정상 종료 시 다음 시작에서 복구에 사용
events.jsonl
guard_checks.jsonl
decisions.jsonl
ideas.jsonl
experiments.jsonl
projects/
다른 위치에 저장하려면 WORKFLOW_HUB_DIR를 지정합니다.
WORKFLOW_HUB_DIR=/tmp/workflow-hub-demo wf init
WORKFLOW_HUB_DIR=/tmp/workflow-hub-demo wf dashboard작업기록 비교 위치만 바꾸려면 WORKFLOW_HUB_WORKLOG_DIR를 지정합니다.
WORKFLOW_HUB_WORKLOG_DIR=/tmp/codex-worklog/projects wf audit continuity --project workflow-hubGitea 동기화는 선택 기능입니다. 값을 지정하지 않으면 로컬 기록만 남습니다.
export WORKFLOW_HUB_GITEA_BASE_URL="http://example.local:3000"
export WORKFLOW_HUB_GITEA_REMOTE_NAME="gitea-prmorx"
export WORKFLOW_HUB_GITEA_OWNER="local"
export WORKFLOW_HUB_GITEA_SSH_HOST="gitea-prmorx"
export WORKFLOW_HUB_GITEA_REMOTE_TEMPLATE="ssh://{host}/{owner}/{repo}.git"
export WORKFLOW_HUB_GITEA_TOKEN="..."WORKFLOW_HUB_GITEA_TOKEN은 저장소에 넣지 마세요. 셸 환경, 비밀값 저장소, 실행 환경 설정에만 둡니다.
uv run --extra dev pytest
uvx ruff check .
python -m pip wheel . --no-deps -w /tmp/workflow-hub-wheel다른 환경 설치 점검은 새 가상환경에서 만든 설치 꾸러미(wheel)를 설치해 확인합니다.
python3 -m venv /tmp/workflow-hub-install
/tmp/workflow-hub-install/bin/python -m pip install /tmp/workflow-hub-wheel/workflow_hub-0.1.0-py3-none-any.whl
WORKFLOW_HUB_DIR=/tmp/workflow-hub-data /tmp/workflow-hub-install/bin/wf init
WORKFLOW_HUB_DIR=/tmp/workflow-hub-data /tmp/workflow-hub-install/bin/wf dashboardREADME.md가 프로젝트 목적, 설치 방법, 실행 방법, 환경변수, 검증 명령을 설명한다.pyproject.toml에 빌드 도구, 콘솔 명령, 꾸러미 데이터가 선언되어 있다.workflow_hub/fixtures/demo_dashboard.json가 설치 꾸러미(wheel)에 포함된다.bin/wf에 개발자 개인 경로가 들어 있지 않다..playwright-cli/,output/,.pytest_cache/,.venv/,dist/,*.egg-info/같은 지역 산출물이 커밋되지 않는다.- 비밀값은 환경변수로만 전달하고 저장소에 넣지 않는다.
- 원격 저장소 주소와 공개 범위를 정한 뒤 필요하면 라이선스를 추가한다.
이 저장소는 로컬 설치와 설치 꾸러미(wheel) 설치가 가능한 파이썬 꾸러미 형태를 목표로 합니다. 다만 공개 저장소로 배포하려면 사용자가 라이선스와 GitHub 원격 저장소 주소를 정해야 합니다. 원격 생성, 푸시, 공개 전환은 이 저장소가 자동으로 하지 않습니다.