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://gitea.brrd.tech/rob/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

Composing Tools

SmartTools follows Unix philosophy: each tool does one thing well, and tools chain together for complex workflows.

# Chain SmartTools together
cat error.log | log-errors | summarize | translate --lang Spanish

# Code review pipeline: focus on changes, review, then summarize
git diff | diff-focus | review-code | tldr

# Extract data, convert format, analyze
cat report.pdf | json-extract --fields "revenue, costs, date" | json2csv | csv-insights

# Process text through multiple transformations
cat technical_doc.txt | simplify | fix-grammar | tone-shift --tone friendly

# Generate code, validate it, then explain what it does
echo "parse CSV and calculate averages" | code-validate | explain-code

Mix with standard Unix tools:

# Extract emails, deduplicate, count
cat inbox.txt | extract-emails | sort -u | wc -l

# Find errors in multiple logs, explain them
cat *.log | grep -i error | explain-error

# Generate changelog for specific author
git log --author="rob" --oneline | changelog > CHANGELOG.md

# Review only large files in a commit
git diff --stat | awk '$3 > 100 {print $1}' | xargs cat | review-code

Build shell functions for common pipelines:

# ~/.bashrc
quick-review() {
    git diff "$@" | diff-focus | review-code --focus "bugs and security" | tldr
}

translate-doc() {
    cat "$1" | summarize | translate --lang "$2"
}

# Usage: quick-review HEAD~3
# Usage: translate-doc manual.txt French

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://gitea.brrd.tech/rob/smarttools/raw/branch/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
category: Text  # Optional: Text, Developer, Data, or Other
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}"

Categories

Tools can be organized into categories for easier navigation in the UI:

Category	Description
Text	Text processing (summarize, translate, grammar)
Developer	Dev tools (explain-error, gen-tests, commit-msg)
Data	Data extraction and conversion (json-extract, csv)
Other	Default for uncategorized tools

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
Scroll content	Mouse wheel
Scroll up	Click top of scrollbar
Scroll down	Click bottom of scrollbar
Page up/down	Click middle of scrollbar
Select text	Shift + mouse drag
Copy	Terminal native (with Shift)
Paste	Ctrl+Shift+V
Undo (code editor)	Alt+U
Redo (code editor)	Alt+R

Tips:

• Hold Shift while using mouse for terminal-native text selection.
• Code/Prompt editors have DOS-style scrollbars with ▲ and ▼ arrow buttons.
• In step dialogs, use Tab to cycle between File, Editor, and Output fields.
• The code editor supports undo/redo (up to 50 states) with Alt+U and Alt+R.
• Use the $EDITOR button to open code or prompts in your external editor.

AI-Assisted Code Generation

When adding or editing a Code Step, the dialog includes an AI assist panel:

┌─ Code ─────────────┐ ┌─ AI Assisted Auto-adjust ─────────────┐
│ result = input...  │ │ Provider: [opencode-deepseek] [▼]    │
│                    │ │ ┌─ Prompt ──────────────────────────┐ │
│                    │ │ │ Modify this code to...           │ │
│                    │ │ │ {code}                           │ │
│                    │ │ └──────────────────────────────────┘ │
│                    │ │ ┌─ Output & Feedback ───────────────┐ │
│                    │ │ │ ✓ Code updated successfully!     │ │
│                    │ │ └──────────────────────────────────┘ │
│                    │ │         < Auto-adjust >              │
└────────────────────┘ └───────────────────────────────────────┘

• Provider: Select any configured AI provider
• Prompt: Fully editable template - use {code} placeholder for current code
• Output: Shows status, success/error messages, and provider feedback
• Auto-adjust: Sends prompt to AI and replaces code with response

This lets you generate or modify Python code using AI directly within the tool builder.

Philosophy

SmartTools is built on Unix philosophy:

1. Do one thing well - Each tool solves one problem. summarize summarizes. translate translates. No bloated mega-tools.

2. Compose freely - Tools read stdin, write stdout. Chain them: cat doc.txt | summarize | translate --lang French

3. Text is the interface - No proprietary formats. Pipe text in, get text out. Works with grep, awk, sed, and every other Unix tool.

4. You own everything - Tools are YAML files. Prompts are plain text. No vendor lock-in, no cloud dependency for your tool definitions.

5. Swap parts freely - Change AI providers per-tool or per-run. Today's best model might not be tomorrow's.

Contributing

git clone https://gitea.brrd.tech/rob/smarttools.git
cd smarttools
pip install -e ".[dev]"
pytest

Support

If SmartTools saves you time, consider supporting the project:

Bitcoin: 3KeLqGv2Xo8jGYkqA1i68a6nXwgQnuJoza

Questions? robdickson444@hotmail.com

License

MIT - Use it, modify it, share it.

Docker

Run SmartTools without installing anything locally:

# Clone the repo
git clone https://gitea.brrd.tech/rob/SmartTools.git
cd SmartTools

# Build the container
docker-compose build

# Run tests
docker-compose run --rm test

# Use the CLI
docker-compose run --rm cli smarttools list

# Interactive shell
docker-compose run --rm shell

Links

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