superagent

---

⚡ Overview

Superagent is a high-performance, terminal-native AI coding assistant built for developers. It executes shell commands, inspects and edits codebases, runs test suites, manages multi-file edits, and automates context pruning—all directly from your local terminal.

Superagent also pairs natively with t-line, its official desktop client.

---

✨ Key Features

• 🎯 Single Agent Mode (Primary): Seamless pair programming with live terminal execution, intelligent tool usage, and subagent delegation.
• 🖥️ Native Desktop Integration: Automatic connection with t-line desktop GUI app without manual configuration.
• 🧠 Smart Context Management: Automatic token tracking, LLM summarization, strategy-based pruning, and message pinning.
• 🛡️ Local Git Checkpoints: Automatic branch checkpoints and safety rollbacks during active sessions.
• 🛠️ Integrated Tooling: Built-in file search, regex ripgrep, background command runners, terminal presets, system-level screenshots, and Playwright web page screenshots.
• 🌐 Remote SSH Workspaces: Secure connection to remote hosts with active boundary protection, interactive path expansion, local-to-remote file transfer, and workspace-based session continuation.
• 🤖 3-Tier Multi-Agent Mode (Experimental): Master Agent orchestrating isolated Superagents across parallel Git worktrees (--multi).

---

🚀 Quick Start

Installation

Requires Bun (v1.0 or later) or Node.js.

# Clone the repository
git clone https://github.com/RudyCity/superagent.git
cd superagent

# Install dependencies & build
bun install
bun run build

# Register globally (optional)
bun install-g .

Usage

# Start Superagent in the current workspace
superagent

# Open Superagent in a specific project directory
superagent --dir /path/to/project

# Launch in Multi-Agent Orchestration mode (Experimental)
superagent --multi

---

💻 Desktop App Integration (t-line)

Superagent connects automatically with t-line, the desktop version of Superagent.

No manual server configuration or extra CLI arguments are required—simply launch t-line alongside Superagent for a unified desktop experience.

---

⌨️ Command Reference

Core & Session Commands

Command	Description
/help	Display interactive command guide and active shortcuts
/new	Start a new session (clear history & screen)
/clear	Clear conversation history
/resume	Resume a conversation session from history via wizard
/session	Manage session history: list, export <id>, clear --empty
/history	Manage SQLite history database: stats, export, backup, migrate, tag
/search-history /sh	Search conversation history. Usage: /sh <query> [--all] [--debug]
/knowledge /k	Browse & search global pinned knowledge (cross-session)
/pin	Pin important messages (full content + agent tag)
/checkpoint	Manage checkpoints to save/restore conversation state
/compact	Show compaction status / force context compaction
/compaction-history /ch	View compaction audit trail
/goal	Activate Goal Mode for long-running overnight tasks
/init	Initialize project (Git setup, agents.md generation, system audit)
/exit /quit	Exit the application
/image	Attach image from clipboard (paste) or file path (attach <path>)

Configuration & Providers

Command	Description
/login	Configure AI provider credentials (e.g. /login openrouter sk-or-...)
/model	Switch model presets or custom tier configurations
/settings	View current rate limit, concurrency & app settings
/setting-concurrency <0|1>	Set LLM concurrency limit
/setting-rpm <number>	Set rate limit RPM
/setting-capacity <number>	Set rate limit capacity
/setting-streaming <on|off>	Enable or disable streaming
/setting-context-limit <number>	Set context window limit (0 = auto)
/setting-max-iterations <number>	Set max agent iterations (0 = unlimited)
/setting-checklist-limit <number>	Set task checklist visible limit
/setting-history-limit <number>	Set checklist history visible limit
/setting-procs-limit <number>	Set processes panel visible limit
/setting-focus /focus	Set reasoning focus depth: off|low|medium|high|xhigh|max|custom
/setting-focus-budget <number>	Set reasoning focus custom budget tokens
/setting-classifier <on|off>	Enable/disable multi-category request classifier
/setting-classifier-threshold <high|medium|low>	Set classifier heuristic confidence threshold
/setting-rmemory	Configure RMemory: on, off, provider, model, dimensions

Agent, Tools & Automation

Command	Description
/agents	List active subagents and defined subagent types
/processes /procs	List running background processes
/processes stop [id|all]	Stop background processes
/terminal	Manage & execute terminal presets. Subcommands: <command>, preset <name>, bg <cmd>, all, init, stop, list
/skills	List all installed agent skills and templates
/install	Install a skill from skills.sh (e.g. /install vercel-labs/skills/find-skills)
/memory	Manage and inspect RMemory long-term memory: status, sync, search, add, delete, list-scenes, read-scene, read-persona
/mcp	Manage MCP (Model Context Protocol) servers: list, add, remove, reload
/macro	Manage and run browser macro presets: list, run, delete
/internal-hooks /ih	Manage custom internal hook tools: init, dev, list, active

Workspace Management

Command	Description
/workspace /w	Manage local, remote (SSH) workspaces, and workspace chains
/worktrees /worktree	Manage Git worktrees: list, prune, remove
/ssh	Manage active SSH workspace boundary (only available in SSH mode)

/workspace subcommands:

• status — Show current workspace info & SSH remote status
• add <path\|ssh://...> — Register a workspace (local path or SSH remote)
• use <path\|index> — Switch to a registered workspace

SSH remote format: ssh://user@host:port/path?key=/path/key.pem Declaring extra allowed paths: ssh://user@host:port/path?key=/path/key.pem&allow=/var/www/html,/etc/nginx

SSH workspace example:

# Add SSH remote workspace
/workspace add ssh://root@192.168.1.100:22/home/projects/myapp?key=~/.ssh/id_rsa

# Switch to it
/workspace use ssh://root@192.168.1.100:22/home/projects/myapp

# Check remote status
/workspace status

/ssh subcommands:

• status — Show current SSH host, workspace path, and allowed paths
• expand <path> — Whitelist an extra absolute path (e.g. /var/www/html)
• allowed — List all currently whitelisted extra paths

🔒 SSH Workspace Boundary Expansion & Allowed Paths

Superagent enforces strict boundary protection on SSH remote workspaces to prevent unauthorized file read/write operations. You can expand access to additional paths:

• Automatic Boundary Expansion: If a tool attempts to access a path outside the remote workspace, Superagent will pop up an interactive confirmation dialog. Once approved, the boundary is dynamically expanded.
• Allowed Paths via URL: Specify additional directories during connection using the ?allow= parameter.
• Runtime Command: Whitelist a directory at any time using /ssh expand <path>.

📂 Local Session Scratch & File Transfer

When operating in an SSH remote workspace, you can still leverage local workspace operations:

• Local Routing Bypass: File reads and writes under the current local session history directory (~/.superagent-r/history/<mode>/<sessionId>/) automatically bypass remote SSH routing.
• File Transfer Tool (transfer_ssh_file): Use this tool to upload files from your local session scratch directory to the remote workspace, or download results from the remote workspace to the local session scratch directory.

🔗 Workspace Chaining (Cross-Workspace Development)

Workspace Chaining allows you to link multiple workspaces—both local directories and remote SSH targets—into a single connected topology. This enables the AI agent to understand relationships between your services (e.g. backend api, frontend app, database, worker) and perform cross-workspace operations.

• Workspace Chains Wizard: Manage chains interactively by opening the /workspace wizard and selecting 🔗 Manage workspace chains.... You can list, create, edit, add nodes, remove nodes, and delete chains.
• Node Context Descriptions: When adding a node to a chain, you can specify a text description (purpose/context) describing what the node represents.
• Dynamic Context Injection: The active chain's topology, node roles, paths, and purpose descriptions are dynamically injected into the AI's base prompt.
• Automatic Workspace Switching: Switching workspaces automatically switches to the workspace chain associated with the active workspace.
• Cross-Workspace Execution: The agent uses cross_workspace_exec to run commands, read files, and write code across different local or remote nodes within the chain.

/worktrees subcommands:

• list — Show all Git worktrees
• prune — Clean stale worktree metadata
• remove <path> — Remove a worktree

Keyboard Shortcuts

Shortcut	Description
Ctrl+C	Abort current process / Exit if input is empty
Ctrl+P	Show checkpoints interactive wizard dialog
Ctrl+H	Toggle search history panel
Ctrl+T	Toggle checklist focus mode (when plan is approved)
Ctrl+O	Cycle through and toggle expand/collapse of tool/system entries
Esc	Reset input focus, cancel active wizard, or reset scroll
↑/↓	Scroll message viewer or navigate CLI history
Tab	Autocomplete slash commands or cycle suggestions
Click	Focus or scroll panels via terminal mouse interaction
!<command>	Quick shortcut to run a shell command (e.g. !npm run dev)

---

🏗️ Architecture

                               ┌────────────────────────────────┐
                               │       Superagent CLI           │
                               └──────────────┬─────────────────┘
                                              │
                     ┌────────────────────────┴────────────────────────┐
                     ▼                                                 ▼
        ┌────────────────────────┐                        ┌────────────────────────┐
        │  Single Agent Mode     │                        │  t-line Desktop Client │
        │  (Direct Execution)    │                        │  (Automatic Bridge)    │
        └───────────┬────────────┘                        └────────────────────────┘
                    │
         ┌──────────┴──────────┐
         ▼                     ▼
┌──────────────────┐  ┌──────────────────┐
│ Shell & FileOps  │  │ Atomic Subagents │
└──────────────────┘  └──────────────────┘

View Experimental 3-Tier Multi-Agent System

When enabled via --multi, Superagent runs a 3-tier hierarchy:

Master Agent (Orchestrator)
  ├── Superagent A (Git Worktree 1 - Feature A)
  │     ├── Subagent (Search & Read)
  │     └── Subagent (Code Writer)
  └── Superagent B (Git Worktree 2 - Feature B)
        └── Subagent (Tester / Debugger)

---

📄 License & Author

Developed by Rudy City (@RudyCity) • 📧 Contact: hrudy715@gmail.com

Distributed under the MIT License.