터미널 기반의 실험적인 AI 코딩 어시스턴트 Koder

Koder는 터미널을 위한 실험적인 AI 코딩 어시스턴트 (AI coding assistant)입니다. 스트리밍 TUI (TUI), 지속 가능한 로컬 세션 (persistent local sessions), 저장소 인식 도구 (repository-aware tools), 확장 가능한 기술 (extensible skills), MCP 통합, 그리고 멀티 에이전트 워크플로 (multi-agent workflows)를 하나의 Python 런타임 (Python runtime)에 결합했습니다.

상태: 알파 (Alpha). Koder는 에이전트 기반 코딩 시스템 (agentic coding systems)을 탐구하기 위한 학습 중심 프로젝트입니다. 빠른 반복과 간혹 발생하는 미숙한 부분이 있을 수 있습니다.

Koder는 워크플로를 변경하지 않고 다양한 모델 제공업체(model providers)를 가로질러 작동할 수 있는 로컬 우선(local-first) 코딩 어시스턴트를 원하는 개발자를 위해 설계되었습니다.

• 자신만의 모델 사용: OpenAI, Anthropic, Google/Gemini, GitHub Copilot, Azure, OAuth 기반 구독, OpenRouter, 그리고 100개 이상의 LiteLLM 제공업체를 지원합니다.
• 터미널 내 유지: 슬래시 명령어 (slash commands), 파일 언급 (file mentions), 셸 모드 (shell mode), 히스토리 검색 (history search), 실시간 사용 출력 (live usage output), 그리고 선택적인 음성 받아쓰기 (voice dictation)를 사용하세요.
• 컨텍스트를 로컬에 유지: 세션 (sessions), 트랜스크립트 (transcripts), 메모리 (memories), 작업 기록 (task records), 설정 (settings), 기술 (skills), 에이전트 (agents), 그리고 팀 상태 (team state)는 Koder가 소유한 로컬 경로에 저장됩니다.
• 런타임 확장: 프로젝트 기술 (project skills), 사용자 기술 (user skills), 플러그인 (plugins), MCP 서버 (MCP servers), 채널 (channels), 그리고 Magic Docs를 추가할 수 있습니다.
• 신중한 위임: 메인 세션이 통합을 담당하는 동안 백그라운드 서브 에이전트 (subagents)와 로컬 팀을 실행합니다.

영역	제공 기능
대화형 TUI (Interactive TUI)	스트리밍 출력 (Streaming output), 슬래시 완성 (slash completion), 셸 모드 (shell mode), 파일 언급 (file mentions), 상태 라인 (status line), 역방향 히스토리 검색 (reverse history search), 그리고 다중 행 프롬프트 (multi-line prompts).
...

uv를 사용하여 배포된 CLI를 설치하세요:

uv tool install koder

또는 pip를 사용하세요:

pip install koder

이 저장소에서 로컬 개발을 수행하려면:

git clone https://github.com/feiskyer/koder.git
cd koder
uv sync
...

모델 자격 증명 (model credential)을 설정하고 대화형 TUI를 시작하세요:

export KODER_API_KEY="your-api-key"
export KODER_MODEL="gpt-4o"
koder

셸에서 단일 프롬프트를 실행하세요:

koder "summarize the current repository"

프로젝트나 기능에 대해 지속적인 컨텍스트가 필요한 경우 이름이 지정된 세션을 사용하세요:

koder -s billing-refactor
koder -s billing-refactor "continue the failing test investigation"
koder --resume

TUI(Terminal User Interface) 내에서 사용하기 좋은 초기 명령어:

/onboarding
/status
/model
...

작업	명령어
TUI 열기	koder
...

전체 슬래시 명령어(slash-command) 카탈로그는 명령어 참조(Command Reference)를 확인하세요.

Koder는 다음 순서로 설정을 해결(resolve)합니다:

• CLI 인자 (CLI arguments)
• 환경 변수 (Environment variables)
• ~/.koder/config.yaml
• 내장 기본값 (Built-in defaults)

범용 환경 변수는 모든 제공자(provider)에 걸쳐 작동합니다:

변수	용도	예시
KODER_API_KEY	범용 API 키	sk-...
KODER_MODEL	활성 모델	gpt-4o , claude-opus-4-20250514
KODER_BASE_URL	사용자 정의 OpenAI 호환 엔드포인트	http://localhost:8080/v1
KODER_REASONING_EFFORT	추론 노력 (Reasoning effort)	low , medium , high
KODER_REASONING_DISPLAY	추론 표시 모드 (Reasoning display mode)	off , summary , full

제공자별 예시:

OPENAI_API_KEY="sk-..." KODER_MODEL="gpt-4o" koder
ANTHROPIC_API_KEY="..." KODER_MODEL="claude-opus-4-20250514" koder
GOOGLE_API_KEY="..." KODER_MODEL="gemini/gemini-2.5-pro" koder
...

구독 기반 제공자는 로컬 OAuth 토큰 저장소를 사용합니다:

koder auth login google
koder auth login claude
koder auth login chatgpt
...

로그인 후, 제공자 접두사(provider prefix)와 함께 OAuth 기반 모델을 선택하세요:

KODER_MODEL="google/gemini-3-pro-preview" koder
KODER_MODEL="claude/claude-opus-4-5-20250514" koder
KODER_MODEL="chatgpt/gpt-5.2" koder

OAuth 토큰과 캐시된 모델 목록은 ~/.koder/tokens/ 아래에 저장됩니다.

지속적인 기본값은 ~/.koder/config.yaml에 저장됩니다:

model:
  name: "gpt-4o"
  provider: "openai"
...

유용한 설정 명령어:

koder config show
koder config edit
koder config export ~/koder-settings.json
...

제공자 설정, OAuth, 설정 번들(settings bundles), 관리형 설정(managed settings), MCP 설정, 그리고 음성 라우팅(voice routing)에 대해서는 설정 가이드(Configuration Guide)를 참조하세요.

Koder는 프로젝트, 사용자 및 플러그인 수준에서 확장될 수 있습니다.

스킬(Skills)은 필요할 때 로드되는 로컬 지침 번들(instruction bundles)입니다:

.koder/skills/api-review/SKILL.md
~/.koder/skills/personal-style/SKILL.md

---
name: api-review
description: Review API changes for compatibility and error handling
...

/skills 명령어로 스킬(Skills)을 검사합니다.

/init-verifiers 명령어로 검증기(verifier) 스킬을 생성합니다.

MCP 서버는 런타임(runtime)에 외부 도구를 추가합니다:

koder mcp add filesystem "python -m mcp.server.filesystem" --scope project
koder mcp add api --transport http --url http://localhost:8000
koder mcp list

플러그인(Plugins)은 스킬(skills), 명령(commands), MCP 서버, 채널(channels) 및 의존성(dependencies)을 제공할 수 있습니다:

koder plugin install ./my-plugin --scope project
koder plugin list
koder --channels server:my-channel
...

전체 확장 모델에 대한 자세한 내용은 Skills, Plugins, MCP 섹션을 참조하세요.

koder_agent/
├── agentic/ # 에이전트 생성, 훅(hooks), 가드레일(guardrails), 승인(approvals)
├── auth/ # OAuth 제공자, 토큰 저장소, 제공자별 라우팅(routing)
...

런타임 흐름(Runtime flow):

cli.py는 인자(arguments)를 파싱하고 런타임 요청을 생성합니다.

HarnessRuntime은 권한을 로드하고 대화형(interactive), 프롬프트(prompt) 및 서브커맨드(subcommand) 모드를 실행합니다.

• 세션 흐름(Session flow)은 컨텍스트(context), 훅(hooks), 플러그인(plugins), 에이전트(agents), 슬래시 명령(slash commands) 및 스케줄러 실행을 연결합니다.

AgentScheduler는 모델 실행을 스트리밍하고 사용량을 추적합니다.

• 도구(Tool) 및 권한(permission) 레이어는 파일, 셸(shell), MCP, 스킬(skill) 및 팀원(teammate) 작업을 검증합니다.

EnhancedSQLiteSession은 대화 기록(transcripts)과 세션 메타데이터를 ~/.koder/koder.db에 영구 저장합니다.

저장소(repository) 설정:

uv sync
uv run koder

코드 품질 및 테스트:

uv run black .
uv run ruff format
uv run ruff check --fix
...

집중 테스트 예시:

uv run pytest tests/test_file_tools.py
uv run pytest -v -k "test_name"

• API 키는 프로젝트 파일이 아닌 환경 변수(environment variables) 또는 로컬 사용자 설정에 보관해야 합니다.
• OAuth 토큰 및 캐시된 제공자 모델 목록은 ~/.koder/tokens/에 저장됩니다.
• 세션(Sessions), 대화 기록(transcripts), 메모리(memories), 작업(tasks), 에이전트(agents) 및 팀(teams)은 로컬의 ~/.koder/ 및 프로젝트의 .koder/ 아래에 저장됩니다.

경로(paths). - Koder는 세션(sessions)을 Koder 호스팅 서비스로 업로드하지 않습니다. 모델 요청(model requests)은 여전히 사용자가 구성한 제공자(provider)로 전송됩니다.

• 셸(Shell), 파일(file), MCP, 그리고 팀원(teammate) 작업은 로컬 권한 및 샌드박스(sandbox) 정책에 의해 중재됩니다. /sandbox status 명령어가 해당 백엔드를 사용 가능한 것으로 보고하면, 포그라운드 셸(foreground shell) 명령은 실제 샌드박스 백엔드를 사용할 수 있습니다.

경계(boundaries)를 검사하려면 다음 명령어를 사용하세요:

/privacy-settings
/permissions
/sandbox
...

자세한 내용은 샌드박스 가이드(Sandbox Guide) 및 권한과 개인정보 보호(Permissions and Privacy)를 참조하세요.

• 기능 가이드(Feature Guide) - Koder의 주요 사용자 대상 기능에 대한 주제 지도(topic map)
• 시작하기(Getting Started) - 첫 설치, 제공자 설정 및 안전한 첫 세션
• 대화형 TUI(Interactive TUI) - 프롬프트 제어, 슬래시 명령어(slash commands), 멘션(mentions), 셸 모드(shell mode) 및 음성 입력(voice input)
• 설정 가이드(Configuration Guide) - 설정 파일(config files), 환경 변수(environment variables), 제공자(providers), OAuth 및 설정 번들(settings bundles)
• 세션 및 메모리(Sessions and Memory) - 이름이 지정된 세션, 재개(resume), 압축(compaction), 되감기(rewind), 메모리 및 로컬 저장소(local storage)
• 에이전트 및 팀(Agents and Teams) - 백그라운드 하위 에이전트(subagents), 프로젝트 에이전트, 팀, 팀원 모드(teammate modes) 및 팀 메모리
• 워크플로(Workflows) - 검토(review), 계획(planning), Git, GitHub, 릴리스(release) 및 검증(verification) 워크플로
• 기술, 플러그인 및 MCP(Skills, Plugins, and MCP) - 기술(skills), 플러그인(plugins), MCP 서버, 채널(channels) 및 Magic Docs를 통한 Koder 확장
• 권한 및 개인정보 보호(Permissions and Privacy) - 승인(approvals), 샌드박스 정책(sandbox policy), 관리형 설정(managed settings), 워크스페이스 루트(workspace roots) 및 데이터 경계(data boundaries)
• 샌드박스 가이드(Sandbox Guide) - 셸 샌드박스 백엔드(shell sandbox backends), 상태 필드(status fields), 구성 및 문제 해결(troubleshooting)
• 음성 모드(Voice Mode) - 음성 받아쓰기(voice dictation) 설정 및 제공자별 참고 사항
• 명령어 참조(Command Reference) - 전체 슬래시 명령어 카탈로그

기여(Contributions)를 환영합니다.

• 저장소(repository)를 포크(Fork)하세요.

• 기능 브랜치(feature branch)를 생성하세요:
  git checkout -b feature/amazing-feature

• 테스트 또는 검증(validation)과 함께 집중적인 변경 사항을 만드세요.

• 변경 사항을 커밋(Commit)하세요:
  git commit -m 'Add amazing feature'

• 브랜치를 푸시(Push)하고 풀 리퀘스트(pull request)를 생성하세요.

가이드라인은 CONTRIBUTING.md를 참조하세요.

MIT License. 자세한 내용은 LICENSE를 참조하세요.