Alan Code

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.

Highlights

• 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.

Installation

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 .

Quickstart

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 session

The 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.

Usage

CLI mode

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.

Commands

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.

Parameters

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 session

Other 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.

GUI mode

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.

As a python library

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.

Example 1 : Build a CLI agent in 10 lines of code:

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.

Example 2 : Auto-fix loop — let the agent iterate until tests pass

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.

Example 3 : Stream assistant text and tool calls live

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.

Programmatic mode — Alan as an embedded library

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.

Features

Core

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

Original to Alan Code

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)

Other

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

Not (yet) implemented

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.

What's new

See CHANGELOG.md for the full history.

• 2026-05-11 — Provider / model UX redesign — --provider is replaced by --backend (auto / anthropic-native / scripted); the upstream provider lives inside the model string as a prefix (ollama/llama3, openrouter/..., gemini/...). --backend is inferred from --model — bare Claude names use the native Anthropic SDK, everything else uses LiteLLM. Old --provider flag, settings key, and /provider command 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/, project ALAN.md, AGT bootstrap) and the network/git/ask-user tools. New tools= and disabled_tools= constructor params for fine-grained tool control.
• 2026-04-28 — Prompt caching — Alan now places cache_control breakpoints 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.

Further reading

• Slash commands reference
• CLI flags reference
• Local models guide
• Cost & token tracking
• Examples — CLI agent, auto-fix loop, streaming
• LICENSE — Apache 2.0

Notes

• 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 yolo permission 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.