An open-source python coding agent, inspired by Claude Code. Usable in CLI, GUI, or as a Python library to build upon.
Alan Code implements many features of modern CLI agents, such as tool use, hooks, skills, context compaction and more, and adds unique ones such as cross-session memory, live cost tracking, and a GUI with a Chat, the model's exact perspective, and a git tree view.
Works with any LiteLLM compatible API key or provider, and several local model providers.
- Browser GUI with three panels — Chat, LLM Perspective (the model's exact view of the conversation), and a Git Tree of the agent's turns.
--gui - Cross-session memory — per-project and global memory the agent reads/writes between sessions, with three modes (
off/on/intensive). - Live cost + token tracking — estimated $ and token usage per API call, visible in-session.
- Runs anywhere — Anthropic direct, any LiteLLM provider (OpenAI, OpenRouter, Gemini, …), or local models via vLLM / SGLang / Ollama, with a text-based tool-call fallback for models without native tool use.
- Python library — drive the agent from your own code with sync, async, or streaming APIs. Build auto-fix loops, orchestrators, or custom UIs in a few lines.
Clone the repo and install in editable mode. Requires Python 3.11+.
git clone [email protected]:tboulet/Alan-Code-agent.git
cd Alan-Code-agent
pip install -e .Set your provider's API key in the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY, …).
alancode # default: claude-sonnet-4-6
alancode --model openrouter/google/gemini-2.5-pro # any provider/model
alancode --model ollama/llama3.1 # local Ollama
alancode --model openai/my-model --base-url http://localhost:8000/v1 # vLLM / SGLang
alancode --gui # browser GUI
alancode --resume # last sessionThe provider goes inside the model string (ollama/..., openrouter/..., gemini/...). A bare Claude name (claude-sonnet-4-6) automatically uses the native Anthropic SDK; everything else routes through LiteLLM. See CLI flags for the full list.
A terminal-based chat interface. Type a prompt and press Enter; Alan will stream its reply, request permission before running tools, and persist the session so you can --resume later.
| Command | Purpose |
|---|---|
/help |
List all available commands |
/clear |
Clear the conversation and start fresh |
/compact |
Manually trigger context compaction |
/status |
Show session info (model, tokens, cost) |
/cost |
Token usage and estimated $ |
/model |
Show or switch the current model |
/backend |
Show or switch the transport backend (auto / anthropic-native / scripted) |
/save |
Ask the agent to persist key info to memory |
/commit |
Stage + commit changes with an AI-generated message |
/diff |
Show git diff of uncommitted changes |
/memodiff |
Show differences in the agent's memory |
/skill |
Run a skill — /skill list, /skill <name>, /skill create |
/settings |
Show or update session settings |
/settings-project |
Show project settings. Edit .alan/settings.json to change |
/exit |
Quit the session |
Other commands in docs/reference/slash-commands.md.
alancode \
--model [model_name] \ # bare (gpt-4o, claude-sonnet-4-6) or
# provider/model (ollama/llama3.1, ...)
--backend [auto/anthropic-native/scripted] \ # advanced; inferred from --model
--api-key [key] \ # or set environment variable
--base-url [url] \ # for local servers (http://localhost:8000/v1)
--permission-mode [safe/edit/yolo] \
[--gui] \ # to launch in GUI mode
[--resume] # to resume last sessionOther parameters in docs/reference/cli.md.
Parameters can also be set in .alan/settings.json (auto-generated on first run) or modified at runtime with the /settings <key> <value> command.
Argument --gui launches a local GUI interface, with a Chat panel.
Additionally, it can also show:
- an LLM Perspective panel that shows the model's conversation
- a Git Tree panel that shows the git tree and the path of the agent conversation on it (feature in development).
The Git Tree feature (in development and unstable) allows you to move your agent over different branches of your git repo, and revert the conversation to previous points. To use with the /commit command.
Alan Code can also be used as a Python library using the AlanCodeAgent class, allowing you to build agents or orchestrator systems on top of it.
from alancode import AlanCodeAgent
agent = AlanCodeAgent()
while True:
try:
message = input("> ")
except (EOFError, KeyboardInterrupt):
break
if message.strip():
print(agent.query(message))Full example: examples/example_1_cli_agent.py. Run with python examples/example_1_cli_agent.py after installing the package.
Run your tests, feed the failures back to the agent, repeat until green. This is the kind of agentic orchestration you can't get from the plain CLI.
import subprocess
from alancode import AlanCodeAgent
agent = AlanCodeAgent(permission_mode="yolo")
agent.query("Read code_bugged.py and write a fixed version to code_fixed.py.")
for attempt in range(5):
result = subprocess.run(
["pytest", "-q", "test_inventory.py"], capture_output=True, text=True,
)
if result.returncode == 0:
print(f"All green after {attempt + 1} attempt(s).")
break
agent.query(f"Tests still fail:\n{result.stdout}\nFix the remaining bugs.")Full example (with a buggy module and a test suite): examples/example_2_auto_fix_loop/run_alan.py.
For embedding in a web app, TUI, or WebSocket bridge — receive events as the agent produces them.
import asyncio
from alancode import AlanCodeAgent
from alancode.messages.types import AssistantMessage, TextBlock, ToolUseBlock
async def main():
agent = AlanCodeAgent(permission_mode="yolo")
async for event in agent.query_events_async("List files, then summarize."):
if not isinstance(event, AssistantMessage):
continue
for block in event.content:
if event.hide_in_api and isinstance(block, TextBlock):
print(block.text, end="", flush=True)
elif not event.hide_in_api and isinstance(block, ToolUseBlock):
print(f"\n[tool: {block.name}({block.input})]")
asyncio.run(main())Full example: examples/example_3_streaming_agent.py.
When Alan runs inside another program (a benchmark harness, a parent agent, an unattended pipeline) rather than as a developer assistant, pass programmatic=True:
agent = AlanCodeAgent(
model="claude-sonnet-4-6",
cwd="/path/to/experiment",
permission_mode="yolo",
programmatic=True,
extra_tools=[MyDomainTool()], # optional
)This detaches Alan from project- and host-level state that would otherwise contaminate a controlled run: ~/.alan/ALAN.md, project ALAN.md, ~/.alan/memory/MEMORY.md, AGT bootstrap, and the network/git/ask-user tools (WebFetch, GitCommit, AskUserQuestion, Skill). Refine the tool set further with tools=[...] (full replacement) or disabled_tools=[...] (subtractive).
See docs/reference/python-api.md#programmatic-mode for details.
| Feature | What it does | How to use |
|---|---|---|
| Async agentic loop | Streaming responses, thinking blocks, concurrent tool use | default |
| Built-in tools | Bash, File I/O, Grep/Glob, WebFetch, AskUserQuestion, SkillTool, GitCommit | default |
| Context compaction | Summarizes conversation when context fills up | auto, or /compact |
Universal backend (auto) |
LiteLLM transport — 100+ providers including OpenAI, OpenRouter, Gemini, Ollama, vLLM, … | default for non-Claude models |
| Native Anthropic backend | Direct Anthropic SDK with cache_control, native thinking, native tool_use |
default for bare claude-* names; force with --backend anthropic-native |
| Local models | vLLM / SGLang / Ollama, with text-based tool-call fallback for models without native tool use | docs |
| Hooks | Pre/post-tool shell hooks for guardrails or logging | .alan/settings.json |
| Skills | User-defined prompt + tool filter, discoverable at runtime | /skill list, /skill create |
| Feature | What it does | How to use |
|---|---|---|
| Browser GUI | Chat + LLM Perspective + Git Tree panels on localhost | --gui |
| LLM Perspective panel | See the model's exact view of the conversation — debug prompts, tool calls, compaction | --gui, then toggle panel |
| Git Tree panel | Navigate the agent's turn-by-turn git history; revert to any commit | --gui, /move, /revert |
| Cross-session memory | Per-project + global memory the agent reads/writes between sessions. Modes: off (default), on (read at start, write on /save), intensive (read at start, write after every significant response) |
Set memory with /memory [on/intensive] or /save |
| Live cost tracking | Estimated $ and token usage per API call | default (docs) |
| Feature | What it does | How to use |
|---|---|---|
| Session persistence | Sessions saved to disk; resume any time | --resume, --continue <id> |
| Permission modes | Per-tool gating with project-scoped rules — safe (ask each), edit (ask edits), yolo (no checks) |
--permission-mode <mode> |
| Git integration | AI-written commit messages, diffs | /commit, /diff |
| Project + global instructions | Auto-loaded into the system prompt | ALAN.md, ~/.alan/ALAN.md |
| Python library API | Sync query(), async query_async(), streaming query_events_async() — build loops, orchestrators, or custom UIs on top |
from alancode import AlanCodeAgent |
Features of modern CLI coding agents that Alan Code does not ship with yet. Contributions welcome.
| Feature | Status | Notes |
|---|---|---|
| Subagents / Task tool | planned | Spawn isolated sub-conversations with their own context for parallel exploration or delegation. |
| MCP (Model Context Protocol) | planned | Connect external tool servers (databases, APIs, IDEs) through the MCP standard. |
| Plan mode | planned | Force the agent to write and get approval for a plan before touching code. |
| Image input | planned | Paste or attach images to the conversation; Gives Alan tools for image inference. |
| Stop / PreCompact / PostCompact hooks | partial | Only Pre/PostToolUse hooks are implemented today. |
| WebSearch tool | planned | The WebFetch tool can fetch and summarize pages, but doesn't do active searching yet. |
See CHANGELOG.md for the full history.
- 2026-05-11 — Provider / model UX redesign —
--provideris replaced by--backend(auto/anthropic-native/scripted); the upstream provider lives inside the model string as a prefix (ollama/llama3,openrouter/...,gemini/...).--backendis inferred from--model— bare Claude names use the native Anthropic SDK, everything else uses LiteLLM. Old--providerflag, settings key, and/providercommand keep working as deprecated aliases for one release. - 2026-05-07 — Programmatic mode —
AlanCodeAgent(programmatic=True, ...)runs Alan as a library component for benchmark harnesses, parent agents, and unattended pipelines. Skips host-level state (~/.alan/ALAN.md,~/.alan/memory/, projectALAN.md, AGT bootstrap) and the network/git/ask-user tools. Newtools=anddisabled_tools=constructor params for fine-grained tool control. - 2026-04-28 — Prompt caching — Alan now places
cache_controlbreakpoints on tool definitions, system prompt, and conversation history, for both providers. System prompt was optimized to avoid cache-killing dynamic content. Reduce the cost of Alan Code.
- Slash commands reference
- CLI flags reference
- Local models guide
- Cost & token tracking
- Examples — CLI agent, auto-fix loop, streaming
- LICENSE — Apache 2.0
- This project is inspired by the Claude Code npm package, but is built from the ground up in python with our own architecture, and include additional features.
- We are not responsible for any damage caused by the agent in
yolopermission mode, although models are instructed to be cautious about destructive actions. - The name "Alan" comes from Alan Turing, a father of computer science along Claude Shannon.