3.6 KiB

Raw Blame History

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

Prompt Step: Calls AI provider with template, stores result in output_var
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.

Web UI & Registry

SmartTools includes a web interface and tool registry:

Web Modules (`src/smarttools/web/`)

app.py: Flask app factory, registers blueprints
routes.py: Main web routes (docs, tutorials, tools, etc.)
forum/: Community forum blueprint
- models.py: Forum database schema (categories, topics, replies)
- routes.py: Forum routes (/forum, /forum/c/, /forum/t/)
filters.py: Jinja2 filters (timeago, markdown, etc.)
docs_content.py: Documentation and tutorial content

Registry Modules (`src/smarttools/registry/`)

app.py: Registry API (tool publishing, search, downloads)
db.py: SQLite schema and queries

Key URLs

/forum - Community forum
/docs - Documentation
/tutorials - Tutorial guides
/tools - Tool registry browser

Running the Web UI

# Development
python -m smarttools.web.app

# Production (example)
SMARTTOOLS_REGISTRY_DB=/path/to/db PORT=5050 python -m smarttools.web.app

3.6 KiB Raw Blame History