Add Home
commit
285fbe0f97
|
|
@ -0,0 +1,353 @@
|
|||
# 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.*
|
||||
Loading…
Reference in New Issue