deepagent-runner 0.1.0

A terminal application for running DeepAgent in a workspace directory

DeepAgent Runner 🤖

A cross-platform terminal application that runs a DeepAgent in your workspace directory to help you write code, fix bugs, and execute shell commands.

Features

• 🗂️ Workspace Sandbox: Agent operates only within your selected directory
• 🐚 Cross-platform Shell Execution: Prefers Linux-style shells (bash), falls back to PowerShell on Windows
• 🤖 DeepAgent Integration: Full planning, filesystem tools, and subagent capabilities
• 🎨 Rich Terminal UI: Colorful, intuitive command-line interface with Markdown rendering
• 🔒 Human-in-the-loop: Approve/edit/reject sensitive operations before execution
• 💬 Interactive REPL: Natural conversation with multi-turn context

Prerequisites

• Python 3.11 or higher
• OpenAI API key

Installation

Quick Install (from PyPI - Recommended)

Nếu package đã được publish lên PyPI:

# Cài đặt trực tiếp từ PyPI (không cần source code)
pip install deepagent-runner

# Hoặc với uv (nhanh hơn)
uv pip install deepagent-runner

# Với optional dependencies (web research)
pip install "deepagent-runner[tavily]"

Sau đó chỉ cần tạo file .env với API keys và sử dụng ngay!

Install from Git Repository

Nếu chưa publish lên PyPI, có thể cài từ Git:

# Cài trực tiếp từ Git repo (không cần clone)
pip install git+https://github.com/yourusername/CodeAgent.git

# Hoặc với uv
uv pip install git+https://github.com/yourusername/CodeAgent.git

Install from Source (Development)

Nếu muốn develop hoặc modify code:

# Clone repository
git clone <repository-url>
cd CodeAgent

# Create virtual environment
uv venv
source .venv/bin/activate  # On Linux/macOS
# .venv\Scripts\activate   # On Windows

# First install deepagents (required dependency)
uv add deepagents

# Then install the package in editable mode
uv pip install -e .

Hoặc với pip:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Linux/macOS
# .venv\Scripts\activate   # On Windows

# Install deepagents first (required dependency)
pip install deepagents

# Then install the package
pip install -e .

Development installation

# After activating venv
pip install -e ".[dev]"

Note: Always activate your virtual environment before running commands. See INSTALL.md for detailed installation instructions.

Configuration

Create a .env file in the project root:

OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=openai:gpt-4o  # Optional, defaults to gpt-4o

# Optional: for web research capabilities
TAVILY_API_KEY=your-tavily-key-here

Usage

Important: Make sure your virtual environment is activated before running commands:

source .venv/bin/activate  # On Linux/macOS
# .venv\Scripts\activate   # On Windows

Basic usage

Run in current directory:

deepagent-runner --workspace .

Specify workspace:

deepagent-runner --workspace /path/to/project

Example Session

$ deepagent-runner --workspace my-project

Welcome to DeepAgent Runner! 🤖

You: List all Python files in src/

Agent: Found 5 Python files:
- src/main.py
- src/utils.py
...

You: Run the tests

⚠️ Agent wants to execute: pytest tests/
Decision (approve/edit/reject): approve

✓ All tests passed!

You: /exit
Goodbye! 👋

REPL Commands

• /help - Show help and examples
• /workspace - Display workspace info
• /config - Show configuration
• /clear - Clear conversation history
• /exit - Exit session

Advanced options

deepagent-runner \
  --workspace /path/to/project \
  --model openai:gpt-4o \
  --max-runtime 600 \
  --log-file agent.log \
  --verbose

For detailed examples and workflows, see USAGE.md.

Check system configuration

# Make sure venv is activated first!
deepagent-runner check

Show version

# Make sure venv is activated first!
deepagent-runner version

Troubleshooting: If you get command not found: deepagent-runner, make sure:

1. Virtual environment is activated: source .venv/bin/activate
2. Package is installed: pip install -e . or uv pip install -e .

See INSTALL.md for more troubleshooting tips.

CLI Options

Option	Short	Description	Default
--workspace	-w	Path to workspace directory	Current directory (interactive)
--model	-m	Model identifier (e.g., openai:gpt-4o)	From OPENAI_MODEL or openai:gpt-4o
--max-runtime		Max command execution time (seconds)	300
--log-file		Path to log file	None
--verbose	-v	Enable verbose output	False

Development Status

Status: ✅ FULLY FUNCTIONAL 🎉

All milestones completed:

• ✅ Milestone 1: Skeleton (CLI, config, OS detection)
• ✅ Milestone 2: Filesystem sandbox (secure file operations)
• ✅ Milestone 3: Cross-platform execute (shell commands)
• ✅ Milestone 4: Agent wiring (complete integration)
• ✅ Milestone 5: Interactive REPL (conversation loop)
• ✅ Milestone 6: HITL & Hardening (approval workflows)

Ready for production use!

Project Structure

deepagent-runner/
├── src/
│   └── deepagent_runner/
│       ├── __init__.py
│       ├── cli.py          # CLI entrypoint
│       ├── config.py       # Configuration & OS detection
│       ├── backend.py      # (Milestone 2) Filesystem backend
│       ├── agent.py        # (Milestone 4) Agent setup
│       ├── shell_exec.py   # (Milestone 3) Shell execution
│       └── session.py      # (Milestone 5) Interactive REPL
├── pyproject.toml
├── README.md
└── .env.example

Documentation

• USAGE.md - Complete usage guide with examples
• INSTALL.md - Installation instructions
• TECH_STACK.md - Technical decisions
• STATUS.md - Project status and progress

Contributing

This project follows these principles:

• 🧪 Test cross-platform behavior (Linux, macOS, Windows)
• 🔒 Maintain workspace sandboxing security
• 📝 Write clear documentation
• 🎨 Use rich terminal UI for better UX

What Can the Agent Do?

Code Analysis & Navigation:

• List and search files
• Read and analyze code structure
• Find patterns, TODOs, bugs

Code Modification:

• Write new files
• Edit existing files (with approval)
• Refactor code
• Add documentation

Testing & Execution:

• Run test suites
• Execute build scripts
• Run linters and formatters
• Any shell command (with approval)

Project Management:

• Plan multi-step tasks
• Track progress with todos
• Delegate to subagents

All within the safety of workspace sandboxing! 🔒

License

MIT