shaharia-lab/agento

Agento는 웹 UI 및 CLI를 통해 AI 에이전트 (AI agents)를 구축하고 상호작용할 수 있는 로컬 플랫폼입니다. 이 플랫폼은 이미 사용자의 기기에 설치된 Claude Code CLI 위에서 실행되므로, 별도의 API 키나 클라우드 계정이 필요하지 않습니다.

사용자는 커스텀 시스템 프롬프트 (system prompts)와 도구 (tools)를 사용하여 에이전트를 정의할 수 있으며, 에이전트와 멀티턴 대화 (multi-turn conversations)를 시작하고, 브라우저 또는 터미널에서 직접 모든 것을 관리할 수 있습니다.

⭐

Agento가 유용하다면 저장소에 스타 (star)를 눌러주세요. 이는 프로젝트의 성장과 다른 사람들이 프로젝트를 발견하는 데 큰 도움이 됩니다.

💬 채팅 (Chats) — 에이전트와의 멀티턴 대화

직접 구축한 모든 에이전트와 대화를 시작하고 여러 턴에 걸쳐 대화를 이어갈 수 있습니다. 세션은 로컬에 저장되므로 중단했던 지점부터 바로 다시 시작할 수 있습니다. 응답은 서버 전송 이벤트 (Server-Sent Events, SSE)를 통해 실시간으로 스트리밍되어 전체 답변을 기다릴 필요가 없습니다. 중요한 채팅은 즐겨찾기에 추가할 수 있으며, 작업 공간을 정리하기 위해 채팅 제목을 인라인으로 변경할 수 있습니다. 파일을 드래그 앤 드롭하거나 이미지를 채팅 입력창에 직접 붙여넣어 에이전트와 공유할 수 있습니다.

🗂️ 멀티 채팅 워크스페이스 (Multi-Chat Workspace) — 여러 대화를 병렬로 실행

탭 기반의 워크스페이스에서 여러 채팅 세션을 동시에 열 수 있습니다. 각 탭은 고유한 에이전트, 세션 상태, 스트리밍 출력을 가진 완전히 독립적인 환경입니다. 탭 상태는 페이지를 새로고침해도 유지되므로, 다른 곳으로 이동하더라도 작업 위치를 잃어버리지 않습니다.

🤖 에이전트 빌더 (Agent Builder) — 커스텀 AI 에이전트 정의

커스텀 이름, 시스템 프롬프트 (system prompt), Claude 모델, 그리고 사고 모드 (adaptive, enabled, 또는 disabled)를 사용하여 에이전트를 생성합니다. 각 에이전트가 접근할 수 있는 도구를 정확하게 지정할 수 있습니다. 여기에는 내장된 Claude Code 도구, 로컬 프로세스 내 도구, 외부 MCP 서버, 또는 제3자 통합 기능이 포함됩니다. 에이전트는 사용자의 기기에 로컬로 저장되며 YAML 파일로도 정의할 수 있습니다. {{current_date}} 및 {{current_time}}와 같은 템플릿 변수는 런타임 (runtime) 시 시스템 프롬프트에 자동으로 주입됩니다.

사용 가능한 내장 도구: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task

🔌 Integrations (연동) — 에이전트 도구로서 외부 서비스 연결

외부 서비스를 에이전트가 대화 중에 직접 호출할 수 있는 도구로 변환하세요. 각 연동(Integration)은 별도의 외부 데몬(Daemon) 없이 프로세스 내 MCP 서버로 실행됩니다.

지원되는 연동:

Google— OAuth를 통해 Calendar (이벤트 읽기/생성), Gmail (읽기/전송), Drive (파일 검색/읽기) 지원
GitHub— 개인 액세스 토큰(Personal Access Token)을 통해 Repos, Issues, Pull Requests, Actions Workflows 및 Releases 지원
Slack— 봇 토큰(Bot Token)을 통해 채널 및 메시지 읽기, 메시지 전송, 검색, 사용자 조회 지원
Jira— API 토큰을 통해 프로젝트 탐색, JQL을 이용한 이슈 검색, 이슈 생성 및 업데이트 지원
Confluence— API 토큰을 통해 Space 및 Page 읽기, CQL을 이용한 검색 지원
Telegram— 봇 토큰을 통해 메시지, 사진, 투표(Polls) 및 위치 정보 송수신 지원

🔗 External MCP Servers (외부 MCP 서버) — 모든 MCP 호환 도구 서버 연결

~/.agento/mcps.yaml에 목록을 추가하여 모든 MCP 서버로 에이전트를 확장하세요.

stdio (서브프로세스), streamable_http, sse 세 가지 전송 방식(Transport)을 모두 지원합니다. 환경 변수 참조(${ENV:VAR_NAME})를 사용하여 설정 파일에 자격 증명(Credentials)이 노출되지 않도록 관리할 수 있습니다. 등록된 MCP 도구는 에이전트 빌더(Agent Builder)에서 내장 도구와 함께 나타나며, 에이전트별로 선택적으로 할당할 수 있습니다.

⏰ Task Scheduler (작업 스케줄러) — 반복되는 에이전트 작업 자동화

Cron 표현식을 사용하여 모든 에이전트가 자동으로 실행되도록 예약하세요. Agento는 백그라운드에서 작업을 실행하며, 모든 실행의 결과, 소요 시간 및 출력을 기록합니다. 일일 요약, 자동 보고서, 주기적인 파일 처리 또는 수동으로 예약 실행하던 모든 워크플로(Workflow)에 이를 활용하세요.

📋 Job History (작업 이력) — 모든 예약된 실행에 대한 감사(Audit)

모든 작업 실행은 시작 시간, 소요 시간, 종료 상태(Exit Status) 및 전체 에이전트 출력과 함께 로그로 기록됩니다. 작업 이력 페이지를 탐색하여 각 에이전트가 수행한 작업을 검토하고, 실패 원인을 진단하며, 로그 파일을 뒤지는 번거로움 없이 시간에 따른 추세를 추적하세요.

🗄️ Claude Sessions (Claude 세션) — Claude Code 세션 이력 탐색

Agento는 사용자의 기기에 있는 Claude Code 세션 JSONL 파일을 자동으로 스캔하여 UI에서 탐색할 수 있도록 만듭니다. 모든 세션의 전체 메시지 이력을 확인하고, 개별 도구 호출 (tool calls)을 상세히 파헤치며, 시작부터 끝까지의 전체 세션 여정을 따라갈 수 있습니다. 결과는 로컬에 캐싱 (cached)되며, 새로운 세션이 나타나면 백그라운드에서 점진적으로 업데이트됩니다.

📊 Token Usage Analytics (토큰 사용량 분석) — 시간에 따른 비용 및 소비 추적

Claude 세션이 소비하는 토큰 양을 입력 (input), 출력 (output), 캐시 (cache) 토큰별로 상세히 확인하세요. 차트를 통해 선택한 날짜 범위 동안의 추세를 보여주며, 예상 비용을 통해 청구서가 도착하기 전에 지출을 관리할 수 있습니다. 모델별 필터링을 통해 Claude Sonnet, Haiku, Opus 간의 사용량을 비교해 보세요.

📈 General Usage Analytics (일반 사용량 분석) — 세션 패턴 이해

하루에 실행하는 세션 수, 가장 많이 사용하는 모델, 그리고 활동 히트맵 (activity heatmap)을 통한 가장 활발한 활동 시간을 시각화합니다. 임의의 날짜 범위를 비교하여 모든 Claude Code 작업 전반에 걸친 성장 추세나 사용량 급증을 파악할 수 있습니다.

**💡 Insights (인사이트) — AI 워크플로우를 위한 생산성 지표 **(실험적 기능) **

(실험적 기능)

단순한 토큰 수를 넘어선 더 깊이 있는 분석 뷰를 제공합니다. Insights는 자율성 점수 (Autonomy Score) (인간의 개입을 바탕으로 Claude가 얼마나 독립적으로 작업했는지), 생산성 점수 (Productivity Score) (자율성, 캐시 효율성, 오류 없는 세션의 복합 지표), 평균 도구 호출 횟수, 세션 지속 시간, 그리고 상위 10개 도구 사용량 분석을 계산합니다. 모든 지표는 전기 대비 비교 (period-over-period comparison)를 지원하므로, 에이전트가 시간이 지남에 따라 더 효과적으로 변하고 있는지 확인할 수 있습니다.

⚙️ Settings (설정) — 일반, Claude 프로필, 외관 등

모든 설정은 탭으로 구성된 단일 설정 페이지에서 관리됩니다:

General (일반)— 기본 작업 디렉토리(working directory)와 Claude 모델을 설정합니다. 환경 변수(environment variables)에 의해 잠긴 필드는 해당 환경 변수 이름과 함께 읽기 전용으로 표시됩니다.

Claude Settings Profiles (Claude 설정 프로필)— 여러 개의 이름이 지정된 Claude 설정 프로필을 생성하여(각 프로필은 ~/.claude/settings_<slug>.json으로 저장됨) 에이전트별 또는 채팅별로 프로필을 전환할 수 있습니다. 첫 실행 시 기존의 ~/.claude/settings.json 파일을 기반으로 기본 프로필이 자동으로 생성됩니다.

Appearance (외관)— 다크/라이트 모드를 전환하고, 글꼴 크기와 글꼴(font family)을 선택합니다. 변경 사항은 전체 UI에 즉시 적용됩니다.

Notifications (알림)— 작업 완료 및 에이전트 이벤트에 대한 SMTP 이메일 전송을 구성합니다. UI에서 직접 전송 테스트를 수행할 수 있으며 알림 로그를 탐색할 수 있습니다.

Monitoring (모니터링)— 트레이스(traces), 메트릭(metrics), 로그(logs)를 위해 OpenTelemetry 익스포터(exporters, OTLP gRPC 또는 Prometheus)를 구성합니다. 재시작 없이 설정을 핫 리로드(Hot-reload)할 수 있습니다.

Advanced (고급)— 추가적인 저수준(low-level) 구성 옵션입니다.

💻 CLI — 터미널에서 에이전트를 직접 실행

브라우저를 열지 않고도 agento ask를 사용하여 모든 에이전트에 일회성 쿼리(one-shot query)를 보낼 수 있습니다. 기존 대화를 이어가려면 위치 인자(positional argument)로 세션 ID(session ID)를 전달하세요. 스크립팅, 빠른 조회, 또는 Agento를 다른 쉘(shell) 워크플로에 통합할 때 유용합니다.

agento ask "What changed in the repo today?"
agento ask --agent my-agent "Follow up" <session-id>

🔄 Auto-Update (자동 업데이트) — 명령 하나로 최신 상태 유지

Agento는 시작 시 새로운 릴리스가 있는지 확인하며, 업데이트가 가능할 경우 UI 상단에 황색 배너를 표시합니다. 버전별로 배너를 닫거나 agento update를 실행하여 즉시 업그레이드할 수 있습니다. 업데이트 확인 결과는 1시간 동안 캐시되어 워크플로 속도에 영향을 주지 않습니다.

📡 Observability (관측성) — OpenTelemetry 트레이스, 메트릭 및 로그

모든 HTTP 요청, 에이전트 실행(agent run), 도구 호출(tool call), 그리고 스토리지 작업은 OpenTelemetry 스팬(spans) 및 메트릭(metrics)으로 계측(instrumented)됩니다. 모니터링(Monitoring) 설정 탭에서 직접 OTLP gRPC 내보내기(export) 또는 Prometheus 풀(pull) 엔드포인트를 구성할 수 있으며, 별도의 설정 파일이나 재시작이 필요하지 않습니다. 구조화된 JSON 로그는 ~/.agento/logs/system.log에 기록되며, 세션별 로그는 ~/.agento/logs/sessions/<id>.log에 기록됩니다.

💡

기능이 누락되었나요? Agento에서 보고 싶은 기능이 있다면 GitHub에 이슈(issue)를 생성해 주세요. 여러분의 의견을 기다립니다.

Agento의 핵심 기능들이 실제로 작동하는 모습을 확인해 보세요. 아래 섹션 중 아무 곳이나 클릭하면 데모가 확장됩니다.

💬 AI 에이전트와 채팅하기

직접 구축한 에이전트와 멀티턴(multi-turn) 대화를 시작하세요. 응답은 서버 전송 이벤트(Server-Sent Events)를 통해 브라우저에 실시간으로 스트리밍되므로, 터미널과 마찬가지로 출력이 생성되는 과정을 즉시 확인할 수 있습니다.

demo.webm

🗂️ 멀티 채팅 워크스페이스 (Multi-Chat Workspace)

탭 기반의 워크스페이스를 사용하여 여러 대화를 나란히 열 수 있습니다. 각 탭은 자체적인 세션 상태(session state)를 유지하므로, 문맥(context)을 잃지 않고 독립적인 에이전트 작업을 병렬로 실행할 수 있습니다.

Multi-Tab.Chat.-.Demo.webm

⭐ 즐겨찾기 및 채팅 제목

중요한 대화를 즐겨찾기로 표시하고 채팅 제목을 인라인(inline)으로 변경할 수 있습니다. 채팅 화면을 벗어나지 않고도 워크스페이스를 깔끔하게 정리할 수 있습니다.

Favorite.and.Chat.Title.Demo.webm

🔌 통합 (Google, GitHub, Slack 등)

외부 서비스인 Google Calendar, Gmail, Drive, GitHub, Slack, Jira, Confluence, Telegram 등을 연결하고, 이를 에이전트가 대화 중에 호출할 수 있는 도구(tools)로 노출할 수 있습니다.

⏰ 작업 스케줄러 (Task Scheduler)

크론 표현식(cron expression)에 따라 에이전트가 자동으로 실행되도록 예약할 수 있습니다. 각 실행은 전체 작업 이력(job history)과 함께 로그로 기록되므로, 에이전트가 무엇을 했는지, 언제 실행되었는지, 그리고 성공했는지 여부를 검토할 수 있습니다.

📊 토큰 사용량 분석 (Token Usage Analytics)

모든 Claude 세션에 걸쳐 토큰 소비량, 캐시 히트율(cache hit rates), 예상 비용을 추적합니다. 차트는 모델 및 시간 범위별로 사용량을 세분화하여 보여주므로 토큰이 어디에 사용되는지 항상 파악할 수 있습니다.

📈 일반 사용량 분석 (General Usage Analytics)

시간 경과에 따른 세션 볼륨, 모델별 상세 내역, 그리고 활동 히트맵 (activity heatmaps)을 시각화합니다. 에이전트가 얼마나 빈번하게, 그리고 언제 사용되고 있는지 빠르게 파악할 수 있는 방법입니다.

🗄️ Claude Code 세션 여정 (Claude Code Session Journey)

도구 호출 (tool calls), 메시지, 토큰 사용량의 전체 타임라인과 함께 Claude Code 세션 기록을 찾아보고 다시 재생할 수 있습니다. 이는 에이전트가 실행 중에 실제로 무엇을 했는지 감사 (auditing)하는 데 유용합니다.

📡 모니터링 및 관측 가능성 (Monitoring & Observability)

설정 (Settings) UI에서 직접 트레이스 (traces), 메트릭 (metrics), 로그 (logs)를 위한 OpenTelemetry 익스포터 (exporters)를 구성할 수 있으며, 별도의 설정 파일이 필요하지 않습니다. 모든 OTLP 호환 수집기 (collector) 또는 Prometheus와 연동됩니다.

🔔 알림 (Notifications)

작업 완료 및 에이전트 이벤트에 대한 SMTP 이메일 알림을 설정하세요. 수신자 구성, 전송 테스트, 알림 로그 검토를 모두 설정 페이지에서 수행할 수 있습니다.

🎨 외관 설정 (Appearance Settings)

라이트 모드와 다크 모드 사이를 전환하고, 워크플로 선호도에 맞춰 UI 외관을 맞춤 설정할 수 있으며, 변경 사항은 앱 전체에 즉시 적용됩니다.

• 기기에 Claude Code CLI가 설치되어 있고 인증된 상태
• Go 1.25+ 및 Node.js
  (소스 코드로부터 빌드할 때만 필요)

Anthropic API 키는 필요하지 않습니다. Agento는 기본적으로 Claude Code CLI의 기존 인증을 사용합니다. Anthropic API를 직접 호출하는 것을 선호한다면, 선택적 오버라이드 (override)로 ANTHROPIC_API_KEY를 설정할 수 있습니다.

GitHub Releases에서 사용 중인 플랫폼에 맞는 최신 릴리스를 다운로드하세요:

플랫폼	파일
Linux (x86_64)	agento_Linux_x86_64.tar.gz
...

압축을 풀고 agento 바이너리를 PATH에 포함된 디렉토리로 이동하세요:

tar -xzf agento_Linux_x86_64.tar.gz
sudo mv agento /usr/local/bin/

Homebrew:

brew install shaharia-lab/tap/agento

소스 코드로부터 빌드 (Go 1.25+ 및 Node.js 필요):

git clone https://github.com/shaharia-lab/agento.git
cd agento
make build

agento web

이 명령은 8990 포트에서 Agento를 시작하고 브라우저를 자동으로 엽니다. 브라우저를 건너뛰려면:

agento web --no-browser

다른 포트를 사용하려면:

agento web --port 3000

별도의 설정이 필요하지 않습니다. Agento는 사용자의 로컬 Claude Code 설정을 사용하여 즉시 작동합니다. 모든 설정은 선택 사항이며 환경 변수 (Environment variables)를 통해 재정의할 수 있습니다.

환경 변수 (Environment variables)

변수 (Variable)	기본값 (Default)	설명 (Description)
PORT	8990	HTTP 서버 포트
AGENTO_DATA_DIR	~/.agento	에이전트 (agents), 채팅 (chats), 로그 (logs)를 위한 루트 디렉토리. ~ 확장을 지원함
LOG_LEVEL	info	로그 상세 수준 (Log verbosity): debug, info, warn, error
ANTHROPIC_API_KEY	—	Claude Code CLI 인증 대신 Anthropic API를 직접 사용
AGENTO_DEFAULT_MODEL	(Claude 기본값)	직접 채팅 세션에 사용되는 Claude 모델을 고정
AGENTO_WORKING_DIR	/tmp/agento/work	에이전트 세션을 위한 기본 작업 디렉토리
OTEL_EXPORTER_OTLP_ENDPOINT	—	OTLP gRPC 컬렉터 엔드포인트 (예: localhost:4317). 설정 UI를 통해서도 구성 가능
OTEL_METRICS_EXPORTER	—	otlp (push) 또는 prometheus (/metrics를 통한 pull)
OTEL_LOGS_EXPORTER	—	otlp

로그는 ~/.agento/logs/system.log에 JSON 형식으로 기록됩니다.

세션별 로그는 ~/.agento/logs/sessions/<session-id>.log에 저장됩니다.

LOG_LEVEL=debug로 설정하십시오.