Agent-2

🚀 What it is

Agent-2 runs on your machine, talks to Google Gemini with your own API keys, and keeps every byte of state in one agent2.db beside the code. No account, no service, no telemetry, no build step.

It ships in three surfaces that are not three applications. They share the system prompt, the tool dispatcher, the memory and rules tables, the diff engine, the command watchdog, the model router and the database. Switching from the terminal to a browser tab changes what you look at and nothing about what the agent can do.

⚡ Quick start

git clone https://github.com/aaravshah1311/Agent-2.git
cd Agent-2
python run.py                # creates .venv, installs deps, prompts for a Gemini API key

run.py is the universal launcher and the package manifest — the dependency tables live there and nowhere else.

python run.py --cli          # CLI (default)
python run.py --web          # web server
python run.py --dual         # both at once
python run.py --addapi       # manage Gemini API keys
python run.py --update       # pull latest (preserves agent2.db)
python run.py --reset        # wipe .venv and reinstall
python run.py --uninstall    # remove venv, DB, global command
python run.py --docker       # Docker runtime + global `agent2` command

After the first run a global agent2 command exists: agent2 (CLI), agent2 web, agent2 dual, plus the Docker subcommands stop | restart | logs | status | update | uninstall.

Direct entry, skipping the launcher: .venv/bin/python agent2cli.py (Windows: .venv\Scripts\python agent2cli.py).

Requires Python 3.9+. Get a free Gemini API key at aistudio.google.com/apikey.

🧠 Three surfaces, one brain

Everything below is shared. That is the point of the architecture, and it is enforced by a rule the codebase applies everywhere: each fact has exactly one home, because a second copy drifts silently — each surface still looks right on its own.

🛠 The 18 agent tools

Core (13) — run_command, read_file, write_file, multi_edit_files, list_dir, grep_search, delete_file, scan_project, web_search, update_todo, save_memory, emit_plan, update_project_doc

File Intelligence (5) — detect_file, file_capabilities, run_file_op, convert_file, search_workspace — router-dispatched shims into agent2.fileintel, so backends are chosen internally.

Seventeen of them go through tools.dispatch_tool. run_command alone goes through terminal.stream_command, which is why the exec capability gate is implemented twice on purpose — and why the CLI's copy sits outside the retry loop: a refusal must not become an allow on retry.

When an MCP bridge is connected its tools are added dynamically and force-prefixed (burp_, zap_). Ownership is membership, not prefix: registry.resolve() asks each bridge whether it actually holds a name, so a disconnected ZAP stops claiming zap_* instead of swallowing the call.

The tool capability gate returns a tool error, never an exception. The model reads errors and adapts; an exception would end the turn.

🤖 Models and modes

config.MODELS and config.MODES are the only declaration of either, and two tests guard each direction.

⚠️ THINKING_GROUPS is the empty tuple, so every group supports thinking. supports_thinking() reads True if not THINKING_GROUPS else group in THINKING_GROUPS — empty means no group is excluded, not no group qualifies. The thinking mode description string still names specific groups; that string is the stale half. Never re-derive the answer from a model key: the predicate takes a group precisely so a new model joins an existing group and inherits the answer for free.

Routing is opt-in and explicit selection always wins. Both surfaces send a model key every turn, so a router that ran unasked could not tell a choice from a default. auto is a user-selectable pseudo-key — deliberately not in config.MODELS, which is the list of things that can be called. AGENT2_MODEL_ROUTING widens it to default_only or always.

A mid-turn failure is a continue in the existing loop, not a restart: context, tokens, tool context, checkpoints and the cancel token all survive, because restarting would replay completed tool calls. The hop budget is per turn, not per model.

Custom providers

Any OpenAI- or Anthropic-compatible endpoint (base URL + key + model id + format) appears in the selector as custom:<id>. llm/provider_agent.py mirrors agent.py exactly — same tools, same Socket.IO events, stdlib urllib only.

🧩 Subsystems