tboulet/Alan-Code-agent

Claude Code에서 영감을 받은 오픈 소스 Python 코딩 에이전트입니다. CLI, GUI 또는 확장하여 사용할 수 있는 Python 라이브러리로 활용 가능합니다.

Alan Code는 툴 사용(tool use), 후크(hooks), 스킬(skills), 컨텍스트 압축(context compaction) 등 현대적인 CLI 에이전트의 다양한 기능을 구현하며, 여기에 세션 간 메모리(cross-session memory), 실시간 비용 추적(live cost tracking), 그리고 Chat 및 LLM 관점(perspective)을 갖춘 GUI를 추가했습니다.

LiteLLM과 호환되는 모델 제공업체와 로컬 OpenAI 호환 서버에서 작동합니다.

브라우저 GUI: 백엔드별 쉐이핑 전에 정규화된 시스템 프롬프트와 대화를 보여주는 Chat 및 LLM 관점 기능(--gui).

세션 간 메모리: 프로젝트별 및 전역 메모리를 에이전트가 세션 사이에 읽고 쓰는 기능이며, 세 가지 모드(off, on, intensive)를 지원합니다.

실시간 비용 + 토큰 추적: API 호출당 예상 $와 토큰 사용량을 인-세션에서 확인할 수 있습니다.

광범위한 모델 지원: Anthropic 직접 연결, 모든 LiteLLM 백엔드(OpenAI, OpenRouter, Gemini 등), 또는 vLLM / SGLang / Ollama를 통한 로컬 모델을 지원하며, 네이티브 툴 사용 기능이 없는 모델을 위한 텍스트 기반 툴 호출 폴백(fallback) 기능을 제공합니다.

Python 라이브러리: 동기식(sync), 비동기식(async), 또는 스트리밍 API를 통해 자체 코드에서 에이전트를 구동할 수 있습니다. 몇 줄의 코드로 자동 수정 루프, 오케스트레이터, 또는 사용자 정의 UI를 구축하세요.

저장소를 클론하고 편집 가능한 모드로 설치하세요. Python 3.11 이상이 필요합니다.

git clone [email protected]:tboulet/Alan-Code-agent.git
cd Alan-Code-agent
pip install -e .

Linux와 macOS를 지원합니다. Windows에서는 WSL을 사용하세요. 세션 잠금 기능이 Unix API에 의존하기 때문에 네이티브 Windows는 현재 지원되지 않습니다.

환경 변수에 모델 제공업체의 API 키를 설정하세요 (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY 등).

alancode # 기본값: claude-sonnet-4-6
alancode --model openrouter/google/gemini-2.5-pro # 제공업체/모델 라우팅
alancode --model ollama/llama3.1 # 로컬 Ollama
...

LiteLLM 경로의 경우, 모델 제공업체가 모델 문자열 안에 포함됩니다 (ollama/..., openrouter/..., gemini/...). 순수한 Claude 이름(claude-sonnet-4-6)만 사용하면...

) 자동으로 네이티브 Anthropic SDK를 사용하며, 나머지 모든 것은 LiteLLM을 통해 라우팅됩니다. 전체 목록은 CLI 플래그를 참조하세요.

터미널 기반 채팅 인터페이스입니다. 프롬프트를 입력하고 Enter를 누르면 Alan이 응답을 스트리밍하고, 도구 실행 전 구성된 권한 정책을 적용하며, 나중에 --resume할 수 있도록 세션을 지속합니다.

기본 edit 모드에서는 exec 도구가 요청할 때 읽기와 쓰기가 자동으로 실행됩니다.

다른 명령어는 docs/reference/slash-commands.md에 있습니다.

alancode \
--model [모델_이름] \ # bare (gpt-4o, claude-sonnet-4-6) 또는
# provider/model (ollama/llama3.1, ...)
...

다른 매개변수는 docs/reference/cli.md에 있습니다.

매개변수는 또한 .alan/settings.json에서 설정하거나 /settings <key> <value> 명령어를 사용하여 런타임에 수정할 수 있습니다.

--gui 인수는 로컬 GUI 인터페이스를 실행하며, 여기에는 **채팅 패널(Chat panel)**이 포함됩니다.

또한 정규화된 대화와 백엔드 호출 직전의 시스템 프롬프트를 담고 있는 LLM Perspective 패널을 표시할 수도 있습니다.

Alan Code는 또한 AlanCodeAgent 클래스를 사용하여 Python 라이브러리로 사용될 수 있으며, 이를 통해 에이전트 또는 오케스트레이터 시스템을 구축할 수 있습니다.

import asyncio
from alancode import AlanCodeAgent
agent = AlanCodeAgent()
...

전체 예시: examples/example_1_cli_agent.py

패키지를 설치한 후 다음 명령어로 실행합니다.

python examples/example_1_cli_agent.py

테스트를 실행하고, 실패 내용을 에이전트에게 다시 피드백하여 녹색(green) 상태가 될 때까지 반복합니다. 이는 일반적인 CLI로는 얻을 수 없는 종류의 에이전트 오케스트레이션입니다.

import subprocess
from alancode import AlanCodeAgent
agent = AlanCodeAgent(permission_mode="yolo")
...

전체 예시 (버그가 있는 모듈과 테스트 스위트 포함): examples/example_2_auto_fix_loop/run_alan.py

웹 앱, TUI 또는 WebSocket 브릿지에 임베딩하려면 에이전트가 생성하는 이벤트들을 수신합니다.

import asyncio
from alancode import AlanCodeAgent
from alancode.messages.types import AssistantMessage, TextBlock, ToolUseBlock
...

전체 예시: examples/example_3_streaming_agent.py

Alan이 개발자 어시스턴트로서가 아니라 다른 프로그램(벤치마크 하네스, 상위 에이전트, 비감독 파이프라인) 내부에서 실행될 때는 programmatic=True를 전달합니다.

:

agent = AlanCodeAgent(
model="claude-sonnet-4-6",
cwd="/path/to/experiment",
...

이것은 그렇지 않으면 제어된 실행을 오염시킬 수 있는 프로젝트 및 호스트 수준의 상태(예: ~/.alan/ALAN.md, 프로젝트 ALAN.md, ~/.alan/memory/MEMORY.md, 그리고 네트워크/git/ask-user 도구들 (WebFetch, GitCommit, AskUserQuestion, Skill))로부터 Alan을 분리합니다. tools=[...] (전체 교체) 또는 disabled_tools=[...] (차감적)를 사용하여 도구 세트를 추가로 다듬을 수 있습니다.

자세한 내용은 docs/reference/python-api.md#programmatic-mode를 참조하십시오.

Alan Code가 아직 지원하지 않는 최신 CLI 코딩 에이전트의 기능들입니다. 기여를 환영합니다.

전체 이력은 CHANGELOG.md를 참조하세요.

2026-09-02 - Alan Code 1.3.14 - Alan 해파리가 CLI 배너, GUI 상단 바, 그리고 이 README에 추가되었습니다.2026-08-25 - Alan Code 1.3.13 - 압축 요약기 호출이 이제 비용 추적(cost tracking)에 표시됩니다., ALANCODE_WIRE_LOG=<path>

JSONL 형식으로 정확한 제공자 요청을 와이어 감사(wire audits)용으로 덤프하고, 비활성 v1 호환성 필드를 사용하는 도구가 그렇게 말합니다. 새로운 알려진 제한 사항 참조.2026-08-24 - Alan Code 1.3.12- 로컬 추론 모델을 위한 두 가지 선택적 제어(no_verbalize_warning (모델이 서술 없이 작동하도록 상기시키는 것) 및 disable_thinking (서버 측 채팅 템플릿에 추론 생성을 중지하도록 요청하는 것))가 추가되었습니다. 또한, 도구 호출 형식에 대한 설정을 더 이상 지연시키지 않는 CLI를 포함한 문서화 및 코드 정리 작업이 이루어졌습니다.2026-08-19 - Alan Code 1.3.11- 선택적 교차 턴 추론 재주입(persist_thinking) 및 추론 전용/빈 응답에 대한 경계 복구 기능이 추가되었습니다. 1.3.2-1.3.11 시리즈에서는 최대 출력 복구를 강화하고 로컬 모델을 위한 bash_block, kimi, kimi_k3, deepseek, minimax 및 자동 감지된 텍스트 도구 호출 형식이 추가되었습니다.2026-08-10 - Alan Code 1.3.1- Ollama 및 기타 엄격한 OpenAI 호환 서버에서 다중 턴 도구 사용을 수정하여, 도구 전용 어시스턴트 메시지를 JSON null 대신 빈 문자열 콘텐츠로 직렬화했습니다. 프로그래밍 방식 모드가 더 이상 자동 날짜/시간 알림을 주입하지 않습니다.2026-08-08 - Alan Code 1.3- 느리거나 오프라인 로컬 모델 작동, 추론 스트림에 내장된 도구 호출, 타임아웃 및 컨텍스트 창 제어, 백엔드 수명 주기 정리, 동시 공유 상태 쓰기 및 오류 보고가 강화되었습니다. 내부 전송 용어는 이제 일관되게 backend입니다.

, 사용하지 않는 GUI, REPL 및 세션 복잡성이 제거되었습니다.2026-07-25 - Alan Code 1.2 - 컨텍스트 예산이 이제 모델에 적응하고 모든 호출에서 법적 출력 공간을 예약합니다. 긴 세션은 컨텍스트 기반 자르기(context-scaled truncation), 압축 재시도, 그리고 결정론적 최후의 수단 폴백(deterministic last-resort fallback)을 통해 집계된 도구 출력 증가, 프롬프트 너무 김 응답 및 실패한 요약으로부터 복구됩니다. 로컬 모델 컨텍스트 창은 서버 메타데이터 또는 캐시된 프로브에서 해결할 수 있으며, 중단된 턴은 유효한 도구 호출 기록을 유지합니다.2026-05-11 - 백엔드/모델 UX 재설계---backend

selectsauto

,anthropic-native

, 또는 scripted

, 그리고 --model에서 생략된 경우 추론됩니다. 순수 Claude 이름은 네이티브 Anthropic SDK를 사용하며, 나머지 모든 것은 LiteLLM을 사용합니다.2026-05-07 — 프로그래밍 방식 모드—AlanCodeAgent(programmatic=True, ...)

은 벤치마크 하네스, 상위 에이전트 및 무인 파이프라인용 라이브러리 구성 요소로 Alan을 실행합니다. 호스트 수준 상태(~/.alan/ALAN.md, ~/.alan/memory/, 프로젝트 ALAN.md)와 네트워크/git/ask-user 도구는 건너뜁니다. 세밀한 도구 제어를 위한 새로운 tools= 및 disabled_tools= 생성자 매개변수가 있습니다.2026-04-28 — 프롬프트 캐싱— Alan은 이제 백엔드 모두에서 도구 정의, 시스템 프롬프트 및 대화 기록에 cache_control 중지점을 배치합니다. 시스템 프롬프트는 캐시를 무효화하는 동적 콘텐츠를 피하도록 최적화되었습니다. Alan Code의 비용을 줄이세요.

• 슬래시 명령어 참조

• CLI 플래그 참조

• 로컬 모델 가이드

• 비용 및 토큰 추적

• 예제 — CLI 에이전트, 자동 수정 루프, 스트리밍

• LICENSE — Apache 2.0

• 이 프로젝트는 Claude Code npm 패키지에서 영감을 받았지만, 자체 아키텍처로 Python에 처음부터 구축되었으며 추가 기능을 포함합니다.

• 도구는 사용자의 장치를 수정할 수 있습니다: 기본 edit 모드는 쓰기 도구를 허용하며 yolo는 모든 것을 허용합니다. safe를 사용하세요.

per-mutation 승인을 위해 작업 트리를 검토하고 신뢰하는 환경에서만 자율 에이전트를 실행하세요. - 이름 'Alan'은 컴퓨터 과학의 아버지 중 한 명인 Alan Turing과 Claude Shannon에게서 유래했습니다.