Metadata-Version: 2.4
Name: deepagent-runner
Version: 0.1.0
Summary: A terminal application for running DeepAgent in a workspace directory
Author: DeepAgent Runner Team
License: MIT
Requires-Python: >=3.11
Requires-Dist: deepagents>=0.1.0
Requires-Dist: langchain-openai>=0.2.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Provides-Extra: tavily
Requires-Dist: tavily-python>=0.3.0; extra == 'tavily'
Description-Content-Type: text/markdown

# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:**

```bash
# 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

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

**Note:** Always activate your virtual environment before running commands. See [INSTALL.md](INSTALL.md) for detailed installation instructions.

## Configuration

Create a `.env` file in the project root:

```env
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:

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

### Basic usage

Run in current directory:

```bash
deepagent-runner --workspace .
```

Specify workspace:

```bash
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

```bash
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](USAGE.md).

### Check system configuration

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

### Show version

```bash
# 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](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](USAGE.md)** - Complete usage guide with examples
- **[INSTALL.md](INSTALL.md)** - Installation instructions
- **[TECH_STACK.md](TECH_STACK.md)** - Technical decisions
- **[STATUS.md](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

