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

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:

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)