9.2 KiB

Raw Blame History

SmartTools Wiki

Welcome to SmartTools - a lightweight personal tool builder for AI-powered CLI commands.

SmartTools lets you turn any AI model into a Unix-style pipe command. Build your own AI tools once, use them forever - no coding required.

What is SmartTools?

Think of SmartTools as a universal adapter between you and AI. Instead of opening a chat window and copy-pasting text, you create reusable command-line tools:

# Before: Copy text, open browser, paste into ChatGPT, wait, copy result
# After:
cat article.txt | summarize

# Before: Manually ask AI to fix grammar
# After:
echo "teh cat sat on teh mat" | fix-grammar
# Output: The cat sat on the mat.

# Chain tools together like any Unix command
cat report.txt | summarize | translate --lang Spanish

Core Philosophy

SmartTools follows the Unix philosophy:

Each tool does one thing well - summarize summarizes, translate translates
Tools are composable - Chain them with pipes: cat file | tool1 | tool2
Text is the interface - Works with grep, awk, sed, and every other Unix tool
You own everything - Tools are simple YAML files, no vendor lock-in

Quick Start Options

Option 1: Try It Now (60 seconds, no install)

# Pull the pre-built container
docker pull gitea.brrd.tech/rob/smarttools:latest

# Run it
docker run -it --rm gitea.brrd.tech/rob/smarttools bash

# Inside container - install OpenCode (includes FREE AI models)
smarttools providers install   # Select option 4, then 'y'
source ~/.bashrc

# Try a tool! Uses free Big Pickle model
cat README.md | eli5

Option 2: Native Install

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

Understanding Providers

SmartTools doesn't include any AI - it connects to AI providers. A provider is any CLI tool that reads text from stdin and outputs a response.

Available Providers

Provider	Models	Cost	Best For
OpenCode	75+ models	4 FREE, others paid	Best starting point
Claude	Haiku, Sonnet, Opus	Pay-per-use	High quality
Codex	GPT models	Pay-per-use	Reliable
Gemini	Flash, Pro	Free tier	Large documents (1M tokens)
Ollama	Llama, Mistral, etc.	FREE (local)	Privacy, offline use

Free Models in OpenCode

When you install OpenCode, these models are available immediately with no sign-up:

Big Pickle - High quality, used by eli5 and other tools by default
GLM-4.7 - Chinese AI lab model
Grok Code Fast 1 - Fast but less accurate
MiniMax M2.1 - Alternative free option

Installing a Provider

smarttools providers install

This interactive guide shows all options and runs the installation for you. After installing, run the provider once to authenticate (opens browser).

The 27 Built-in Tools

SmartTools comes with ready-to-use tools organized by category:

Text Processing

Tool	What it does	Example
`summarize`	Condense documents	`cat article.txt \| summarize`
`translate`	Translate to any language	`echo "Hello" \| translate --lang Spanish`
`fix-grammar`	Fix spelling and grammar	`cat draft.txt \| fix-grammar`
`simplify`	Rewrite for clarity	`cat legal.txt \| simplify --level "5th grade"`
`tone-shift`	Change writing 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	What it does	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	`git 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 messages	`git diff --staged \| commit-msg`

Data Tools

Tool	What it does	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`
`csv-insights`	Analyze CSV data	`cat sales.csv \| csv-insights --question "trends?"`

Multi-Step Tools

These tools combine AI prompts with code for validation:

Tool	Pattern	What it does
`log-errors`	Code→AI	Extract and explain errors from huge logs
`diff-focus`	Code→AI	Extract only added lines, then review
`changelog`	Code→AI→Code	Parse git log, generate changelog, format it
`code-validate`	AI→Code	Generate code, validate syntax

Creating Your Own Tools

Using the TUI

The easiest way to create tools:

smarttools ui

Navigate with arrow keys, create tools visually, edit prompts, test with mock provider.

Tool Anatomy (YAML)

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

name: my-tool
description: What this tool does
arguments:
  - flag: --style
    variable: style
    default: "casual"
steps:
  - type: prompt
    prompt: |
      Rewrite this in a {style} style:

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

Variables

Variable	Description
`{input}`	The piped/file input
`{argname}`	Value of `--argname` flag
`{previous_output}`	Output from previous step

Multi-Step Example

Chain AI with code for validated output:

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

  # Step 2: Python validates
  - type: code
    code: |
      import json
      try:
          parsed = json.loads(raw_json)
          result = json.dumps(parsed, indent=2)
      except:
          result = '{"error": "Invalid JSON"}'      
    output_var: result

output: "{result}"

Provider Selection Strategy

Choosing the Right Provider

Use Case	Recommended Provider
Quick tasks, free	`opencode-pickle`
Daily use, cheap	`opencode-deepseek`
High quality	`claude-haiku` or `claude-opus`
Large documents	`gemini` (1M token context)
Complex reasoning	`opencode-reasoner`
Offline/private	`ollama`

Override at Runtime

Any tool can use a different provider for a single run:

# Tool defaults to opencode-pickle, but use claude this time
cat important.txt | summarize --provider claude-opus

Change Tool Default

Edit the tool's config or use the TUI:

smarttools ui
# Select tool → Edit → Change provider in step

Troubleshooting

"Command 'X' not found"

The AI CLI isn't installed:

smarttools providers install
# Select the provider and follow instructions

"Model 'X' is not available"

The model isn't connected in your provider:

# For OpenCode models:
opencode
# Connect the required provider in the menu

# Or use a different model:
cat file.txt | tool --provider opencode-pickle

Tool returns empty output

Check the provider is configured: smarttools providers check
Test the provider directly: smarttools providers test opencode-pickle
Try a different provider: --provider opencode-pickle

Provider is slow

Use gemini-flash instead of gemini
Use claude-haiku instead of claude-opus
Use opencode-deepseek for best speed/quality ratio

Advanced Usage

Shell Integration

Add to ~/.bashrc:

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

# Aliases
alias wtf='explain-error'
alias fixme='fix-grammar'
alias gc='git diff --staged | commit-msg'

Git Hooks

Auto-generate commit messages:

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

Vim Integration

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

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

Pipeline Examples

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

# Translation pipeline: summarize then translate
cat article.txt | summarize | translate --lang Japanese

# Code review: only check large changes
git diff --stat | awk '$3 > 100 {print $1}' | xargs cat | review-code

9.2 KiB Raw Blame History