RomanNum3ral
/
cai
mirror of https://github.com/aliasrobotics/cai.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document --continue mode 

Signed-off-by: Víctor Mayoral Vilches <v.mayoralv@gmail.com>
This commit is contained in:
Víctor Mayoral Vilches 2025-11-14 12:40:58 +01:00
parent e3b456f7f7
commit ccf823a2d5
5 changed files with 569 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/cai_quickstart.md
View File

@ -36,6 +36,28 @@ That should initialize CAI and provide a prompt to execute any security task you
Here's a quick [demo video](https://asciinema.org/a/zm7wS5DA2o0S9pu1Tb44pnlvy) to help you get started with CAI. We'll walk through the basic steps — from launching the tool to running your first AI-powered task in the terminal. Whether you're a beginner or just curious, this guide will show you how easy it is to begin using CAI.
### Autonomous Mode with --continue
CAI can run autonomously using the `--continue` flag, which makes agents automatically continue their work without waiting for user input:
```bash
# Have CAI tell security jokes continuously
cai --continue --prompt "tell me a joke about security"
# Run autonomous security audit
cai --continue --prompt "perform security audit of authentication system"
# Hunt for vulnerabilities automatically
cai --continue --prompt "find SQL injection vulnerabilities"
```
With `--continue`, CAI will:
- Analyze the conversation context after each turn
- Generate intelligent continuation prompts
- Keep working until the task is complete or interrupted
See the [Continue Mode Guide](continue_mode.md) for detailed information.
From here on, type on `CAI` and start your security exercise. Best way to learn is by example:
### Environment Variables

332
docs/continue_mode.md Normal file
View File

@ -0,0 +1,332 @@
# CAI Continue Mode
## Overview
The `--continue` flag enables CAI agents to operate autonomously by automatically generating intelligent continuation prompts when they would normally stop and wait for user input. This feature uses AI-powered analysis to provide contextual advice based on the conversation history, allowing agents to work on complex tasks without manual intervention.
## Quick Start
```bash
# Tell jokes continuously
cai --continue --prompt "tell me a joke about security"
# Analyze code autonomously
cai --continue --prompt "find all SQL injection vulnerabilities in this codebase"
# Run security audit
cai --continue --prompt "perform a comprehensive security audit"
```
## Example: Security Jokes with Continue Mode
Here's what happens when you run `cai --continue --prompt "tell me a joke about security"`:
```bash
$ cai --continue --prompt "tell me a joke about security"
🤖 Processing initial prompt: tell me a joke about security
Agent: Why did the hacker break up with their password?
Because it wasn't strong enough! 💔🔐
🤖 Auto-continuing with: Tell another cybersecurity joke or pun.
Agent: Why don't cybersecurity experts tell secrets at parties?
Because they're afraid of social engineering! 🎉🕵️
🤖 Auto-continuing with: Tell another cybersecurity joke or pun.
Agent: What's a hacker's favorite season?
Phishing season! 🎣💻
[Continues until interrupted with Ctrl+C]
```
## How It Works
### 1. Intelligent Context Analysis
When an agent completes a turn, the continuation system analyzes:
- **Original request**: The initial task or prompt from the user
- **Conversation history**: Recent messages and responses
- **Tool usage**: Which tools were used and their outputs
- **Error states**: Any errors encountered and their types
- **Task progress**: Current state of task completion
### 2. AI-Powered Continuation Generation
The system uses the configured AI model (default: alias1) to generate contextual continuation prompts:
```python
# The system creates a detailed context summary
context_summary = """
ORIGINAL TASK: Tell me a joke about security
CONVERSATION FLOW:
User: Tell me a joke about security
Agent: Why did the hacker break up with their password? Because it wasn't strong enough!
CURRENT STATUS:
- Last action: Told a cybersecurity joke
- Tools used: None
- Errors: No
Generate a specific continuation prompt...
"""
```
### 3. Smart Fallback System
When the AI model is unavailable, the system provides intelligent fallbacks based on context:
| Scenario | Fallback Continuation |
|----------|----------------------|
| Security joke told | "Tell another cybersecurity joke or pun." |
| File not found | "Search for the correct file path or create the missing resource." |
| Search completed | "Examine the search results in detail and investigate the most relevant findings." |
| Security analysis | "Analyze the code for security vulnerabilities like injection flaws or authentication issues." |
| Permission denied | "Check permissions and try accessing the resource with appropriate credentials." |
## Common Use Cases
### 1. Automated Security Audits
```bash
cai --continue --prompt "perform a security audit of the authentication system"
```
The agent will:
- Search for authentication-related files
- Analyze code for vulnerabilities
- Check for common security issues
- Generate a comprehensive report
### 2. Continuous Bug Hunting
```bash
cai --continue --prompt "find and document all XSS vulnerabilities"
```
The agent will:
- Search for user input handling code
- Identify potential XSS vectors
- Document findings
- Suggest fixes
### 3. Extended Code Analysis
```bash
cai --continue --prompt "analyze this codebase for OWASP Top 10 vulnerabilities"
```
The agent will:
- Systematically check for each vulnerability type
- Provide detailed findings
- Continue until all categories are covered
### 4. Entertainment Mode
```bash
cai --continue --prompt "tell me cybersecurity jokes and fun facts"
```
The agent will:
- Tell jokes about security topics
- Share interesting security facts
- Continue entertaining until stopped
## Configuration
### Environment Variables
```bash
# Use a different model for continuation generation
export CAI_MODEL=gpt-4
cai --continue --prompt "analyze this code"
# Set a fallback model if primary fails
export CAI_CONTINUATION_FALLBACK_MODEL=gpt-3.5-turbo
cai --continue --prompt "test application security"
# Configure API keys for custom models
export ALIAS_API_KEY=your-api-key
cai --continue --prompt "perform penetration testing"
```
### Combining with Other CAI Features
```bash
# Use specific agent with continue mode
CAI_AGENT_TYPE=bug_bounter_agent cai --continue --prompt "test example.com"
# Set workspace for file operations
CAI_WORKSPACE=project1 cai --continue --prompt "audit all Python files"
# Enable streaming for real-time output
CAI_STREAM=true cai --continue --prompt "monitor security events"
```
## Advanced Features
### Continuation Decision Logic
The system decides whether to continue based on:
1. **Completion indicators**: Stops if agent says "completed", "finished", "done"
2. **Active work detection**: Continues if tools are being used
3. **Error recovery**: Attempts to resolve errors automatically
4. **Task progress**: Evaluates if the original goal is achieved
### Context-Aware Prompts
The continuation prompts adapt based on:
- **Task type**: Security analysis, testing, code review, etc.
- **Current state**: Errors, findings, progress
- **Tool usage**: Different prompts for different tools
- **Conversation flow**: Maintains coherent task progression
## Best Practices
### 1. Clear Initial Prompts
```bash
# Good - Specific and actionable
cai --continue --prompt "find SQL injection vulnerabilities in user.py"
# Less effective - Too vague
cai --continue --prompt "check security"
```
### 2. Monitor Progress
- Check output periodically to ensure correct direction
- Use Ctrl+C to stop if needed
- Review logs for detailed execution history
### 3. Set Appropriate Limits
```python
# In code integration, use max_turns
run_cai_cli(
starting_agent=agent,
initial_prompt="analyze security",
continue_mode=True,
max_turns=10 # Limit to 10 turns
)
```
### 4. Error Handling
The system automatically:
- Retries failed operations with different approaches
- Searches for alternatives when files are missing
- Adjusts strategies based on error types
## Troubleshooting
### Issue: Generic Continuation Messages
**Symptom**: Always see "Continue working on the task based on your previous findings"
**Solution**:
- Check model configuration is correct
- Ensure API keys are valid
- Review debug logs for API errors
### Issue: Continuation Not Triggering
**Symptom**: Agent stops after completing a task
**Possible causes**:
- Agent explicitly said task is "completed" or "done"
- No recent tool usage detected
- Error in continuation module
**Solution**:
- Use more open-ended initial prompts
- Check logs for completion indicators
- Verify --continue flag is properly set
### Issue: Infinite Loops
**Symptom**: Agent keeps doing the same thing
**Solution**:
- Set max_turns limit
- Use more specific initial prompts
- Interrupt with Ctrl+C and refine the task
## Technical Implementation
### Core Components
1. **`src/cai/continuation.py`**: Main continuation logic
- `generate_continuation_advice()`: Creates AI-powered prompts
- `should_continue_automatically()`: Decides when to continue
2. **`src/cai/cli.py`**: Integration point
- `--continue` flag handling
- Continuation loop implementation
3. **Context Analysis**:
- Extracts conversation history
- Identifies tool usage patterns
- Detects error conditions
### API Integration
The continuation system uses LiteLLM for model calls:
```python
response = await litellm.acompletion(
model=model_name,
messages=[{"role": "user", "content": context_summary}],
temperature=0.3, # Low temperature for focused responses
max_tokens=150
)
```
## Examples Gallery
### Security Audit Continuation
```
Original: "Audit the login system"
→ "Search for authentication-related files in the codebase."
→ "Analyze the login function for SQL injection vulnerabilities."
→ "Check password hashing implementation for security best practices."
→ "Review session management for potential security issues."
```
### Bug Bounty Continuation
```
Original: "Test example.com for vulnerabilities"
→ "Perform initial reconnaissance to gather information about the target."
→ "Scan for exposed endpoints and services."
→ "Test authentication endpoints for common vulnerabilities."
→ "Check for information disclosure in error messages."
```
### Code Review Continuation
```
Original: "Review api.py for security issues"
→ "Analyze input validation in API endpoints."
→ "Check for proper authentication and authorization."
→ "Review error handling for information leakage."
→ "Examine data serialization for injection vulnerabilities."
```
## Example Scripts
Explore working examples in the `examples/` directory:
### Security Jokes Example
```python
# examples/continue_mode_jokes.py
# Demonstrates continuous joke telling with --continue flag
python examples/continue_mode_jokes.py
```
### Security Audit Example
```python
# examples/continue_mode_security_audit.py
# Shows autonomous vulnerability scanning with --continue
python examples/continue_mode_security_audit.py
```
These examples demonstrate:
- How to use --continue flag programmatically
- Handling continuous output
- Graceful interruption with Ctrl+C
- Practical security use cases
## Summary
The `--continue` flag transforms CAI into an autonomous cybersecurity assistant capable of:
- Working independently on complex tasks
- Recovering from errors intelligently
- Maintaining context across multiple operations
- Providing entertainment with continuous jokes
Whether you're conducting security audits, hunting for bugs, or just want some cybersecurity humor, continue mode keeps your agent working until the job is done.

77
examples/continue_mode_jokes.py Normal file
View File

@ -0,0 +1,77 @@
#!/usr/bin/env python3
"""
Example: Using CAI Continue Mode for Security Jokes
This example demonstrates how to use CAI's --continue flag to have an agent
continuously tell cybersecurity jokes without manual intervention.
Usage:
python examples/continue_mode_jokes.py
Or directly from command line:
cai --continue --prompt "tell me a joke about security"
"""
import subprocess
import sys
import os
import signal
def run_joke_session():
"""Run CAI with continue mode to tell security jokes"""
print("🎭 CAI Security Joke Session")
print("=" * 60)
print("Starting CAI in continue mode to tell cybersecurity jokes...")
print("Press Ctrl+C to stop when you've had enough laughs!")
print("=" * 60)
# Command to run CAI with continue flag
cmd = [
sys.executable,
"src/cai/cli.py",
"--continue",
"--prompt", "tell me a joke about cybersecurity"
]
try:
# Run CAI
proc = subprocess.Popen(
cmd,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
stdin=subprocess.PIPE,
text=True,
bufsize=1
)
# Close stdin to prevent hanging
proc.stdin.close()
# Read and display output
for line in proc.stdout:
print(line, end='')
# Highlight continuation messages
if "Auto-continuing with:" in line:
print("🔄 " + "=" * 56)
except KeyboardInterrupt:
print("\n\n✋ Joke session interrupted by user")
if proc.poll() is None:
proc.terminate()
print(" Gracefully stopping CAI...")
except Exception as e:
print(f"\n❌ Error: {e}")
print("\n" + "=" * 60)
print("Thanks for using CAI joke mode! 🎉")
if __name__ == "__main__":
# Change to project root directory
script_dir = os.path.dirname(os.path.abspath(__file__))
project_root = os.path.dirname(script_dir)
os.chdir(project_root)
run_joke_session()

137
examples/continue_mode_security_audit.py Normal file
View File

@ -0,0 +1,137 @@
#!/usr/bin/env python3
"""
Example: Autonomous Security Audit with CAI Continue Mode
This example shows how to use CAI's --continue flag to perform an autonomous
security audit that continues analyzing files and finding vulnerabilities
without manual intervention.
Usage:
python examples/continue_mode_security_audit.py
Or directly from command line:
cai --continue --prompt "perform a security audit of all Python files"
"""
import subprocess
import sys
import os
import time
import signal
def run_security_audit():
"""Run CAI with continue mode for autonomous security auditing"""
print("🔒 CAI Autonomous Security Audit")
print("=" * 60)
print("Starting autonomous security audit...")
print("CAI will continuously analyze code for vulnerabilities.")
print("Press Ctrl+C to stop the audit.")
print("=" * 60)
# Create a sample vulnerable file for demonstration
sample_file = "sample_vulnerable.py"
with open(sample_file, "w") as f:
f.write('''
# Sample file with security vulnerabilities for CAI to find
import os
import sqlite3
def login(username, password):
# SQL Injection vulnerability
conn = sqlite3.connect('users.db')
query = f"SELECT * FROM users WHERE name='{username}' AND pass='{password}'"
cursor = conn.execute(query)
return cursor.fetchone()
def execute_command(user_input):
# Command Injection vulnerability
os.system(f"echo {user_input}")
def read_file(filename):
# Path Traversal vulnerability
with open(f"/app/data/{filename}", "r") as f:
return f.read()
# Hardcoded credentials
API_KEY = "sk-1234567890abcdef"
DB_PASSWORD = "admin123"
''')
# Command to run CAI audit
cmd = [
sys.executable,
"src/cai/cli.py",
"--continue",
"--prompt", f"Perform a comprehensive security audit of {sample_file}, "
f"identify all vulnerabilities, and suggest fixes"
]
try:
# Run CAI
proc = subprocess.Popen(
cmd,
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT,
stdin=subprocess.PIPE,
text=True,
bufsize=1
)
# Close stdin
proc.stdin.close()
# Track findings
vulnerabilities_found = []
continuation_count = 0
# Read output
for line in proc.stdout:
print(line, end='')
# Track vulnerabilities
vuln_keywords = ["injection", "vulnerability", "security issue",
"hardcoded", "insecure", "exposed"]
if any(keyword in line.lower() for keyword in vuln_keywords):
vulnerabilities_found.append(line.strip())
# Track continuations
if "Auto-continuing with:" in line:
continuation_count += 1
print(f"🔄 Continuation #{continuation_count} " + "=" * 40)
# Stop after finding multiple issues
if continuation_count >= 5:
print("\n📋 Audit Summary: Found multiple security issues.")
print(" Stopping audit after thorough analysis.")
proc.terminate()
break
except KeyboardInterrupt:
print("\n\n✋ Security audit interrupted by user")
if proc and proc.poll() is None:
proc.terminate()
except Exception as e:
print(f"\n❌ Error: {e}")
finally:
# Cleanup
if os.path.exists(sample_file):
os.remove(sample_file)
print(f"\n🗑️ Cleaned up {sample_file}")
print("\n" + "=" * 60)
print("🔒 Security Audit Complete")
if vulnerabilities_found:
print(f" Found {len(set(vulnerabilities_found))} potential security issues")
print("=" * 60)
if __name__ == "__main__":
# Change to project root directory
script_dir = os.path.dirname(os.path.abspath(__file__))
project_root = os.path.dirname(script_dir)
os.chdir(project_root)
run_security_audit()

1
mkdocs.yml
View File

@ -93,6 +93,7 @@ nav:
# ========================================
- Guides:
- Running Agents: running_agents.md
- Continue Mode: continue_mode.md
- Working with Results: results.md
- Streaming: streaming.md
- Tracing & Debugging: tracing.md