4.1 KiB

Raw Permalink Blame History

CmdForge

Turn useful AI workflows into commands you own.

CmdForge is a personal tool-building environment for the command line. A tool can combine prompts, Python, other CmdForge tools, and Model Context Protocol (MCP) calls, then behave like an ordinary Unix command:

cat meeting.txt | meeting-decisions
git diff --staged | review-change
cmdforge run classify-private --no-fallback --require-local

Tools are readable YAML, stored either in ~/.cmdforge/ for personal use or ./.cmdforge/ when they belong to a project. You choose the provider at build time or runtime: a local Ollama model, an installed coding CLI, or an OpenAI-compatible API.

Install

CmdForge requires Python 3.10 or newer. pipx is recommended for a personal command-line application:

pipx install "cmdforge[mcp,pty]"

Or install it in a virtual environment:

python -m pip install "cmdforge[mcp,pty]"

The base cmdforge package includes the CLI and desktop tool builder. The mcp extra adds MCP client/server support, while pty adds interactive CLI providers.

Verify the installation and discover providers already present on the machine:

cmdforge --version
cmdforge providers discover
cmdforge providers discover --add

Begin with One Useful Command

cmdforge create explain --prompt "Explain this clearly for a beginner: {input}"
echo "def area(r): return 3.14159 * r * r" | cmdforge run explain

Use the deterministic mock provider while developing:

echo "sample input" | cmdforge run explain --provider mock
cmdforge inspect explain

For AI-assisted creation, install CmdForge's official forge-tool:

cmdforge registry install official/forge-tool

echo "Create a tool that extracts decisions and owners from meeting notes" \
  | forge-tool --name meeting-decisions --project

Four Kinds of Step

Prompt steps call a selected AI provider.
Code steps perform deterministic Python transformations.
Tool steps compose existing CmdForge tools and delegated contexts.
MCP steps call tools exposed by external MCP servers.

Contracts, deterministic preflight, regression baselines, schema compatibility, and evidence-based quality scores help distinguish “worked once” from a tool you can maintain.

Use CmdForge from Coding Agents

CmdForge can act as an MCP server for Codex and Claude Code. It is closed by default: configuring a host does not expose any tools until you add an explicit allowlist to ~/.cmdforge/mcp.yaml.

cmdforge mcp configure codex --dry-run
cmdforge mcp configure codex

cmdforge mcp configure claude-code --scope project --dry-run

Agents can also discover the local and remote catalogs without reading prompt or code bodies:

cmdforge list --json --filter "commit message" --limit 10
cmdforge registry search "release notes" --json --limit 5
git diff | cmdforge run-once "Summarize this change: {input}"

Privacy and Provenance

Fallback is a data-movement decision. Sensitive callers can require a local provider, particular capabilities, and verified runtime identity:

cmdforge run incident-summary \
  --provider local-reasoner \
  --no-fallback \
  --require-local \
  --require-capability structured-json \
  --data-classification private \
  --require-model-identity \
  --result-envelope json

The result envelope reports the requested provider, actual provider, attempted fallback chain, model, digest, and locality. Those fields are produced by CmdForge rather than invented by the model.

Learn More

CmdForge is beta software, distributed under the MIT License. Review generated tools and third-party registry tools as you would any other executable code.

4.1 KiB Raw Permalink Blame History