117 lines
3.6 KiB
Markdown
117 lines
3.6 KiB
Markdown
# 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 UI
|
|
cmdforge ui
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Core Modules (`src/cmdforge/`)
|
|
|
|
- **cli.py**: Entry point (`cmdforge` 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 `~/.cmdforge/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**: `~/.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
|
|
```
|