Use farness with Codex, Claude Code, or the local CLI.
The install story is package-first. The PyPI package now includes the CLI, MCP server, and packaged Codex and Claude skills. The CLI itself is local-only and does not call an LLM or require an API key.
Best path if you want native tools, persistent decisions, and the `$farness` trigger.
Use this if you want a decision log and calibration loop without any agent integration.
Use the plugin if you want the slash-command flow and Claude-specific integration.
Install the package and choose a path
1. Codex with MCP
This gives Codex native tools, access to stored decisions, and a reusable `$farness` skill.
python -m pip install 'farness[mcp]' farness setup codex # restart Codex, then use $farness
2. Claude Code local skill
This gives Claude Code the same local MCP-backed workflow as Codex, but through Claude skills instead of the Codex skill format.
python -m pip install 'farness[mcp]' farness setup claude # restart Claude Code
3. Local CLI / Python
This path creates and scores decisions locally. No LLM API key is required for these commands.
python -m pip install farness farness new "Should we rewrite the auth layer?" farness list farness calibration
If you prefer the older plugin flow instead of local Claude skills, it still works:
claude plugin marketplace add MaxGhenis/farness claude plugin install farness@maxghenis-plugins # then use /farness:decide
What each piece actually does
Creates, lists, reviews, and scores decisions in ~/.farness/decisions.jsonl.
Exposes the same decision store as native tools, resources, and prompts for agent clients.
Tells Codex when to use the MCP tools and what the farness workflow should produce.
Tells Claude Code when to use the same local MCP server. The older plugin path stays optional.
Two commands, then restart the client
python -m pip install 'farness[mcp]' farness setup codex
python -m pip install 'farness[mcp]' farness setup claude
`farness setup` installs the packaged skill and registers the local MCP server with the same Python interpreter that launched `farness`. The last step is just restarting Codex or Claude Code.
farness doctor codex
farness doctor claude
`farness doctor` checks three things: whether the packaged skill is installed, whether the agent CLI is on `PATH`, and whether the local MCP server is already registered.
See the packaged flow before you install
This is the actual package-first Codex path from the docs: install, run setup, use $farness in Codex, then confirm the decision landed in the local store.
python -m pip install 'farness[mcp]' farness setup codex farness doctor codex
Rendered from a real Codex session using the local farness skill and MCP server, then exported as a clean 4K terminal demo.
Fix drifted installs or reset cleanly
Repair in place
If the skill file drifted, the agent CLI moved, or MCP setup only half-worked, let `doctor` repair what it can.
farness doctor codex --fix farness doctor claude --fix
Reset from scratch
Remove the local skill and MCP registration, then run setup again.
farness uninstall codex farness setup codex farness uninstall claude farness setup claude
What to expect from the framework
The framework is not “ask an LLM for advice.” It is a structured decision workflow:
- Define the KPI and time horizon.
- Expand the option set beyond the initial framing.
- Anchor on a reference class or base rate.
- Show the mechanism or decomposition.
- Surface disconfirming evidence and traps.
- Give point estimates with 80% confidence intervals.
- Set a review date and score outcomes later.
Decision: Should we rewrite the auth layer now? KPI: critical_auth_incidents / 90d Options: rewrite now | defer 60d | harden existing system Base rate: 27% of similar infra rewrites produce >40% reliability gains Forecast (rewrite now): 58% [42, 71] Disconfirming evidence: ops fixes may solve this faster Review date: 2026-06-15
Three concrete ways to use it
Should we rewrite the auth layer now or harden the existing service first?
KPI: critical_auth_incidents / 90d Options: rewrite now | defer 60d | harden existing Forecast: rewrite now 58% [42, 71] Base rate: 27%
Should we launch the new onboarding flow this sprint or hold for one more iteration?
KPI: activated_users / signup cohort Options: ship now | hold 2 weeks | A/B limited rollout Forecast: limited rollout 64% [49, 77] Disconfirming evidence: sample size may be too small
Should we hire a generalist engineer now or wait for a more specialized infra candidate?
KPI: roadmap throughput / quarter Options: hire generalist | wait for specialist | contractor bridge Forecast: contractor bridge 51% [38, 63] Review date: 2026-09-01
What needs credentials
No model credentials required. The CLI reads and writes local decision records only.
No separate farness API key. Your agent client uses its own normal model credentials.
The experiment runners do call external models and need provider keys like `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
The common failure cases
Run `farness doctor codex` or `farness doctor claude`, then restart the client. Skills are loaded at startup.
Install the `codex` or `claude` CLI first, then rerun `farness doctor --fix` to register MCP with the right interpreter.
Use `farness uninstall codex` or `farness uninstall claude`, then rerun `farness setup ...` instead of editing config by hand.