Hanseol (English)

OpenAI-Compatible CLI Coding Agent

A developer-focused coding agent for local or on-prem LLM environments.
Works with vLLM, Ollama, LM Studio, and any OpenAI-compatible API.

https://github.com/user-attachments/assets/77cc96c9-cb22-4411-8744-3a006b00c580

What You Can Do

• Read/search/edit/create code with safe, file-level changes.
• Plan & Execute: breaks tasks into TODOs and runs them step by step.
• Supervised Mode: approval required before file modifications.
• Deep Research: Built-in web search via headless Chrome — no Tavily, Google API, or external search service needed. Searches Naver & Google, visits source pages, cross-verifies facts, and returns cited answers.
• Browser automation: Chrome/Edge CDP control (navigate, click, screenshot).
• Office automation: PowerShell/COM control for Excel/Word/PowerPoint.
• Session management: save and restore conversation history.
• Auto retry & recovery for failed tool calls.

Quick Start

# 1. Install
git clone https://github.com/A2G-Dev-Space/Hanseol.git
cd Hanseol
npm install && npm run build

# 2. Run
node dist/cli.js       # or use 'hanseol' after npm link

The endpoint setup wizard launches automatically on first run.

Highlights

Supervised Mode

Request approval before running file modification tools.

Plan & Execute

Automatically turns requests into TODOs and executes them in order.

Deep Research (Search Sub-Agent)

Performs Perplexity-level web research using its own headless Chrome engine — no external search API (Tavily, SerpAPI, Google API) required.

• Dual-engine search: Naver (primary) + Google (secondary)
• Internal source search: Configure additional URLs (Confluence, internal wikis) via researchUrls in config
• Visits actual source pages, extracts content, cross-verifies facts
• Injects today's date for recency assessment
• Returns comprehensive answers with source citations
• Handles Cloudflare-blocked sites gracefully (auto-skip + alternative sources)

Confluence Integration

Edit or create Confluence pages directly via confluence_request:

• Opens a visible browser to access Confluence
• Supports macros, tables, rich text, ProseMirror/TinyMCE editors
• Configure browserServices with type confluence in config to enable

{
  "browserServices": [{ "type": "confluence", "name": "My Confluence", "url": "https://confluence.example.com" }],
  "researchUrls": [{ "name": "My Confluence", "url": "https://confluence.example.com" }]
}

Jira Integration

Manage Jira issues directly via jira_request:

• Opens a visible browser to access Jira (no API key needed)
• Fetch assigned/watching issues via JQL, create issues (Epic, Story, Task, Bug, Sub-task), add comments, transition status
• Two-phase issue creation: fill form → user confirmation → submit
• Autonomous DOM discovery — works with Cloud, Server, and Data Center
• Configure browserServices with type jira in config to enable

{
  "browserServices": [{ "type": "jira", "name": "My Jira", "url": "https://jira.example.com" }]
}

Automation Extensions

• Browser: PowerShell/Chrome CDP, no external server required.
• Office: PowerShell/COM automation for Excel/Word/PowerPoint.

Commands & Shortcuts

Slash Commands

| Command | Description | |---------|-------------| | /help | Help | | /clear | Reset conversation | | /compact | Compress conversation | | /load | Load saved session | | /model | Switch model | | /settings | Settings menu | | /usage | Token usage | | /docs | Docs management | | /tool | Toggle optional tools (browser/office) |

Keyboard Shortcuts

• Ctrl+C Exit
• ESC Interrupt
• Tab Auto ↔ Supervised
• @ File browser
• / Command autocomplete

Configuration

hanseol         # Setup wizard on first run
/settings       # Settings menu while running

Any OpenAI-compatible API works: vLLM, Ollama, LM Studio, Azure OpenAI, or internal LLM servers.

Requirements

• Node.js v20+
• npm v10+
• Git (for docs/repo usage)

Contact

Email: [email protected]

Documentation

• Developer Guide
• Logging System
• Testing Guide
• Roadmap

License

MIT License

GitHub: https://github.com/A2G-Dev-Space/Hanseol

Hanseol (한국어)

OpenAI-Compatible CLI Coding Agent

로컬/사내 LLM 환경에서 바로 사용할 수 있는 개발자용 코딩 에이전트입니다.
vLLM, Ollama, LM Studio 등 OpenAI 호환 API를 지원합니다.

이 툴로 할 수 있는 것

• 코드 읽기/검색/수정/생성: 파일 단위로 안전하게 수정합니다.
• Plan & Execute: 작업을 TODO로 분해하고 단계적으로 실행합니다.
• Supervised Mode: 파일 변경 전 사용자 승인 기반 작업.
• Deep Research (자체 웹 검색): Tavily, Google API 등 외부 검색 서비스 없이 자체 headless Chrome으로 Naver/Google을 직접 검색하고 소스 페이지를 방문하여 정보를 수집·교차검증·합성합니다.
• 브라우저 자동화: Chrome/Edge CDP 제어(탭 이동, 클릭, 스크린샷 등).
• Office 자동화: PowerShell/COM 기반 Excel/Word/PowerPoint 제어.
• 세션 관리: 대화 및 작업 히스토리 저장/복원.
• 자동 재시도/에러 복구: 도구 호출 실패 시 자동 재시도.

Quick Start

# 1. Install
git clone https://github.com/A2G-Dev-Space/Hanseol.git
cd Hanseol
npm install && npm run build

# 2. Run
node dist/cli.js       # 또는 npm link 후 'hanseol'

첫 실행 시 LLM 엔드포인트 설정 마법사가 자동으로 열립니다.

주요 기능 하이라이트

Supervised Mode

파일 수정 도구 실행 전에 승인 요청:

┌─────────────────────────────────────────────────────────────┐
│  🔧 edit_file                                                │
│  ─────────────────────────────────────────────────────────   │
│  📁 file_path: /src/utils/helper.ts                          │
│  📝 diff: + added lines ...                                  │
│  ─────────────────────────────────────────────────────────   │
│  ▸ [1] ✅ Approve                                            │
│    [2] ❌ Reject                                             │
└─────────────────────────────────────────────────────────────┘

• Tab: Auto ↔ Supervised 모드 전환
• 파일 수정 도구만 승인 필요
• Reject 시 피드백을 반영해 재시도

Plan & Execute

요청을 TODO로 분해해 순차 실행:

You: 로깅 시스템 추가해줘

┌────────────────────────────────────────────────┐
│ 📋 TODO List                            1/3    │
│ ████████░░░░░░░░░░░░░░░░░ 33%                  │
│ ├─ ☑ logger.ts 생성                          │
│ ├─ ⣾ 기존 코드에 import 추가                 │
│ └─ ☐ 에러 핸들링 적용                         │
└────────────────────────────────────────────────┘

Deep Research (자체 웹 검색 엔진)

외부 검색 API(Tavily, SerpAPI, Google API) 없이 자체 headless Chrome 엔진으로 웹 리서치를 수행합니다.

• 듀얼 엔진: Naver(1차) + Google(2차) 동시 검색
• 내부 소스 검색: config의 researchUrls에 Confluence, 사내 위키 등의 URL을 추가하면 웹 검색과 함께 자동 검색
• 검색 결과의 실제 소스 페이지를 방문하여 본문 내용 추출
• 복수 소스 간 교차 검증 후 출처와 함께 종합 답변 생성
• 오늘 날짜 자동 주입으로 최신 정보 여부 판단
• Cloudflare 차단 사이트 자동 우회 (블로그/뉴스 경유)

Confluence 연동

confluence_request로 Confluence 페이지를 직접 편집하거나 생성할 수 있습니다.

• config의 browserServices에 Confluence URL을 추가하면 활성화
• config의 researchUrls에 추가하면 Deep Research에서도 Confluence 검색 가능
• 매크로, 테이블, 리치 텍스트, ProseMirror/TinyMCE 에디터 지원

{
  "browserServices": [{ "type": "confluence", "name": "My Confluence", "url": "https://confluence.example.com" }],
  "researchUrls": [{ "name": "My Confluence", "url": "https://confluence.example.com" }]
}

Jira 연동

jira_request로 Jira 이슈를 직접 관리할 수 있습니다.

• 가시적 브라우저로 Jira에 직접 접속 (API 키 불필요)
• JQL로 할당/워처 이슈 조회, 이슈 생성(Epic/Story/Task/Bug/Sub-task), 코멘트, 상태 전환
• 이슈 생성 시 2단계 확인: 폼 입력 → 사용자 확인 → 제출
• 자율 DOM 탐색으로 Cloud, Server, Data Center 모두 지원
• config의 browserServices에 Jira URL을 추가하면 활성화

{
  "browserServices": [{ "type": "jira", "name": "My Jira", "url": "https://jira.example.com" }]
}

최신 자동화 확장

• 브라우저 자동화: PowerShell/Chrome CDP 기반, 별도 서버 없음
• Office 자동화: PowerShell/COM 기반, Excel/Word/PowerPoint 직접 제어

명령어 & 단축키

Slash Commands

| Command | 설명 | |---------|------| | /help | 도움말 | | /clear | 대화 초기화 | | /compact | 대화 압축 | | /load | 세션 불러오기 | | /model | 모델 전환 | | /settings | 설정 메뉴 | | /usage | 토큰 사용량 | | /docs | 문서 관리 | | /tool | 선택 기능 토글 (browser/office) |

Keyboard Shortcuts

• Ctrl+C 종료
• ESC 작업 중단
• Tab Auto ↔ Supervised
• @ 파일 브라우저
• / 명령어 자동완성

Configuration

hanseol         # 최초 실행 시 설정 마법사
/settings       # 실행 중 설정 메뉴

OpenAI 호환 API라면 대부분 연결 가능합니다: vLLM, Ollama, LM Studio, Azure OpenAI, 사내 LLM 서버 등.

Requirements

• Node.js v20+
• npm v10+
• Git (문서/리포 사용 시)

문의

Email: [email protected]

Documentation

• Developer Guide
• Logging System
• Testing Guide
• Roadmap

License

MIT License

GitHub: https://github.com/A2G-Dev-Space/Hanseol