Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
laoHuangCode는 터미널에서 작동하는 오픈소스 AI 프로그래밍 어시스턴트입니다. 사용자가 자연어로 작업을 설명하면, Agent가 코드를 읽고 파일을 수정하며 명령을 실행할 수 있도록 지원합니다. 독립 설치기 또는 npm을 통해 환경 설정 및 업데이트가 용이하게 설계되었습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기터미널에서 작동하는 오픈소스 AI 프로그래밍 어시스턴트입니다.
자연어로 작업을 설명하면 Agent가 코드를 읽고, 파일을 수정하며, 명령을 실행할 수 있도록 합니다.
Node.js나 npm 사전 설치 없이 독립 설치기 사용을 권장합니다. macOS, Linux glibc, Windows의 x64 / ARM64를 지원합니다. Bash가 필요하며, Windows 사용자는 먼저 Git for Windows를 설치해야 합니다.
macOS / Linux:
curl -fsSL https://github.com/hxr223/laoHuangCode/releases/latest/download/install.sh | sh
Windows PowerShell:
irm https://github.com/hxr223/laoHuangCode/releases/latest/download/install.ps1 | iex
설치기는 다운로드 검증, 실행 가능 여부 확인을 수행하고 사용자 PATH를 자동으로 구성합니다. 설치 후 새 터미널을 열거나 설치기가 표시하는 환경 새로고침 명령을 실행하면 laohuang을 사용할 수 있습니다.
설치 경로, 지정 버전, 업그레이드 복구 및 제거는 설치 설명서를 참고하세요.
또한 npm을 통해 전역으로 설치할 수도 있습니다. 이 경우 Node.js >=22.19.0과 Bash가 필요하며, npm 전역 명령어 디렉토리가 PATH에 포함되어 있는지 확인해야 합니다:
npm install -g laohuang
프로젝트 디렉토리로 이동하여 대화형 세션을 시작합니다:
cd your-project
laohuang
최초 실행 시 공급자 선택, 입력 API 키 숨기기, 모델 선택 등의 안내를 받으며 수동으로 환경 변수를 설정할 필요가 없습니다.
현재 설치 업데이트:
laohuang update
독립 설치는 GitHub Releases의 최신 설치 패키지를 다운로드하고, 체크섬 및 테스트 실행에 성공하면 진입점을 전환하며 이전 버전을 보존합니다. npm 설치는 현재 실행 중인 설치를 파악하여 npm latest 안정 버전으로 업데이트하고 설치 결과를 검증합니다.
업데이트가 완료되면 laohuang을 재시작해야 합니다. npm 업데이트는 이미 최신 버전일 경우 반복적으로 설치하지 않으며, 자동으로 다운그레이드되지도 않습니다.
npm 업데이트는 전역 설치, 프로젝트 직접 종속성(direct dependency), workspace 직접 종속성을 지원합니다. 로컬 업데이트 시에는 해당 package.json 및 lockfile이 수정됩니다. 소스 코드, link, npx 임시 설치 및 기타 패키지 관리자가 관리하는 설치는 각자의 업데이트 방식을 통해 처리해야 하며, 명령어가 관련 안내를 제공할 것입니다.
작업을 직접 입력합니다. 예를 들어:
이 프로젝트의 디렉토리 구조를 정리하고 주요 모듈 간의 관계를 설명해 주세요.
Agent는 read, write, edit, bash, skill 도구를 제공하며, 스트리밍 응답, 실행 중 추가 작업 및 실행 취소를 지원합니다.
/model: 구성된 모든 공급자의 사용 가능한 모델을 검색하고 선택합니다./login: 공급자 자격 증명(credentials)을 설정합니다./providers: 공급자와 해당 구성, 검증 상태를 확인합니다./cancel: 현재 작업을 취소합니다./codemode off|on|only: 현재 세션의 도구 호출 모드를 전환합니다. /codemode는 현재 및 기본값을 확인합니다./codemode default off|on|only: 새 세션의 기본 모드를 설정하며, 세션은 자신의 모드를 유지합니다./name MCP 接入设计: 현재 세션 이름을 저장합니다. /name으로 이름을 확인합니다./copy: 최근 완료된 어시스턴트 응답 본문을 Markdown을 보존하여 복사합니다./skill:review 파라미터: Skill을 명시적으로 로드하며, 이름은 자동 완성 기능을 지원합니다./help: 모든 명령어를 확인합니다./exit: 종료합니다./login으로 공급자 자격 증명을 추가한 후에는, /model에서 구성된 공급자의 전체 모델 목록이 바로 표시되며, 공급자 ID, 모델 ID 또는 모델 이름으로 검색할 수 있습니다. 환경 변수로 자격 증명이 설정된 공급자도 목록에 나타납니다.
목록은 스크롤을 지원하며, 사용 가능한 모델이 없을 경우 /login을 먼저 실행하라는 메시지가 표시됩니다.
/model <provider>는 특정 공급자의 모델만 볼 수 있으며, /model <provider> <model>로 직접 전환할 수 있습니다.
모델 전환은 현재 세션에만 영향을 미치며 기본 프로필(Profile)을 수정하지 않습니다.
세션 이름은 복원 및 세션 목록에 유지됩니다. clone은 현재 이름을 상속받고, fork는 분기 시점의 이름을 상속받습니다.
/copy는 사고 과정(thought process), 도구 결과 또는 스트리밍 중인 조각을 복사하지 않으며, 생성 중에는 이전 기록된 응답을 복사합니다. SSH 세션은 OSC 52를 통해 현재 터미널로 복사 요청을 전송하며, 이는 요청이 전송되었음을 확인하는 것일 뿐이며 실제 쓰기는 터미널 설정에 따라 달라집니다. 사용 가능한 클립보드 백엔드가 없을 경우 그 이유가 설명됩니다.
기본값은 off이며, 직접 도구 호출 및 tool_search를 사용합니다. on은 직접 호출과 JavaScript 오케스트레이션을 동시에 허용하며, only는 일반적인 직접 호출 및 tool_search를 비활성화하고 모든 일반 도구를 codemode를 통해 호출하게 합니다. 전환은 다음 모델 요청에서 발효되며, 현재 실행 배치(batch)는 자체 도구 스냅샷을 사용합니다.
모델은 codemode에 JavaScript를 전달합니다. 스크립트는 await searchTools(query)를 사용하여 도구를 검색하고, await tools.name({...})을 통해 호출하며, 중간 결과는 스크립트 내에 유지됩니다. text(), console, image() 및 성공적인 non-undefined 반환 값이 모델이 수신하는 내용을 결정합니다. store(key,value) / load(key)는 현재 세션 분기의 작은 JSON 상태를 저장하며, store(key,undefined)로 삭제합니다. 오직 성공 또는 exit()만이 상태를 커밋하고, 취소, 시간 초과, 실패는 커밋하지 않으며, 외부 도구의 부작용은 롤백되지 않습니다.
기본 실행은 총 시간 제한이 없으나, 스크립트 첫 줄에 설정할 수 있습니다:
// @options: {"timeout_ms":30000,"max_output_tokens":10000}
const toolsFound = await searchTools('read');
text(toolsFound);
...
시간 초과는 대기열(queueing), 로딩, 계산 및 도구 대기를 포함합니다. CLI는 2개의 Worker를 공유하며, FIFO 대기열은 최대 60초입니다. 취소는 스크립트를 중지하고 내부 도구에 알리지만, 무시된 취소에도 불구하고 호스트 도구는 계속 마무리 작업을 수행할 수 있습니다. 각 QuickJS 인스턴스는 최대 256 MiB를 사용합니다. 출력 하드 제한은 16777216 UTF-16 문자 또는 100,000개 항목이며, store 단일 값은 최대 262,144 JSON 문자, 키 포함 총량은 최대 1,048,576 문자를 초과할 수 없습니다. 모델 텍스트는 기본적으로 약 10,000 토큰(문자당 4자로 추정)을 넘지 않습니다. 초과 시 미리보기가 잘리며, 전체 명시적 텍스트를 구성 파일 옆 codemode-artifacts/<sessionId>/에 저장하려고 시도하지만, 디스크 쓰기에 실패하면 미리보기만 유지됩니다. 내부 이미지는 image()를 사용하여 명시적으로 선택해야 하며, 이미지 참조는 현재 세션에서 승인된 첨부파일만 허용합니다.
QuickJS는 생성된 스크립트를 격리하며, 호스트 파일 및 Bash 도구는 여전히 현재 사용자 권한으로 실행됩니다.
네이티브 macOS에서는 Ctrl+V를, 네이티브 Windows에서는 Alt+V를 사용합니다: 시스템 클립보드의 이미지를 우선 읽어 임시 PNG로 저장하고, 입력창 커서 위치에 따옴표가 포함된 경로를 삽입합니다. 이미지가 없을 경우 텍스트를 붙여넣습니다. 경로 옆에 "이 이미지를 읽기"라고 작성한 후 제출하면 Agent가 read_image를 호출하며, 붙여넣는 순간 바로 이미지가 전송되는 것은 아닙니다.
macOS의 Cmd+V, Windows 터미널 자체의 텍스트 붙여넣기 동작은 변경되지 않습니다.
이미지는 첨부파일 원본 파일 제한(20 MiB, 6400만 화소, 최대 변 길이 8192)을 따르며, 텍스트는 1 MiB로 제한됩니다. 읽기 실패 시 알림이 표시되며 자동으로 제출되지 않습니다. 읽기 도중에 입력 수정, 팝업 열기 또는 세션 전환이 발생하면 이번 붙여넣기는 취소됩니다. 임시 이미지는 현재 CLI 종료 시 정리되며, read_image를 통해 가져온 첨부파일에는 영향을 미치지 않습니다. 읽히지 않은 임시 경로는 종료 후 사용 가능성이 보장되지 않습니다. 비정상 종료된 임시 디렉토리는 시스템 임시 디렉토리 정책에 의해 처리됩니다. 이 시스템 클립보드 입력은 네이티브 macOS/Windows에만 적합하며, Linux, WSL, SSH의 경우 실행 호스트의 이미지 경로를 사용해야 합니다.
공급업체 및 모델은 pi-ai의 API 키 카탈로그에서 가져옵니다. 사용 가능 범위, 인증 방식 및 검증 상태는 모델 구성 문서를 참조하십시오.
도구 호출은 확인 요청 없이 직접 실행됩니다. Bash는 운영 체제 수준의 샌드박스가 없으며 파일 접근도 프로젝트 디렉토리에 국한되지 않습니다.
사용 전에 보안 모델을 읽어주십시오.
소스 코드(source code)를 통한 실행, 테스트 및 터미널 검증은 개발 가이드를 참조하십시오.
배포 관련 설명은 배포 프로세스와 npm 배포 안내서를 참고하십시오.
laoHuangCode의 개발은 OpenCode, Pi, DSH, OpenAI Codex, Kimi Code 등 여러 프로젝트에서 영감을 받았습니다. 이 프로젝트들을 읽고 사용하면서 터미널 프로그래밍 어시스턴트의 설계와 구현에 대해 깊이 생각할 수 있었습니다.
코드와 엔지니어링 경험을 공개적으로 공유해 주신 이들 프로젝트의 저자, 유지 관리자 및 기여자분들께 감사드립니다.
특히, laoHuangCode는 pi-ai를 사용하여 모델 연결 능력(model access capability)을 제공합니다.