Prepare CmdForge 0.2.0 for PyPI

2026-07-21 15:19:02 -03:00
parent ca6135ac72
commit 1e698996b2
12 changed files with 342 additions and 25 deletions
@@ -0,0 +1,133 @@
+# 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.