134 lines
4.1 KiB
Markdown
134 lines
4.1 KiB
Markdown
# 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.
|