⚡ Agent-2

A self-hosted autonomous AI agent powered by Google Gemini —
coding assistant, terminal agent, security tester and persistent memory in one interface.

What it is • Quick start • Surfaces • Tools • Models • Subsystems • Security • Config • Architecture • Tests • Docs

🚀 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

Personal Intelligence Layer

Three modules over one memory and one passive learning engine, entirely offline:

• Prediction — trie/prefix + n-gram + phrase ghost-text. Never calls an LLM.
• Grammar (off by default) — deterministic rules; masks technical spans, corrects,
  restores verbatim.
• Improve (off by default) — adds only preferences proven above a weight floor. Never
  invents requirements.

Learning is weight adjustment in SQLite, not model training: accept +0.08, ignore
−0.03, accept-then-delete −0.20. Both agent loops learn from the original text and
send the processed copy; history and display keep the original. POST /api/pil/wipe is the
forget-me path. Every function swallows errors and returns a safe default — PIL failure
degrades to do nothing.

🔐 Security posture

Agent-2 is built for security research, which puts two obligations on it: the tools have to be
genuinely capable, and the agent has to be genuinely constrained. Those are separate systems
with separate owners.

Who may reach the web surface — server/auth.py. One decision function, decide(),
installed as a single before_request, so an app that has the API has the guard. Modes come
from AGENT2_WEB_AUTH: auto (loopback trusted, everything else needs the token) · always
· off. The Socket.IO handshake does not pass through Flask's before_request, so
sockets.on_connect asks socket_allowed() itself — run_raw_command is a socket event, so
guarding /api/* alone would lock every reader and leave the shell open. Origin is checked on
unsafe methods before identity, because loopback trust cannot tell your own tab from a page
you happened to visit. The access token is memory-only; web_sessions stores SHA-256
digests, so a copied agent2.db grants nothing.

What an identity may do — core/permissions.py. Roles: owner (default) · operator
(may drive the agent, may not touch credentials or MCP endpoints) · viewer (read).
AGENT2_WEB_ROLE describes web clients; AGENT2_DENY_CAPS subtracts from this process,
CLI included. An unknown role falls back to viewer, never owner; an unmapped mutating
/api/ route falls to destructive. Both fallbacks point at the strict end.

How a credential is stored — core/secrets.py. Credentials persist as a2s:
references, never values, in exactly three columns. Backends in order: OS keyring (only if
a probe round-trip actually succeeds) → AES-256-GCM or a stdlib BLAKE2b+HMAC construction →
announced plaintext. resolve() passes a non-reference through unchanged, so every legacy row
keeps working, and seal() reads back what it wrote rather than let a caller persist a
dangling reference. The master key defaults to ~/.agent2/secret.key, outside the DB
directory — a key beside agent2.db travels with every copy of it. Honest scope: this defends
against exposure of the database alone, and describe() says so in its own payload.

Masking is a constant. ••••••••, its length not derived from the secret. The old
k[:6]…k[-4:] form printed most of a ten-character ZAP key.

There is deliberately no “skip TLS verification” switch. Quietly trusting any certificate
on a security tool's control channel is exactly the silent downgrade this project refuses to
ship.

Security testing

run_command supports the real toolchain — nmap, nikto, gobuster, ffuf, sqlmap,
hydra, metasploit, searchsploit, theharvester, binwalk, strings, volatility.
When Burp is connected, burp_* tools drive proxy history, Repeater, Intruder, Scanner and
the site map.

Both command kill ceilings default off, and only the stuck report is on at 20 seconds.
A security scan is supposed to sit silent for twenty minutes; a default timeout would kill a
legitimate nmap -p- mid-sweep and hand the model a truncated result it cannot recognise as
truncated.

⚙️ Configuration

All state is in agent2.db — never a .env file. config.DB is the one source of truth for
its path. Environment variables cover only the decisions that must be made before the database
is open; there are 116 of them, documented in full at
Environment variables. The ones most people set:

The graph family has its own ceilings, and every one of them is reported rather than silent:

Other limits worth knowing: MAX_CTX_MESSAGES=40, MAX_TOOL_OUTPUT=6000,
MAX_AGENT_ITERS=80, AGENT2_MAX_FILE_SIZE 100 MB.

🖥 CLI commands

Thirty-six slash commands. The full table, with the grammars that have real depth, is at
Slash commands. The families worth knowing here:

/mcp                                  ephemeral menu of every MCP server
/mcp <server> connect|disconnect|list|status|config
/mcp connect | /mcp disconnect        every server at once
/mcp health                           ✓/✗ per server, then [R]etry · [S]ettings

/workspace · /cd <dir>                where the agent is rooted
/tasks · /pause · /resume             background work, paused and picked up again
/offline                              which subsystems may reach the network
/history · /clearhistory              transcript · wipe it

/init [description]                   analyse THIS workspace, write .agent2/agent2.md
/skills [list|on|off|reset|show|last|reload]
                                      the project's own skills — a block list, not a force list

/workflow                             the plans in .agent2/workflows/ — executes nothing
/workflow run <name>                  validate → build the DAG → SHOW THE PLAN → run
/workflow auto <goal>                 a goal sentence becomes a graph; the plan is drawn first
/workflow state                       the live run, the waves, what starts next — and it
                                      releases what a dead process parked, by name

/ultracode start <goal>               the autonomous loop. One of exactly two doors
/ultracode run                        drive it — terminal only; the browser's next turn does
                                      this work through workflow.for_turn()
/ultracode approve · cancel · state · policy

/health                               ✓/⚠/✗/○ per subsystem, then problems and warnings
/metrics [reset]                      thirteen signals — count · avg · p50 · p95 · max
/recovery [scan|ack|retry|kill <kind> <id>]
                                      what a killed run left behind, and what the scan decided

/model [name|auto]                    switch model (auto = Agent-2 picks per turn)
/model routing [off|default_only|always]
/model caps [<model>] [field=value …] show or correct a capability record
/model rank [<model>|all] [force]     ask a model to classify an unrecognised id
/mode [fast|pro|thinking]

/settings (/config)                   one menu onto every settings area
/rules                                activate/deactivate injected rules
/keys · /addapi                       key status and usage · add a Gemini key
/theme · /color                       colour theme · accent colour
/memory · /addmem <text>              list memories · save one
/clear · /shrink · /clearhistory      clear screen · summarize · wipe history
/load                                 CLI only — the last conversation from THIS directory
/scan [path] · /run <cmd> · /read <file> · /search <query>

Auto-connect is per project, and it is set implicitly — connect / disconnect and the
bare /mcp menu write it through set_auto_connect(); there is no /mcp auto sub-command,
though POST /api/mcp/<key>/auto exists for the web surface.

/mcp's parser contains no literal server name — it resolves through registry.get(),
so a third bridge appears in the grammar by being registered. /mcp config with no server
asks instead of picking one, because a guessed target would silently edit the wrong
server's endpoint. /burp is retired from the help table but still forwards to /mcp burp …
and prints where it went — a command is never silently removed.

🌐 API surface

• 81 METHOD+path pairs in agent2/server/routes.py — the things a client can actually
  call, not the decorators — plus 4 in agent2/server/auth.py.
  Full reference: REST API.
• 25 distinct server→client Socket.IO events; 8 guarded client→server handlers plus
  connect/disconnect. guarded(event) is the one way a data handler is registered, so a
  handler and its capability arrive together. Full reference:
  Socket.IO events.

Highlights: GET /api/health (aggregate, 200/503 + problems, counters only — and a
disabled MCP server is not a problem), GET /api/mcp (every server, never a credential),
GET /api/commands, GET /api/sync, GET /api/models, GET /api/platform.

The graph family's routes read the same way the commands do. GET /api/workflows takes
?force=1 and ?verify=1 — verification is asked for, never volunteered, because
runner.verify() reads two ledgers and writes an audit line every time it runs, and a panel
polls this endpoint. POST /api/workflows/auto defaults to mode: "plan", which writes
nothing at all. GET/POST /api/ultracode are the web half of the loop, with start ·
approve · cancel — and run is terminal-only, named in the panel rather than omitted,
because engine.drive() needs a synchronous worker owning a whole model turn and a request
thread has neither the sid nor the stream. A refusal from any of them is
{"ok": false, "reason": …} inside a 200, and no payload ever carries a node's
instruction.

/api/burp* is gone: the four bespoke Burp routes were removed once /api/mcp reached
parity. Do not add a per-server route set back — that is the drift /api/mcp exists to end.

🏗 Architecture

User message
  → server/routes.py | server/sockets.py
  → core/scheduler.submit()      bounded pool; direct thread when disabled,
                                 rejects a full backlog with a visible message
  → agent.py:run_agent()         (or llm/provider_agent.py for custom providers)
      → pil.learn_from_message() + pil.process_outgoing_prompt()
      → core/broker.assemble()      ONE bundle per turn — 10 sources, one guard each,
                                    then budget.apply() decides what FITS
                                    → system_prompt(context=bundle)
      → core/diffs.capture_for()    snapshot BEFORE a file-writing tool runs
      → tools.dispatch_tool()       local tools
      → terminal.stream_command()   run_command (shell)
      → integrations.registry       resolve()s every MCP tool
      → fileintel.EXECUTOR          detect / run / convert / search
  → Socket.IO stream → browser  /  Rich output → CLI

There is a second, deliberately separate arm — autonomous execution. It shares the DAG,
the task rows, the checkpoints and the verifier with the turn path above, and it is reachable
through two doors only, because this loop writes code:

/ultracode start <goal>  |  POST /api/ultracode {"action":"start"}
  → core/ultracode/engine.start()
      → plan.brief()                 evidence: projectscan + gitstate + skills,
                                     names and counts only, never prose
      → skills.for_turn()            DISCOVER SKILLS, before a model sees the goal
      → workflow/dynamic.draft()     the goal becomes steps (one broker.assemble())
      → plan.graph_for()             steps + a verify node (+ a PAUSED approval gate
                                     the roots depend on, unless it is off)
      → dag/store.create()           1 exec_workflows row + N agent_tasks rows
  → engine.drive()                   ↺ schedule.run() — plan_next() picks; every declined
                                       node says why
      → engine.work(node)            dispatch on Node.kind (build · check · approval · fix)
      → core/verify.verify_tasks()   the record, not the claim
      → dynamic.replan()             only on R_BLOCKED / R_EXHAUSTED
  → engine.finalize()                re-reads, verifies, THEN settles

An ordinary prompt can never enter here, however the knobs are set — the importer list is
asserted structurally rather than promised. The stage is derived from the rows and never
stored, so a run killed mid-flight reports the stage that is true now.

The agent2/ package: server/ (browser surface), cli/, llm/, integrations/, core/,
fileintel/, plus top-level config.py, database.py, agent.py, tools.py, terminal.py.
The old flat paths (agent2.keys, agent2.routes, …) remain as shims resolving to the same
module object and singletons — agent2.keys.rotator is agent2.llm.keys.rotator.

Storage: 27 SQLite tables, 32 migrations, WAL mode, a pooled connection layer, and a
checkpoint thread. Nothing outside database.py may import sqlite3.

Full map: Architecture.

🧪 Tests

python -m pytest .github/tests/                 # 2670 tests
python -m pytest .github/tests/test_config.py   # single file

2670 tests (2668 pass, 2 skip) across 51 test modules, all under .github/tests/ (the root test/ directory is empty).
Many are sabotage-verified — the test was proven to fail against a deliberate break, not
assumed to work. Treat a test that looks trivial as suspect only after reading it: two
tautology traps — assertions that compared a thing to itself and stayed green while the
behaviour was deleted — have been found and fixed in this repository.

Some decisions are documented but deliberately not asserted, because no writer can produce
the state that would distinguish them. Document the invariant; don't assert on an unreachable
state.

🐳 Docker

python run.py --docker      # build the image and install the global `agent2` command
agent2 status | logs | stop | restart | update | uninstall

AGENT2_DB redirects the database to a mounted volume (/data), and AGENT2_LOG_DIR
defaults beside the database so logs land on the same volume. BURP_MCP_URL defaults to
http://host.docker.internal:9876 inside a container. Set SECRET_KEY for sessions that
survive a restart.

AGENT2_MODE selects the entrypoint: web | cli | dual (both is a legacy alias). The
detached compose service stays web — a background container has no TTY to host a CLI.
agent2 cli / agent2 dual run a one-off interactive container, and dual brings the
detached web half up first so both share the data volume rather than fighting over the
published port.

Because the secrets master key defaults outside the DB directory, a container wants
AGENT2_SECRET_MASTER_KEY (or a mounted key file) rather than the key travelling inside the
data volume with the ciphertext.

🩺 Troubleshooting

More, with the code behind each: Troubleshooting.

📚 Documentation

The full documentation is 45 pages at agent2.is-best.net/docs — served statically,
no build step. Every subsystem page states the rule and the bug the rule prevents.

Also in this repository: FEATURES.md (what it can do, feature by feature),
USAGE.md (how to drive it), CLAUDE.md (the invariant index for
contributors), and agent2.is-best.net/innovation (what is new here and why).

🧭 Agent-2-Pro

Agent-2-Pro is a planned hosted edition. Nothing described on the Pro page is implemented —
the shipping product is the self-hosted build this README documents. It is marked as such
wherever it appears, because a document that describes an unbuilt feature in the present tense
costs a reader real time before they discover it.

🤝 Contributing

Read CLAUDE.md first. It is an index of rules and where their rationale
lives — each hard-won invariant is pinned by a test and explained at length in the module
docstring of the file that owns it. ⚠️ marks one that has already been regressed once.

Before changing a ⚠️ module, read its docstring, then its test. Several rules are
load-bearing in non-obvious ways, and a few exist specifically to block a bug that produces
no error — just wrong output. If a rule looks redundant, the docstring says why it is not.

Then: run the suite, add a test that fails against a deliberate break of your change, and keep
each fact in exactly one place.

_{Built by Aarav Shah · aaravshah1311.is-great.net}