\n<\/p>\n
slash-agent is an ultra-lightweight, zero-overhead AI coding partner that integrates natively into your active Bash shell. It is designed to act as a seamless extension of your command line, keeping you focused in your terminal with 100% local, private LLM support (via Ollama) or cloud powerhouses (OpenAI\/Azure OpenAI).
\nImportantA Natural Coding Partner in Your Shell\u2014Zero Workflow Interruption.
\nslash-agent operates directly inside your active Bash session. It stays completely out of your way and consumes zero background resources (no running daemons, no background processes) when not in use. Simply type \/agent when you hit a blocker: it instantly grabs your recent terminal context (tmux pane scrollback or command history) to diagnose errors, edit files, and execute commands\u2014automatically syncing directory changes (cd) and environment exports back to your parent shell session when it exits.<\/p>\n
\u26a1 Quick Start (5-Second Install)
\nGet up and running instantly. Run the quick installer script in your shell (supports Bash, Zsh, Ksh, and Fish):
\ncurl -fsSL https:\/\/raw.githubusercontent.com\/akatzmann\/slash-agent\/master\/bin\/installer.sh | bash
\n(This automatically clones the repo to ~\/.slash-agent, configures a Python virtual environment, installs requirements, and registers the shell integration in your appropriate shell profile file, e.g. ~\/.zshrc, ~\/.bashrc, ~\/.bash_profile, or config.fish.)<\/p>\n
\ud83e\udd16 LLM Agnostic & Privacy First: Supports local offline models (like Ollama) with zero keys required and zero data leaving your machine, as well as OpenAI and Azure OpenAI.<\/p>\n
\ud83d\udd0c Zero-Overhead Integration: Completely passive. Consumes zero CPU\/memory until you run \/agent\u2014no running background daemons, cron jobs, or log listeners.<\/p>\n
\ud83d\udd0d Context-Aware Diagnoses: Instantly extracts the last 50 lines of your active tmux pane or terminal history, letting the LLM read error outputs and tracebacks without manual copy-pasting.<\/p>\n
\u26a1 State Synchronization: Working directory transitions (cd) and environment exports (export KEY=VAL) made by the agent automatically sync back to your parent shell session on exit.<\/p>\n
\ud83c\udf09 Interactive PTY Bridge: Executes proposed commands in a pseudo-terminal (PTY), allowing you to interactively type passwords (e.g. sudo), view colored output, and see progress bars.<\/p>\n
\ud83d\udd79\ufe0f Steerable Confirmation Loop: Full control over every action:<\/p>\n
y (yes): Run the command.
\nn (no): Refuse the command and inform the agent.
\ne (edit): Inline edit the command before running it.
\nc (comment): Type natural language guidance back to the agent (e.g. “Use yarn instead of npm”).<\/p>\n
\ud83d\udee1\ufe0f Dry-run & Auto-confirm Modes: Preview agent actions safely with -n \/ –dry-run, or run fully unattended with -y \/ –yes.<\/p>\n
$ npm run build
\n\u274c ERROR: Build failed. Cannot find module ‘dotenv’ in server.js:12<\/p>\n
$ \/agent Fix this
\n(Agent Shell) Initializing with model ‘gemma4:e4b-it-qat’ at ‘http:\/\/127.0.0.1:11434’…
\n(Agent Started Task)
\nAnalyzing terminal context… Identified missing dependency ‘dotenv’ in server.js.<\/p>\n
(Agent) Proposed Command:
\n $ npm install dotenv && npm run build<\/p>\n
Confirm action: (y)es \/ (n)o \/ (e)dit \/ (c)omment ? y
\n(Agent Running): npm install dotenv && npm run build
\n…
\nadded 1 package, and audited 120 packages in 1s
\n\u2713 Build completed successfully!<\/p>\n
I have installed the missing ‘dotenv’ package and verified that the build now passes.<\/p>\n
\ud83d\udee0\ufe0f Build & Test Crashes: When a compiler error, script traceback, or unit test fails, simply run \/agent to let it read the error logs directly and propose a fix.
\n\ud83d\udce6 Dependency Resolution: Missing package imports? The agent reads the import error, installs the package, and verifies the build.
\n\ud83d\udcbb Quick Scripting & Automation: Ask the agent to generate helper scripts, configure development environments, or perform regex logs processing on the fly.
\n\u2699\ufe0f System Configuration: Easily set up local databases, systemd services, or configuration files without looking up command flags.<\/p>\n
Unlike standard agents that run in isolated subshells (and cannot modify your current directory or environment), slash-agent uses a lightweight state synchronization protocol:<\/p>\n
graph TD
\n A(Active Bash Session) –>|1. Type \/agent| B(Bash Sourcing Wrapper bin\/slash-agent.sh)
\n B –>|2. Capture Screen Output| C(Python Orchestrator slash_agent\/main.py)
\n C –>|3. Interface with local\/cloud LLM| C
\n C –>|4. Propose commands| D(PTY Execution Bridge)
\n D –>|5. Interactive Steering Loop| A
\n D –>|6. Capture exit code, PWD, env updates| B
\n B –>|7. Source sync file on exit| A<\/p>\n
Loading<\/p>\n
Context Capture: The shell wrapper automatically captures the active tmux pane buffer (or history) to give the LLM immediate context.
\nInteractive PTY Bridge: Commands run inside a real pseudo-terminal (PTY) so you see colored outputs, progress bars, and can interact with prompts (like typing passwords for sudo).
\nParent Shell Sync: Directory changes (cd) or environment variables (export) are safely passed back to your main shell session via a temporary sourcing script on exit.<\/p>\n
If you prefer to set up the agent manually instead of using the Quick Start script:<\/p>\n
Clone the Repository:
\ngit clone https:\/\/github.com\/akatzmann\/slash-agent.git ~\/.slash-agent
\ncd ~\/.slash-agent<\/p>\n
Install Python Requirements:
\npip install -r requirements.txt<\/p>\n
Register Shell Integration:
\nAdd the appropriate sourcing statement to your shell configuration file:<\/p>\n
Bash (Linux): source ~\/.slash-agent\/bin\/slash-agent.sh in ~\/.bashrc
\nBash (macOS): source ~\/.slash-agent\/bin\/slash-agent.sh in ~\/.bash_profile (or ~\/.profile)
\nZsh: source ~\/.slash-agent\/bin\/slash-agent.sh in ~\/.zshrc
\nKsh: source ~\/.slash-agent\/bin\/slash-agent.sh in ~\/.kshrc
\nFish: source ~\/.slash-agent\/bin\/slash-agent.fish in ~\/.config\/fish\/config.fish<\/p>\n
\ud83d\udcbb Windows Support (WSL2)
\nslash-agent runs natively inside Unix-like PTY environments. Native Windows execution (under standard CMD or PowerShell) is not supported due to PTY emulation limitations.
\nHowever, the tool is 100% compatible with WSL2 (Windows Subsystem for Linux). Windows users can run slash-agent by opening any WSL2 Linux terminal (such as Ubuntu or Debian) and running the standard Quick Start installation command.<\/p>\n
Configure the LLM backend, endpoint, model, and capture settings in your .env file or shell profile:
\n# LLM Backend: openai (default), ollama, azure_openai, dummy
\nexport AGENT_BACKEND=”openai”<\/p>\n
# Model name (Defaults: gpt-4o-mini for openai, gemma4:e4b-it-qat for ollama)
\nexport AGENT_MODEL=”gpt-4o-mini”<\/p>\n
# API endpoint base URL (defaults to official OpenAI API endpoint)
\nexport AGENT_ENDPOINT=””<\/p>\n
# OpenAI API Key (required for default OpenAI backend)
\nexport OPENAI_API_KEY=”your-api-key-here”<\/p>\n
# Context extraction settings
\nexport AGENT_TMUX_LINES=50 # Lines captured from active tmux scrollback
\nexport AGENT_HISTORY_COMMANDS=20 # Commands captured from history fallback
\nFor a full list of configuration variables (e.g., Azure OpenAI variables), see the .env.template file.<\/p>\n
1. General Command Execution
\n\/agent create a new directory named ‘sandbox’ and write a basic python flask server inside it<\/p>\n
If a compiler, build tool, or script crashes, run \/agent with no arguments (or a request to fix it):<\/p>\n
Simulate proposed steps and check the agent’s plan without making actual system changes:
\n\/agent -n setup a docker compose file for PostgreSQL and Redis<\/p>\n
Run tasks without any confirmation prompts for safe, low, or moderate risk commands:
\n\/agent -y update package lists and install tree
\n5. Auto-confirm Critical Commands
\nBy default, critical commands (like rm -rf or commands using sudo) are not auto-confirmed by -y to prevent accidental damage. To auto-confirm even critical commands, pass the –unsafe-yes flag:
\n\/agent –unsafe-yes clean up docker volumes and system cache<\/p>\n