⚡ Agent-2-Beta

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

Overview • Install • Run • Keys • CLI • Troubleshoot • Usage • Features • Pro Version • Contribute

---

🚀 Overview

Agent-2-Beta is a self-hosted autonomous AI agent powered by Google Gemini. It ships in three modes:

Mode	Entry point	Description
⚡ CLI (default)	agent2cli.py	Terminal-native agent — Rich + prompt_toolkit, same brain, tools, and memory as the web UI
🌐 Web UI	agent2web.py	Browser interface — workspaces, multi-tab terminals, Three.js 3D welcome, real-time streaming
🔀 Dual	agent2dual.py	Web UI on a background thread + CLI in the foreground. One agent2.db, both surfaces live at once

All three modes share the same 17 agentic tools, persistent memory engine, offline Personal Intelligence Layer, File Intelligence System, Burp Suite MCP bridge, custom-provider support, and an agent2.db SQLite store for keys/memories/rules.

---

✨ Core Features

	Feature	Description
🗂️	Workspaces	Claude Projects-style context — path browser, per-workspace memory, framework detection
🤖	17 Agent Tools	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 + File Intelligence (detect_file, file_capabilities, run_file_op, convert_file, search_workspace)
🗂️	File Intelligence	Plugin-based universal file processing — detect any common type (69 formats, 11 plugins), then read/summarize/convert/analyze/OCR/extract/search across a workspace
📝	Multi-File Editing	Precise find-and-replace patching across multiple files autonomously
🧠	Persistent Memory	Global, workspace-scoped, and auto-extracted memories across sessions
🔮	Personal Intelligence Layer	Fully offline personalization — ghost-text prediction, opt-in grammar correction, and prompt enrichment from your own proven preferences. No network, no retraining
🔄	Cross-surface Sync	Add a memory in the browser, use it in the CLI on the next turn. Versioned sync_state counters + an in-process event bus keep both surfaces coherent over one SQLite file
💻	Multi-tab Terminals	Live streaming, stdin injection, ↑↓ command history, 2-stage kill
🔑	API Key Rotation	Up to 9 keys, auto-rotate on quota, pin a key, per-key usage stats
🔌	Custom Providers	Bring your own API — any OpenAI- or Anthropic-compatible endpoint (base URL + key + model id)
🕷️	Burp Suite MCP	Connect to Burp's MCP server and expose every Burp tool (Proxy, Repeater, Intruder, Scanner…) to the agent
🔒	Security Testing	Autonomous vulnerability scanning, logic flaw detection (XSS/SQLi), nmap, metasploit built-in workflows
🌐	Web Search	DuckDuckGo instant answers — no extra API key required
✏️	Message Editing	Edit any past message and re-run the agent from that point
⏹️	Stop Generation	Cancel agent mid-flight at any time
📎	File Attachments	Attach code, images, PDFs as context
▶️	One-click Run	Click ▶ on any tool block to instantly run that command in the active terminal
🎨	3D Welcome Screen	Three.js — neural particles, hexagonal node network, rotating orbits
📦	Project Auto-Setup	Detect framework → install deps → run project automatically

---

🖼️ Screenshots

_{Left: Web Interface  •  Right: Installation & Setup}

_{Agent2 CLI — Rich UI, key rotation, ↑↓ history, and all 17 tools in the terminal}

---

🧱 Project Structure

Agent-2-Beta/
├── run.py                  ← Universal launcher — setup, run, update, manage keys
├── install.py              ← One-line network installer (curl | python)
├── agent2web.py            ← Web UI entry point
├── agent2cli.py            ← CLI agent entry point
├── agent2dual.py           ← Dual mode — web on a thread, CLI in the foreground
├── agent2.db               ← SQLite DB — keys, memories, rules, providers (auto-created)
├── public/                 ← Static web assets (style.css, script.js, favicon.ico)
├── website/                ← Marketing / docs landing page (responsive, light + dark)
│   ├── index.html          ← Landing page
│   ├── 3.js                ← Three.js scenes (logo network + ambient background)
│   └── docs/               ← Documentation site
└── agent2/
    ├── config.py           ← Platform detection, models, modes, constants
    ├── database.py         ← Pooled SQLite helpers + schema + migrations (WAL)
    ├── tools.py            ← 17 tool implementations + Gemini schema
    ├── terminal.py         ← stream_command, stdin, kill, stop events
    ├── agent.py            ← system_prompt, context builder, Gemini agent loop
    ├── core/               ← Shared engine: sync, memory, rules, session,
    │   │                      workspace, logging + pil/ (Personal Intelligence)
    │   ├── sync.py         ← Centralized sync: RWLock, EventBus, cross-process versions
    │   └── pil/            ← Offline prediction / grammar / prompt-improvement
    ├── llm/                ← keys (KeyRotator), providers, provider_agent, resilience
    ├── server/             ← routes.py, sockets.py, ui.py, weblog.py, ports.py
    ├── fileintel/          ← Plugin-based File Intelligence (detect/read/convert/OCR)
    └── integrations/       ← burp_mcp — Burp Suite MCP bridge

# Back-compat shims (agent2.keys, agent2.routes, …) re-export the subpackage
# modules — both spellings resolve to the SAME object and the same singletons.

Note: Agent2 no longer uses .env. All keys and settings live in agent2.db.
Any legacy .env is imported once on first run, then renamed to .env.migrated.

---

⚙️ Installation

Option A — One-line install (recommended)

Run this in any terminal. It downloads Agent2, builds an isolated .venv, installs
every dependency, and starts the app — no manual clone required:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/aaravshah1311/Agent-2-Beta/main/install.py | python3 -

# Windows (PowerShell)
irm https://raw.githubusercontent.com/aaravshah1311/Agent-2-Beta/main/install.py | python -

The installer clones into ./Agent-2-Beta. Override anything with env vars:

AGENT2_DIR=~/tools/agent2   \   # where to install   (default: ./Agent-2-Beta)
AGENT2_MODE=cli             \   # cli | web | dual | none    (default: cli)
curl -fsSL https://raw.githubusercontent.com/aaravshah1311/Agent-2-Beta/main/install.py | python3 -

ℹ️ Why a dedicated install.py? Piping run.py straight into Python does not
work — the launcher is interactive (it prompts for keys) and a piped script has no
keyboard on stdin. install.py is built for the pipe: it never prompts, clones the
repo, then hands off to run.py for setup. Add your Gemini key afterwards in the web
Settings panel or with agent2 --addapi.

🔑 Free Gemini API key → https://aistudio.google.com/app/apikey

---

Option B — Manual clone

1 — Clone

git clone https://github.com/aaravshah1311/Agent-2-Beta.git
cd Agent-2-Beta

2 — Run the launcher

python run.py

run.py will automatically:

• ✅ Create an isolated virtual environment (.venv)
• ✅ Install all dependencies (flask, flask-socketio, google-genai, rich, mcp, …)
• ✅ Prompt for your Gemini API key and save it to agent2.db
• ✅ Install a global agent2 command and start the app

Option C — Docker (run the same project on any device, one command)

Docker gives you one identical, self-contained runtime on any machine — no local
Python, venv, or dependency setup. State (API keys, providers, memories, rules)
lives in a named volume, so it survives rebuilds and is isolated per device.

Run setup once and you get a global agent2 command backed by Docker:

git clone https://github.com/aaravshah1311/Agent-2-Beta.git
cd Agent-2-Beta

python run.py --docker      # pick OS, auto-install Docker if missing, install `agent2`

--docker walks you through it: choose your target OS (defaults to the one it
detects), and if Docker isn't installed it installs it for you via your platform's
package manager (winget/choco on Windows, brew on macOS, apt/dnf/yum/pacman on
Linux). Then it installs the global agent2 command and does the first build.

Prefer a one-click installer script? They live in the docker/ folder and do
the exact same thing (they just hand off to run.py --docker):

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File docker\dockerinstall.ps1

# macOS / Linux
bash docker/dockerinstall.sh

From then on, in any terminal, just type:

agent2            # interactive CLI session inside the container (default)
agent2 cli        # same as above
agent2 web        # start the Web UI and open the browser (builds on first run)
agent2 dual       # Web UI in the background + a CLI in this terminal
agent2 stop       # stop the container (keeps your data volume)
agent2 restart    # restart the container
agent2 logs       # follow container logs
agent2 status     # show container status
agent2 update     # rebuild the image from the latest code
agent2 uninstall  # stop + remove the container AND its data volume
agent2 help       # all commands

The first agent2 web opens http://localhost:1311 — add your Gemini API key in the
UI once and it persists in the agent2-data volume.

On Windows, open a new terminal after --docker so PATH refreshes. The
agent2 command auto-starts Docker Desktop if it isn't already running.

Prefer raw Compose? You can skip the agent2 command and drive Compose directly:

docker compose up -d --build   # start
docker compose down            # stop (keeps data)
docker compose down -v         # stop AND wipe the data volume

Notes

• Persisted state: the DB path is set by AGENT2_DB=/data; back up or share the agent2-data volume to move state between machines.
• Session secret: set a stable SECRET_KEY (env or a .env file next to docker-compose.yml) so web sessions survive restarts.
• Burp Suite: Burp runs on the host, so the container reaches it via host.docker.internal. Point it explicitly with BURP_MCP_URL (default http://host.docker.internal:9876) and set BURP_MCP_ENABLED=1 to auto-connect.

---

▶️ Run Modes

agent2 command — all flags at a glance

After the initial installation, the agent2 command is added to your PATH globally.

agent2                 setup + start CLI agent  (default)
agent2 --cli           setup + start CLI agent
agent2 --web           setup + start Web UI
agent2 --dual          setup + start DUAL — Web UI in the background, CLI here
agent2 --addapi        add / manage API keys
agent2 --update        update to the latest code  (keeps agent2.db)  (-up also works)
agent2 --reset         wipe venv and reinstall everything
agent2 --uninstall     completely remove Agent2 (venv, keys, DB, global command)
agent2 -h              show this help menu

---

🌐 Web UI

agent2 --web

Opens at → http://localhost:1311

If port 1311 is already taken (a second instance, or another app), Agent2 automatically
picks the next free and safe port — 1312, 1313, … — and prints the one it chose.
Privileged ports (<1024), well-known service ports (MySQL, Postgres, Redis, RDP …),
Burp's MCP port (9876) and the OS ephemeral range are never used. Pin a port
explicitly with AGENT2_PORT=8123.

---

⚡ CLI Agent

agent2
# or explicitly
agent2 --cli

Or call directly after first setup:

# macOS / Linux
.venv/bin/python agent2cli.py

# Windows
.venv\Scripts\python agent2cli.py

---

🔀 Dual mode (web + CLI at once)

agent2 --dual

Runs the Web UI in a background thread and the CLI in the foreground, so you get a
browser session and a terminal session at the same time. Both halves share the same
agent2.db, so keys, memories, rules, providers and chats are identical either way.

• Web UI → http://localhost:1311 (or the next free port), opened in your browser automatically
• CLI → this terminal; /exit shuts down both halves
• Web logs go to agent2-web.log instead of the console, so nothing paints over the
  CLI prompt. Only a short summary block is printed on startup — it lists the loopback
  and LAN URLs, so you can open the UI from your phone or another machine.

# bring the web logs back to this terminal
AGENT2_WEB_QUIET=0    agent2 --dual
AGENT2_LOG_LEVEL=debug agent2 --dual     # full request + socket.io tracing (also un-quiets)
AGENT2_NO_BROWSER=1   agent2 --dual      # don't open a browser tab
AGENT2_HOST=127.0.0.1 agent2 --dual      # loopback only — not reachable from the network

Note — the Web UI has no authentication. Bound to the default 0.0.0.0, anyone who
can reach your machine on that port can drive the agent. Use AGENT2_HOST=127.0.0.1 on
untrusted networks. Not for public deployment.

⚠️ Demo / security note: the web server binds 0.0.0.0 by default and the UI has
no login — it exposes run_command (arbitrary shell). Anyone who can route to the
port can drive the agent. For demos and local work set AGENT2_HOST=127.0.0.1 (loopback
only) or run behind a firewall. Do not expose the port to the public internet.

Direct entry after setup:

# macOS / Linux
.venv/bin/python agent2dual.py

# Windows
.venv\Scripts\python agent2dual.py

---

🔑 Managing API Keys

Via agent2 — recommended

agent2 --addapi

Walks you through adding keys interactively and saves them to agent2.db.
Keys are stored in the api_keys table and auto-rotated when one exhausts its quota. No downtime — the next key is picked up on the very next request.

Inside a CLI session

/addapi

Paste a new key without leaving the session — saved to agent2.db immediately and active on the next call.

Reset everything

agent2 --reset

Wipes .venv/ and reinstalls all dependencies. Use when packages break or Python is upgraded.

Full uninstall

agent2 --uninstall

Removes the virtual environment and generated files, leaving source code intact.

---

🗂️ First Run — Workspace Setup (Web UI)

1. Open http://localhost:1311
2. Click + Create Workspace in the sidebar
3. Enter a name and optionally a project path — leave blank to auto-create a folder
4. Click the workspace → New Chat → start working

Every chat belongs to a workspace. The agent always knows your project path, detected framework, and accumulated workspace memories.

---

⌨️ CLI Commands Reference

Command	Description
/help	Show all commands
/addapi	Add a Gemini API key to agent2.db
/keys	Show current API key status and usage
/burp [connect|disconnect|list|status]	Manage the Burp Suite MCP bridge — connect to a running Burp and expose all its tools to the agent
/provider [add|list|use|del|test]	Add your own model API (base URL + API key + model ID; OpenAI- or Anthropic-compatible) and switch to it
/model [name]	Switch model (2.5-flash · 2.5-pro · 3.1-flash · 3.1-pro)
/mode [name]	Switch mode (fast ⚡ · pro ★ · thinking 🧠)
/theme [name]	Switch the CLI colour theme (arrow-key picker)
/color [name]	Set the accent colour
/clear	Clear the screen (keeps conversation history)
/shrink	Summarize and shrink history manually
/clearhistory	Clear the conversation history
/load	CLI only — load the last conversation from this directory. Every CLI launch starts fresh; /load is how you carry on where you left off (/resume is the broader picker, incl. other projects)
/history	Show last 10 messages
/memory	List all saved memories with importance scores
/addmem <text>	Save a memory manually
/scan [path]	Scan and analyze entire project directory, tech stack, and structure
/run <cmd>	Run a shell command directly
/read <file>	Read and display a file's contents
/search <query>	Web search via DuckDuckGo (no key required)
/exit · Ctrl+C	Quit

---

🧪 Setup Checklist

• Python 3.10+ installed
• python run.py completed without errors
• Gemini API key saved to agent2.db
• Web UI → server starts at http://localhost:1311, first workspace created
• CLI → prompt you Agent2 [PowerShell|2.5-flash|★]> appears (the second field is your current directory)

---

🤖 Models Available

Key	Model	Group
2.5-flash	Gemini 2.5 Flash (default)	2.5
2.5-pro	Gemini 2.5 Pro	2.5
3.1-flash	Gemini 3.1 Flash	3.1
3.1-pro	Gemini 3.1 Pro	3.1

Need a different model or provider? Add any OpenAI-/Anthropic-compatible endpoint
with /provider add (CLI) or the Providers tab in web Settings — it then appears
in the model dropdown alongside the built-in Gemini models.

⚡ Reasoning Modes

Mode	Max Tokens	Best for
⚡ Fast	2 048	Quick answers, simple commands — lowest cost
★ Pro	8 192	Most tasks — balanced speed and quality
🧠 Thinking	16 384	Complex reasoning, architecture, hard bugs (2.5 / 3.1 only)

---

🛠️ Tech Stack

Layer	Technology
Backend	Python 3.10+, Flask, Flask-SocketIO
AI Engine	Google Gemini (google-genai)
Database	SQLite (stdlib sqlite3)
Terminal	subprocess.Popen — live stdout streaming
Web frontend	Vanilla JS, xterm.js, marked.js, highlight.js, Three.js
3D scene	Three.js r128 — particles, hexagonal node network, orbit rings
CLI UI	Rich — panels, markdown, syntax highlight, spinner
Memory	Auto-extraction via background Gemini call after each reply
Web search	DuckDuckGo Instant Answer API — no key required
Concurrency	Pooled SQLite + WAL, writer-preferring RWLock, per-chat KeyedLock, cross-process version counters
Tests	pytest — 264 tests, real-thread concurrency assertions

---

🏗️ Engineering Notes

The parts worth reading if you're evaluating the codebase:

Cross-surface synchronization — agent2/core/sync.py
Agent2 is concurrent three ways at once: threads in one process, two processes over one
SQLite file (dual mode), and two surfaces over one user. One module handles all three —
a writer-preferring RWLock (readers can't starve an invalidation), a KeyedLock that
reclaims idle locks so chat ids don't leak, an EventBus that counts subscriber errors
instead of propagating them, and sync_state version counters for the cross-process half.

Connection-pool failsafe — agent2/database.py
sqlite3 opens an implicit transaction on a statement that raises. Pooling that
connection would let a later, unrelated commit() flush the failed statement's partial
write — so a connection that raised is discarded, never pooled, and _release() rolls
back before returning one. Covered by test_db_pool_failsafe.py.

A subtle ordering bug, found and fixed — agent2/agent.py
created_at is datetime('now') — second-granular. A single agent turn writes its
user / tool_call / tool_result / assistant rows well inside one second, so ordering by
that column alone left the whole turn tied, and SQLite broke the tie by rowid — which
under DESC means reversed. The model was being handed turns backwards, with
tool_result before its tool_call (which the pairing rule then silently dropped).
rowid is the real tie-break.

Graceful degradation as a rule — every PIL and File Intelligence entry point swallows
its errors and returns a safe default. A missing optional library produces a structured
"pip install X" hint, not a stack trace. With zero optional libraries installed, the
File Intelligence System still registers 11 plugins / 69 formats / 331 operations.

python -m pytest .github/tests/     # 264 passed

---

🔒 Security Testing Workflows

Agent-2-Beta is purpose-built for security research and CTF work:

portscan 10.10.1.1
enumerate http://target:8080 with gobuster
run sqlmap on http://target/login?id=1
check for open ports on localhost
scan for vulnerabilities on 192.168.1.0/24
brute force SSH on 10.10.1.5 with hydra

Supports: nmap, nikto, gobuster, ffuf, sqlmap, hydra, metasploit,
searchsploit, theharvester, binwalk, strings, volatility, and more.

---

📌 Troubleshooting

Problem	Solution
No API keys configured	python run.py --addapi or type /addapi in the CLI
Key quota exhausted	Keys rotate automatically. Add more: python run.py --addapi
Model returns empty response	Switch to 2.5 Flash: /model 2.5-flash
Terminal not showing output	Refresh the browser tab and reconnect
python not found on Windows	Use py run.py or install from the Microsoft Store
Port 1311 already in use	Nothing to do — Agent2 auto-picks the next free safe port and prints it. Pin one with AGENT2_PORT=8123
Broken venv / import errors	python run.py --reset — wipes and reinstalls cleanly
CLI spinner frozen	Ctrl+C — cancels the request and returns to prompt
rich not installed	python run.py --reset — rich is included in the install list
Want to start completely fresh	python run.py --uninstall then python run.py

---

📖 Usage Guide

New here? USAGE.md walks you through your first task — the exact
prompt that makes the agent build a project from scratch, what to expect while it
runs, and the day-to-day commands. Quick start:

export AGENT2_HOST=127.0.0.1      # loopback only — the Web UI has no login
python -m pytest .github/tests/   # 264 passed
agent2

✨ Features, Tests & Code Quality

Want the full inventory? FEATURES.md covers every feature
(17 tools, 11 plugins · 69 formats · 331 operations, PIL, Burp MCP, sync), the
test suite breakdown (264 tests, what each file asserts), and an honest
code-quality assessment — strengths and known gaps.

---

🚀 Agent-2-Pro

Unlock the full power of autonomous AI engineering.

Agent-2-Pro is the professional-grade evolution of Agent-2-Beta — a proper Software Engineer and Brutal Pentester in one agent.

Pro Feature Highlights

🏗️ Software Engineering Mode
Analyzes your prompt, architects the full solution, and engineers a complete multi-file project in a series of precise, self-correcting steps. One prompt → production-ready codebase.

🎯 DeepDive
Breaks a single complex task into multiple focused sub-tasks, solves each with precision, then assembles the final result. Dramatically higher accuracy on hard problems.

🔴 Brutal Pentester
Goes far beyond basic scanning — full kill-chain automation: recon → enumeration → exploitation → post-exploitation → report generation, all in one session.

🧪 QA Mode
Automatically generates unit tests, integration tests, and edge-case coverage for any codebase it builds or is given.

Get Agent-2-Pro

📧 Contact: [email protected]
🐙 GitHub: github.com/aaravshah1311

---

🤝 Contributing

Contributions are welcome and appreciated! Agent-2-Beta is open to improvements in any area.

How to contribute

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name
   

3. Make your changes and commit with a clear message

   git commit -m "feat: add your feature description"
   

4. Push to your fork

   git push origin feature/your-feature-name
   

5. Open a Pull Request against main

What we're looking for

• 🐛 Bug fixes — especially edge cases on Windows/Mac/Linux
• 🌐 New tools — additional agent capabilities
• 🎨 UI improvements — frontend polish, accessibility
• 📚 Documentation — clearer explanations, more examples
• 🔒 Security workflows — new pentest automation patterns
• ⚡ Performance — faster startup, lower memory, better streaming
• 🌍 Portability — improvements for different platforms or Python versions

Guidelines

• Keep changes focused — one PR per feature/fix
• Follow the existing code style in each file
• Test on at least one platform before submitting
• Add a brief description in the PR explaining what and why

Report issues

Found a bug or have a feature request? Open an issue — please include your OS, Python version, and the exact error message.

---

👤 Authors

Aarav Shah

Rudra Marathe

Naitik Soni

---