chaz

Chaz는 eidetica를 기반으로 구축된 실험적인 AI 에이전트 프레임워크입니다. ReAct 도구 호출 루프, 다중 에이전트 오케스트레이션, 영속적이며 동기화 가능한 세션별 상태 기능을 제공합니다. 주요 연결 고리는 모든 OpenAI 호환 LLM 제공업체에 연결되는 Matrix 봇입니다. 또한 TUI(Text User Interface)도 포함되어 있습니다.

⚠️ 실험적 기능. API, 설정, 온디스크 상태는 예고 없이 변경될 수 있습니다. 손해를 감당할 수 없는 데이터로 실행하지 마십시오.

일상적인 사용에 초점을 맞춘 보다 성숙한 Matrix 챗봇을 원한다면 baibot을 참고하십시오.

공지 블로그 게시물: Chaz: LLM <-> Matrix 챗봇

도움말 받기

사용 가능한 공개 Matrix 방은 #chaz:jackson.dev입니다.

기능

• ReAct 도구 호출 루프 — 에이전트가 9개의 내장 도구를 사용하여 추론하고, 행동하며, 관찰하는 루프를 가집니다.
• 확장 프레임워크 — 도구, 슬래시 명령어(slash commands), 라이프사이클 후크는 모두 선언된 확장을 통해 흐르며, 세션별 활성화, 설정 및 이벤트 로그 감사 추적을 제공합니다 (docs/ 참조).
• 다중 에이전트 오케스트레이션 — 에이전트(피어 엔티티, 키 + 아이덴티티)가 깊이 제한 및 전이 도구 축소 기능을 갖춘 개별 에이전트 워커 템플릿(일회성 LLM 호출, 아이덴티티 없음)을 호출합니다.
• TUI 모드 — Matrix 없이 테스트 및 디버깅을 위한 로컬 터미널 인터페이스입니다.
• 세션 공유 — eidetica 동기화를 통해 chaz 인스턴스 간에 세션을 공유할 수 있습니다.
• 보안 — 유출 감지, 네트워크 제어, 셸 샌드박싱, 도구 승인 게이트를 제공합니다.
• 영속적 세션 — eidetica SQLite를 통해 대화 기록이 재시작 후에도 유지됩니다.

내장 도구

실행

TUI (기본값)

터미널 인터페이스는 다른 모드 플래그 없이 chaz를 실행할 때 시작됩니다:

chaz --config config.yaml

단순한 실행은 세션 허브(session hub)를 열어 현재 세션을 나열하며, **새 세션(New session)**을 선택하기 전까지는 아무것도 생성하지 않습니다. 초기 프롬프트를 위치 인자(positional argument)로 전달하여 해당 내용이 미리 채워지고 전송되지 않은 새로운 대화를 열 수 있으며, 이를 검토하고 보낼 수 있습니다. 대신 --session NAME을 추가하면 (또는) 이름 지정된 세션을 열거나 생성할 수 있습니다:

chaz "오늘의 스탠드업 요약하기"

One-shot — -p / --print

단일 프롬프트를 전송하고, 응답을 출력한 후 종료합니다. 파이프(pipes) 및 스크립트에 유용합니다:

chaz -p "오늘의 스탠드업 요약하기"

각 호출은 기본적으로 새로운 임시 세션(ephemeral session)을 생성합니다. --session NAME을 전달하여 여러 호출에 걸쳐 하나의 세션을 재사용할 수 있습니다 (찾거나 생성).

Matrix 브릿지

Matrix 브릿지는 자체 바이너리이자 독립적인 피어입니다. 에이디티카 싱크(eidetica sync)를 통해 에이전트 프로세스와 브릿지를 나란히 실행합니다. 그러면 TUI 사용자와 Matrix 방 사용자가 동시에 같은 호스팅 세션을 구동할 수 있습니다.

chaz --config config.yaml daemon &          # agent peer, 터미널 불필요
chaz-matrix --config matrix-bridge.yaml     # Matrix 전송만

로컬 인터페이스를 브릿지와 함께 사용하고 싶다면 daemon을 일반 TUI 호출로 교체하세요.

TUI 명령어

TUI 키 바인딩

세션 공유

Chaz 인스턴스는 eidetica의 sync 프로토콜을 사용하여 네트워크를 통해 세션을 공유할 수 있습니다. 이를 통해 다음이 가능해집니다:

• 로컬 TUI에서 원격 에이전트의 대화 보기
• 여러 인스턴스가 동일한 세션에 협업하기
• 실시간 업데이트 — 어느 쪽에서 작성하든 자동으로 전파됨

작동 방식

각 chaz 인스턴스는 HTTP sync 서버를 자동으로 시작합니다. 세션은 **데이터베이스 티켓(database tickets)**을 통해 공유되는데, 이는 해당 세션의 데이터베이스 ID와 서버 주소를 인코딩한 URL입니다.

세션 공유하기

세션을 가지고 있는 인스턴스에서:

/share

이 명령어는 다음과 같은 티켓 URL을 출력합니다:

eidetica:?db=sha256:abc123...&pr=http:127.0.0.1:12345

원격 세션 동기화하기

다른 인스턴스에서, 티켓을 붙여넣습니다:

/sync eidetica:?db=sha256:abc123...&pr=http:192.168.1.10:12345

동기화 후, /sessions를 사용하여 동기화된 세션을 찾고 열 수 있습니다. 어느 쪽에서 새 메시지가 오든 자동으로 전파됩니다.

참고 사항

• 두 인스턴스는 네트워크를 통해 서로 도달할 수 있어야 합니다.
• sync 서버는 기본적으로 임의의 포트에 바인딩됩니다 (시작 시 로깅됨).
• Matrix에서 동기화된 세션은 TUI 세션 목록에 나타납니다.

Matrix 명령어

Matrix 방에 있을 때, Chaz는 !chaz로 접두사가 붙은 명령에 응답합니다. DM(Direct Message)에서는 모든 메시지에 응답합니다.

!chaz help      — 사용 가능한 명령어 표시
!chaz print     — 대화 컨텍스트 출력
!chaz send <msg> — 컨텍스트 없이 메시지 전송
...

설정(Configuration)

YAML 설정 파일을 생성합니다:

homeserver_url: https://matrix.org
username:

Nix flakes와 direnv 사용:

```bash
direnv allow        # 또는: nix develop .#
just build          # cargo build
just test           # cargo test
...

변경되지 않은 소스 코드를 다시 빌드하지 않고 반복적인 필터링된 테스트를 사용하려면, 워크스페이스 루트에서 nix run .#test -- -E 'test(test_error_size)'를 사용하세요.
재사용, 소스 무효화, 그리고 필요한 전체 최종 게이트에 대한 내용은 컴파일된 아카이브 테스트를 참조하세요.

저장소 (Repository)

GitHub와 Codeberg에 미러링되었습니다. GitHub가 공식 리포지토리이지만, 어느 곳을 사용해도 기여할 수 있습니다.