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

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

```bash
pipx install "cmdforge[mcp,pty]"
```

Or install it in a virtual environment:

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

```bash
cmdforge --version
cmdforge providers discover
cmdforge providers discover --add
```

## Begin with One Useful Command

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

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

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

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

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

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

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

- [Documentation](https://cmdforge.brrd.tech/docs)
- [MCP and coding agents](https://cmdforge.brrd.tech/docs/mcp-overview)
- [Providers and privacy policy](https://cmdforge.brrd.tech/docs/providers)
- [Contracts and quality evidence](https://cmdforge.brrd.tech/docs/contracts-quality)
- [Registry](https://cmdforge.brrd.tech/tools)
- [Source and issues](https://gitea.brrd.tech/rob/CmdForge)

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