smarttools/wiki/Home.md

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

```bash
# 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**:

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

---

## Quick Start Options

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

```bash
# 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

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

```bash
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:

```bash
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`:

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

```yaml
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:

```bash
# 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:

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

---

## Troubleshooting

### "Command 'X' not found"

The AI CLI isn't installed:

```bash
smarttools providers install
# Select the provider and follow instructions
```

### "Model 'X' is not available"

The model isn't connected in your provider:

```bash
# 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

1. Check the provider is configured: `smarttools providers check`
2. Test the provider directly: `smarttools providers test opencode-pickle`
3. 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`:

```bash
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:

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

### Vim Integration

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

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

### Pipeline Examples

```bash
# 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
```

---

## Links

- **Repository**: https://gitea.brrd.tech/rob/SmartTools
- **Docker Image**: `gitea.brrd.tech/rob/smarttools:latest`
- **Issues**: https://gitea.brrd.tech/rob/SmartTools/issues

---

*SmartTools is MIT licensed. Use it, modify it, share it.*