CmdForge/CLAUDE.md

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

# 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, collections
• tool.py: Tool definition dataclasses (Tool, ToolArgument, PromptStep, CodeStep), YAML config loading/saving, wrapper script generation
• collection.py: Collection management (Collection dataclass, resolve_tool_references(), classify_tool_reference()), local collection storage in ~/.cmdforge/collections/
• 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, Collections page, Providers management
  • dialogs/: Step editors, Argument editor, Provider dialog, Connect/Publish dialogs

Key Paths

• Tools storage: ~/.cmdforge/<toolname>/config.yaml
• Tool defaults: ~/.cmdforge/<toolname>/defaults.yaml (optional, published with tool)
• Tool settings: ~/.cmdforge/<toolname>/settings.yaml (user overrides, auto-created from defaults)
• Wrapper scripts: ~/.local/bin/<toolname> (auto-generated bash scripts)
• Provider config: ~/.cmdforge/providers.yaml
• Collections storage: ~/.cmdforge/collections/<name>.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
• {settings.key} - from tool's settings.yaml (top-level scalars only in templates)
• settings['key'] - full dict access in code steps

Variable substitution is handled in runner.py:substitute_variables(). Settings are loaded from settings.yaml if it exists, otherwise an empty dict is used.

Provider System

Providers are CLI tools that accept prompts via stdin and output to stdout. Defined in ~/.cmdforge/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

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/, /forum/t/)
• 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

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