Skip to content

Installation Guide

Get started with Agent Script Tools in your development environment.

Prerequisites

Before installing Agent Script Tools, ensure you have the following requirements:

System Requirements

  • Python 3.13+ - Leveraging modern Python features
  • uv - Fast, reliable package manager
  • Git - For cloning the repository

Installing uv

If you don't have uv installed, get it with:

Bash
1
curl -LsSf https://astral.sh/uv/install.sh | sh
Bash
1
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Bash
1
2
3
4
5
6
7
8
# Via pip
pip install uv

# Via conda
conda install -c conda-forge uv

# Via homebrew (macOS)
brew install uv

Installation Methods

Clone the repository and install in development mode:

Bash
1
2
3
4
5
6
7
8
9
# Clone the repository
git clone https://github.com/theagenticguy/agent-script.git
cd agent-script

# Install all dependencies including development tools
uv sync --all-groups

# Activate virtual environment (optional with uv)
source .venv/bin/activate

Production Installation

For production use, install without development dependencies:

Bash
1
2
3
4
# Clone and install production dependencies only
git clone https://github.com/theagenticguy/agent-script.git
cd agent-script
uv sync

Package Installation

Install individual packages:

Bash
1
2
# Install from workspace root
uv add agent-script-tools
Bash
1
2
# Install specification models only
uv add agent-script-spec

Verification

Verify your installation works correctly:

Bash
1
2
3
4
5
6
7
8
9
# Test CLI commands
uv run agent-script-json
uv run agent-script-markdown

# Run the test suite
uv run poe test

# Check code quality
uv run poe code-quality

Expected Output

If installation is successful, you should see:

  • JSON and Markdown output from the CLI commands
  • All tests passing
  • No linting or type errors

Development Setup

For contributing to Agent Script Tools:

1. Clone and Install

Bash
1
2
3
git clone https://github.com/theagenticguy/agent-script.git
cd agent-script
uv sync --all-groups

2. Install Pre-commit Hooks

Bash
1
2
# Install git hooks for code quality
pre-commit install

3. Configure Your Editor

Install recommended extensions:

JSON
1
2
3
4
5
6
7
8
{
  "recommendations": [
    "ms-python.python",
    "ms-python.mypy-type-checker",
    "charliermarsh.ruff",
    "ms-python.black-formatter"
  ]
}

Configure the Python interpreter:

  1. File → Settings → Project → Python Interpreter
  2. Add → Existing Environment
  3. Point to .venv/bin/python

Project Structure

After installation, your project structure will look like:

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
agent-script/
├── pyproject.toml                    # Main project configuration
├── uv.lock                          # Dependency lock file
├── src/
│   └── agent_script_tools/          # CLI tools package
│       ├── __init__.py
│       ├── scripts.py               # Command implementations
│       └── drivers.py               # Conversion logic
├── packages/
│   └── agent-script-spec/           # Specification models
│       ├── pyproject.toml
│       └── src/
│           └── agent_script_spec/
│               ├── models.py        # Pydantic models
│               └── generate.py      # Schema generation
├── examples/                        # Example specifications
├── tests/                          # Test suite
├── docs/                           # Documentation
└── .venv/                          # Virtual environment

Quick Commands Reference

Common commands for daily development:

Command Description
uv sync --all-groups Install/update all dependencies
uv run poe format Format code with Ruff
uv run poe lint Lint code
uv run poe typecheck Type check with MyPy
uv run poe code-quality Run all quality checks
uv run poe test Run tests
uv run poe cov Run tests with coverage
uv run poe docs Serve documentation locally

Troubleshooting

Common Issues

Python Version

Issue: python: command not found or wrong Python version

Solution:

Bash
1
2
3
4
5
6
7
8
9
# Check Python version
python --version  # Should be 3.13+

# Install Python 3.13 if needed
# On macOS with homebrew:
brew install python@3.13

# On Ubuntu/Debian:
sudo apt install python3.13 python3.13-venv

uv Installation

Issue: uv: command not found

Solution:

Bash
1
2
3
4
5
# Reinstall uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Restart your shell or source profile
source ~/.bashrc  # or ~/.zshrc

Permission Errors

Issue: Permission denied when installing

Solution:

Bash
1
2
3
4
5
# Don't use sudo with uv
# Create virtual environment explicitly
uv venv
source .venv/bin/activate
uv sync --all-groups

Getting Help

If you encounter issues:

  1. Check the logs: Most uv commands provide verbose output with -v
  2. Search GitHub Issues: github.com/theagenticguy/agent-script/issues
  3. Create an Issue: Include your OS, Python version, and error messages

Next Steps

Now that you have Agent Script Tools installed: