Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
CodeShell은 범용 AI 에이전트 오케스트레이션 프레임워크로, 터미널 CLI, Electron 데스크톱 앱, SDK 형태로 제공됩니다. 이 프레임워크는 도메인에 구애받지 않는(domain-agnostic) 구조를 통해 복잡한 에이전트 워크플로우와 컨텍스트 관리를 지원합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기CodeShell은 세 가지 모습을 갖춘 오케스트레이션 엔진입니다:
code-shell),import { Engine } from "@cjhyy/code-shell").핵심은 의도적으로 **도메인 비종속적(domain-agnostic)**입니다. 턴 루프(turn loop), 컨텍스트 관리, 권한(permissions), MCP 통합, 후크(hooks), 태스크(tasks), cron, 서브 에이전트(sub-agents), 세션(sessions), 메모리 등 모든 것이 일반적인 형태로 유지됩니다. 코딩 도구, git/worktree 동작 방식, LSP, 검토(review), 할당량(quota), 그리고 코딩 프롬프트는 물리적으로 분리된 @cjhyy/code-shell-capability-coding 패키지에 존재하며 CLI/데스크톱 호스트에 의해 구성됩니다. (참고: packages/core/CONTRIBUTING.md: "코어는 정책이 아닌 메커니즘만 담당합니다.")
상태: 0.9.x. 데스크톱 앱이 주요 제품이며, CLI와 SDK는 동일한 코어 엔진을 공유합니다. 게시된 릴리스 및 현재 릴리스 승인 기록을 참조하십시오.
bypass 모드를 갖춘 명시적인 승인 흐름 뒤에 위치합니다.~/.code-shell/ 아래에 저장되며, 자격 증명 파일은 소유자 전용(0o600)으로 작성됩니다.# 기본 CLI 프리셋: 터미널 코딩 어시스턴트 (대화형 REPL)
npx @cjhyy/code-shell
...
Node.js >= 20.10이 필요합니다.
데스크톱 앱(packages/desktop)은 Electron 클라이언트입니다. 소스에서 실행하려면 다음과 같습니다:
bun install
bun run dev # 개발 모드에서 데스크톱 앱을 실행합니다
스트리밍 출력을 지원하는 채팅 기능, 파일/브라우저/터미널/diff 패널이 나란히 배치된 도킹 스테이션, 모델 및 자격 증명(credential) 관리, 확장 마켓플레이스, 자동화/cron 스케줄링, 영구 목표 설정(persistent goals), 메모리, 그리고 휴대폰 리모컨을 제공합니다. 이 모든 기능은 세션별 에이전트 워커 프로세스를 통해 동일한 핵심 엔진을 구동합니다.
@cjhyy/code-shell-core)complete_goal 선언을 갖춘 영구 목표 설정 (Persistent goals)| 프리셋 (Preset) | 목적 (Purpose) | 추가 도구 (Extra tools) |
|---|---|---|
harness-min | 임베딩을 위한 도메인 중립 핵심 기본값 | 최소 파일 시스템, 셸, MCP, 메모리, 작업 및 에이전트 메커니즘 |
| ... |
프리셋은 시스템 프롬프트, 내장 도구 세트 및 권한 기본값을 선택합니다. 이는 SDK, CLI의 --preset 플래그 또는 설정을 통해 구성할 수 있습니다.
@cjhyy/code-shell-tui)run 모드와 더불어 repl, sessions, 및 runs 하위 명령어.@ 언급을 통한 파일/스킬 검색, 명령어 자동 완성, REPL 내 크론 스케줄링.Shift+Tab 권한 모드 순환, 기록 탐색, 세션 재개 및 비용/사용량 보고.@cjhyy/code-shell-desktop)예를 들어, Mimi에게 작업 세션(work Session)을 생성하지 않고 내일 오전 10시에 알림을 설정해 달라고 요청할 수 있습니다. 작업을 계속하려면 명시적인 승인이 필요합니다. Wake는 데스크톱 앱이 열려 있는 동안 실행되며, 재시작 후 기본 복구 기간은 예정 시간으로부터 24시간입니다. 만료된 항목은 실패 이유를 유지하며, 불확실한 전송이나 시작은 자동으로 다시 재생되지 않습니다.
Core 자체는 최소한의 harness-min 프리셋으로 기본 설정됩니다. CLI와 Desktop은 코딩 기능 패키지를 구성하며, 호스트 기본값은 terminal-coding입니다. 런타임 가드(Runtime guards)는 사용 불가능한 제공업체(providers), 자격 증명(credentials), 쿠키 또는 활성 목표(active goal)가 필요한 도구를 숨길 수 있습니다.
Read, Write, Edit, ApplyPatch, Glob, GrepBash, BashOutput, KillShell, ListShells, PowerShell, REPL, Sleepbrowser_observe, browser_act, browser_navigate, WebSearch, WebFetch, GenerateImage, GenerateVideoAskUserQuestion, AskUserQuestionAsync, EnterPlanMode, ExitPlanMode, ToolSearch, TodoWrite, Agent, AgentCancel, DriveAgent, DriveClaudeCode, CheckQuotaCronCreate, CronDelete, CronList, Config, Skill, AddMarketplace, InstallCapability, MCPTool, ListMcpResources, ReadMcpResource, EditModelCatalog, ConfigureModelConnectionMemoryList, MemoryRead, MemorySave, MemoryDelete, UseCredential, InjectCredential, complete_goal, cancel_goalEnterWorktree, ExitWorktree, NotebookEdit, LSP, BriefInstallCapability를 사용하면 대화에서 마켓플레이스 플러그인, 독립형 프로젝트 Skill, MCP 서버를 나열하고, 검사하고, 설치하고, 업데이트하고, 활성화하고, 비활성화하며, 제거할 수 있습니다. MCP 구성은 private-local, shared-project, user-wide 범위를 지원합니다. 변경 사항(mutations) 및 외부 Skill 레지스트리 검사는 계속 승인 게이트(approval-gated)를 거쳐야 합니다.
메타 패키지는 핵심 엔진을 재내보내므로, 레거시 SDK 임포트도 작동합니다:
import { Engine } from "@cjhyy/code-shell";
const generalEngine = new Engine({
...
모든 것은 패키지 루트에서 내보내집니다 — import { ... } from "@cjhyy/code-shell" (또는 @cjhyy/code-shell-core에서 직접). /run, /arena, 또는 /product 하위 경로 진입점은 없습니다.
실행 가능한 SDK 예제는 examples/에 있습니다 — 각각은 bun run <파일>로 직접 실행되며, API 키가 구성되지 않은 경우 --dry-run (스크립트 모의 LLM)을 지원합니다:
examples/01-minimal-agent.ts — 하나의 엔진, 한 번의 실행, 스트리밍 출력examples/02-approval-flow.ts — 사용자 정의 ApprovalBackend 게이팅 도구 호출examples/03-in-process-transport.ts — 권장되는 createServer / createClient 팩토리 쌍CLI 프리셋 선택:
npx @cjhyy/code-shell --preset general
npx @cjhyy/code-shell --preset terminal-coding
설정 기반 구성 (~/.code-shell/settings.json, 프로젝트 레벨 오버라이드 포함):
{
"agent": {
"preset": "general",
...
지원되는 agent 설정: preset, enabledBuiltinTools, disabledBuiltinTools, customSystemPrompt, appendSystemPrompt.
CodeShell의 터미널 UI는 기본적으로 전체 화면(alt-screen + ScrollBox)입니다 — 창 크기 조정 시 깨끗하게 다시 그려지는(repaints cleanly) 모드입니다. Flow mode는 리사이즈 후 스크롤백에 중복 콘텐츠를 표시할 수 있습니다. 이는 CodeShell이 지우기 전에 터미널이 이전 뷰포트를 위로 밀어내기 때문입니다.
시작 시 CODESHELL_FULLSCREEN=0|false|off로 제외하거나, /fullscreen off로 런타임에 토글할 수 있습니다. Flow mode는 전사 기록(transcript)이 터미널의 네이티브 스크롤백으로 흐르도록 합니다 (셸 히스토리를 CodeShell 위에 표시하는 것을 선호하는 경우 유용합니다).
OpenAI와 호환되는 제공자(provider)는 청크 없이 CODESHELL_STREAM_IDLE_TIMEOUT_MS ms(기본값 90000) 동안 유휴 상태인 모든 LLM 스트림을 중단시킨 후, 기존의 withRetry 정책을 통해 재시도하며, 이는 CODESHELL_STREAM_WATCHDOG_RETRIES(기본값 2)에 의해 제한됩니다. 이 기능은 상위(upstream) 오류가 무기한이 아닌 약 90초(s)로 제한되도록 합니다. 제외하려면 CODESHELL_ENABLE_STREAM_WATCHDOG=0을 설정하세요. 사용자가 시작하는 중단(Esc / Ctrl+C)은 절대 재시도되지 않습니다.