monol-x - 진화하는 AI 개발 플랫폼

성과 기반 자연선택으로 스스로 진화하는 AI 에이전트 시스템

Claude Code와 함께 멀티 세션, 멀티 worktree 환경에서 효율적으로 작업하며, **18개의 Cell(모듈)**이 성과에 따라 자동으로 진화합니다.

📊 웹 대시보드 - 브라우저에서 Cell 관리 및 진화 시뮬레이션 📚 장기 작업 가이드 - 2시간+ 자율 작업 방법 🧬 진화 시스템 - Cell 진화 메커니즘

핵심 개념

┌───────────────────────────────────────────────────────────────────────┐
│                           monol-x v1.0                                │
├───────────────────────────────────────────────────────────────────────┤
│  Worktree   │  Session    │  Context   │  Evolution  │  Dashboard    │
│  ─────────  │  ─────────  │  ─────────  │  ─────────  │  ─────────    │
│  브랜치별    │  작업 단위   │  상태 저장  │  Cell 진화   │  웹 시각화    │
│  작업 공간   │  시작/종료   │  복원 가능  │  자연선택    │  실시간 관리  │
└───────────────────────────────────────────────────────────────────────┘

기본 기능

• Worktree: git worktree 기반 병렬 작업 공간
• Session: 작업 시작~종료 단위, Claude 세션과 연동
• Context: 작업 상태 스냅샷, 나중에 복원 가능
• Log: 빠른 메모, 일일/주간 리포트
• Condition: 조건 만족까지 장기 작업 지속 (Stop hook)

Cell 진화 시스템 (v0.7+)

• Cell: 독립적인 AI 에이전트 모듈 (18개)
• Genome: 능력 가중치 (coding, testing, core 등)
• Phenotype: 관찰 가능한 성과 (점수, 트렌드)
• Evolution: 성과 기반 자연선택, 변이 생성

웹 대시보드

브라우저에서 모든 Cell을 시각적으로 관리합니다.

# 대시보드 시작
monol dashboard start --open

# 상태 확인
monol dashboard status

# 종료
monol dashboard stop

대시보드 기능

| 탭 | 기능 | |-----|------| | Overview | 전체 Cell 현황, Diversity Score, Score Trends | | Cells | Cell 목록, 필터링, 상세 조회/편집 | | Evolution | 진화 시뮬레이션, Mutation 생성 | | Lineage | 계보 트리, 부모-자식 관계 | | Lessons | 레슨 포인트 분석 |

Cell 목록 (18개)

| Cell | Role | Score | |------|------|-------| | dev-senior | developer | 92.0 | | debugger-expert | developer | 88.0 | | architect-system | planner | 85.0 | | evaluator-core | evaluator | 85.0 | | ... | ... | ... |

전체 목록: monol evolution dashboard

설치

이미 설정됨:

• CLI: ~/.zshrc에 PATH 추가됨
• Plugin: ~/.claude/plugins/monol 심볼릭 링크

# 확인
which monol
ls -la ~/.claude/plugins/monol

CLI 사용법

초기화

cd /your/project
monol init

.monol/ 디렉토리가 생성됩니다.

대시보드

monol status    # 또는 mn st

모든 worktree, 현재 세션, 최근 활동을 한눈에.

Worktree 관리

# 목록 보기
monol wt list

# 새 worktree 생성
monol wt add feature-auth           # feature-auth 브랜치로 생성
monol wt add bugfix fix/bug-123     # fix/bug-123 브랜치로 생성

# worktree 제거
monol wt remove feature-auth

# 특정 worktree 상태
monol wt status feature-auth

Worktree 생성 후:

cd ../project-feature-auth    # 새 worktree로 이동
claude                        # Claude 세션 시작

세션 관리

# 세션 시작
monol hello "API 개발"        # focus 설정과 함께

# 세션 종료
monol bye "엔드포인트 3개 완성"

# 세션 상태 확인
monol session status

# Claude 세션 목록
monol session list

# 세션 검색
monol session search "API"

# 전체 worktree 세션 오버뷰
monol session overview

로그 기록

# 빠른 기록
monol log "인증 모듈 완료"

# 오늘 로그 보기
monol log today

# 최근 로그 목록
monol log list        # 최근 7일
monol log list 14     # 최근 14일

# 로그 검색
monol log search "인증"

# 일일 요약
monol log summary             # 오늘
monol log summary 2024-01-10  # 특정 날짜

# 주간 리포트
monol log weekly      # 이번 주
monol log weekly 1    # 지난 주

컨텍스트 관리

# 현재 상태 저장
monol ctx save checkpoint-1
monol ctx save "리팩토링 전" --description "대규모 변경 전 백업"

# 저장된 컨텍스트 목록
monol ctx list

# 컨텍스트 로드/확인
monol ctx load checkpoint-1

# 차이점 확인
monol ctx diff checkpoint-1

# monol.md 편집
monol ctx edit

조건 기반 장기 작업

# TODO 완료까지 작업 (가장 권장)
monol condition todo

# 테스트 통과까지
monol condition test "npm test"

# 빌드 성공까지
monol condition build "npm run build"

# 커스텀 스크립트
monol condition script ./check-ready.sh

# 복합 조건
monol condition multi --todo TODO.md --test "npm test"

# 상태 확인
monol condition status

# 강제 종료
monol condition stop

자세한 사용법: 장기 작업 가이드

Claude 플러그인 사용법

Claude Code 안에서 슬래시 커맨드로 사용:

세션

/mn-hello API 개발      # 세션 시작 + 상황 분석 + 제안
/mn-bye 작업 완료       # 세션 종료 + 요약

# 한국어 별칭
/안녕 API 개발
/바이 작업 완료

대시보드

/mn-status              # 전체 현황
/모놀                   # 한국어 별칭

Worktree

/mn-wt                  # worktree 목록
/mn-wt add feature-x    # 새 worktree
/mn-wt remove old-wt    # worktree 제거

로그

/mn-log API 완료        # 빠른 기록
/mn-log today           # 오늘 로그
/mn-log weekly          # 주간 리포트

/기록 메모 내용         # 한국어 별칭

컨텍스트

/mn-ctx save backup     # 상태 저장
/mn-ctx load backup     # 상태 복원
/mn-ctx list            # 목록

검색

/mn-search 키워드       # 로그, 세션, 컨텍스트 통합 검색

워크플로우 예시

1. 하루 시작

cd ~/Work/my-project
monol status              # 현황 파악

Claude에서:

/mn-hello 오늘 할 일

→ 이전 세션 요약, 미완료 작업, pull 필요 여부 등 자동 분석

2. 새 기능 작업

monol wt add feature-auth
cd ../my-project-feature-auth
claude

Claude에서:

/안녕 인증 모듈 개발

3. 작업 중 기록

/기록 JWT 토큰 발급 로직 완료
/기록 리프레시 토큰 구현 중

4. 컨텍스트 저장 (중요 지점)

/mn-ctx save before-refactor

5. 작업 종료

/바이 인증 모듈 1차 완성

6. 다른 worktree로 전환

cd ~/Work/my-project      # 메인으로
monol session overview    # 모든 worktree 세션 확인

7. 주간 리뷰

monol log weekly

디렉토리 구조

프로젝트 내 (.monol/)

project/
├── .monol/
│   ├── config.yaml       # 프로젝트 설정
│   ├── state.json        # 현재 상태
│   ├── sessions/         # 세션 기록
│   ├── contexts/         # 저장된 컨텍스트
│   ├── logs/             # 일별 로그 (YYYY-MM-DD.md)
│   └── worktrees/        # worktree 메타 정보
└── monol.md              # 프로젝트 컨텍스트 문서

글로벌 (~/.monol/)

~/.monol/
├── config.yaml           # 글로벌 설정
├── projects/             # 프로젝트 레지스트리
└── templates/            # 템플릿

팁

Worktree 네이밍 규칙

project/              # 메인 (main/master)
project-feature-x/    # 기능 개발
project-bugfix-123/   # 버그 수정
project-experiment/   # 실험

세션 관리

• 하나의 worktree = 하나의 Claude 세션 권장
• 세션은 자동으로 Claude 세션과 연동됨
• /mn-hello로 시작하면 이전 컨텍스트 자동 로드

로그 활용

• 짧게, 자주 기록
• 나중에 검색으로 찾기 쉽게
• 커밋 메시지 작성할 때 참고

컨텍스트 저장 타이밍

• 큰 변경 전
• 실험 시작 전
• 하루 끝날 때
• 브랜치 전환 전

커맨드 요약

| CLI | Claude | 설명 | |-----|--------|------| | monol init | - | 프로젝트 초기화 | | monol status | /mn-status, /모놀 | 대시보드 | | monol hello | /mn-hello, /안녕 | 세션 시작 | | monol bye | /mn-bye, /바이 | 세션 종료 | | monol wt * | /mn-wt | Worktree 관리 | | monol log | /mn-log, /기록 | 로그 기록 | | monol ctx * | /mn-ctx | 컨텍스트 관리 | | monol session * | - | 세션 관리 | | monol condition * | /mn-condition, /조건 | 장기 작업 조건 | | - | /mn-search | 통합 검색 |

조건 타입 상세

기본 조건

| 타입 | 사용 시점 | 완료 조건 | |------|----------|-----------| | todo | 명확한 작업 목록이 있을 때 | 모든 [ ] → [x] | | test | 테스트 통과가 목표일 때 | 테스트 명령어 성공 (exit 0) | | build | 빌드 성공이 목표일 때 | 빌드 명령어 성공 (exit 0) | | script | 커스텀 검증이 필요할 때 | 스크립트 exit 0 |

파일/패턴 조건

| 타입 | 사용 시점 | 완료 조건 | |------|----------|-----------| | file | 특정 파일 생성이 목표일 때 | 지정 파일 존재 | | no_file | 특정 파일 삭제가 목표일 때 | 지정 파일 없음 | | no_pattern | 코드에서 패턴 제거가 목표일 때 | 코드에서 패턴 사라짐 |

복합 조건 (multi)

여러 조건을 동시에 만족해야 할 때:

# TODO 완료 + 테스트 통과 + 빌드 성공
monol condition multi \
  --todo TODO.md \
  --test "npm test" \
  --build "npm run build"

# TODO 완료 + 코드에서 TODO 주석 제거
monol condition multi \
  --todo TODO.md \
  --no-pattern "// TODO:" "**/*.ts"

쉘 통합

프롬프트에 세션 상태 표시

현재 활성 세션을 쉘 프롬프트에 표시합니다:

# 프롬프트 확인
monol prompt          # [🎪 focus]
monol prompt full     # [🎪 branch:focus]

# zshrc/bashrc에 추가
monol prompt install

# 제거
monol prompt uninstall

설치 후 프롬프트 예시:

[🎪 API 개발] ~/Work/project $

자동완성 설정

# zsh 사용자
echo 'source <(monol completion zsh)' >> ~/.zshrc

# bash 사용자
echo 'source <(monol completion bash)' >> ~/.bashrc

# 적용
source ~/.zshrc  # 또는 ~/.bashrc

자동완성 기능:

• 커맨드/서브커맨드 완성 (Tab)
• worktree 이름 동적 완성
• context 이름 동적 완성
• git 브랜치 동적 완성

문제 해결

monol 명령어가 없다고 나올 때

source ~/.zshrc
# 또는 새 터미널 열기

Claude에서 /mn-* 커맨드가 안 될 때

# 플러그인 링크 확인
ls -la ~/.claude/plugins/monol

# Claude 재시작

jq 관련 에러

brew install jq

버전

• v1.0.0 (현재) - 안정화 및 문서 완성

  • Dashboard: 글로벌 에러 핸들러 추가
  • Docs: API 문서화, README 정리
  • Quality: 통합 테스트, 정합성 검증

• v0.9.0 - 도메인 에이전트 확장

  • Cells: debugger-core, documenter-core 추가
  • Docs: 웹 대시보드 시나리오 문서

• v0.8.0 - 웹 대시보드 + Cell 메타포

  • Dashboard: FastAPI 서버 + Vanilla JS 프론트엔드
  • Dashboard: Cell CRUD, Mutation 생성, Evolution 시뮬레이션
  • Terminology: Cell 생물학적 용어 체계
    • Module → Cell
    • Foundation Weights → Genome
    • Score/Traits → Phenotype

• v0.7.0 - 진화 시스템 강화

  • Evolution: 자동 진화 트리거
  • Cells: developer 롤 모듈 확장 (11개)
  • Feedback: 피드백 기반 자동 변이

• v0.6.0 - 고급 자동화

  • Automation: 컨텍스트 자동 복원, 스마트 요약
  • CI/CD: GitHub Actions, GitLab CI 연동

• v0.5.0 - 분석 및 인사이트

  • Analytics: 생산성 대시보드, AI 패턴 분석
  • Reports: 주간/월간 리포트 자동 생성

• v0.4.0 - 팀 협업

  • Team: 세션 공유, 멘션/알림, 활동 피드

• v0.3.0 - 진화적 에이전트 시스템

  • Foundation: 계층 구조 (core, git, logging, state, testing)
  • Module: 시스템, 세션 평가

• v0.2.0 - 조건 기반 장기 작업

  • Condition: TODO/Test/Build/Script 조건
  • Stop hook: 조건 만족까지 작업 지속

• v0.1.0 - 초기 버전

  • Core: config, worktree, session, context, log
  • CLI: monol/mn
  • Plugin: Claude Code 통합