smarttools/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SmartTools is a lightweight personal tool builder for AI-powered CLI commands. It lets users create custom terminal commands that call AI providers, chain prompts with Python code steps, and use them like any Unix pipe command.

Development Commands

# Install for development
pip install -e ".[dev]"

# Run tests
pytest

# Run a single test
pytest tests/test.py::test_name

# Run the CLI
python -m smarttools.cli

# Launch the UI
smarttools ui

Architecture

Core Modules (src/smarttools/)

• cli.py: Entry point (smarttools command). Routes subcommands: list, create, edit, delete, test, run, ui, refresh
• tool.py: Tool definition dataclasses (Tool, ToolArgument, PromptStep, CodeStep), YAML config loading/saving, wrapper script generation
• runner.py: Execution engine. Runs tool steps sequentially, handles variable substitution ({input}, {varname}), executes Python code steps via exec()
• providers.py: Provider abstraction. Calls AI CLI tools via subprocess, reads provider configs from ~/.smarttools/providers.yaml
• ui.py: UI dispatcher - selects between urwid and snack implementations
• ui_urwid.py: Full TUI implementation using urwid library
• ui_snack.py: Fallback TUI using python-newt/snack

Key Paths

• Tools storage: ~/.smarttools/<toolname>/config.yaml
• Wrapper scripts: ~/.local/bin/<toolname> (auto-generated bash scripts)
• Provider config: ~/.smarttools/providers.yaml

Tool Structure

Tools are YAML configs with:

• name, description, category
• arguments: Custom flags with defaults (e.g., --max → {max})
• steps: Ordered list of prompt or code steps
• output: Template for final output (e.g., "{response}")

Step Types

1. Prompt Step: Calls AI provider with template, stores result in output_var
2. Code Step: Executes Python code via exec(), captures specified variables

Variable Flow

Variables are passed between steps:

• {input} - always available (stdin/file content)
• {argname} - from tool arguments
• {step_output_var} - from previous step's output_var

Variable substitution is simple string replacement in runner.py:substitute_variables().

Provider System

Providers are CLI tools that accept prompts via stdin and output to stdout. Defined in ~/.smarttools/providers.yaml:

providers:
  - name: claude
    command: "claude -p"
  - name: mock
    command: "echo '[MOCK]'"

The mock provider is built-in for testing without API calls.