# CLAUDE.md

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

## Project Overview

CmdForge 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

```bash
# 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 cmdforge.cli

# Launch the GUI
cmdforge
```

## Architecture

### Core Modules (`src/cmdforge/`)

- **cli/**: CLI commands entry points (`cmdforge` command). Routes subcommands: list, create, edit, delete, test, run, 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 `~/.cmdforge/providers.yaml`
- **gui/**: PySide6 desktop GUI
  - **main_window.py**: Main application window with sidebar navigation
  - **pages/**: Tools page, Tool Builder, Registry browser, Providers management
  - **dialogs/**: Step editors, Argument editor, Provider dialog, Connect/Publish dialogs

### Key Paths

- **Tools storage**: `~/.cmdforge/<toolname>/config.yaml`
- **Wrapper scripts**: `~/.local/bin/<toolname>` (auto-generated bash scripts)
- **Provider config**: `~/.cmdforge/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 `~/.cmdforge/providers.yaml`:

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

CmdForge includes a web interface and tool registry:

### Web Modules (`src/cmdforge/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/<slug>, /forum/t/<id>)
- **filters.py**: Jinja2 filters (timeago, markdown, etc.)
- **docs_content.py**: Documentation and tutorial content

### Registry Modules (`src/cmdforge/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

```bash
# Development
python -m cmdforge.web.app

# Production (example)
CMDFORGE_REGISTRY_DB=/path/to/db PORT=5050 python -m cmdforge.web.app
```

## Infrastructure Documentation

For deployment, server details, and operations, see the `docs/` folder:

- **docs/servers.md** - Server IPs (192.168.0.162), SSH access, paths, service commands
- **docs/deployment.md** - Architecture diagram, deploy process, systemd service config
- **docs/maintenance.md** - Backups, updates, troubleshooting
- **docs/architecture.md** - Module structure, data flow diagrams

### Production Server Quick Reference

| Property | Value |
|----------|-------|
| Server | 192.168.0.162 (OpenMediaVault) |
| SSH | `ssh rob@192.168.0.162` |
| App Path | `/srv/mergerfs/data_pool/home/rob/cmdforge-registry/` |
| Service | `systemctl --user status cmdforge-web` |
| Public URL | https://cmdforge.brrd.tech |
| Port | 5050 (via Cloudflare tunnel) |