MagicCube/agentara

Claude Code와 OpenAI Codex를 기반으로 작동하는 24/7 개인 비서, Tara를 만나보세요. 멀티 채널 메시징 (Multi-channel messaging), 장기 기억 (Long-term memory), 기술 (Skills), 작업 스케줄링 (Task scheduling), 세션 관리 (Session management) 등을 모두 로컬에서 실행합니다.

에이전트 기반 세션 (Agent-powered sessions)— 전체 스트리밍 (Streaming) 지원을 갖춘 관리형 세션을 통해 Claude Code 및 OpenAI Codex와 상호작용합니다.
멀티 채널 메시징 (Multi-channel messaging)— 여러 채널(예: Feishu/Lark)로부터 메시지를 수신하고 응답합니다.
메시지 스트리밍 (Message streaming)— IM 채널을 위한 스트리밍 응답 (메시지 업데이트/패칭이 지원되는 경우, 예: Feishu)
작업 스케줄링 (Task scheduling)— 세션별 직렬 실행 및 세션 간 병렬 실행을 지원하는 큐 기반 작업 디스패처 (Task dispatcher)
크론 잡 (Cron jobs)— 크론 패턴 (Cron patterns)을 사용하여 반복 작업 스케줄링
세션 지속성 (Session persistence)— 전체 메시지 기록이 포함된 JSONL 파일로 세션 저장
웹 대시보드 (Web dashboard)— 세션, 작업 및 메모리를 관리하기 위한 React 기반 UI
파일 및 이미지 지원 (File and image support)— 메시지 채널을 통해 파일 및 이미지 송수신
RESTful API— 타입 안전 (Type-safe) RPC 클라이언트를 갖춘 Hono 기반 API 서버

• amap
• claude-usage
• consulting-analysis
• current-time
• daily-hunt
• data-analysis
• deep-research
• find-skills
• fix-my-life
• frontend-design
• github-deep-research
• heartbeat
• image-generation
• ppt-generation
• pulse
• scheduled-tasks
• skill-creator
• stock
• technical-writing-skill
• vercel-deploy-claimable
• weather-report
• web-design-guidelines

백엔드 (Backend)

카테고리	기술
런타임 (Runtime)	Bun
...
프론트엔드 (Frontend)

카테고리	기술
프레임워크 (Framework)	React 19 + Vite 7
...

• Bun (최신 버전)
• 다음 중 하나의 코딩 에이전트:
• Claude Code 설치 및 설정 완료
• OpenAI Codex 설치 및 설정 완료

먼저, 저장소 (Repo)를 클론(Clone)하고 모든 의존성 (Dependencies)을 설치하세요.

git clone https://github.com/magiccube/agentara.git
cd agentara
make install

그 다음, 개발 (DEVELOPMENT) 모드로 실행하세요. 백엔드 서버와 프론트엔드 웹사이트가 모두 실행됩니다.

make dev

처음 실행 시, Agentara는 ~/.agentara를 생성합니다.

기본 설정(config), 워크스페이스(workspace), 그리고 데이터 디렉터리(data directories)가 포함됩니다.

백엔드(backend)는 http://localhost:1984에서 실행되며,

프론트엔드 개발 서버(frontend dev server)는 http://localhost:8000에서 실행됩니다

(API 요청을 백엔드로 프록시(proxying)합니다).

사용 중인 IM 클라이언트로 이동하여 Tara와 대화를 시작하세요:

/bootstrap

또는 크론잡(cronjob)을 예약하세요:

Hey, Tara! Schedule a cronjob to run every 7:30 AM and 5:30 PM to run the `/pulse` skill.

변수 (Variable)	설명 (Description)	기본값 (Default)
AGENTARA_HOME	모든 Agentara 데이터의 홈 디렉터리 (Home directory)	~/.agentara
AGENTARA_LOG_LEVEL	로그 레벨 (Log level) (trace, debug, info, warn, error)	info
AGENTARA_SERVICE_PORT	API 서버 포트 (API server port)	1984
AGENTARA_SERVICE_HOST	API 서버 호스트 (API server host)	localhost

config.yaml 파일은 첫 실행 시 $AGENTARA_HOME/config.yaml에 자동으로 생성됩니다. 예시는 다음과 같습니다:

agents:
  default:
    type: claude # 사용할 Agent runner
...

$로 시작하는 문자열 값은 로드 시점에 환경 변수(environment variables)로부터 자동으로 해결(resolved)됩니다. 모든 필드는 시작 시 Zod를 통해 검증(validated)되며, 누락되거나 잘못된 값은 명확한 에러를 발생시킵니다.

모든 데이터는 $AGENTARA_HOME(기본값: ~/.agentara`) 아래에 저장됩니다:

~/.agentara/
├── config.yaml # 설정 파일 (Configuration file)
├── workspace/ # Agent 워크스페이스 (Agent workspace)
...

src/
├── shared/ # 레이어 간 타입, 유틸리티, 컨벤션 (Cross-layer types, utilities, conventions)
│ ├── agents/ # AgentRunner 인터페이스 (AgentRunner interface)
...

명령어 (Command)	설명 (Description)
bun run dev	개발 모드(dev mode)에서 백엔드 및 프론트엔드 시작
bun run dev:server	백엔드만 시작
bun run dev:web	프론트엔드만 시작
bun run check	타입 체크(Type-check) 및 린트(lint)
bun run build:bin	독립 실행형 바이너리(standalone binary)로 컴파일
bun run build:js	JS 번들(JS bundle) 빌드

기여(Contributions)를 환영합니다! 시작하는 방법은 다음과 같습니다:

**저장소를 포크(Fork)**하세요.
기능 추가 또는 수정을 위한 브랜치(branch)를 생성하세요: git checkout -b feat/my-feature

의존성 설치(Install dependencies): bun install

변경 사항을 적용하고 체크를 통과하는지 확인하세요: bun run check # 타입 체크 + 린트

Conventional Commits 규칙을 따라 명확한 메시지와 함께 커밋 (Commit) 하세요:

feat:

새로운 기능 추가

fix:

버그 수정

chore:

유지보수

docs:

문서 작업

main 브랜치를 대상으로 풀 리퀘스트 (Pull Request)를 생성하세요.

• 로깅을 위해 @/shared에서 logger를 사용하세요. — console.log를 직접 사용하지 마세요.
• 서브 경로 (sub-paths)가 아닌 @/shared에서 직접 임포트 (Import) 하세요.
• 엔티티 (Entities)는 Zod 스키마 (schemas)로 먼저 정의하고, 그 다음에 TypeScript 인터페이스 (interfaces)를 정의합니다.
• 엔티티 필드에는 언더스코어 (underscore) 명명 규칙을 사용하세요.
• 클래스의 프라이빗 (Private) 멤버에는 _ 접두사를 붙이세요.
• 모든 공개 API (public APIs)에 대해 TSDoc을 제공하세요.