larql
Run, serve, query and edit AI models โ a Rust model runtime built on VINDEX3, an executable, inspectable model format.
- 1.2k
- Rust
- Apache-2.0
- 13 h ago
The maintainer has not written a description at the source.
Repo chrishayuk/virtual-shell, read from GitHub 12 min ago. chrishayuk has not joined Take My Repo.
chrishayuk/virtual-shell is a public repo on GitHub by chrishayuk. It declares no license on GitHub. Public does not mean open source: without a license, nobody is granted the right to reuse it. It is written mainly in Python, has 6 stars and last changed on 2026-11-21. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
A powerful virtual shell environment with MCP (Model Context Protocol) integration and AI agents as Unix processes, perfect for AI automation and sandboxed execution environments.
Revolutionary Feature: Run AI agents as first-class shell processes! Agents behave like Unix commands with PIDs, pipes, background execution, and process management.
# Run agents like shell commands
echo "Hello" | agent assistant.agent
# Agent pipelines
cat data.csv | agent analyzer.agent | agent reporter.agent > report.md
# Background agents
agent monitor.agent -b &
# Process management
agent -l # List agents
agent -k agent_1 # Kill agent
๐ฌ Watch the Demo | ๐ Full Documentation
Chuk Virtual Shell provides a complete POSIX-like virtual shell environment designed specifically for AI agents and automation:
# Install with uv (recommended)
uv pip install chuk-virtual-shell
# Or with pip
pip install chuk-virtual-shell
# For MCP server functionality, install optional dependency (Unix/macOS only)
uv pip install chuk-virtual-shell[mcp-server]
# Or with pip
pip install chuk-virtual-shell[mcp-server]
# Note: MCP server requires Unix-like OS (Linux/macOS) due to uvloop dependency
# Windows users can use WSL or run the shell without MCP server features
# For development (if you cloned the repo)
cd chuk-virtual-shell
uv sync
# Or run directly without installation using uvx
uvx chuk-virtual-shell
# Start interactive shell
uv run chuk-virtual-shell
# Use a pre-configured sandbox (recommended)
uv run chuk-virtual-shell --sandbox ai_sandbox
# Start MCP server for AI agents
uv run python -m chuk_virtual_shell.mcp_server
# Run with different storage backends
uv run chuk-virtual-shell --fs-provider sqlite --fs-provider-args 'db_path=my_shell.db'
# Run scripts
uv run chuk-virtual-shell examples/hello_world.sh
# Start telnet server for remote access
uv run chuk-virtual-shell --telnet --port 8023
# See examples/mcp_client_demo.py for complete example
from examples.mcp_client_demo import SimpleMCPClient
client = SimpleMCPClient()
await client.start_server()
# Create isolated session
result = await client.call_tool("bash", {"command": "pwd"})
session_id = result["session_id"]
# Commands share state within session
await client.call_tool("bash", {
"command": "export PROJECT=MyApp && mkdir -p /project/src",
"session_id": session_id
})
# State persists across commands
result = await client.call_tool("bash", {
"command": "echo $PROJECT && ls /project",
"session_id": session_id
})
# Output: MyApp\nsrc
# Run the complete MCP demonstration
uv run examples/mcp_client_demo.py
# Expected output shows:
# โ
User isolation and session management
# โ
State persistence across commands
# โ
Background task execution
# โ
Multiple concurrent sessions
# โ
Complex multi-step workflows
Full Model Context Protocol implementation with user isolation:
# Available MCP tools:
- bash # Execute shell commands with session persistence
- whoami # Get user context and session info
- list_sessions # List all active sessions for current user
- get_session_state # Get session details (pwd, env, lifetime)
- destroy_session # Clean up sessions
- get_task_output # Get background task results
- cancel_task # Cancel running background tasks
User Isolation Features:
Advanced Shell Features via MCP:
2>, 2>>, 2>&1)&>, &>>)Stateful sessions that maintain context - essential for AI workflows:
from chuk_virtual_shell.session import ShellSessionManager
from chuk_virtual_shell.shell_interpreter import ShellInterpreter
# Create session manager
manager = ShellSessionManager(shell_factory=lambda: ShellInterpreter())
# Create persistent session
session_id = await manager.create_session()
# Commands share state
await manager.run_command(session_id, "cd /project")
await manager.run_command(session_id, "export API_KEY=secret")
await manager.run_command(session_id, "echo 'data' > file.txt")
# State persists
result = await manager.run_command(session_id, "pwd && echo $API_KEY && cat file.txt")
# Output: /project\nsecret\ndata
Perfect for agentic coding workflows where context matters:
# See examples/agentic_coding_demo.py for full example
agent = CodingAgent(session_manager)
await agent.start_project("api-service", "FastAPI")
await agent.execute_task(create_structure_task)
await agent.execute_task(implement_endpoints_task)
await agent.execute_task(add_tests_task)
# Context maintained throughout!
Revolutionary feature: AI agents run as shell processes with full Unix semantics:
# Run an agent like any command
agent assistant.agent
# Pipe input to agents
echo "analyze this" | agent analyzer.agent
# Chain agents in pipelines
cat data.csv | agent parser.agent | agent reporter.agent > report.txt
# Background execution
agent monitor.agent -b &
# Process management
agent -l # List running agents
agent -k agent_123 # Kill an agent
agent -s agent_123 # Check agent status
Agent Features:
<, >, >>, and |& or -b flagComprehensive redirection support (see docs/features/redirection.md):
# Output redirection
echo "Hello" > output.txt
echo "World" >> output.txt
# Input redirection
sort < unsorted.txt > sorted.txt
# Pipelines
cat data.txt | grep "pattern" | sort | uniq > results.txt
# Here-documents (in scripts)
cat << EOF > config.yaml
server: localhost
port: 8080
EOF
# Advanced redirection
command 2> errors.txt # Stderr redirection
command 2>&1 # Merge stderr to stdout
command &> all_output.txt # Combined output
command 2>> errors.txt # Append stderr
command &>> all.txt # Append combined output
Full quoting semantics (see docs/features/quoting.md):
# Single quotes - literal
echo 'Hello $USER' # Output: Hello $USER
# Double quotes - with expansion
echo "Hello $USER" # Output: Hello alice
# Backslash escaping
echo "Price: \$100" # Output: Price: $100
echo file\ with\ spaces.txt # Output: file with spaces.txt
# Mixed quoting
echo "It's"' a nice day' # Output: It's a nice day
Ready-to-use secure environments:
# config/ai_sandbox.yaml - Restricted AI agent environment
environment:
HOME: /sandbox
USER: ai
PATH: /bin
SANDBOX_MODE: restricted
filesystem:
provider: memory
initialization:
- mkdir -p /sandbox/workspace
- echo "AI Sandbox Ready" > /sandbox/README.txt
Available sandboxes:
ai_sandbox - Restricted environment for AI code executiondefault - Balanced development environment readonly - Read-only exploratione2b - E2B.dev compatible environmenttigris - Tigris Data S3-compatible storage| Feature Category | Feature | Status | Notes |
|---|---|---|---|
| MCP Integration | MCP Server | โ | Full protocol support |
| User Isolation | โ | Session & task isolation | |
| Background Tasks | โ | Async execution with streaming | |
| Session Persistence | โ | State maintained across commands | |
| I/O Redirection | Basic pipes (|) |
โ | Multi-stage pipelines |
Output redirect (>, >>) |
โ | Write and append | |
Input redirect (<) |
โ | Read from files | |
Stderr redirect (2>, 2>>) |
โ | Full stderr redirection | |
Combined (2>&1, &>, &>>) |
โ | Merge stdout/stderr | |
Here-docs (<<, <<-) |
โ | Full interactive & script support | |
| Shell Operators | Chaining (&&, ||, ;) |
โ | Full conditional execution |
Command substitution ($()) |
โ | Both syntaxes supported | |
| Variable expansion | โ | $VAR, ${VAR} |
|
Glob patterns (*, ?) |
โ | Full support | |
| Control Flow | if/then/else | โ | Conditional logic |
| for/while loops | โ | Full iteration support | |
| case statements | โ | Pattern matching | |
| Functions | โ | Planned | |
| Commands | File operations | โ | cp, mv, rm, mkdir, touch |
| Text processing | โ | grep, sed, awk, sort, uniq | |
| File viewing | โ | cat, head, tail, more | |
| System utilities | โ | find, which, tree, date |
Legend:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ MCP Client (AI Agent) โ
โโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ MCP Protocol
โโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ MCP Server (chuk_virtual_shell) โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ User Isolation & Session Management โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Shell Interpreter & Command Executor โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Virtual Filesystem (Memory/SQLite/S3) โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
# && - Execute next command only if previous succeeds
mkdir /tmp && cd /tmp && echo "Success"
# || - Execute next command only if previous fails
cd /nonexistent || echo "Directory not found"
# ; - Execute commands sequentially regardless of status
echo "First"; echo "Second"; echo "Third"
# Set and use environment variables
export NAME="World"
echo "Hello $NAME" # Output: Hello World
echo "Path: ${HOME}/documents" # Output: Path: /home/user/documents
# Special variables
echo "Exit code: $?" # Last command's exit code
echo "Current dir: $PWD" # Current working directory
# * - Match any characters
ls *.txt # List all .txt files
rm /tmp/*.log # Remove all log files
# ? - Match single character
ls test?.py # Matches test1.py, test2.py, etc.
# Works with any command
cp *.txt /backup/ # Copy all text files
grep "error" *.log # Search in all log files
# Modern $() syntax
echo "Current time: $(date)"
export COUNT=$(ls | wc -l)
# Legacy backtick syntax
echo "User: `whoami`"
# Output redirection
echo "Hello" > file.txt # Write to file
echo "World" >> file.txt # Append to file
# Input redirection
wc < file.txt # Read from file
# Stderr redirection
command 2> errors.txt # Redirect stderr
command 2>&1 # Merge stderr to stdout
command &> all_output.txt # Combined output
# Pipelines
cat file.txt | grep pattern # Basic pipe
cat data.csv | awk -F, '{print $1}' | sort # Multi-stage pipeline
# The shell automatically loads ~/.shellrc on startup
cat > ~/.shellrc << 'EOF'
# Environment variables
export EDITOR=nano
export PATH=/usr/local/bin:/usr/bin:/bin
# Aliases
alias ll="ls -la"
alias ..="cd .."
alias grep="grep -i"
# Enable command timing
timings -e
EOF
Create shortcuts for frequently used commands:
alias ll="ls -la" # Create alias
alias # List all aliases
unalias ll # Remove alias
Track and search through your command history:
history # Show all history
history 10 # Show last 10 commands
history grep # Search for commands containing 'grep'
history -c # Clear history
Monitor command execution performance:
timings -e # Enable timing
timings # Show statistics
timings -s avg # Sort by average time
timings -c # Clear statistics
timings -d # Disable timing
Visualize directory structures with the tree command:
tree # Show current directory tree
tree -L 2 # Limit depth to 2 levels
tree -d # Show directories only
tree -a # Include hidden files
Find where commands are located:
which ls # Find the ls command
which -a python # Find all python executables
PyodideShell is fully compatible across multiple operating systems:
The virtual filesystem uses forward slashes (/) for all path operations internally, ensuring consistent behavior across platforms. The CI/CD pipeline automatically tests on all three major operating systems with Python versions 3.9 through 3.12.
The filesystem now supports multiple storage backends through a provider-based architecture:
You can easily switch between providers or create custom ones to suit your needs.
All commands are implemented as separate classes that extend the ShellCommand base class, making it easy to add new commands.
The shell includes 50+ commands organized into logical categories. For complete documentation with usage examples, options, and integration guides, see the Command Documentation.
The virtual shell supports full input/output redirection and pipelines, enabling powerful command composition:
<< - Here-document for multi-line input<<- - Here-document with leading tab stripping# Create multi-line file content
cat > config.txt << EOF
server {
listen 80;
server_name example.com;
root /var/www/html;
}
EOF
# With tab stripping (<<-)
cat > script.sh <<- 'SCRIPT'
#!/bin/bash
echo "Indented script"
if [ -f file.txt ]; then
echo "File exists"
fi
SCRIPT
> - Redirect output to a file (overwrites existing content)>> - Append output to a fileecho "Hello" > file.txt # Write to file
echo "World" >> file.txt # Append to file
ls -la > directory_list.txt # Save directory listing
grep ERROR log.txt > errors.txt # Save filtered output
< - Redirect input from a filewc < file.txt # Count lines/words/bytes from file
sort < unsorted.txt # Sort file contents
grep pattern < input.txt # Search in redirected input
sed 's/old/new/g' < input.txt # Process redirected input
| - Pipe output of one command to input of anothercat file.txt | grep pattern # Search in file output
ls -la | grep ".txt" # Filter directory listing
cat data.csv | awk -F, '{print $1}' | sort # Extract and sort CSV column
cat log.txt | grep ERROR | wc -l # Count error lines
# Sort numbers and save top 3
cat numbers.txt | sort -n | head -n 3 > top3.txt
# Process CSV and save results
awk -F, '{print $1,$3}' < data.csv | sort > names_roles.txt
# Filter logs and save errors
grep ERROR < app.log | sort | uniq > unique_errors.txt
# Complex pipeline with multiple stages
cat access.log | awk '{print $1}' | sort | uniq -c | sort -rn > ip_stats.txt
Complete documentation for all shell commands is available in the docs/ directory:
Each command includes detailed documentation with:
For a quick overview of available commands by category:
help # Show all available commands
help <command> # Show detailed help for specific command
The examples/ directory contains several demonstration scripts showing the virtual shell's capabilities:
hello_world.sh - Basic shell script demonstrationfile_operations.sh - File system operationstext_processing.sh - Text processing commands (grep, awk, sed, etc.)diff_patch_demo.sh - Demonstrating diff and patch commandsredirection_pipeline_demo.sh - Comprehensive redirection and pipeline examplescontrol_flow.sh - Shell control flow structureshello_world.py - Python script executiondata_processing.py - Python data processingfile_operations.py - Python file operationssystem_interaction.py - Python system interactionTo run an example script:
# Method 1: As a command-line argument
uv run python -m chuk_virtual_shell.main examples/text_processing.sh
# Method 2: From within the interactive shell
uv run virtual-shell
$ script /path/to/example.sh
# Method 3: Using Python
from chuk_virtual_shell.shell_interpreter import ShellInterpreter
from chuk_virtual_shell.script_runner import ScriptRunner
shell = ShellInterpreter()
runner = ScriptRunner(shell)
# Copy script to virtual filesystem
with open('examples/text_processing.sh', 'r') as f:
content = f.read()
shell.fs.write_file('/tmp/script.sh', content)
# Run it
result = runner.run_script('/tmp/script.sh')
print(result)
# Using uvx (no installation required)
uvx virtual-shell
# Using uv (if cloned locally)
uv run virtual-shell
# Using pip install
virtual-shell
# Use SQLite storage
uvx virtual-shell --fs-provider sqlite --fs-provider-args 'db_path=my_shell.db'
# Use S3 storage
uvx virtual-shell --fs-provider s3 --fs-provider-args '{"bucket_name": "my-bucket", "prefix": "shell1"}'
# Or with uv run if cloned locally
uv run virtual-shell --fs-provider sqlite --fs-provider-args 'db_path=my_shell.db'
python main.py --fs-provider list
# With default memory provider
python main.py --telnet
# With SQLite provider
python main.py --telnet --fs-provider sqlite --fs-provider-args 'db_path=telnet_shell.db'
Then connect using any telnet client:
telnet localhost 8023
# Run a script with specific provider
python main.py --script my_script.sh --fs-provider sqlite --fs-provider-args 'db_path=my_shell.db'
When running in a browser environment with Pyodide, the shell operates in interactive mode:
import main
main.run_interactive_shell("sqlite", {"db_path": ":memory:"}) # With provider selection
Run AI agents as shell processes:
# Clean demo with filtered output
uv run python demo.py
# Full demo with all output
uv run python examples/agent_clean_demo.py
Watch multiple agents work together as a team:
# Software development team simulation
uv run python examples/software_team_demo.py
# Multi-agent collaboration with pipelines
uv run python run_multi_agent.py
These demos showcase:
Run the session demo to see all session features in action:
uv run python examples/session_demo.py
This demonstrates:
The shell provides real-time streaming output with sequence IDs to ensure proper ordering:
# Stream output from long-running commands
async for chunk in manager.run_command(session_id, "ls -la /large_directory"):
print(f"[Seq {chunk.sequence_id}] {chunk.data}")
# Output arrives in real-time with sequence IDs
Control long-running processes with cancellation and timeouts:
# Set timeout for command execution (in milliseconds)
try:
async for chunk in manager.run_command(
session_id,
"python long_script.py",
timeout_ms=5000 # 5 second timeout
):
print(chunk.data)
except asyncio.TimeoutError:
print("Command timed out")
# Cancel a running command
task = asyncio.create_task(
manager.run_command(session_id, "sleep 100")
)
# ... later ...
task.cancel() # Cancel the running command
See how AI agents can use sessions for complex development tasks:
uv run python examples/agentic_coding_demo.py
This shows:
# Basic shell operations
uv run python examples/hello_world.sh
# File operations with new commands
uv run python examples/file_operations.sh
# All new features (aliases, history, tree, etc.)
uv run python examples/new_features_demo.sh
ls / # List files in root directory
cd /home/user # Change directory
pwd # Show current directory
mkdir my_folder # Create a directory
touch file.txt # Create an empty file
echo "Hello" > file.txt # Create a file with content
cat file.txt # Display file content
cp file.txt backup.txt # Copy a file
mv old.txt new.txt # Move/rename a file
rm file.txt # Remove a file
find . -name "*.txt" # Find files by pattern
tree # Show directory structure
# grep - Search for patterns in files
grep "pattern" file.txt # Search for pattern
grep -i "pattern" file.txt # Case-insensitive search
grep -n "pattern" file.txt # Show line numbers
grep -v "pattern" file.txt # Invert match
# awk - Pattern scanning and processing
awk '{print $1}' file.txt # Print first field
awk -F: '{print $2}' file.txt # Use : as field separator
awk '{sum+=$1} END {print sum}' # Sum first column
# sed - Stream editor
sed 's/old/new/' file.txt # Replace first occurrence
sed 's/old/new/g' file.txt # Replace all occurrences
sed -i 's/old/new/g' file.txt # Edit file in-place
# sort and uniq
sort file.txt # Sort lines
sort -n numbers.txt # Numeric sort
uniq file.txt # Remove duplicates
sort file.txt | uniq -c # Count occurrences
# head/tail
head -n 5 file.txt # First 5 lines
tail -n 5 file.txt # Last 5 lines
Create and work with AI agents as first-class shell processes:
Here's a complete example of creating and running an agent from within the shell:
# Start the virtual shell
$ uv run chuk-virtual-shell
# Create a simple assistant agent using heredoc
$ cat > my_assistant.agent << 'EOF'
#!agent
name: my_assistant
model: gpt-3.5-turbo
system_prompt: |
You are a helpful programming assistant.
Answer questions about code, debugging, and best practices.
Keep responses concise and practical.
tools:
- cat
- ls
- grep
- echo
input: stdin
output: stdout
memory: session
temperature: 0.7
max_tokens: 300
timeout: 30
EOF
# Verify the agent file was created
$ ls -la *.agent
-rw-r--r-- 1 user user 234 Dec 14 10:30 my_assistant.agent
# View the agent definition
$ cat my_assistant.agent
#!agent
name: my_assistant
model: gpt-3.5-turbo
system_prompt: |
You are a helpful programming assistant.
Answer questions about code, debugging, and best practices.
Keep responses concise and practical.
tools:
- cat
- ls
- grep
- echo
input: stdin
output: stdout
memory: session
temperature: 0.7
max_tokens: 300
timeout: 30
# List available agents
$ agent -l
Available agents:
my_assistant.agent
# Run the agent with a simple question
$ echo "How do I create a Python list?" | agent my_assistant.agent
To create a Python list, use square brackets:
# Empty list
my_list = []
# List with items
my_list = [1, 2, 3, "hello", True]
# Using list() constructor
my_list = list([1, 2, 3])
You can add items with append(), extend(), or insert() methods.
# Interactive session with the agent
$ agent my_assistant.agent
> What's the difference between a list and a tuple in Python?
Lists are mutable (can be modified) and use square brackets [1, 2, 3].
Tuples are immutable (cannot be modified) and use parentheses (1, 2, 3).
Lists are for collections that change, tuples for fixed data.
> How do I handle exceptions in Python?
Use try-except blocks:
```python
try:
result = 10 / 0
except ZeroDivisionError:
print("Cannot divide by zero")
except Exception as e:
print(f"An error occurred: {e}")
finally:
print("This always runs")
^D # Press Ctrl+D to exit interactive mode
$ cat > sample_code.py << 'EOF' def calculate_average(numbers): total = sum(numbers) return total / len(numbers)
result = calculate_average([1, 2, 3, 4, 5]) print(result) EOF
$ agent my_assistant.agent < sample_code.py This code calculates the average of a list of numbers. It's mostly good but has one issue:
Potential Problem: Division by zero if empty list is passed.
Improved version:
def calculate_average(numbers):
if not numbers:
return 0 # or raise ValueError("Empty list")
total = sum(numbers)
return total / len(numbers)
The rest of the code looks clean and functional.
$ agent my_assistant.agent -b & [1] 12345 Agent my_assistant started with PID 12345
$ agent -l Running agents: PID 12345: my_assistant.agent (background)
$ echo "Explain Python decorators briefly" | agent -p 12345 Decorators modify or extend function behavior without changing the function itself.
Basic syntax:
@decorator
def function():
pass
Common example:
@property
def name(self):
return self._name
They're functions that take functions as input and return modified functions.
$ agent -k 12345 Agent 12345 terminated
$ cat > code_reviewer.agent << 'EOF' #!agent name: code_reviewer model: gpt-4 system_prompt: | You are a code reviewer. Focus on finding bugs, security issues, and suggesting improvements. Be specific and constructive. tools: [cat, grep, find] temperature: 0.3 max_tokens: 500 EOF
$ cat sample_code.py | agent my_assistant.agent | agent code_reviewer.agent [Assistant analyzes code, then reviewer provides detailed feedback]
The code structure is good, but here are specific improvements:
Recommended revision:
def calculate_average(numbers: list[float]) -> float:
"""Calculate the arithmetic mean of a list of numbers.
Args:
numbers: List of numeric values
Returns:
The average as a float
Raises:
ValueError: If the list is empty
"""
if not numbers:
raise ValueError("Cannot calculate average of empty list")
return sum(numbers) / len(numbers)
#### Creating Agent Definitions
Create an agent definition file using heredoc:
```bash
# Create a helpful assistant agent
cat > assistant.agent << 'EOF'
#!agent
name: assistant
model: gpt-3.5-turbo
system_prompt: |
You are a helpful AI assistant.
Answer questions concisely and clearly.
Use the available tools when helpful.
tools:
- ls
- cat
- echo
- grep
input: stdin
output: stdout
memory: session
temperature: 0.7
max_tokens: 500
timeout: 30
EOF
# Create a code reviewer agent
cat > code_reviewer.agent << 'EOF'
#!agent
name: code_reviewer
model: gpt-4
system_prompt: |
You are an expert code reviewer.
Analyze code for bugs, security issues, and best practices.
Provide specific, actionable feedback.
tools:
- cat
- grep
- find
input: stdin
output: stdout
memory: session
temperature: 0.3
max_tokens: 1000
timeout: 60
EOF
# Create a data analyzer agent
cat > analyzer.agent << 'EOF'
#!agent
name: analyzer
model: gpt-3.5-turbo
system_prompt: |
You are a data analysis expert.
Process CSV data and provide insights.
Focus on patterns, trends, and anomalies.
tools:
- cat
- awk
- sort
- uniq
- wc
input: stdin
output: stdout
memory: session
temperature: 0.2
max_tokens: 800
timeout: 45
EOF
# List available agents
agent -l
# Get agent status
agent -s
# Run an agent with input
echo "What is Python?" | agent assistant.agent
# Run agent with file input
agent assistant.agent < question.txt
# Interactive agent session
agent assistant.agent
# Type your questions, press Ctrl+D to end
# Create sample data
cat > data.csv << EOF
name,age,city
Alice,25,New York
Bob,30,Boston
Charlie,35,Chicago
Diana,28,Denver
EOF
# Multi-agent data processing pipeline
cat data.csv | \
agent analyzer.agent | \
agent assistant.agent > analysis_report.txt
# Code review workflow
find . -name "*.py" | \
head -1 | \
xargs cat | \
agent code_reviewer.agent > review.txt
# Parallel agent processing
for file in *.txt; do
echo "Analyzing $file..."
agent analyzer.agent < "$file" > "analysis_$file" &
done
wait # Wait for all background agents to complete
# Agent chain with file processing
echo "Explain this data structure" > prompt.txt
cat data.csv >> prompt.txt
agent assistant.agent < prompt.txt | \
agent code_reviewer.agent > detailed_analysis.txt
# Start agent in background
agent assistant.agent -b &
AGENT_PID=$!
# Check running agents
agent -l
# Send input to background agent
echo "Hello from background" | agent -p $AGENT_PID
# Kill background agent
agent -k $AGENT_PID
# Multiple background agents
agent analyzer.agent -b &
agent code_reviewer.agent -b &
agent assistant.agent -b &
# List all running agents
agent -l
# Kill all agents
agent -k all
# Software development team simulation
mkdir -p /project/src /project/tests /project/docs
# Create specialized agents
cat > product_owner.agent << 'EOF'
#!agent
name: product_owner
model: gpt-4
system_prompt: |
You are a product owner. Create user stories and requirements
from high-level product descriptions. Focus on user value.
tools: [echo, cat]
temperature: 0.5
EOF
cat > tech_lead.agent << 'EOF'
#!agent
name: tech_lead
model: gpt-4
system_prompt: |
You are a technical lead. Design system architecture
and break down user stories into technical tasks.
tools: [cat, echo, find]
temperature: 0.4
EOF
# Development workflow
echo "Build a user authentication system" | \
agent product_owner.agent > /project/requirements.txt
cat /project/requirements.txt | \
agent tech_lead.agent > /project/architecture.md
# Code generation and review cycle
echo "Implement login function based on requirements" | \
agent assistant.agent > /project/src/auth.py
agent code_reviewer.agent < /project/src/auth.py > /project/review.txt
# Documentation generation
cat /project/src/auth.py | \
agent assistant.agent -p "Generate API documentation for this code" > /project/docs/api.md
# Monitor agent performance
agent -l --verbose # Detailed agent status
# Set resource limits
export AGENT_TIMEOUT=120 # 2 minute timeout
export AGENT_MAX_TOKENS=1500
# Agent health checks
agent -h assistant.agent # Check agent health
# Agent logs
agent -logs assistant.agent # View agent execution logs
# Agent metrics
agent -metrics # Show performance metrics
# Create agent configurations directory
mkdir -p ~/.agents/config
# Global agent settings
cat > ~/.agents/config/global.yaml << EOF
default_timeout: 60
default_model: gpt-3.5-turbo
default_temperature: 0.7
max_concurrent_agents: 5
EOF
# Per-agent overrides
cat > ~/.agents/config/code_reviewer.yaml << EOF
model: gpt-4
temperature: 0.1
timeout: 120
EOF
# Load configuration
agent --config ~/.agents/config/global.yaml assistant.agent
env # Show environment variables
export VAR=value # Set environment variable
alias ll="ls -la" # Create alias
history # Show command history
which command # Find command location
whoami # Display current user
date # Show current date/time
timings # Show command execution stats
In-memory storage that is fast but does not persist data:
uv run chuk-virtual-shell --fs-provider memory
Stores the filesystem in a SQLite database for persistence:
# File-based database
uv run chuk-virtual-shell --fs-provider sqlite --fs-provider-args 'db_path=my_shell.db'
# In-memory database
uv run chuk-virtual-shell --fs-provider sqlite --fs-provider-args 'db_path=:memory:'
Stores the filesystem in Amazon S3 or compatible service:
# Set up credentials in .env file
cat > .env << EOF
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1
S3_BUCKET_NAME=my-shell-bucket
EOF
# Use S3 storage (automatically loads .env)
uv run chuk-virtual-shell --fs-provider s3
# Or specify bucket explicitly
uv run chuk-virtual-shell --fs-provider s3 --fs-provider-args '{"bucket_name": "my-bucket"}'
The examples/ directory contains demonstration scripts showing the virtual shell's capabilities:
# Run the complete MCP demonstration
uv run examples/mcp_client_demo.py
# Shows:
# โ
User isolation and session management
# โ
State persistence across commands
# โ
Background task execution
# โ
Multiple concurrent sessions
# โ
Complex multi-step workflows
# Basic shell operations
uv run chuk-virtual-shell examples/hello_world.sh
# File operations and manipulation
uv run chuk-virtual-shell examples/file_operations.sh
# Text processing with grep, awk, sed
uv run chuk-virtual-shell examples/text_processing.sh
# Advanced redirection and pipelines
uv run chuk-virtual-shell examples/redirection_pipeline_demo.sh
# Shell control flow (if/for/while/case)
uv run chuk-virtual-shell examples/control_flow.sh
# Working demo of all features
uv run chuk-virtual-shell examples/working_demo.sh
# Run session demo to see persistence features
uv run python examples/session_demo.py
# Demonstrates:
# - Stateful command execution
# - Working directory persistence
# - Environment variable persistence
# - Command history tracking
# - Multi-session isolation
# Method 1: As command-line argument
uv run chuk-virtual-shell examples/text_processing.sh
# Method 2: From within interactive shell
uv run chuk-virtual-shell
$ script examples/hello_world.sh
# Method 3: With specific sandbox
uv run chuk-virtual-shell --sandbox ai_sandbox examples/secure_script.sh
# Method 4: With persistent storage
uv run chuk-virtual-shell --fs-provider sqlite --fs-provider-args 'db_path=session.db' examples/data_processing.sh
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=chuk_virtual_shell
# Run specific test categories
uv run pytest tests/test_mcp_server.py
uv run pytest tests/test_quoting_comprehensive.py
uv run pytest tests/test_advanced_redirection.py
Current test status: 1398 tests passing (9 skipped)
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
# Clone the repository
git clone https://github.com/chrishayuk/chuk-virtual-shell.git
cd chuk-virtual-shell
# Install with dev dependencies
uv pip install -e ".[dev]"
# Run tests
uv run pytest
# Run linting
uv run ruff check .
# Run type checking
uv run mypy chuk_virtual_shell
Problem: ModuleNotFoundError: No module named 'chuk_mcp_server'
Solution: Install the MCP server optional dependency:
uv pip install chuk-virtual-shell[mcp-server]
# or with pip
pip install chuk-virtual-shell[mcp-server]
Problem: RuntimeError: uvloop does not support Windows at the moment
Solution: MCP server functionality requires Unix-like OS due to uvloop dependency:
[mcp-server] extraProblem: MCP demo fails with JSON decode error
Solution: Ensure the MCP server dependency is installed and the server is accessible:
# Test MCP server directly
uv run python -m chuk_virtual_shell.mcp_server
# Run the interactive demo
uv run examples/mcp_client_demo.py
Problem: Command not found errors
Solution: Ensure you're using the correct command syntax. Check available commands:
# In interactive mode
help
# Check specific command help
help ls
Problem: File permission errors
Solution: The virtual filesystem has simulated permissions. Use appropriate commands:
# Create directories with proper paths
mkdir -p /path/to/directory
# Check current working directory
pwd
chuk_virtual_shell/commands/ShellCommand__init__.pyExample:
# chuk_virtual_shell/commands/system/example.py
from chuk_virtual_shell.commands.command_base import ShellCommand
class ExampleCommand(ShellCommand):
name = "example"
help_text = "example - Description of what it does\nUsage: example [args]"
def execute(self, args):
# Command implementation
return "Example command output"
chuk_virtual_fs/providers/ directoryStorageProviderExample:
# chuk_virtual_fs/providers/custom.py
from chuk_virtual_fs.provider_base import StorageProvider
class CustomStorageProvider(StorageProvider):
"""Custom storage provider implementation"""
def __init__(self, custom_arg=None):
self.custom_arg = custom_arg
# Initialize your storage here
def initialize(self) -> bool:
# Initialize your storage backend
return True
# Implement other required methods...
Create custom sandbox configurations by creating YAML files:
# config/my_sandbox.yaml
environment:
HOME: /my_home
USER: myuser
PATH: /usr/local/bin:/usr/bin:/bin
CUSTOM_VAR: custom_value
filesystem:
provider: memory
security_policy:
allowed_paths:
- /my_home
- /tmp
denied_patterns:
- "*.secret"
initialization:
- mkdir -p /my_home/workspace
- echo "Welcome to My Sandbox" > /my_home/README.txt
Then use it:
uv run chuk-virtual-shell --sandbox config/my_sandbox.yaml
Chuk Virtual Shell is fully compatible across multiple operating systems:
Platform-Specific Notes:
/) internally for consistent behaviorThe project follows a highly modular design:
chuk_virtual_shell/
โโโ shell_interpreter.py # Core shell interpreter
โโโ session/ # Session management
โโโ core/ # Core shell functionality
โ โโโ executor.py # Command execution engine
โ โโโ redirection.py # I/O redirection parser
โ โโโ control_flow_executor.py # Control flow (if/for/while)
โโโ commands/ # Command modules
โ โโโ filesystem/ # File operations (cp, mv, rm, etc.)
โ โโโ navigation/ # Directory navigation (ls, cd, pwd)
โ โโโ text/ # Text processing (grep, sed, awk)
โ โโโ system/ # System utilities (which, history, etc.)
โ โโโ mcp/ # Dynamic MCP command loading
โโโ sandbox/ # Sandbox configuration and loading
โโโ mcp_server.py # MCP server implementation
Each component is designed to be:
MIT License - see LICENSE for details.
Run make help to see all available targets:
test, coverage, coverage-htmllint, format, typecheckbuild, check-build, cleanpublish, publish-testversion, bump-patch, bump-minor, bump-majorrelease-patch, release-minor, release-majorAgents are defined in YAML files with a special #!agent shebang:
#!agent
name: assistant
model: gpt-3.5-turbo
system_prompt: |
You are a helpful AI assistant.
Use the available tools to help users.
tools:
- ls
- cat
- echo
- grep
input: stdin
output: stdout
memory: session
temperature: 0.7
max_tokens: 500
timeout: 30
Create specialized agents that work together:
# From examples/software_team_demo.py
shell.execute("agent /team/product_owner.agent < requirements.txt")
shell.execute("agent /team/tech_lead.agent < user_stories.txt")
shell.execute("agent /team/backend_dev.agent -b") # Background
shell.execute("agent /team/qa_engineer.agent < code.py")
# Data processing pipeline
cat raw_data.csv | \
agent parser.agent | \
agent analyzer.agent | \
agent formatter.agent > report.md
# Parallel processing
for file in *.txt; do
agent processor.agent < "$file" &
done
wait # Wait for all background agents
Set up your API keys for real LLM integration:
# In .env file or environment
export OPENAI_API_KEY=your_key
export ANTHROPIC_API_KEY=your_key
# Install chuk-llm for LLM support
pip install chuk-llm
Ready to give your AI agents a powerful shell environment? Get started with uv pip install chuk-virtual-shell! ๐
chrishayuk/virtual-shell is a public repo on GitHub by chrishayuk. Its maker has not written a description.
It declares no license on GitHub. Public does not mean open source: without a license, nobody is granted the right to reuse it.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-11-21. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.
Run, serve, query and edit AI models โ a Rust model runtime built on VINDEX3, an executable, inspectable model format.
Take My Repo has not tested this on your machine. Requirements come from the project's own documentation.