Doorman11991/smallcode

소형 LLM (≤20B 파라미터)에 최적화된 AI 코딩 에이전트 (AI coding agent)

SmallCode는 소비자용 하드웨어에서 실행되는 로컬 모델 (7B-20B)로부터 유용한 작업을 추출하도록 밑바닥부터 설계된 터미널 네이티브 코딩 에이전트 (terminal-native coding agent)입니다. OpenCode와 같은 도구들이 128k 이상의 컨텍스트 (context)와 완벽한 도구 호출 (tool calling) 능력을 갖춘 프론티어 모델 (frontier models)을 가정하는 반면, SmallCode는 지능적인 아키텍처를 통해 소형 모델의 한계를 보완합니다.

비교 항목	OpenCode	SmallCode
대상 (Target)	프론티어 모델 (Claude, GPT-5)	7B-20B 로컬 모델
컨텍스트 (Context)	모든 것을 쏟아부음	예산 관리형, 요약 방식
도구 호출 (Tool calling)	신뢰할 수 있는 JSON을 가정	관대한 다중 형식 파서 (multi-format parser)
계획 (Planning)	싱글샷 (Single-shot)	TODO 파일로 분해된 단계
편집 (Editing)	전체 파일 쓰기	검색 및 교체 패치 (Search-and-replace patch)
개인정보 보호 (Privacy)	클라우드로의 API 호출	완전 로컬, 네트워크 불필요

# npm을 통해 전역 설치
npm install -g smallcode
# 또는 npx로 직접 실행
...

Windows, macOS, Linux용으로 사전 컴파일된 타르볼 (tarballs)이 매 릴리스마다 빌드됩니다. 이 타르볼들은 Node.js와 모든 네이티브 애드온 (native addons)을 포함하고 있어, node-gyp이나 C++ 빌드 도구가 전혀 필요하지 않습니다.

플랫폼	한 줄 설치 명령어
Linux / macOS	`bash <(curl -fsSL https://raw.githubusercontent.com/Doorman11991/smallcode/main/install.sh)`
Windows	`iwr -Uri https://raw.githubusercontent.com/Doorman11991/smallcode/main/install.ps1 -UseBasicParsing

설치 스크립트는 사용자의 플랫폼에 맞는 올바른 타르볼을 다운로드하여 ~/.smallcode에 압축을 풀고 PATH에 추가합니다. smallcode --help를 실행하여 확인하세요.

SmallCode는 BoneScript와 budget-aware-mcp를 의존성 (dependencies)으로 포함하고 있어, 모든 것이 한 번에 설치됩니다.

Node.js 18 이상 (LTS 권장 — 20.x 또는 22.x는 SQLite용 사전 빌드된 바이너리를 제공함)
로컬 LLM 서버 (LM Studio, Ollama, 또는 모든 OpenAI 호환 엔드포인트)

선택 사항 (코드 그래프 + FTS5 메모리 검색용):

better-sqlite3

사용 중인 Node 버전용 사전 빌드된 바이너리(prebuilt binaries)가 없는 경우 네이티브 컴파일(native compilation)이 필요합니다.

Node LTS (20.x, 22.x) 버전의 Linux/macOS/Windows용 사전 빌드된 바이너리가 존재합니다. 이 경우 빌드 도구가 필요하지 않습니다.
LTS가 아닌 Node 버전(23+, 25+ 등)을 사용하는 경우 다음이 필요합니다:

Linux: python3, make, gcc/g++ (sudo apt install build-essential python3 또는 pacman -S base-devel python)
macOS: Xcode Command Line Tools (xcode-select --install)
Windows: "C++를 사용한 데스크톱 개발" 워크로드가 포함된 Visual Studio Build Tools, 또는 npm install -g windows-build-tools

빌드에 실패하더라도 SmallCode는 여전히 작동합니다 — 자동으로 JSON 기반 메모리로 대체(fallback)됩니다.

프로젝트 루트에 .env 파일을 생성하세요:

# 필수 항목
SMALLCODE_MODEL=your-model-name
SMALLCODE_BASE_URL=http://localhost:1234/v1
...

모든 옵션은 .env.example을 참조하세요. 또한 하위 호환성을 위해 smallcode.toml도 지원합니다.

SmallCode는 모듈형 아키텍처(modular architecture)로 구축되었습니다:

bin/
├── smallcode.js 엔트리 포인트(Entry point), 에이전트 루프(agent loop), TUI 오케스트레이션 (1570 라인)
├── config.js 설정 로드, 엔드포인트 감지, 인증 헤더
...

SmallCode의 지능은 MarrowScript로 선언되며 프로덕션 런타임(production runtime)으로 컴파일됩니다. 단 50라인의 .marrow 선언만으로 캐싱, 재시도(retry), 검증(validation), 트레이스(traces), 예산 집행(budget enforcement) 기능이 포함된 1400라인 이상의 TypeScript 코드가 무료로 생성됩니다.

prompt classify_task_type(user_message: string) {
model: TinyClassifier
timeout: 3s
...

컴파일된 인지 레이어(cognition layer)는 다음을 제공합니다:

프롬프트 캐싱 (Prompt caching) — 캐시 히트 시 0ms, TTL이 포함된 콘텐츠 해시 키 사용
구조화된 트레이스 (Structured traces) — 모든 LLM 호출에 대해 trace_id/span_id 제공 (SMALLCODE_COGNITION_LOG=stderr로 활성화)
계층 기반 라우팅 (Tier-based routing) — 단순한 작업은 작은 모델(tiny model)로, 복잡한 작업은 중간 모델(medium model)로 라우팅
토큰 예산 (Token budgets) — 비용 등급별 집행, 초과 지출 방지
검증 및 복구 (Validation + repair) — 스키마 체크 및 잘못된 출력에 대한 자동 재시도

Node.js/TypeScript 백엔드의 경우, SmallCode는 BoneScript를 사용합니다 — 단 하나의 .bone 파일을 작성하면

단 하나의 .bone 파일을 작성하고 이를 완전한 프로젝트(routes, auth, DB, events, migrations, SDK, admin panel, Docker, CI)로 컴파일합니다. 8~~15회의 도구 호출(tool calls)을 1~~2회로 줄여, 소형 모델(small models)의 신뢰성을 극적으로 향상시킵니다.

재시도(retry) 및 분해(decompose) 이후에도 로컬 모델이 완전히 실패할 경우, SmallCode는 선택적으로 더 강력한 클라우드 모델(Claude, OpenAI, DeepSeek)로 에스컬레이션(escalate)할 수 있습니다. 이는 완전히 선택 사항(opt-in)이며 API 키가 필요합니다. 비용 폭주를 방지하기 위해 세션 제한(Session-limited)이 적용됩니다.

에스컬레이션 대상 (클라우드, 완전 실패 시에만 사용):

Claude Sonnet 4.5 / 4.6, Haiku 4.5
GPT-5.4 Mini / Nano
DeepSeek V4 / V4 Pro / V4 Flash

사용 중인 모델의 컨텍스트 윈도우(context window)를 절대 초과하지 않습니다. 도구 결과는 4k 자로 제한되며, 대화 중간에 컨텍스트가 너무 커지면 오래된 결과를 제거(eviction)하고, 시맨틱 압축(semantic compression)을 통해 이력을 삭제하는 대신 요약합니다.

스키마 컨텍스트 오버헤드(schema context overhead)를 절반으로 줄입니다. 모델이 먼저 카테고리(read/write/search/run/plan)를 선택하면, 관련된 도구 스키마만 전달받습니다. 이는 8~16k 컨텍스트를 가진 모델들에게 매우 중요합니다.

반복 루프(repetition loops), 패치 스파이럴(patch spirals, 손상된 파일에 갇혀 강제로 재작성하는 현상), 인사 회귀(greeting regression, 모델이 컨텍스트를 잃어 인사를 반복하는 현상)를 감지합니다. 토큰과 시간을 절약합니다.

소형 모델은 지저분한 출력을 생성합니다. SmallCode는 JSON, YAML, XML, Hermes 형식 또는 일반 텍스트에서 도구 호출(tool calls)을 파싱합니다. 흔한 실수(잘못된 파라미터 이름, 타입 불일치)를 자동으로 수정(Auto-repairs)합니다.

주요 편집 프리미티브(edit primitive)로 검색 및 교체(Search-and-replace)를 사용합니다. 소형 모델은 전체 파일을 안정적으로 재현할 수 없으며, 내용을 생략하거나 환각(hallucinate)을 일으키거나 내용이 어긋나는(drift) 경향이 있습니다. patch 방식이 더 안전하고 컨텍스트 효율적입니다.

복잡한 작업은 원자적 단계(atomic steps)로 분해됩니다. 모델은 매 턴마다 TODO 파일을 읽어 현재 위치를 파악합니다. 각 단계는 다음으로 넘어가기 전에 검증(lint/compile)됩니다.

모델별 설정: 컨텍스트 길이, 도구 형식(native/hermes/json/xml/text), 채팅 템플릿(chat template), 강점/약점. 프롬프팅 전략을 자동으로 적응시킵니다.

턴(turn)이 지나도 유지되는 지속적인 스크래치패드(scratchpad)입니다. 제한된 추론 깊이(reasoning depth)를 보완하여, 모델이 스스로에게 메모를 남길 수 있게 합니다.

명령어	설명
`/quit` , `/q`	SmallCode 종료
`/clear`	대화 초기화
`/stats`	세션 통계 표시
`/tokens`	상세 토큰 사용량 보고서
`/budget`	컨텍스트 윈도우 (Context window) 예산 + 시각적 바
`/trace`	실행 트레이스 (execution traces) 목록/표시/내보내기
`/eval`	프롬프트 평가 (prompt evaluation) 스위트 실행
`/memory`	작업 메모리 (working memory) 표시
`/plan`	현재 작업 계획 표시
`/model`	모델 표시/전환
`/profile`	감지된 모델 프로필 + 라우팅 모드 표시
`/cognition`	MarrowScript 인지 레이어 (cognition layer) 상태 표시
`/mcp`	연결된 외부 MCP 서버 표시
`/skill`	재사용 가능한 스킬 (skills) 관리
`/plugin`	플러그인 (plugins) 설치/관리
`/sessions`	저장된 세션 목록/재개
`/help`	모든 명령어 표시

SmallCode는 토큰 사용량과 실행 트레이스를 자동으로 추적합니다:

토큰 모니터 (Token Monitor)— 모든 LLM 호출은 프롬프트/완성 (prompt/completion) 토큰을 기록합니다. /tokens로 확인 가능합니다.

컨텍스트 예산 (Context Budget)— 컨텍스트 윈도우 (context window) 사용량에 대한 시각적 지표입니다. /budget으로 확인 가능합니다.

실행 트레이스 (Execution Traces)— 모든 에이전트 턴 (agent turn)은 .smallcode/traces/에 기록됩니다. /trace list로 확인 가능합니다.

트레이스-투-테스트 (Trace-to-Test)— 트레이스로부터 회귀 테스트 (regression tests)를 생성합니다: /trace test <id>

프롬프트 평가 (Prompt Evaluations)— 분류기 정확도 (classifier accuracy) 및 도구 선택 (tool selection)을 측정합니다: /eval classify_accuracy

# CLI에서 평가 실행
smallcode --eval classify_accuracy
smallcode --eval tool_selection

자신의 도구, CI 파이프라인, 또는 TypeScript 프레임워크에서 라이브러리로 SmallCode를 사용하세요:

const { SmallCode } = require('smallcode');
const agent = new SmallCode({
model: 'gemma-4-e4b',
...

구조화된 RunResult를 반환하며, 여기에는 다음이 포함됩니다: 응답 텍스트, 도구 호출 기록 (tool call records), 생성/수정된 파일, 토큰 사용량, 소요 시간 및 성공 상태.

도구 (Tool)	설명 (Description)
`bone_compile`	.bone 파일을 전체 백엔드 프로젝트로 컴파일
`bone_check`	.bone 파일 검증 (타입 오류, 제약 조건)
`list_projects`	통계와 함께 인덱싱된 모든 프로젝트 목록 표시
`graph_search`	코드 그래프 심볼 (symbol) 검색
`explain_symbol`	심볼에 대한 상세 설명 (호출자, 피호출자)
`read_file`	파일 내용 읽기
`write_file`	파일 생성/덮어쓰기
`patch`	검색 및 교체 (search-and-replace) 편집
`bash`	셸 명령 (shell commands) 실행
`search`	정규 표현식 (Regex) 검색 (ripgrep)
`find_files`	Glob 파일 검색
`memory_load`	관련 프로젝트 메모리 로드
`memory_remember`	지식을 메모리에 저장
`web_search`	DuckDuckGo를 통한 웹 검색 (`SMALLCODE_WEB_BROWSE=true` 필요)
`web_fetch`	URL에서 텍스트 가져오기 및 추출 (`SMALLCODE_WEB_BROWSE=true` 필요)

SmallCode에는 탐지되지 않는 웹 브라우징을 위해 스텔스 모드 (stealth mode)가 적용된 Playwright가 포함되어 있습니다. 기본적으로는 비활성화되어 있으며, 웹 컨텍스트 (web context)를 효과적으로 합성할 수 있는 중대형 모델 (20B 이상)에서 활성화하십시오:

# .env 파일 내
SMALLCODE_WEB_BROWSE=true

활성화하면 모델이 작업 중에 웹을 검색하고 문서를 가져올 수 있습니다. CAPTCHA 및 봇 차단을 피하기 위해 안티 디텍션 (anti-detection) 기능이 포함된 헤드리스 크로미움 (headless Chromium)을 사용합니다. Playwright를 사용할 수 없는 경우 단순 HTTP fetch로 대체됩니다.

MIT

Doorman11991/smallcode

요약

핵심 포인트

댓글