awesh is an AI-aware interactive shell that provides intelligent assistance while preserving all the power and familiarity of traditional bash operations.
# Clone and install awesh
git clone https://github.com/joebertj/awesh.git
cd awesh
# Build and deploy
python3 simple_deploy.py full
# Or step by step:
python3 simple_deploy.py build # Build awesh
python3 simple_deploy.py deploy # Deploy to ~/.local/bin
python3 simple_deploy.py test # Run test suite# OpenAI (recommended)
python3 switch_model.py gpt4 # Use GPT-4-turbo
python3 switch_model.py status # Check current config
# Or OpenRouter (free)
python3 switch_model.py mistral # Use Mistral (free)
# Edit ~/.aweshrc for custom settings
vi ~/.aweshrc# Launch awesh (from anywhere after deployment)
~/.local/bin/awesh
# Try these examples:
> create a script to check all open ports
> find all python files modified today
> what does netstat do?
> check disk space
> update port to 8080 in config.py# Fast development cycle
python3 simple_deploy.py full # Kill, build, deploy, commit, push
python3 simple_deploy.py build # Build only
python3 simple_deploy.py deploy # Deploy only
python3 simple_deploy.py test # Run tests
python3 simple_deploy.py kill # Kill processes# Edit ~/.aweshrc for persistent settings
VERBOSE=1 # 0=silent, 1=info, 2=debug
AI_PROVIDER=openai # openai or openrouter
MODEL=gpt-5 # AI model to use# Inside awesh
aweh # Show help and all available commands
awes # Show verbose status (API provider, model, debug state)
awea # Show current AI provider and model
awea openai # Switch to OpenAI
awea openrouter # Switch to OpenRouter
awem # Show current model
awem gpt-4 # Set model to GPT-4
awem gpt-3.5-turbo # Set model to GPT-3.5 Turbo
awem claude-3 # Set model to Claude 3
awev # Show verbose level
awev 0/1/2 # Set verbose level
awev on/off # Enable/disable verboseThat's it! You now have AI-powered shell assistance with security middleware, intelligent command routing, and full bash compatibility.
AIOps: Artificial Intelligence for IT Operations - A comprehensive guide to the AI revolution in IT operations, documenting real-world transformations and practical implementation strategies. Written by the creator of this toolkit, it provides the theoretical foundation and strategic insights behind these tools.
"Bash by default, AI to augment as needed"
💎 Naming Inspiration: awesh draws its name from my eldest daughter, Awit Perl - where "Awit" means "Psalm" in Filipino, representing both "Awe" and "Wit," while "Perl" refers to the PERL programming language (still more OG than the Python we have today). This shell embodies the same wonder and wisdom that inspired its creation.
An intelligent shell that seamlessly blends natural language AI interaction with traditional command-line operations. Built by Ops, for Ops - designed for systems administrators, DevOps engineers, and infrastructure professionals who live in the terminal.
💡 The "Free Cursor" Concept: awesh represents what we really want from AI-assisted development: the AI assistance without the IDE bloat. It's a "free cursor" that's purely shell-based - giving you AI-powered development in your terminal without the overhead of editors or opinionated tool prompts.
🌍 Democratizing AI-Powered Development: awesh brings the Cursor/Claude Code experience to every shell, democratizing AI-assisted development by making it a shell primitive, not an editor feature:
- 🚀 Universal Access: Any Linux/Unix system becomes AI-powered - no editor lock-in
- ⚡ Shell-Native AI: Natural language commands get AI interpretation and auto-execution
- 🔄 Intent Recognition: "read md files" → AI understands →
ls *.md→ Shows results seamlessly - 🛠️ Tool Integration: Works with vi, nano, grep, git - your existing workflow enhanced
- 🔓 Open Ecosystem: Not dependent on proprietary platforms or specific editors
Instead of being locked into AI editors, every shell becomes an AI-powered operations environment. This democratizes access to AI-assisted infrastructure management for anyone with a terminal.
🔧 The Ops-First Philosophy: awesh embraces the minimalistic yet powerful approach that operations professionals know and love:
- 🖥️ Shell + vi Workflow: Designed for those who live in terminals and edit with vi/vim
- ⚡ No IDE Bloat: Pure shell experience - familiar, fast, and efficient
- 🛠️ Infrastructure-Focused: Built for system administration, not application development
- 📊 Ops Mindset: Troubleshooting, monitoring, deployment - operations tasks first
- 🔍 Minimal Learning Curve: If you know bash and vi, you know awesh
For the shell/vi professional who wants AI assistance without abandoning the minimalistic, powerful tools that make operations efficient.
🎯 Ideal Test Users: A 23-year terminal veteran is the perfect test user for writing an AI-enhanced terminal - not developers who spent time in advanced IDEs pampered by so much GUI tooling. Experienced terminal users understand the real workflow, know what's actually needed, and can identify when AI assistance genuinely enhances rather than complicates the shell experience.
🌟 Core Philosophy:
- Bash First: Shell commands execute directly - no AI overhead
- AI Augmentation: AI helps when commands fail or you need assistance
- Intelligent Routing: Automatically detects Bash vs AI intent
- Context-Aware: Remembers your environment and command history
- Safety First: AI suggestions validated in sandbox before execution
- Zero-Friction: Works alongside your existing workflow seamlessly
🚀 Key Features:
- Bash-First Execution: Shell commands execute directly without AI overhead
- AI Augmentation: AI helps when commands fail or you need intelligent assistance
- Smart Command Routing: Detects shell syntax, commands, and natural language automatically
- Multi-Provider AI Integration: Powered by OpenAI, OpenRouter, Perplexity, or Ollama with configurable models
- Agent System: Specialized agents (ResponseAgent, FileAgent, FileEditor, ExecutionAgent, ShellAgent, TODOAgent) for intelligent task execution
- System Prompt Support: Customizable AI behavior for your operations context
- Streaming Responses: Real-time AI output with conversation continuity
- Environment Variable Support: Easy configuration via
~/.aweshrc - MCP Integration: Secure tool execution through Model Context Protocol
- Full Bash Compatibility: All your existing commands work exactly as before
💡 Example Usage:
awesh> ls -la # → Sandbox validation → Direct execution
awesh> what files are here? # → Sandbox validation → AI query via middleware
awesh> find . -name "*.py" # → Sandbox validation → Direct execution
awesh> explain this error # → Sandbox validation → AI query via middleware
awesh> cat file.txt | grep error # → Sandbox validation → Direct execution
awesh> summarize this directory structure # → Sandbox validation → AI query via middleware
awesh> why did the build fail? # → Sandbox validation → AI query via middleware
awesh> awem gpt-4 # → Built-in command (set model)
awesh> awev 1 # → Built-in command (enable verbose)"Bash by default, AI to augment as needed."
🔧 Installation:
# Use deployment MCP for clean installation with virtual environment
python3 deployment_mcp.py clean_install
# Configure your OpenAI API key
export OPENAI_API_KEY=your_api_key_here
awesh🐍 Virtual Environment Enforcement: AIOps automatically uses a Python virtual environment for all operations, ensuring:
- Dependency isolation from system Python packages
- Consistent environments across different systems
- Clean deployments with reproducible setups
- No conflicts with system-installed packages
The deployment script automatically creates and manages the virtual environment, installing all dependencies in isolation.
🔧 Configuration: Set these environment variables in your shell:
# AI Provider Configuration
export AI_PROVIDER=openai # openai or openrouter
export OPENAI_MODEL=gpt-5 # Model to use
export OPENAI_API_KEY=sk-proj-abc123...xyz # Your OpenAI API key (truncated)
# OpenRouter Configuration (if using openrouter)
export OPENROUTER_API_KEY=sk-or-v1-abc...xyz # Your OpenRouter API key (truncated)
export OPENROUTER_MODEL=anthropic/claude-3-sonnet
# Display Options
export VERBOSE=1 # 0=silent, 1=info, 2=debug (default: 1)
# File Agent Options
export FILE_AGENT_ENABLED=1 # 1=enabled, 0=disabled (default: 1)
# Note: AI prompt enhancement is always enabled for built-in agents
export FILE_AGENT_MAX_FILE_SIZE=50000 # Max size per file in bytes (default: 50000)
export FILE_AGENT_MAX_TOTAL_CONTENT=10000 # Max total content to inject (default: 10000)
export FILE_AGENT_MAX_FILES=5 # Max number of files to include (default: 5)Example configuration:
export AI_PROVIDER=openai
export OPENAI_MODEL=gpt-5
export OPENAI_API_KEY=sk-proj-JrUoBu9D4iCb...T3BlbkFJMEjXf8l0w9SPKE-Rw
export VERBOSE=1Currently optimized for OpenAI GPT-5: awesh is actively tested and developed using OpenAI's GPT-5 model. While OpenRouter and other AI providers are supported, they may exhibit unexpected behavior or suboptimal performance. We recommend using OpenAI with GPT-5 for the most reliable experience while we continue testing and improving compatibility with other providers.
🎛️ Control Commands:
# Help & Status
aweh # Show all available awesh control commands
awes # Show verbose status (API provider, model, debug state)
awea # Show current AI provider and model
# Model Management
awem # Show current model
awem gpt-4 # Set model to GPT-4
awem gpt-3.5-turbo # Set model to GPT-3.5 Turbo
awem claude-3 # Set model to Claude 3
# Verbose Debug Control
awev # Show verbose level status
awev 0 # Set verbose level 0 (silent)
awev 1 # Set verbose level 1 (info)
awev 2 # Set verbose level 2 (debug)
awev on # Enable verbose logging (level 1)
awev off # Disable verbose logging (level 0)
# AI Provider Switching
awea openai # Switch to OpenAI (GPT models)
awea openrouter # Switch to OpenRouter (multiple providers)Control commands use the awe prefix to avoid conflicts with bash builtins and create a clean namespace for awesh operations.
This project is open source and available under the Apache License 2.0.
awesh: Where artificial intelligence meets shell operations. Making the complex simple, the manual automatic, and bringing AI assistance to every terminal.
Click to expand
┌─────────────────────────────────────────────────────────────────────────────────┐
│ awesh System Architecture │
│ "Bash by default, AI to augment as needed" │
│ 4-Component Architecture │
└─────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ User Input │ │ C Frontend │ │ Security Agent │ │ Python Backend │
│ │ │ (awesh.c) │ │ (awesh_sec) │ │ (awesh_backend) │
│ • Natural Lang │───▶│ │───▶│ │───▶│ │
│ • Shell Commands│ │ • Readline UI │ │ • Middleware │ │ • AI Processing │
│ • Mixed Input │ │ • Command Route │ │ • Security Gate │ │ • MCP Tools │
└─────────────────┘ │ • Socket Client │ │ • RAG Analysis │ │ • File Agent │
│ • PTY Support │ │ • Socket Server │ │ • Socket Server │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Bash Sandbox │ │ Unix Sockets │ │ AI Provider │ │ Config Files │
│ (awesh_sandbox) │ │ │ │ │ │ │
│ │ │ • ~/.awesh_sandbox.sock│ • OpenAI API │ │ • ~/.aweshrc │
│ • Bash Validation│ │ • ~/.awesh_security_agent.sock│ • OpenRouter │ │ • ~/.awesh_config.ini│
│ • Syntax Check │ │ • ~/.awesh.sock │ │ • GPT-4/5 │ │ • Verbose Control│
│ • Return Codes │ │ • Status Sync │ │ • Streaming │ │ • AI Settings │
│ • No Execution │ │ • Command Flow │ │ • Tool Calling │ │ • Security Rules│
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ C Frontend (awesh.c) │
├─────────────────────────────────────────────────────────────────┤
│ • Interactive Shell with Readline Support │
│ • Smart Command Routing (Sandbox → AI → Direct) │
│ • Built-in Commands: cd, pwd, exit, quit │
│ • Socket Communication with Backend & Sandbox │
│ • Security Agent Integration │
│ • Dynamic Prompt Generation (0ms) │
│ • Process Health Monitoring & Auto-restart │
│ • PTY Support for Interactive Commands │
│ • Independent Operation (works as regular bash) │
└─────────────────────────────────────────────────────────────────┘
Key Functions:
├── Command Routing Logic
│ ├── is_awesh_command() - Control commands (aweh, awes, awev, awea)
│ ├── is_builtin() - Built-in shell commands
│ ├── test_command_in_sandbox() - Sandbox command testing
│ ├── is_interactive_command() - Interactive command detection
│ └── execute_command_securely() - Main command execution
│
├── Communication
│ ├── send_to_backend() - Backend socket communication
│ ├── send_to_sandbox() - Sandbox socket communication
│ ├── send_to_security_agent() - Security agent communication
│ └── init_frontend_socket() - Frontend socket server
│
├── Process Management
│ ├── restart_backend() - Backend process restart
│ ├── restart_security_agent() - Security agent restart
│ ├── restart_sandbox() - Sandbox process restart
│ └── attempt_child_restart() - Auto-restart failed processes
│
└── Security Integration
├── get_security_agent_status() - Threat status
├── get_health_status_emojis() - Process health (🧠:🔒:🏖️)
└── Config file reading (~/.aweshrc)
┌─────────────────────────────────────────────────────────────────┐
│ Python Backend (awesh_backend) │
├─────────────────────────────────────────────────────────────────┤
│ • Socket Server (Unix Domain Sockets) │
│ • AI Client Integration (OpenAI/OpenRouter/Perplexity/Ollama) │
│ • MCP (Model Context Protocol) Tool Execution │
│ • Agent System (4 specialized agents) │
│ • RAG (Retrieval Augmented Generation) System │
│ • Security Integration │
└─────────────────────────────────────────────────────────────────┘
Components:
├── AweshSocketBackend (server.py)
│ ├── Socket Server (~/.awesh.sock)
│ ├── Command Processing
│ ├── AI Client Management
│ └── Agent Orchestration
│
├── AweshAIClient (ai_client.py)
│ ├── OpenAI/OpenRouter/Perplexity/Ollama Integration
│ ├── Streaming Responses
│ ├── System Prompt Management
│ └── Tool Function Calling
│
└── Agent System
├── FileAgent (file_agent.py)
│ ├── File Detection & Context Injection
│ ├── Smart Content Extraction
│ └── Binary File Filtering
│
├── FileEditor (file_editor.py)
│ ├── Search/Replace Editing
│ ├── Automatic Backups
│ └── Validation & Undo
│
├── ExecutionAgent (execution_agent.py)
│ ├── Routes commands to Shell Agent (C-based)
│ ├── Result Capture (stdout/stderr/exit codes)
│ └── Multi-step Iteration
│
└── ResponseAgent (response_agent.py)
├── Analyzes AI responses
├── Routes to specialized agents
└── Coordinates multi-agent workflows
│
└── TODOAgent (todo_agent.py)
├── Goal Management
├── Progress Tracking
└── Iterative AI Feedback Loops
┌─────────────────────────────────────────────────────────────────┐
│ Security Agent (awesh_sec) │
├─────────────────────────────────────────────────────────────────┤
│ • Process Monitoring (Every 5 seconds) │
│ • AI-Powered Threat Detection (Every 5 minutes) │
│ • Pattern-Based Security Filtering │
│ • Config File Reading (~/.aweshrc) │
│ • RAG Data Collection & Analysis │
│ • Isolated Operation (no socket server) │
└─────────────────────────────────────────────────────────────────┘
Security Features:
├── Process Scanning
│ ├── Backend API calls for process data
│ ├── RAG Data Collection (Every 5s)
│ └── AI Analysis (Every 5min)
│
├── Pattern Detection
│ ├── Dangerous Commands (rm -rf /, dd, mkfs, etc.)
│ ├── Sensitive Data (passwords, keys, tokens)
│ └── Regex-based Filtering
│
└── Communication
├── Backend Socket Connection (security analysis only)
├── Config File Reading (verbose control)
└── Threat Alert Propagation
┌─────────────────────────────────────────────────────────────────┐
│ Bash Sandbox (awesh_sandbox) │
├─────────────────────────────────────────────────────────────────┤
│ • PTY-based Bash Environment │
│ • Command Testing & Execution │
│ • Interactive Command Detection │
│ • Socket Communication with Frontend │
│ • Automatic Cleanup on Interactive Commands │
└─────────────────────────────────────────────────────────────────┘
Sandbox Features:
├── Command Execution
│ ├── PTY Support for proper TTY
│ ├── 2-second timeout for command testing
│ ├── Bash prompt detection
│ └── Interactive command cleanup (Ctrl+C)
│
├── Communication
│ ├── Unix Domain Socket (~/.awesh_sandbox.sock)
│ ├── Command/Response Protocol
│ └── INTERACTIVE_COMMAND detection
│
└── Process Management
├── Persistent bash process
├── Automatic cleanup on exit
└── Error handling and recovery
User Input → C Frontend → Command Routing Decision
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
Built-in Commands Sandbox Test AI Processing
│ │ │
│ ▼ │
│ Valid Bash? │
│ │ │
│ ┌──────┼──────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Direct AI Middleware│
│ Execution Route Route │
│ │ │ │ │
│ │ │ ▼ │
│ │ │ Security │
│ │ │ Analysis │
│ │ │ │ │
│ │ │ ▼ │
│ │ │ Backend │
│ │ │ AI Query │
│ │ │ │ │
│ │ │ ▼ │
│ │ │ Results │
│ │ │ Display │
│ │ │ │ │
└────────┼──────┼──────┼───────┘
│ │ │
▼ ▼ ▼
User Output
AI Response → Mode Detection
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
Normal Mode Command Mode Display Mode
(default) awesh: cmd (text only)
│ │ │
│ ▼ │
│ Security Check │
│ │ │
│ ▼ │
│ Command Execute │
│ │ │
└───────────┼───────────┘
│
▼
User Output
Security Agent → Process Scanning (5s) → RAG Data Collection
│
▼
Backend RAG Storage
│
▼
AI Analysis (5min) → Threat Detection
│
▼
Shared Memory Update
│
▼
Frontend Status Display
Protocol: ~/.awesh.sock (Unix Domain Socket)
Commands:
├── STATUS - AI readiness check
├── CWD:<path> - Working directory sync
├── QUERY:<prompt> - AI query
├── BASH_FAILED:<code>:<cmd>:<file> - Bash failure context
├── VERBOSE:<level> - Verbose level update
├── AI_PROVIDER:<provider> - Provider switch
└── GET_PROCESS_DATA - Process data for security agent
Responses:
├── AI_READY / AI_LOADING - Status response
├── OK - Acknowledgment
└── <AI Response> - Streaming AI output
Protocol: ~/.awesh_sandbox.sock (Unix Domain Socket)
Commands:
├── <command> - Any shell command to validate
Responses:
├── EXIT_CODE:0\nSTDOUT_LEN:Y\nSTDOUT:...\nSTDERR_LEN:Z\nSTDERR:...\n - Valid bash
└── EXIT_CODE:-2\nSTDOUT_LEN:0\nSTDOUT:\nSTDERR_LEN:0\nSTDERR:\n - Invalid bash (AI query)
Protocol: ~/.awesh.sock (Same socket, different messages)
Security Messages:
├── GET_PROCESS_DATA - Request process data from backend
├── RAG_ADD_PROCESS:<data> - Process data for RAG
├── PROCESS_ANALYSIS:ANALYZE_RAG_5MIN - AI analysis request
└── RAG_CLEAR_PROCESS_DATA - Clear RAG data after analysis
Responses:
├── <process_data> - Process information from ps command
├── <AI Analysis Result> - Threat analysis
└── OK - Acknowledgment
Protocol: Config File (~/.aweshrc)
Status Updates:
├── VERBOSE=<level> - Verbose level control
├── AI_PROVIDER=<provider> - AI provider setting
└── Other configuration settings
Note: Security agent reads config file directly, no socket communication
VERBOSE=0 # 0=silent, 1=info, 2=debug
AI_PROVIDER=openai # openai or openrouter
MODEL=gpt-5 # AI model to use
OPENAI_API_KEY=sk-... # API key
OPENROUTER_API_KEY=sk-... # OpenRouter key
~/.awesh_system.txt # Custom AI behavior
Default: Operations-focused prompt for infrastructure management
- Sandbox Validation: All commands validated in sandbox first (bash syntax check)
- Direct Execution: Valid bash commands executed directly by frontend
- AI Routing: Invalid bash commands routed to backend via middleware
- Built-in Commands: aweh, awes, awev, awea, awem (handled by frontend)
- Synchronous Communication: Frontend waits for backend responses with 5-minute timeout
- Real-time Monitoring: Process scanning every 5 seconds
- AI Threat Detection: Analysis every 5 minutes
- Pattern Filtering: Dangerous commands and sensitive data
- Visual Indicators: Emoji-based status in prompt (🧠:🔒:🏖️)
- Isolated Security: Security agent reads config, no socket server
- Instant Prompt: 0ms prompt generation (no blocking calls)
- Non-blocking: All children start in background
- Streaming: Real-time AI responses
- Health Monitoring: Automatic process restart
- Independent Operation: Works as regular bash when needed
- Interactive Commands: vi, top, ssh, python, etc. work properly
- TTY Detection: Sandbox detects interactive commands automatically
- Clean State: Sandbox cleaned up after interactive detection
- Direct Execution: Interactive commands run in frontend with proper TTY
- Tool Execution: Secure tool calling through MCP
- File Operations: FileAgent for file reading/analysis
- Safety: No direct shell execution from AI
- Audit: Configurable logging and monitoring
awesh uses an agent-based architecture where all operations flow through specialized agents. The system follows a coordinator pattern where the Response Agent routes AI responses to appropriate specialized agents.
┌─────────────────────────────────────────────────────────────┐
│ Response Agent │
│ (Coordinator & Router) │
│ │
│ - Analyzes AI responses │
│ - Routes to specialized agents │
│ - Coordinates multi-agent workflows │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────────┼───────────────────┬──────────────┐
│ │ │ │
▼ ▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐
│ File Editor │ │ Execution │ │ File Agent │ │ TODO Agent │
│ Agent │ │ Agent │ │ │ │ │
│ │ │ │ │ │ │ │
│ - Edit files │ │ Routes to │ │ - File │ │ - Goal │
│ - Create files│ │ Shell Agent │ │ context │ │ tracking │
│ - File ops │ │ │ │ - Detection │ │ - Iterations│
└───────────────┘ └──────┬────────┘ └──────────────┘ └─────────────┘
│
▼
┌──────────────┐
│ Shell Agent │ ⚡
│ (C-based) │
│ │
│ - Fast exec │
│ - Validation │
│ - Isolated │
│ - PTY support │
└──────────────┘
Key Architecture Points:
- Response Agent coordinates all agents and routes AI responses
- All commands go through: Response Agent → Execution Agent → Shell Agent (C-based)
- Shell Agent is a specialized C-based agent (
awesh_sandbox.c) for fast command execution - File operations centralized through File Editor Agent
- Safety: All commands validated in Shell Agent before returning to user
awesh includes a sophisticated agent system that enables intelligent, context-aware AI interactions. These agents work together to provide a comprehensive AI assistance experience similar to Cursor/Claude Code.
Intelligent file detection and context injection for enhanced AI responses.
Features:
- Smart File Detection: Automatically detects file references in user prompts using:
- Exact filename matching
- Partial filename matching (ignoring extensions)
- Fuzzy filename matching using grep patterns
- Context Injection: Injects relevant file content into AI prompts for better understanding
- Smart Content Extraction:
- Head/tail extraction for large files
- Targeted line extraction when specific lines are referenced
- File type-aware content limiting
- Multiple File Handling: Processes up to 5 files per request (configurable)
- Binary File Filtering: Automatically skips binary files (images, executables, etc.)
Configuration:
FILE_AGENT_ENABLED=1 # Enable/disable (default: 1)
FILE_AGENT_MAX_FILE_SIZE=50000 # Max size per file in bytes (default: 50000)
FILE_AGENT_MAX_TOTAL_CONTENT=10000 # Max total content to inject (default: 10000)
FILE_AGENT_MAX_FILES=5 # Max number of files to include (default: 5)Example Usage:
awesh> what does config.py do? # FileAgent detects config.py
awesh> explain the error in server.py # FileAgent injects server.py context
awesh> how does file_agent.py work? # FileAgent provides file context to AISurgical file editing with automatic backups and validation.
Features:
- Search/Replace Editing: Uses search/replace blocks for precise edits (similar to Cursor/Claude)
- Multiple Edits: Apply multiple edits in a single operation
- Automatic Backups: Creates timestamped backups before modifications
- Validation: Validates file paths and edits before applying
- Context-Aware: Shows surrounding lines for better edit accuracy
- Undo Support: Can restore from backups if needed
Edit Format:
awesh> update port to 8080 in config.py
AI Response:
```edit:config.py
<<<<<<< OLD
PORT = 3000
=======
PORT = 8080
>>>>>>> NEW
### 3. **ExecutionAgent** (`execution_agent.py`)
Routes commands to Shell Agent (C-based) for fast execution.
**Key Distinction:** This agent is **separate** from direct user command execution:
- **User Commands**: Execute directly in the user's terminal (unfiltered, immediate)
- **AI Commands**: Route through Execution Agent → Shell Agent (C-based) → Validated execution
**Architecture:**
- Execution Agent → Shell Agent (Sandbox/C) → Command Execution
- Shell Agent is C-based (`awesh_sandbox.c`) for performance and quick response
**Features:**
- **Routes to Shell Agent**: Commands go through C-based Shell Agent for fast execution
- **Capture Results**: Captures stdout, stderr, and exit codes
- **Multi-step Execution**: Supports iterative command execution with feedback loops
- **Information Gathering**: AI uses this to gather information before answering
- **No Interference**: Doesn't affect the user's terminal or working directory
**Use Cases:**
- AI needs to check if a file exists before suggesting edits
- AI verifies command syntax before suggesting to user
- AI gathers system information to provide accurate answers
- AI iterates on commands based on previous results
**Example Flow:**
User: "update the port in config.py"
↓
ExecutionAgent: Runs cat config.py in sandbox to read file
↓
FileEditor: Makes edit based on file content
↓
ExecutionAgent: Verifies edit with grep PORT config.py
↓
AI Response: "Updated PORT to 8080 in config.py"
### 4. **ResponseAgent** (`response_agent.py`)
Coordinates all agents and routes AI responses to appropriate specialized agents.
**Features:**
- **Response Analysis**: Analyzes AI responses to detect commands, file edits, or information
- **Agent Routing**: Routes to File Editor, Execution Agent, or displays as-is
- **Command Detection**: Detects explicit `awesh:` commands for execution
- **File Block Detection**: Detects file edit blocks (` ```edit:filename ``` `)
- **Code Block Detection**: Detects code blocks that should be written to files
- **Thinking Process Cleaning**: Removes Ollama thinking markers from responses
**Routing Logic:**
1. File edit blocks → File Editor Agent
2. `awesh:` commands → Execution Agent → Shell Agent (C)
3. Code blocks that look like files → File Editor Agent
4. Plain responses → Display as-is
### 5. **Shell Agent** (`awesh_sandbox.c` - C-based)
Specialized C-based agent for fast command validation and execution.
**Why C-based:** Performance - provides quick response on shell commands. Critical for fast command validation and execution.
**Features:**
- **Fast Execution**: C implementation for speed
- **Command Validation**: Validates syntax and safety
- **Isolated Environment**: PTY-based isolated execution
- **Result Capture**: Captures stdout, stderr, exit codes
- **Quick Response**: Optimized for fast command testing
**Location:** `awesh_sandbox.c` (not Python - specialized C agent)
**Communication:** Via Unix socket (`~/.awesh_sandbox.sock`)
### 6. **TODOAgent** (`todo_agent.py`)
Goal-oriented task execution with iterative AI feedback loops.
**Features:**
- **Goal Management**: Manages 1 goal with up to 10 iterations
- **Progress Tracking**: Tracks progress toward goal completion
- **Iterative Execution**: AI iterates with feedback until goal is achieved
- **Integration**: Works with FileEditor and ExecutionAgent for multi-step tasks
- **Smart Stopping**: Stops after completing goal or asks user to continue
**Architecture:**
User: "deploy nginx to kubernetes with monitoring" ↓ TODOAgent creates goal with subtasks ↓ Iteration 1: AI creates deployment.yaml → FileEditor Iteration 2: AI applies deployment → ExecutionAgent Iteration 3: AI verifies pods running → ExecutionAgent Iteration 4: AI sets up monitoring → FileEditor + ExecutionAgent ↓ Goal complete ✅ or Ask user to continue
**Response Markers:**
- `✅ GOAL_COMPLETE` - Goal finished successfully
- `🔄 CONTINUE_ITERATION` - Continue with next step
- `❓ NEED_USER_INPUT` - Need user to choose/confirm something
**Example:**
```bash
awesh> set up a web server with nginx on port 80
AI Response:
```edit:nginx.conf
<<<<<<< OLD
=======
server {
listen 80;
server_name localhost;
...
}
>>>>>>> NEW
awesh: sudo systemctl start nginx 🔄 CONTINUE_ITERATION
[Next iteration: AI verifies nginx is running] awesh: systemctl status nginx ✅ GOAL_COMPLETE
### Agent Integration
All agents work together seamlessly through the Response Agent coordinator:
- **ResponseAgent** analyzes and routes AI responses to appropriate agents
- **FileAgent** enhances prompts with file context (used in prompt processing)
- **ExecutionAgent** routes commands to Shell Agent for fast execution
- **FileEditor** makes precise file modifications and creates files
- **ShellAgent** (C-based) provides fast command validation and execution
- **TODOAgent** orchestrates complex multi-step goals
**Command Flow:**
AI Response → Response Agent ├─→ File Edit Block? → File Editor Agent ├─→ awesh: Command? → Execution Agent → Shell Agent (C) ⚡ ├─→ Code Block (file)? → File Editor Agent └─→ Plain Response? → Display as-is
This agent system enables awesh to handle complex, multi-step operations that would require multiple manual interactions in a traditional shell, while maintaining safety and control.
## Installation & Usage
### Quick Start
```bash
cd awesh/
./install.sh
export OPENAI_API_KEY=your_key
awesh
🧠:🔒:🏖️:joebert@maximaal:~:☸️default:🌿main
> ls -la # → Sandbox validation → Direct execution
> vi file.txt # → Sandbox validation → Direct execution
> what files are here? # → Sandbox validation → AI query via middleware
> find . -name "*.py" # → Sandbox validation → Direct execution
> top # → Sandbox validation → Direct execution
> explain this error # → Sandbox validation → AI query via middleware
> cat file.txt | grep error # → Sandbox validation → Direct execution
> summarize this directory structure # → Sandbox validation → AI query via middleware
> awev off # → Built-in command (verbose off)
> awem gpt-4 # → Built-in command (set model)
> exit # → Built-in command (clean exit)- 🧠 = Backend ready (AI available)
- ⏳ = Backend loading/not ready
- 💀 = Backend failed
- 🔒 = Security agent ready
- ⏳ = Security agent not ready
- 🏖️ = Sandbox ready
- ⏳ = Sandbox not ready
This architecture provides a robust, secure, and intelligent shell environment that seamlessly blends traditional command-line operations with AI assistance while maintaining the performance and security requirements of operations professionals.