flought

Flought is an AI coding engine: sprints, memory, and routing in one CLI.

Version 0.1.2. Node ^20.19.0 || >=22.12.0. 950 package tests (110 files, 4 skipped).

Cost-first provider failover: the same model id across Kilo, OpenRouter, direct APIs, and custom gateways uses the cheapest catalog route first, then fails over on credit / rate-limit / quota errors. Optional --provider pin tries that route first.

Coding-tool backends: flought setup lists Claude Code, Codex, Gemini CLI, Cursor Agent, plus HTTP gateways (OpenCode, Kilo, Command Code). Per tool: S = subscription, K = API key, B = both (subscription_then_api failover). Antigravity is listed and skipped (interactive IDE only). Kill-switch: FLOUGHT_CLI_BACKENDS=0.

Doctor: flought doctor probes configured backends (--version / --help for CLIs, /v1/models for HTTP). Failures warn with setup / env / install hints.

npx flought --help
npx flought sprint "Add cursor pagination to users endpoint" --dry-run --json

# Cheapest provider route for a model id (gateway discounts count)
npx flought sprint "Summarize module" --model deepseek/deepseek-v4-flash

# Pin OpenRouter first; failover to other routes if OpenRouter fails
npx flought sprint "Summarize module" --model deepseek/deepseek-v4-flash --provider openrouter

npm i -g flought
flought setup
flought doctor
flought sprint "Add pagination" --json > result.json

# npm 11+ may skip native install scripts (tree-sitter, onnx, sharp).
# If you saw `allow-scripts` warnings:
npm approve-scripts --allow-scripts-pending
# then allow the listed packages and reinstall: npm i -g flought

Set API keys via env (never committed):

OPENAI_API_KEY=sk-...        # OpenAI
ANTHROPIC_API_KEY=sk-ant-... # Claude
DEEPSEEK_API_KEY=sk-...      # DeepSeek
OPENROUTER_API_KEY=sk-or-... # OpenRouter (one route in the cost-sorted chain)
KILO_API_KEY=...             # Kilo gateway (often cheapest for duplicate model ids)

Optional flags:

FLOUGHT_NO_UPDATE_CHECK=1
FLOUGHT_EMBEDDING=onnx|api
FLOUGHT_SEMANTIC_CACHE=0          # exact+normalized chat() cache off
FLOUGHT_CONFIDENCE_CASCADE=0      # cheap verifier + one-step escalate off
FLOUGHT_BANDIT_PICKBEST=0         # Judge pickBest UCB overlay off
FLOUGHT_CLI_BACKENDS=0            # coding-tool CLI/HTTP extra routes off

HeuristicPreFilter (0 tokens) + Judge still run. Semantic cache never stores security-sensitive prompts, tool-call turns, or live web search. Streaming skips cache and cascade.

Persistent data lives in ~/.flought/ (config.json, memory.db, model-catalog.json, encrypted keys.json).

Built output is dist/ (ESM) — CLI entry bin/flought.mjs.

Adaptive / multi-provider routing docs: start at docs/ROUTING_INDEX.md (overview, decision tree, state/failover, modes). Operator dogfood: docs/ADAPTIVE_ROUTING.md. Default adaptiveRouting stays off. User how-to: USER-GUIDE.md in the source repo.