smarttools/docs/INSTALL.md

Installation Guide

Complete installation instructions for SmartTools.

Quick Install

git clone https://gitea.brrd.tech/rob/SmartTools.git
cd SmartTools
pip install -e .
export PATH="$HOME/.local/bin:$PATH"
smarttools providers install

Detailed Installation

Step 1: Install Python 3.10+

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip

macOS:

brew install python@3.11

Verify:

python3 --version  # Should be 3.10 or higher

Step 2: Install SmartTools

git clone https://gitea.brrd.tech/rob/SmartTools.git
cd SmartTools
pip install -e .

With TUI and development dependencies:

pip install -e ".[dev]"

Step 3: Configure PATH

SmartTools creates executable wrappers in ~/.local/bin/. Add this to your shell config:

Bash (~/.bashrc):

export PATH="$HOME/.local/bin:$PATH"

Zsh (~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

Fish (~/.config/fish/config.fish):

set -gx PATH $HOME/.local/bin $PATH

Then reload:

source ~/.bashrc  # or restart terminal

Step 4: Install an AI Provider

You need at least one AI CLI tool. The easiest way is the interactive installer:

smarttools providers install

This guides you through installing and authenticating providers.

Manual Installation

OpenCode (free tier available):

curl -fsSL https://opencode.ai/install | bash
source ~/.bashrc  # or start new shell
opencode  # Opens browser for sign-in

Claude CLI (pay-per-use):

npm install -g @anthropic-ai/claude-code
claude  # Opens browser for sign-in

Codex (pay-per-use):

npm install -g @openai/codex
codex  # Opens browser for sign-in

Gemini (free tier available):

npm install -g @google/gemini-cli
gemini  # Opens browser for Google sign-in

Ollama (free, runs locally):

curl -fsSL https://ollama.ai/install.sh | bash
ollama pull llama3
smarttools providers add ollama "ollama run llama3" -d "Local Llama 3"

See PROVIDERS.md for full provider setup instructions.

Step 5: Verify Installation

# Check SmartTools is installed
smarttools --version

# List configured providers
smarttools providers list

# Check which providers are available
smarttools providers check

# Test with mock provider (no AI needed)
echo "hello world" | smarttools run --provider mock

Step 6: Create Wrapper Scripts

After installation or any Python environment change:

smarttools refresh

This creates executable scripts in ~/.local/bin/ for all your tools.

Installing Example Tools

Quick Install (All 28 Tools)

python examples/install.py
smarttools refresh

Manual Install

Copy individual tool configs to ~/.smarttools/<toolname>/config.yaml.

See EXAMPLES.md for all tool configurations.

Troubleshooting

"smarttools: command not found"

PATH is not configured. Add to your shell config:

export PATH="$HOME/.local/bin:$PATH"

"Provider 'X' not found"

1. Check provider is installed: which claude or which opencode
2. Check provider is configured: smarttools providers
3. Add missing provider: smarttools providers add

"Permission denied" on tool execution

Refresh wrapper scripts:

smarttools refresh

TUI doesn't start / looks broken

Install urwid:

pip install urwid

Ensure your terminal supports mouse (most modern terminals do).

Tools work with smarttools run but not directly

The wrapper scripts may be outdated. Refresh them:

smarttools refresh

Python version mismatch

If you have multiple Python versions, ensure SmartTools uses the right one:

python3.11 -m pip install smarttools

Uninstalling

# Remove package
pip uninstall smarttools

# Remove config and tools (optional)
rm -rf ~/.smarttools

# Remove wrapper scripts (optional)
rm ~/.local/bin/{summarize,translate,fix-grammar,...}

Upgrading

pip install --upgrade smarttools
smarttools refresh

Directory Structure

After installation:

~/.smarttools/
├── providers.yaml          # Provider configurations
├── summarize/
│   └── config.yaml         # Tool config
├── translate/
│   ├── config.yaml
│   └── prompt.txt          # External prompt file (optional)
└── ...

~/.local/bin/
├── smarttools              # Main command
├── summarize               # Tool wrapper script
├── translate               # Tool wrapper script
└── ...

Next Steps

1. Set up providers
2. Browse example tools
3. Run smarttools ui to create your first tool