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

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

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.

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 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://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.

Links

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