SmartTools

A lightweight personal tool builder for AI-powered CLI commands.

Turn any AI model into a Unix-style pipe command. Build once, use forever.

# Fix grammar in any file
echo "teh cat sat on teh mat" | fix-grammar
# Output: The cat sat on the mat

# Explain errors instantly
cat error.log | explain-error

# Generate commit messages
git diff --staged | commit-msg

# Extract data as validated JSON
echo "Price $49.99, SKU ABC-123" | json-extract --fields "price, sku"
# Output: {"price": 49.99, "sku": "ABC-123"}

Why SmartTools?

• Unix Philosophy - Tools that do one thing well, composable with pipes
• Provider Agnostic - Works with Claude, GPT, Gemini, DeepSeek, local models
• No Lock-in - Your tools are YAML files, your prompts are yours
• Multi-step Pipelines - Chain AI prompts with Python code for validation
• 12+ Providers Profiled - We tested them so you don't have to

Quick Start

# Install
pip install smarttools

# Ensure ~/.local/bin is in PATH
export PATH="$HOME/.local/bin:$PATH"

# Launch the UI
smarttools ui

# Or create your first tool
smarttools create summarize

Installation

From PyPI (Recommended)

pip install smarttools

From Source

git clone https://github.com/yourusername/smarttools.git
cd smarttools
pip install -e .

Requirements

• Python 3.10+
• At least one AI CLI tool installed (see Provider Setup)
• Optional: urwid for the TUI (pip install urwid)

Post-Install

Add to your ~/.bashrc or ~/.zshrc:

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

Then refresh wrapper scripts:

smarttools refresh

Usage

UI Mode (Recommended for Beginners)

smarttools ui

Navigate with arrow keys, Tab, Enter, and mouse. Create tools visually with the built-in prompt editor.

CLI Mode

smarttools list              # List all tools
smarttools create mytool     # Create new tool
smarttools edit mytool       # Edit in $EDITOR
smarttools delete mytool     # Delete tool
smarttools run mytool        # Run a tool
smarttools test mytool       # Test with mock provider
smarttools refresh           # Update executable wrappers

Running Tools

Once created, tools work like any Unix command:

# Direct invocation
mytool -i input.txt -o output.txt

# Pipe input (most common)
cat file.txt | mytool

# With arguments
echo "hello" | translate --lang French

# Preview without calling AI
cat file.txt | mytool --dry-run

# Test with mock provider
cat file.txt | mytool --provider mock

Example Tools

SmartTools comes with 28 pre-built examples you can install:

Text Processing

Tool	Description	Example
summarize	Condense documents	cat article.txt | summarize
translate	Translate text	echo "Hello" | translate --lang Spanish
fix-grammar	Fix spelling/grammar	cat draft.txt | fix-grammar
simplify	Rewrite for clarity	cat legal.txt | simplify --level "5th grade"
tone-shift	Change tone	cat email.txt | tone-shift --tone professional
eli5	Explain like I'm 5	cat quantum.txt | eli5
tldr	One-line summary	cat readme.txt | tldr
expand	Expand bullet points	cat notes.txt | expand

Developer Tools

Tool	Description	Example
explain-error	Explain stack traces	cat error.log | explain-error
explain-code	Explain what code does	cat script.py | explain-code
review-code	Quick code review	cat pr.diff | review-code --focus security
gen-tests	Generate unit tests	cat module.py | gen-tests --framework pytest
docstring	Add docstrings	cat functions.py | docstring
commit-msg	Generate commit message	git diff --staged | commit-msg

Data Tools

Tool	Description	Example
json-extract	Extract as validated JSON	cat text.txt | json-extract --fields "name, email"
json2csv	Convert JSON to CSV	cat data.json | json2csv
extract-emails	Extract email addresses	cat page.html | extract-emails
extract-contacts	Extract contacts as CSV	cat notes.txt | extract-contacts
sql-from-text	Natural language to SQL	echo "get active users" | sql-from-text
safe-sql	SQL with safety checks	echo "delete old records" | safe-sql
parse-log	Analyze log files	cat app.log | parse-log --focus errors
csv-insights	Analyze CSV data	cat sales.csv | csv-insights --question "trends?"

Advanced Multi-Step Tools

Tool	Description	Pattern
log-errors	Extract & explain errors from huge logs	Code→AI
diff-focus	Review only added lines	Code→AI
changelog	Git log to formatted changelog	Code→AI→Code
code-validate	Generate syntax-checked Python	AI→Code

Install Example Tools

# Download and run the example installer
curl -sSL https://raw.githubusercontent.com/yourusername/smarttools/main/examples/install.py | python3

# Or manually copy from examples/

Providers

SmartTools works with any AI CLI tool. We've profiled 12 providers:

Provider	Speed	Accuracy	Cost	Best For
opencode-deepseek	13s	4/4	Cheap	Best value - daily use
opencode-pickle	13s	4/4	FREE	Best free - accurate
claude-haiku	14s	4/4	Paid	Fast + accurate
codex	14s	4/4	Paid	Reliable
claude-opus	18s	4/4	$	Highest quality
gemini	91s	3/4	Paid	Large docs (1M tokens)

See docs/PROVIDERS.md for setup instructions.

Tool Anatomy

A tool is a YAML config file in ~/.smarttools/<name>/config.yaml:

name: summarize
description: Condense documents to key points
arguments:
  - flag: --length
    variable: length
    default: "3-5 bullet points"
steps:
  - type: prompt
    prompt: |
      Summarize this text into {length}:

      {input}      
    provider: opencode-pickle
    output_var: response
output: "{response}"

Multi-Step Tools

Chain AI prompts with Python code for powerful workflows:

name: json-extract
description: Extract data as validated JSON
steps:
  # Step 1: AI extracts data
  - type: prompt
    prompt: "Extract {fields} as JSON from: {input}"
    provider: opencode-deepseek
    output_var: raw_json

  # Step 2: Code validates JSON
  - type: code
    code: |
      import json
      try:
          parsed = json.loads(raw_json)
          validated = json.dumps(parsed, indent=2)
      except:
          validated = "ERROR: Invalid JSON"      
    output_var: validated
output: "{validated}"

Variables

Variable	Description
{input}	The piped/file input
{argname}	Custom argument value
{step_output}	Output from previous step

Shell Integration

Git Hooks

# .git/hooks/prepare-commit-msg
#!/bin/bash
git diff --cached | commit-msg > "$1"

Aliases

# ~/.bashrc
alias gc='git diff --staged | commit-msg'
alias wtf='explain-error'
alias fixme='fix-grammar'

Vim Integration

" Fix grammar in selection
vnoremap <leader>fg :!fix-grammar<CR>

" Explain selected code
vnoremap <leader>ec :!explain-code<CR>

UI Navigation

Action	Keys
Cycle sections	Tab
Go back	Escape
Select	Enter or click
Navigate	Arrow keys
Select text	Shift + mouse drag
Copy	Terminal native (with Shift)
Paste	Ctrl+Shift+V

Tip: Hold Shift while using mouse for terminal-native text selection.

Philosophy

SmartTools is a personal power tool:

• You own your tools - YAML files you can read, edit, share
• You choose the AI - Any provider, swap anytime
• You accept responsibility - No sandboxing, like any script you write
• Unix philosophy - Small tools that compose

Contributing

git clone https://github.com/yourusername/smarttools.git
cd smarttools
pip install -e ".[dev]"
pytest

Support

If SmartTools saves you time, consider:

• GitHub Sponsors
• Buy Me a Coffee

License

MIT - Use it, modify it, share it.

Links

• Installation Guide
• Provider Setup
• Example Tools
• Design Document