plasma-ai/fractal

fractal – 계층적 자율 에이전트 루프

무엇인가요

Git worktree 트리로 재귀적 자율 에이전트를 실행할 수 있는 Python 라이브러리 및 CLI입니다. 트리의 각 노드는 독립적인 에이전트 루프이며, 하위 작업을 위해 자식 노드를 생성할 수 있어 문제의 규모에 맞게 성장하는 프랙탈 구조를 형성합니다.
모든 실행은 로컬 SQLite 데이터베이스에 기록되며, 터미널 기반 UI(TUI)를 통해 검사하거나 제어할 수 있습니다.

작동 방식

루트 노드 – 현재 Git 브랜치가 최상위 "사용자" 노드로 작동합니다 (자신의 worktree를 가지지 않습니다).
생성 – /fractal 스킬(또는 fractal CLI)을 통해 자연어 지시를 내립니다. 에이전트는 지시를 분석하고 필요한 매개변수를 요청한 후, 자식 노드용 새 Git worktree를 생성합니다.
반복 – 각 노드는 tmux 세션 내에서 자율 루프를 실행하며, 지원되는 LLM 백엔드(Claude, Codex, Grok, OpenCode, Oh My Pi) 중 하나를 호출합니다. 루프는 반복, 코드 커밋, 명령 실행, 더 많은 자식 생성이 가능합니다.
제한 – 반복 횟수, 깊이, 자식 수, 시간, 비용에 대한 제한이 있으며, 모든 루프는 제한됩니다. 예산은 실행 및 단계별로 강제되며, 정리용 예약도 선택적으로 가능합니다.
추적 – 모든 반복, 단계, 비용, 신호는 단일 SQLite 파일에 저장됩니다. TUI 대시보드는 트리 구조를 시각화하고 실시간 메트릭을 표시하며, 노드의 일시정지/정지가 가능합니다.

주요 기능

재귀적 자율 조직화 – 노드가 추가 노드를 생성할 수 있어 시스템이 문제에 맞게 구조를 적응시킬 수 있습니다.
다중 LLM 백엔드 – Claude, Codex, Grok, OpenCode, Oh My Pi 지원. OpenRouter를 통한 선택적 라우팅도 가능합니다.
세밀한 제어 – 각 노드별로 최대 반복 수, 최대 깊이, 타임아웃, 비용 상한, 범위 등 설정 가능.
Git 중심 워크플로우 – 각 노드는 독자적인 Git worktree에서 작동하므로 커밋은 브랜치 단위로 격리되어 푸시하거나 로컬에 유지 가능합니다.
터미널 UI – 실시간 대시보드(fractal open)로 트리, 비용, 진행 상황을 확인할 수 있습니다.
스킬 통합 – Claude Code 또는 Codex 에이전트에 /fractal 스킬을 설치 가능하여 자연어로 노드를 생성할 수 있습니다.
보안 경고 – 노드는 기본적으로 권한 확인 프롬프트 없이 실행됩니다. README는 신뢰할 수 없는 작업은 반드시 신뢰할 수 있는 또는 일시적인 호스트에서 실행하도록 강조합니다.

설치

# PyPI에서 (패키지 이름은 "plasma-fractal"이지만 "fractal" 엔트리 포인트도 제공)
pip install plasma-fractal   # 또는: pip install fractal

# 격리된 설치(pipx, uv)의 경우 보조 패키지 "plasma-wiki"도 설치
pipx install plasma-fractal && pipx install plasma-wiki
# 또는 uv로:
uv tool install plasma-fractal --with-executables-from plasma-wiki

설치 후, fractal init으로 초기화된 프로젝트 루트에서 fractal open을 실행하세요 (README는 초기화된 fractal을 전제로 합니다).

일반적인 워크플로우

# 대시보드 열기 (라이트 테마는 선택 사항)
fractal open --light

# TUI 또는 스킬을 통해 지시를 내립니다. 예:
/fractal spawn name=docgen path=./docs title="API 문서 생성" agent=claude max-iters=5

# 시스템은 다음을 수행합니다:
#   • 지시를 분석하고 누락된 필드를 요청
#   • ./docs 아래에 새 Git worktree 생성
#   • Claude 에이전트 루프를 실행하는 tmux 세션 시작
#   • 각 반복을 SQLite DB에 기록
#   • 대시보드에서 진행 상황 표시

fractal node stop <name> 명령이나 UI 상호작용을 통해 노드를 중지, 일시정지, 조정할 수 있습니다.

보안 및 제한 사항

노드는 권한 확인 프롬프트 없이 실행됩니다. 즉, LLM은 시작 사용자의 자격 증명으로 호스트에서 어떤 명령도 실행할 수 있습니다. README는 신뢰할 수 없는 작업은 반드시 사전에 제거 가능한 환경에서 실행하도록 경고합니다.
비용 제한은 강제되지만, USD 기준으로 실행당만 적용됩니다. 비용 폭주를 방지하려면 적절한 max-cost 값을 설정해야 합니다.
시스템은 외부 LLM 제공업체에 의존하므로, 네트워크 접근과 API 키(예: OPENROUTER_API_KEY)가 필요합니다.

문서 및 커뮤니티

공식 문서: https://docs.plasma.ai/fractal
PyPI 페이지: https://pypi.org/project/plasma-fractal/
소스 코드: https://github.com/plasma-ai/fractal (Apache‑2.0 라이선스)

누가 사용할 수 있나요

대규모 코드베이스 리팩터링, 문서 생성, 다단계 AI 기반 작업에 자동화되고 자기 조직화된 워크플로우를 원하는 개발자.
계층적 AI 에이전트 아키텍처를 탐구하는 연구자.
이미 Claude, Codex 또는 기타 지원되는 LLM을 사용하고 있으며 Git과의 더 밀접한 통합을 원하는 팀.

위의 모든 세부 정보는 리포지토리의 README에서 직접 인용되었으며, 추가 기능은 추측되지 않았습니다.

plasma-ai/fractal

fractal – 계층적 자율 에이전트 루프

관련