ai-agentbox

📦 AgentBox (ai-agentbox)

Ultra-lean, token-efficient remote execution, AST outlining, and safe atomic patching proxy for AI coding agents.

Designed for LLM agents (Claude Code, Cursor, Antigravity, Aider, Roo-Code, Windsurf) working on remote servers or local machines.

---

🎯 The Problem

When AI coding assistants work over SSH or terminal sessions, they burn massive token budgets on:

1. Dumping entire files (hundreds of lines of code just to locate one function).
2. Intermediate noise from long commands (cargo build, pytest, docker build streaming lines every second and triggering unnecessary agent turns).
3. Broken shell quoting (escaping nested quotes \" and ' in bash over SSH leads to repeated syntax errors and retry loops).

---

⚡ The Solution: AgentBox

AgentBox provides a Client $\leftrightarrow$ Worker architecture that reduces token consumption by 80% to 95%:

---

🚀 Key Features

• Zero External Dependencies: Built entirely on the Python 3 standard library.
• Self-Bootstrapping Worker: When targeting a remote SSH server, AgentBox automatically verifies, hashes, and deploys its standalone worker in milliseconds.
• Silent Task Runner: Suppresses intermediate stdout noise, streams to a local log file, and returns only execution time, exit code, and failure tail.
• Background Process Manager: Detached process spawning (spawn, status, logs, kill) that survives SSH disconnections.
• AST-Powered Skeletons: Extracts class and function signatures for Python, Rust, JavaScript, TypeScript, C/C++, and Go.
• Escape-Proof Atomic Patching: Sends replacement payloads over stdin IPC streams, eliminating bash quote escaping bugs forever.

---

📦 Installation

pip install ai-agentbox

---

🏠 Zero-Config Local Work

If there is no .agentbox.json in your project, AgentBox automatically runs 100% locally in the current directory. No setup, no SSH connection, and no configuration required:

# Works out of the box in any local directory:
agentbox outline src/app.py
agentbox view src/app.py --tail 50
agentbox patch-lines src/app.py --start 10 --end 15 --content "    return True\n"
agentbox test "pytest tests/"

Remote SSH execution is activated ONLY when you bind a remote host with agentbox config --set-host ... (which saves .agentbox.json).

---

🛠️ Quickstart: 3-Step Setup for Any Remote Project

Step 1: Install ai-agentbox locally

pip install ai-agentbox

Step 2: Bind Remote Server & Generate AI Rules

Run these two commands in your local project root:

# 1. Bind target SSH host, remote project path, and optional virtualenv:
agentbox config --set-host user@remote-server --set-cwd /home/user/my_project
# Optional: explicitly set virtualenv path (otherwise .venv/venv is auto-detected!)
agentbox config --set-venv /home/user/my_project/.venv

# 2. Automatically generate strict anti-token-waste rules for your AI agent:
agentbox init-rules

init-rules creates .cursorrules, AGENTS.md, and CLAUDE.md, strictly prohibiting the AI agent from using raw cat/grep/pytest over SSH and forcing agentbox.

Step 3: Let AI Agent Work (Zero Setup on Remote Server!)

Give any task to your AI assistant (Cursor, Claude Code, Antigravity, Windsurf, Roo-Code).

When the agent executes any agentbox command (e.g. agentbox tree or agentbox outline):

• AgentBox automatically connects via SSH to your Linux server.
• Checks if ~/.agentbox_worker.py exists and matches SHA-256 hash.
• Auto-deploys the zero-dependency worker to the server in milliseconds.
• You never have to log in to the remote server or install anything there manually!

---

📖 Command Reference

1. Code Navigation & Skeletons

agentbox outline <file>

Extracts only class, function, and method signatures with line numbers:

agentbox outline src/gateway.py

Output:

=== OUTLINE: gateway.py (350 lines) ===
  12-  45 | class GatewayConfig:
  48- 110 | async def handle_connection(reader, writer) -> bool
 115- 180 | def commit_flash_block(offset: int) -> None

agentbox get-fn <file> <function_name>

Extracts the exact definition and body of a target function:

agentbox get-fn src/gateway.py handle_connection

agentbox find-fn <name> [path] [--exact]

Recursively scans project AST to locate where a function or class is declared without noisy grep output:

agentbox find-fn get_bank
# Or exact match:
agentbox find-fn Bank --exact

Output:

=== FOUND SYMBOLS: 'Bank' (2 matches) ===
  app/bank/models.py:11   | class Bank(Base)
  archive/app/bank/models.py:13   | class Bank(BasicSecureModel)

agentbox view <file> [--start N --end M] [--tail N]

Displays an exact line slice with 1-indexed line numbers (supports --tail N or negative --start -N):

# Slice specific lines:
agentbox view src/gateway.py --start 48 --end 65

# View last 50 lines of logs or files in 1 step:
agentbox view logs/app.log --tail 50

---

2. Silent & Background Process Runner

agentbox run "<command>" [--tail N] [--timeout T]

Silently executes a command, redirects all stdout/stderr to a log file, and returns only the final verdict:

agentbox run "cargo build --release"

Output on success:

OK [exit 0, 42.15s] Log: /tmp/agent_logs/task_123456.log

Output on failure (automatically prints tail):

FAILED [exit 1, 12.30s] Log: /tmp/agent_logs/task_123456.log
--- Failure Tail (5 lines) ---
error[E0308]: mismatched types
  --> src/main.rs:42:15
   |
42 |     let x: u8 = val;
   |                 ^^^ expected `u8`, found `u16`

agentbox test "<test_command>" [--venv <path>]

Token-optimized test & type runner that suppresses passing tests and noise, extracting only high-signal failure tracebacks. Supports Python (pytest, unittest), Rust (cargo test), and Frontend (svelte-check, tsc, eslint, vitest, pnpm check).

[!TIP] Frontend & Svelte 5 / TypeScript Support: Running agentbox test "pnpm check" or agentbox test "pnpm svelte-check" automatically strips noisy compilation banners and stylistic warnings, highlighting only real type errors, file locations, and failure code snippets!

[!TIP] Automatic Virtualenv Detection: AgentBox automatically checks for .venv or venv in your working directory and parent project directories, prefixing PATH="$VENV/bin:$PATH" so tools like pytest and granian work instantly without full paths! You can also pass --venv /path/to/venv or set it in config (agentbox config --set-venv /path).

# Automatically finds .venv / venv:
agentbox test "pytest tests/"

# Or with explicit virtualenv:
agentbox test "pytest tests/" --venv /home/alex/pl3_2/.venv

Output on success:

OK [tests passed in 1.45s] (12 passed) Log: /tmp/agent_logs/test_491823.log

Output on failure (extracts traceback, saving up to 95% tokens):

FAILED [exit 1, 1.82s] Log: /tmp/agent_logs/test_491823.log
--- High-Signal Failure Traceback ---
>   assert result == 42
E   AssertionError: assert 100 == 42
tests/test_calc.py:15: AssertionError

agentbox spawn "<command>"

Spawns a detached background task that survives SSH disconnects:

agentbox spawn "python3 train_model.py"
# Output: SPAWNED: task_id=bg_849201 pid=4215 log=/tmp/agent_logs/bg_849201.log

agentbox status bg_849201
# Output: TASK: bg_849201 | Status: RUNNING | PID: 4215 | Runtime: 1m 24s

agentbox logs bg_849201 -n 20
# Output: displays last 20 lines of log

agentbox logs bg_849201 -f
# Output: live real-time log streaming (tail -f)

agentbox kill bg_849201
# Output: OK: Task bg_849201 (PID 4215) terminated.

---

3. File Operations & Safe Atomic Patching

agentbox patch-lines <file> --start N --end M [--content "..." | --base64 <b64> | --stdin]

The primary and safest way to edit code. Replaces line range [N..M] with automatic AST syntax validation and auto-backup stored cleanly in .agentbox/backups/:

# Direct replacement:
agentbox patch-lines src/main.py --start 10 --end 15 --content "    return True\n"

# Immune to PowerShell / SSH quoting & Cyrillic encoding bugs via Base64:
agentbox patch-lines src/main.py --start 10 --end 15 --base64 <b64_string>

agentbox write <file> [--content "..."] [--base64 <b64>] [--stdin] [--append]

Safely creates or appends to a file without shell quote escaping issues:

agentbox write src/settings.py --content 'DEBUG = True\nPORT = 8080'
# Or via pipeline:
cat config.json | agentbox write config.json --stdin

agentbox patch <file> --old "<exact_code>" --new "<replacement>"

Safely replaces code block with automatic backup in .agentbox/backups/ and Python AST validation:

agentbox patch src/config.py --old 'PORT = 8000' --new 'PORT = 9000'

agentbox rollback <file>

Restores file from .agentbox/backups/ keeping the Git working tree clean:

agentbox rollback src/config.py
# Output: OK: Restored config.py from backup and removed backup.

agentbox batch '<json_steps>' / agentbox batch --base64 <b64>

Executes multiple AgentBox actions (view, patch-lines, test, etc.) in a single turn to save LLM turns:

agentbox batch '[{"action": "view", "path": "src/app.py", "start": 1, "end": 20}, {"action": "patch_lines", "path": "src/app.py", "start": 5, "end": 7, "content": "    pass\n"}]'

---

4. Search & Directory Tree

agentbox tree [path] [--depth N]

Prints clean directory structure while automatically ignoring .git, node_modules, target, __pycache__, .venv, and build artifacts:

agentbox tree --depth 2

agentbox grep "<query>" [path_or_file] [-F] [--max N]

Fast token-limited search across directories OR a single file (regex or -F exact fixed substring):

# Search directory:
agentbox grep "handle_packet" src/ --max 10

# Search single file with exact match (-F):
agentbox grep "tasks.list" src/App.svelte -F

5. Knowledge Graph & Architecture (graphify)

AgentBox integrates with graphifyy to build and navigate deep code knowledge graphs without blowing LLM context budgets:

agentbox graphify-install [--upgrade]

Silently ensures graphifyy is installed on the local machine or remote SSH server:

agentbox graphify-install

agentbox graphify-build [path] [--deep]

Silently builds a navigable knowledge graph on the target host:

agentbox graphify-build
# Output: OK: Knowledge graph built in 4.2s (180 nodes, 420 edges). Location: graphify-out

agentbox graphify-query "<question>"

Queries graph structure, relationships, and God nodes directly on the host, returning token-capped answers (~150 tokens instead of dumping megabytes of JSON):

agentbox graphify-query "Authentication and Token flow"

---

6. Token-Efficient Git History & Changes

Agents waste thousands of tokens downloading full files just to see what changed or inspect past implementations:

agentbox git-status [path]

Compact status showing only modified and untracked files with (+add, -del) count in a few clean lines:

agentbox git-status

Output (~25 tokens vs 500+):

=== GIT STATUS: 3 changed files ===
  M   src/auth.py (+12, -3)
  M   src/config.py (+2, -0)
  ??  tests/test_auth_new.py

agentbox diff [path] [--rev <rev>] [--cached] [--max-lines N]

Token-optimized diff that automatically ignores lockfiles (package-lock.json, poetry.lock, Cargo.lock), strips formatting whitespace noise (-w), and caps output to avoid context overflow:

agentbox diff src/auth.py
# Or compare against a commit:
agentbox diff --rev HEAD~1

agentbox git-log [path] [-n N]

Ultra-compact one-line commit history:

agentbox git-log -n 5

Output (~30 tokens vs 2,000+):

=== GIT LOG: repository (last 3 commits) ===
df71336 (2 hours ago) docs: add AGENT.md, AGENTS.md <atitoff>
0508bc0 (3 hours ago) fix: update project URLs <atitoff>
2937539 (4 hours ago) feat: initial commit <atitoff>

agentbox git-view <file> [rev] [--start N --end M]

Extracts an exact slice of lines from any Git revision without downloading the entire 800-line historical file:

agentbox git-view src/auth.py HEAD~1 --start 20 --end 45

agentbox git-fn-history <file> <function_name> [-n N]

Traces the AST modification history of a specific function across Git commits:

agentbox git-fn-history src/auth.py verify_jwt -n 3

6. Project Tasks & Recipes (.agentbox.json)

Save recurring project commands and parameters (database connections, custom migrations, restart scripts) in .agentbox.json (automatically discovered in current directory or parent directories up to the Git root) and execute them with a short recipe command:

{
  "host": "user@server",
  "cwd": "/path/to/project",
  "venv": "/path/to/project/.venv",
  "tasks": {
    "db": "PGPASSWORD=secret psql -h localhost -U user -d db -c {args}",
    "migrate": "alembic upgrade head",
    "check-all": "pytest && npm run check"
  }
}

List available tasks

agentbox task
# or: agentbox task list

Run a task with optional arguments

agentbox task migrate
# With argument substitution ({args} or $@):
agentbox task db "SELECT * FROM users LIMIT 5;"
# Or arguments appended cleanly:
agentbox task check-all --verbose

Save or update a task recipe

agentbox task add db "PGPASSWORD=secret psql -h localhost -U user -d db -c {args}"
# Output: OK: Task 'db' saved to .agentbox.json.

Remove a task recipe

agentbox task rm db
# Output: OK: Task 'db' removed from .agentbox.json.

---

8. Sub-Millisecond Remote Execution (Persistent Daemon Bridge)

By default, every remote SSH command would incur a 300–1500ms overhead due to SSH handshakes and Python interpreter cold start. AgentBox solves this with an automatic, transparent Persistent Stdio-Daemon Bridge:

• Zero-config auto-start: Upon your first command, AgentBox automatically spawns a local background bridge that maintains a persistent SSH session connected to python3 ~/.agentbox_worker.py --daemon.
• Sub-millisecond latency: AST parsing, outline extraction, and atomic patching execute in-memory on the remote host in 2–5 ms.
• Auto-teardown: After 30 minutes of inactivity, both the local bridge and remote worker terminate gracefully to free memory.
• Fallback guarantee: If background processes are restricted, AgentBox transparently falls back to direct SSH IPC without interrupting your workflow.

Inspect active daemon connections:

agentbox daemon status
# Output: Host: user@server | Status: ACTIVE (Sub-ms latency) | PID: 12450 | Port: 54312 | Uptime: 45s

Stop daemon bridge manually:

agentbox daemon stop
# Output: Stopped daemon for host: user@server (PID: 12450)

Bypass daemon for a one-off command:

agentbox --no-daemon view src/main.py

---

🤖 Enforce AI Agents to use AgentBox (agentbox init-rules)

Generate strict anti-token-waste rules for AI assistants (Cursor, Claude Code, Antigravity, Windsurf, Roo-Code) with a single command:

agentbox init-rules
# Output: OK: Created AI rule files: .cursorrules, AGENTS.md, CLAUDE.md

Or target a specific environment:

agentbox init-rules --type cursor   # generates .cursorrules
agentbox init-rules --type agents   # generates AGENTS.md
agentbox init-rules --type claude   # generates CLAUDE.md

This installs strict rules prohibiting the AI assistant from running noisy cat, grep, find, or raw test commands over SSH, forcing the use of token-efficient agentbox commands.

---

📄 License

MIT License. Free for open-source and commercial use.