fluffles

Fluffles는 macOS용 자율 에이전트 하네스이자 실행 환경이다. Slack, 이메일, 전화 등 여러 채널을 통한 소통, 지속성 있는 작업 원장, 자체 복구 배포 파이프라인을 갖췄다.

이 저장소는 사용 중단됐다. Mac mini에서 실행되던 Fluffles 하네스의 공개 스냅샷이다. 현재 개발은 이 저장소와 코드를 공유하지 않는 순수 eve 재작성 버전인 DevelopIQ-ai/puffle-app으로 옮겨갔다. 이 저장소는 참고용으로 보존된다.

비밀 정보, 실제 실행 상태, 인증 정보는 이 저장소에 포함된 적이 없다. 환경별 식별자는 플레이스홀더로 대체했다.

포함 항목

  • AGENTS.md: 상시 적용되는 운영 계약과 정체성 규칙을 담는다.
  • agent/: channels/, executors/ 슬롯 파일로 패키지를 Fluffles 에이전트에 연결하는 구성 계층이다. 자세한 내용은 agent/agent.md를 참조한다.
  • automations/: 일정, 이벤트, HTTP 트리거, 수동 실행을 하나의 레지스트리로 관리하며, @fluffles/automations가 실행한다.
  • bin/: 하네스 CLI 명령을 정의하는 간단한 명령 래퍼를 둔다.
  • channels/: Slack, 이메일, 전화 어댑터와 웹훅 수신 서비스(channels/webhooks/), 로컬 채팅 콘솔(channels/chat-console/)을 포함한 모든 리스너를 둔다.
  • config/: config/context-limits.json 같은 하네스 설정을 둔다.
  • deploy/: 시스템 실행과 검증에 필요한 모든 항목을 둔다. launchd 서비스 정의, 호스트 파일, 고정된 Executor(deploy/executor/), 검증 스크립트(deploy/scripts/, deploy/scripts/verify-source.sh 포함)가 여기에 속한다.
  • hooks/: Codex 훅 진입점을 둔다.
  • memory/: 메모리 프로토콜 문서, 지속성 있는 메모리 파일, 일일 메모를 둔다.
  • packages/: 독립형 기능 패키지(@fluffles/*)를 둔다. 자세한 내용은 packages/README.md를 참조한다.
  • skills/: 사용자가 작성한 운영 스킬을 둔다.
  • subagents/: 범위가 정해진 지침과 진입점을 갖춘 디렉터리형 전문 에이전트를 둔다.
  • state/: 런타임 상태 디렉터리의 뼈대만 추적한다. state/browser/도 포함하며 자세한 내용은 state/browser/README.md를 참조한다. 실제 상태 데이터는 머신에 남는다.
  • test/: 하네스 수준 테스트를 둔다.
  • tools/: 호출 가능한 도구 영역이다. MCP 매니페스트(tools/mcp/manifests/), 하네스 헌장(tools/capabilities/harness.json), 문서와 구현을 담은 도구별 디렉터리를 포함한다. 스모크 도구는 tools/smoke/, 통신 도우미는 tools/communications/에 있다.
  • projects/: Fluffles가 담당하는 프로젝트별 디렉터리를 둔다. 처음 포함된 프로젝트는 개인 사이트 소스인 projects/fluffles-site/다. 이 디렉터리는 ~/projects/에 설치되며, 배포 도구가 같은 위치에 보관하는 런타임 소유 체크아웃과 나란히 놓인다.

대화 턴은 하네스가 만들며 소스 관리 대상이 아닌 ~/work를 작업 디렉터리로 사용한다. Codex는 모델이 생성한 셸 쓰기 작업을 이 작업 디렉터리와 선언된 쓰기 가능 루트인 ~/projects, 임시 디렉터리로 제한한다. 따라서 턴은 Executor 데몬이 샌드박스 밖에서 실행하는 MCP 도구를 통해서만 작업 원장, 마크다운 메모리, ~/auth, 설치된 하네스에 접근한다.

제외 항목

  • $HOME/auth
  • $HOME/state의 내용(디렉터리 뼈대만 추적한다)
  • $HOME/Library
  • $HOME/.codex
  • $HOME/.amalgm
  • 원본 대화 기록, 로그, 캐시, 쿠키, 브라우저 프로필, OAuth 상태
  • 파생 메모리 인덱스(state/memory/index.sqlite)와 격리된 메모리 쓰기 내용
  • node_modules, 가상 환경, 외부 소스 페이로드, 생성된 앱 번들
  • 비공개 통신의 원본 내용

제외된 $HOME/auth와 $HOME/state 내용은 머신의 런타임 상태다. $HOME/auth에는 추적되는 미러가 없다. 이 디렉터리에는 Machine Identity 부트스트랩과 폐기 가능한 도구 소유 인증 상태만 들어가며, 자세한 설명은 packages/auth/INFISICAL.md에 있다. 추적되는 state/ 트리에는 디렉터리, 문서, 비밀 정보가 아닌 자동화 설정만 포함된다.

배포

모든 작업은 브랜치에서 진행하고, 풀 리퀘스트를 통해 main에 반영한다. GitHub 소스 검사는 모든 풀 리퀘스트에서 실행된다. 병합된 main 커밋만 배포 대상이 될 수 있다.

Mac mini는 로컬 com.puffle.harness.deploy-main launchd 서비스를 통해 매분 origin/main을 확인한다. 새 커밋을 검증하고 비밀 정보나 런타임 상태를 건드리지 않은 채 복사한 다음 서비스를 재시작하고 스모크 테스트를 수행한다. 스모크 테스트가 실패하면 이전 소스 관리 파일을 복원한다. 배포 트리거가 하나만 남도록 기존 deploy-main 자동화는 비활성화돼 있다.

Mac mini에서 사용할 수 있는 명령은 다음과 같다.

```text

/Users/ai/bin/deploy-main --dry-run

/Users/ai/bin/deploy-main

cat /Users/ai/state/deploy-main/last-run.json

```

병합된 origin/main만 배포 가능한 단일 기준 소스다. 배포 도구는 실행할 때마다 소스 체크아웃을 origin/main에 맞춘다. 로컬 커밋이나 커밋되지 않은 수정 사항은 state/deploy-main/quarantine/와 quarantine/<timestamp> 브랜치에 보존한다. 소스 관리 대상인 런타임 파일을 로컬에서 수정한 내용도 격리 영역에 보존한 뒤 배포된 소스로 덮어쓴다. 보존할 가치가 있는 변경 사항은 풀 리퀘스트를 통해 다시 반영한다.

배포 중에는 작업 원장이 새 실행을 시작하지 않는다. 들어오는 메시지는 지속성 있게 보관되고, 실행 중인 작업은 다음 안전한 턴 경계에서 체크포인트를 남긴다. 재시작 후 체크포인트가 있거나 중단된 작업은 저장된 진행 상황, 다음 동작, Codex 세션과 배포 업데이트 알림을 바탕으로 복구돼 이어서 실행된다.

브랜치를 푸시하기 전에 다음을 실행한다.

```text

deploy/scripts/verify-source.sh

```

규칙

소스는 이곳에 둔다. 지속성 있는 비밀 정보는 Infisical에 둔다. $HOME/auth, 제공자 캐시, 브라우저 프로필에는 부트스트랩 정보나 명시적으로 추적되는 마이그레이션 상태만 들어간다. 당연한 규칙이다. 그래도 기록해 둘 가치가 있다.