📦 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%:

Task	Standard AI Agent over SSH	With AgentBox	Token Savings
Analyze 800-line file	Reads full file (~3,000 tokens)	agentbox outline (~120 tokens)	-96% ⚡
Inspect target function	Guesses line ranges (~600 tokens)	agentbox get-fn (~150 tokens)	-75% 📉
Run long build (cargo)	Streams 200 lines (~1,500 tokens)	agentbox run silent (~40 tokens)	-97% ⚡
Atomic in-place patch	Raw diff / cat (~400 tokens)	agentbox patch (~60 tokens)	-85% 📉
Project navigation	find . / tree (~1,200 tokens)	agentbox tree (~150 tokens)	-88% 📉

---

🚀 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

---

🛠️ Quickstart

1. Configure Target (Optional)

Configure your remote SSH server once (stored in .agentbox.json or ~/.agentbox/config.json):

agentbox config --set-host user@192.168.1.171 --set-cwd ~/my_project

Or pass --host and --cwd directly to any command:

agentbox --host user@192.168.1.171 --cwd ~/my_project tree

To run locally, simply omit the host:

agentbox tree

---

📖 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 view <file> [--start N] [--end M]

Displays an exact line slice with 1-indexed line numbers:

agentbox view src/gateway.py --start 48 --end 65

---

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>"

Token-optimized test runner that suppresses passing tests and extracts high-signal failure tracebacks (pytest, cargo test, npm test):

agentbox test "pytest tests/"

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 write <file> [--content "..."] [--append]

Safely creates or appends to a file without any bash quote escaping issues (supports stdin streaming):

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

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

Safely replaces code with automatic .bak backup creation:

agentbox patch src/config.py --old 'PORT = 8000' --new 'PORT = 9000'
# Output: OK: Replaced 1 occurrence(s) in config.py. Backup: config.py.bak

agentbox rollback <file>

Restores file from backup in case of errors:

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

---

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] [--max N]

Fast token-limited search across text files:

agentbox grep "handle_packet" src/ --max 10

---

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"

---

🤖 System Prompt for AI Agents

Add this rule to your project's AGENTS.md or .cursorrules to instruct your AI agent to use agentbox:

## Remote & Local Execution (AgentBox)
Always use `agentbox` for remote server operations to minimize token consumption:
1. Use `agentbox outline <file>` before reading entire files.
2. Use `agentbox get-fn <file> <name>` to read specific functions.
3. Use `agentbox run "<command>"` for all builds, tests, and long commands.
4. Use `agentbox patch <file> --old "..." --new "..."` for code modifications.

---

📄 License

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