[FEATURE] `cortex ask --do` - AI-Powered Command Execution with Auto-Repair

[Dhruv-89]

[Feature] cortex ask --do - AI-Powered Command Execution with Auto-Repair

Overview

cortex ask --do is an interactive AI assistant that can execute Linux commands based on natural language requests. Unlike simple command execution, it features intelligent error handling, automatic repair, resource conflict detection, and real-time terminal monitoring.

Status

Current Phase: ✅ Core Implementation Complete
Next Phase: Polish & Edge Cases

---

Core Capabilities

1. Natural Language → Linux Commands

$ cortex ask --do "install nginx and configure it for SSL"

The LLM understands the intent and generates a sequence of commands to achieve the goal.

2. Resource Conflict Detection

Before executing commands, Cortex checks for existing resources:

• Docker containers with the same name
• Running services that may conflict
• Files/directories that already exist
• Ports already in use
• Packages already installed

User is prompted with options:

• Use existing resource
• Restart/recreate resource
• Cancel operation

3. Task Tree Execution

Commands are organised in a structured tree:

Root Task: Install Nginx
├── apt update
├── apt install -y nginx
├── systemctl start nginx
└── Repair (if failed)
    ├── Check logs
    └── Fix issue

4. Auto-Repair System

When commands fail, Cortex automatically:

1. Diagnoses the error using pattern matching + LLM analysis
2. Generates a fix command
3. Executes the fix (if non-sudo)
4. Retries the original command
5. Verifies success

Error types handled:

Error	Strategy
Permission denied	Suggest chmod/chown or manual sudo
Command not found	Auto-install missing package
Service not running	Start service, check logs
Port in use	Find and suggest stopping conflicting process
Disk full	Suggest cleanup commands
Config error	Backup + suggest fix

5. Manual Intervention Mode

For sudo commands or when user declines automatic execution:

• Displays commands to run
• Monitors other terminals in real-time
• Tracks command execution status
• Provides error detection and suggestions
• Shows visual feedback when expected commands are run

6. Interactive Session

After execution, users can:

• Ask follow-up questions
• Request next steps
• Modify or retry with new requirements
• View session history

7. LLM-Generated Summary

At the end of command execution, an LLM call generates:

• What was accomplished
• Any issues encountered
• Key findings
• Next recommendations

---

Key Components

Component	File	Purpose
CLI Entry	cli.py	Signal handlers, interactive loop
Ask Handler	ask.py	LLM communication, response parsing
Do Handler	do_runner/handler.py	Execution engine, conflict handling
Executor	do_runner/executor.py	Subprocess management
Conflict Detector	do_runner/verification.py	Pre-flight resource checks
Error Diagnoser	do_runner/diagnosis.py	Error patterns, fix strategies
Terminal Monitor	do_runner/terminal.py	Real-time terminal watching
Watch Service	watch_service.py	Background daemon
Database	do_runner/database.py	Session persistence

---

User Flow

Happy Path

User: "install docker and run hello-world"
         │
         ▼
    Cortex gathers system info (read-only commands)
         │
         ▼
    Conflict check: Is docker installed?
         │
         ▼
    Show commands for approval:
      1. apt update
      2. apt install -y docker.io
      3. systemctl start docker
      4. docker run hello-world
         │
         ▼
    User approves → Execute commands
         │
         ▼
    All succeed → Show summary + suggestions
         │
         ▼
    User asks follow-up or exits

Error Recovery Path

    Command fails (e.g., "command not found")
         │
         ▼
    Auto-diagnose: missing package
         │
         ▼
    Auto-fix: apt install <package>
         │
         ▼
    Retry original command
         │
         ▼
    Success → Continue

Manual Intervention Path

    User declines auto-execution OR sudo required
         │
         ▼
    Show commands to run manually
         │
         ▼
    Monitor user's other terminals
         │
         ▼
    Track which commands were executed
         │
         ▼
    If failed/incomplete → Ask user what to do
      - Retry with modifications
      - Add new requirements
      - End session
         │
         ▼
    Generate LLM summary

---

Setup Requirements

# Install watch service for terminal monitoring
cortex watch --install --service

# Verify installation
cortex watch --status

# Configure API key
export ANTHROPIC_API_KEY=your-key-here

---

Usage Examples

Basic Usage

# Interactive mode
cortex ask --do

# One-shot command
cortex ask --do "install nginx with ssl"

With Terminal Monitoring

# Terminal 1: Cortex
cortex ask --do
> configure postgresql for my app

# Terminal 2: Run sudo commands
$ sudo systemctl start postgresql
$ sudo -u postgres createdb myapp

---

Configuration

Variable	Purpose	Default
ANTHROPIC_API_KEY	Claude API	Required
OPENAI_API_KEY	OpenAI API (fallback)	Optional
CORTEX_DO_TIMEOUT	Command timeout	120s

---

Related Files

• docs/ASK_DO_ARCHITECTURE.md - Full architecture documentation
• scripts/setup_ask_do.py - Automated setup script
• cortex/do_runner/ - Core execution module

---

Checklist

Core Features

• Natural language command generation via LLM
• Multi-step command execution with approval
• Resource conflict detection (Docker, services, files, ports)
• User choice for conflicts (use existing, restart, recreate)
• Task tree execution model
• Error diagnosis with pattern matching
• LLM-powered error analysis
• Auto-repair for non-sudo commands
• Package installation for missing commands
• Manual intervention mode
• Real-time terminal monitoring
• Watch service daemon (systemd)
• Shell hooks for command tracking
• Session persistence (SQLite)
• Interactive follow-up session
• Visual grouping with Rich panels
• LLM-generated summary after execution
• Ctrl+C exits immediately, Ctrl+Z stops current command
• Natural language retry after manual intervention

Terminal Monitoring

• Bash history monitoring
• Zsh history monitoring
• Watch hook for real-time detection
• Terminal ID tracking
• Cursor IDE terminal support
• Command match validation

Error Handling

• Permission errors
• Missing packages/commands
• Service not running
• Port conflicts
• File/directory not found (soft failure)
• Docker container conflicts
• Package mapping (command → apt package)

UX Polish

• Clean visual output with Rich panels
• Command execution progress indicators
• Success/failure status summary
• Guardrails for non-technical queries
• Session history display
• Dynamic next-step suggestions

Pending/Nice-to-Have

• Web UI dashboard
• Command history search
• Undo/rollback support
• Multi-LLM comparison
• Custom package mappings
• Ansible playbook export
• Docker Compose generation

---

Known Issues

1. Sudo commands cannot be auto-executed - By design, for security
2. Some package names require manual mapping - Expanding UBUNTU_PACKAGE_MAP
3. Long-running commands may timeout - Configurable via CORTEX_DO_TIMEOUT

---

Labels

feature, ai, command-execution, terminal, auto-repair

---

References

• Architecture: /docs/ASK_DO_ARCHITECTURE.md
• Setup script: /scripts/setup_ask_do.py
• Watch service: systemctl --user status cortex-watch