aiforcecli-chat

Version: 0.1.5

License: Proprietary / UNLICENSED. See License.MD. Access through npm does not grant open-source rights.

One CLI over multiple coding agents, with routing, verification, racing, local learning, persistent cross-agent chat, local models, FinOps savings, and cost controls.

aiforcecli-chat does not reimplement an agent or host models. It shells out to the agent CLIs you already have installed and authenticated, normalizes their output, records cost/outcomes locally, and uses your repo's tests as the objective signal for choosing what to trust.

Current Product Snapshot

aiforcecli-chat is now a command center for coding agents. It can route work across Claude Code, Codex, Aider, Antigravity/Gemini, and AIForce Local; preserve task continuity across agent handoffs; run verified/self-healing workflows; optimize spend with cheap-first and FinOps mode; and present a cleaner terminal UI with route, handoff, result, and savings cards.

Recent capabilities now available in the CLI:

| Capability | What it does | Developer benefit | Business benefit | | --- | --- | --- | --- | | Persistent routed chat | Starts an interactive session where each turn can auto-route or pin to a specific agent/model. | Work naturally in a conversation instead of restarting commands. | Standardizes agent use without forcing one vendor. | | Cross-agent task continuity | Resolves follow-ups like "do it again", "make it better", or "now use Claude" against the active task, carries handoff context, and shows the handoff details. | Switch agents without losing task intent or file context. | Demonstrates horizontal orchestration that single-agent CLIs cannot provide. | | FinOps mode | --finops and /finops on optimize the prompt pack and show estimated token/cost savings by technique. | Reduce noisy context and understand why a turn cost less. | Gives CXOs and FinOps teams a visible savings narrative. | | Cheap-first routing | --cheap-first, --no-cheap-first, and /cheap-first on|off bias light/docs/general tasks to tier-1 models first. | Small tasks avoid expensive default models. | Direct cost reduction with escalation available through heal/routing. | | Visual terminal cards | Route, Agent, Handoff, Result, and FinOps cards summarize what happened in aligned fields. | Less wall-of-text; faster scan of task, model, cost, changed files, and quality. | Makes demos and governance reporting easier to understand. | | Changed-file summaries | Result output summarizes changed files instead of dumping every file path. | Cleaner end-of-run review. | Better executive readability in demos and logs. | | Session summaries and report export | /summary and /summary today summarize work across the current session or all sessions today; /export-summary md|doc creates shareable reports. | Avoid scrolling through long transcripts; create handoff/status notes quickly. | Gives managers and stakeholders clean daily work, cost, risk, and audit reports. | | AIForce Local integration | Routes to local Ollama-backed coding models through aiforce-local; supports repository tools, approvals, and sessions where model/tool support allows. | Use local/open-source models for suitable coding work. | Scales to lower-cost and private/local model execution. | | Replay cache | Offers reuse for identical successful tasks against the same repo state. | Avoid repeat spending on duplicate asks. | Shows direct avoided cost for repeated workflows. | | Longer inactivity behavior | Default inactivity timeout is now 5 minutes, with wait labels/spinner instead of aggressive abort warnings. | Claude Code and slower local runs get time to produce useful output. | Fewer false failures in demos and enterprise machines. |

What It Wraps

Built-in adapters:

| Agent id | CLI | What it supports | | --- | --- | --- | | claude-code | claude | Claude Code via -p --output-format stream-json; parses usage/cost from the CLI; supports session resume. | | codex | codex | OpenAI Codex via codex exec --json; parses JSONL events; computes cost from token usage; supports thread resume. | | aider | aider | Aider one-shot mode; model-agnostic through Aider's --model; parses Aider's token/cost summary when present. | | antigravity | agy | Google's Antigravity/Gemini CLI through agy -p; runs under a pseudo-terminal because output is TUI-oriented; no token/cost reporting from the CLI. | | aiforce-local | aiforce-local | Local DeepSeek, GLM, Qwen, or exact Ollama tags through the standalone coding agent; supports repository tools, command approvals, JSONL events, and session resume. |

Each adapter implements the same contract: detect whether the CLI exists, run a prompt in a working directory, stream normalized events, and optionally resume an existing session.

Why Use It

The product is built around a simple workflow:

1. Use advise before spending money to choose an agent/model.
2. Use run --heal when you want one agent to fix, verify, retry, and escalate.
3. Use race when quality matters: run multiple agents in isolated git worktrees, verify each result, and apply the passing winner.
4. Use pr when you want a complete branch -> verify -> commit -> push -> GitHub pull request workflow.
5. Use bench and eval to learn which agent/model actually works on your repo.
6. Use cost and budgets to avoid bill shock.

The strongest differentiator is that aiforcecli-chat is horizontal: it compares and governs several coding agents instead of locking you into one.

Quickstart

Install the wrapper:

npm install -g aiforcecli-chat

Install at least one underlying agent CLI:

npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
python -m pip install aider-chat
npm install -g aiforcecli-local

Antigravity uses Google's agy binary; install and authenticate it through Google's current Antigravity distribution.

aiforce-local requires Ollama and a downloaded local model. After installing the standalone package:

aiforce-local doctor
aiforce-local pull glm

Check what is available:

aiforcecli-chat agents
aiforcecli-chat models

Scaffold project config:

cd my-project
aiforcecli-chat init

Run a task:

aiforcecli-chat run "add a health check endpoint and a test for it"

Run through the local Ollama-backed coding agent:

aiforcecli-chat run "fix the parser test" --agent aiforce-local --model glm

In interactive chat, command approvals from the nested local agent are forwarded to the same terminal:

aiforcecli-chat chat
> inspect README.md --agent aiforce-local --model glm

Run a verified healing loop:

aiforcecli-chat run "fix the failing auth test" --heal --verify "npm test"

Race multiple agents:

aiforcecli-chat race "fix the failing tests" --agents claude-code,codex --verify "npm test" --select cheapest

Create a tested GitHub pull request:

aiforcecli-chat pr "add input validation to the signup form" --agent codex --model gpt-5.4-mini --heal

See spend:

aiforcecli-chat cost

Commands

| Command | Summary | | --- | --- | | aiforcecli-chat run "<task>" | Run a coding task. Without --agent, auto-routes to an agent/model. Supports --agent, --model, --cwd, --budget, --resume, --explain, --json, --heal, --max-attempts, --verify, --skip-verify, --route deterministic|bayesian, --explore, and --no-explore. | | aiforcecli-chat advise "<task>" | Recommend an agent/model without running an agent. Supports --cwd, --budget, --explore, and --json. | | aiforcecli-chat scorecard update | Manually fetch public benchmark leaderboards and generate local public-prior scorecard artifacts. | | aiforcecli-chat pr "<task>" | Run a task on a new branch, verify it, commit, push, and open a GitHub pull request. Supports --agent, --model, --cwd, --budget, --branch, --base, --title, --body, --commit-message, --remote, --draft, --no-push, --no-pr, --allow-dirty, --heal, --max-attempts, --verify, --skip-verify, --route, --explore, and --no-explore. | | aiforcecli-chat race "<task>" | Run several agents in parallel in isolated git worktrees, verify each, and apply the winner. Supports --agents, --cwd, --budget, --select cheapest|fastest|first-pass, --verify, --keep, and --json. | | aiforcecli-chat eval | Run private eval cases against installed agent/model targets to calibrate advise. Supports --cwd, --dir, --agents, and --json. | | aiforcecli-chat bench | Local leaderboard from recorded outcomes. Supports --since, --by-task, --clean, and --json. | | aiforcecli-chat models | Show the built-in plus config-added model catalog, tiers, prices, install status, and routing.only allow-list status. Supports --json. | | aiforcecli-chat agents | Show agent install status. Supports --enable <id>, --disable <id>, and --json. | | aiforcecli-chat cost | Report spend by day, agent, or project. Supports --since, --by day|agent|project, and --json. | | aiforcecli-chat init | Write aiforcecli.config.json and install bundled assets. Supports --cwd and --force. | | aiforcecli-chat mcp | Command is reserved for Phase 3. In 0.1.0 it is a stub and exits with a not-implemented message. |

Public Prior Scorecard

Bayesian advise, run --route bayesian, chat auto-routing, and pr --route bayesian use the generated public-prior scorecard by default. Refresh it manually:

aiforcecli-chat scorecard update

The generated scorecard is stored under the installed package at tools/scorecard/generated/scorecard/scorecard.json. If it is unavailable, routing falls back to the bundled static scorecard.

Architecture

CLI
  commands: run, advise, pr, race, eval, bench, models, agents, cost, init, mcp
  adapters: claude-code, codex, aider, antigravity, aiforce-local
  routing: catalog, classifier, deterministic router
  advise: task analysis, public scorecard, private stats, scorer, bandit policy
  core: orchestrator, subprocess runner, worktree isolation, race, heal
  verify: test command detection and execution
  finops: SQLite usage store, budgets, pricing, telemetry

Adapters normalize native agent output into this event shape:

type NormalizedEvent =
  | { type: 'token'; text: string }
  | { type: 'message'; role: 'assistant' | 'user'; text: string }
  | { type: 'tool_call'; name: string; input?: unknown; id?: string }
  | { type: 'command_output'; stream: 'stdout' | 'stderr'; text: string }
  | { type: 'usage'; usage: Usage; cumulative: boolean }
  | { type: 'error'; message: string; fatal: boolean };

A finished run resolves to message, usage, exit code, optional session/thread id, and abort metadata.

Model Catalog

aiforcecli-chat models displays the catalog used for routing estimates and recommendations.

Built-in catalog:

| Key | Agent | Model | Tier | $IN / 1M | $OUT / 1M | | --- | --- | --- | --- | ---: | ---: | | claude-haiku | claude-code | claude-haiku-4-5 | light | 1.00 | 5.00 | | claude-sonnet | claude-code | sonnet | standard | 2.00 | 10.00 | | claude-opus | claude-code | opus | heavy | 5.00 | 25.00 | | claude-fable | claude-code | fable | heavy | 10.00 | 50.00 | | claude-haiku-4.5 | claude-code | claude-haiku-4-5 | light | 1.00 | 5.00 | | claude-sonnet-5 | claude-code | claude-sonnet-5 | standard | 2.00 | 10.00 | | claude-opus-4.8 | claude-code | claude-opus-4-8 | heavy | 5.00 | 25.00 | | claude-fable-5 | claude-code | claude-fable-5 | heavy | 10.00 | 50.00 | | codex-gpt-5.4-mini | codex | gpt-5.4-mini | light | 0.75 | 4.50 | | codex-gpt-5.6-luna | codex | gpt-5.6-luna | light | 1.00 | 6.00 | | codex-gpt-5.4 | codex | gpt-5.4 | standard | 2.50 | 15.00 | | codex-gpt-5.6-terra | codex | gpt-5.6-terra | standard | 2.50 | 15.00 | | codex-gpt-5.5 | codex | gpt-5.5 | heavy | 5.00 | 30.00 | | codex-gpt-5.6-sol | codex | gpt-5.6-sol | heavy | 5.00 | 30.00 | | aider-deepseek | aider | deepseek | standard | 0.27 | 1.10 | | aider-codestral | aider | codestral/codestral-latest | standard | 0.30 | 0.90 | | gemini-3-flash | antigravity | gemini-3-flash | light | 0.50 | 3.00 | | gemini-3.5-flash | antigravity | gemini-3.5-flash | standard | 1.50 | 9.00 | | gemini-3.1-pro | antigravity | gemini-3.1-pro | heavy | 2.00 | 12.00 | | local-qwen | aiforce-local | qwen | light | 0.00 | 0.00 | | local-glm | aiforce-local | glm | standard | 0.00 | 0.00 | | local-deepseek | aiforce-local | deepseek | standard | 0.00 | 0.00 | You can restrict routing with routing.only and add or override catalog entries with routing.models.

Example:

{
  "routing": {
    "only": ["claude-sonnet", "codex-gpt-5.4-mini"],
    "models": [
      {
        "key": "codex-mini",
        "agent": "codex",
        "model": "gpt-5.4-mini",
        "tier": 1,
        "price": { "input": 0.75, "output": 4.5 }
      }
    ]
  }
}

Prices are USD per 1M tokens and are used for estimates. Runtime cost uses the agent CLI's reported cost when available; otherwise it is computed from the local pricing table. The built-in Codex catalog is limited to models accepted by Codex CLI with a ChatGPT account; API-priced models such as GPT-5.4 nano/pro are not routed by default unless you add custom routing.models. Claude Sonnet 5 uses Anthropic's introductory pricing of $2 input / $10 output per 1M tokens through August 31, 2026; update routing.models if your provider/account is billed differently.

Claude Fable is exposed through Claude Code as --model fable and is treated as a heavy-tier option. Its estimate is $10 input / $50 output per 1M tokens. Codex GPT-5.6 Sol is also treated as heavy at $5 input / $30 output per 1M tokens. Reserve these models for harder refactors, architecture work, security-sensitive changes, and complex PRs rather than small edits.

Routing

When run is called without --agent, aiforcecli-chat routes the task.

Routing strategies:

| Strategy | Behavior | | --- | --- | | deterministic | Default. Classifies the prompt as light, standard, or heavy with keyword/length heuristics, estimates candidate costs, and picks the cheapest model that meets the desired tier within the effective budget. | | bayesian | Uses the same learned recommendation pipeline as advise: public priors plus private verified outcomes, with optional Thompson-sampling exploration. |

Effective budget is the tightest of:

• --budget
• budgets.maxCostPerRunUsd
• remaining dailyCapUsd
• remaining weeklyCapUsd
• remaining monthlyCapUsd

Explicit --agent always wins. Explicit --model overrides the routed or configured model.

Examples:

aiforcecli-chat run "fix a typo in the README"
aiforcecli-chat run "refactor the auth architecture" --budget 5 --explain
aiforcecli-chat run "fix the cache bug" --route bayesian --explore
aiforcecli-chat run "add validation" --agent codex --model gpt-5.4-mini
aiforcecli-chat pr "redesign the calculator architecture" --agent claude-code --model fable --branch fable-refactor --base dev-ai-base

Advise

advise is a no-run recommendation engine:

aiforcecli-chat advise "migrate auth from sessions to JWT" --budget 2

It produces:

• task type: bugfix, feature, refactor, test, docs, security, perf, or general
• complexity tier: light, standard, or heavy
• codebase scan: top languages and file count
• test detection
• budget headroom
• ranked agent/model recommendations
• confidence, expected cost, estimated capability, and reasons
• policy mix: how often each arm would be selected under Thompson sampling

Scoring:

capability = posterior(public prior, private pass/fail history)
score = wCapability * capability + wCost * costFit + wSpeed * speedFit

Defaults:

{
  "advise": {
    "weights": { "capability": 0.7, "cost": 0.2, "speed": 0.1 },
    "privatePseudocount": 5,
    "explore": false
  }
}

The public scorecard is a dated, curated prior. Your verified heal, race, and eval outcomes override it as data accumulates.

Race

race is the high-trust workflow:

aiforcecli-chat race "fix the failing checkout test" --agents claude-code,codex --verify "npm test" --select cheapest

What happens:

1. Finds the local git repo root from --cwd or the current directory.
2. Captures tracked and untracked dirty changes.
3. Creates one detached temp git worktree per agent.
4. Carries your current changes into each worktree and commits them as that worktree's base.
5. Runs each agent independently.
6. Runs the verify command in each worktree.
7. Selects a passing non-empty diff by cheapest, fastest, or first-pass.
8. Applies the winner's diff back to your real working tree.
9. Records outcome, cost, duration, task class/type, reward, and winner flag.

Requirements:

• The target directory must be inside a git repo.
• The repo must have at least one commit, because worktrees are created from HEAD.
• A verify command is strongly recommended. Without one, race cannot objectively pick a winner and only offers manual selection in an interactive terminal.

Budget behavior:

• --budget is the total race budget.
• It is split evenly across racers.

Model behavior:

• race --agents accepts agent ids, not per-agent model syntax.
• To race specific models, set agents.<id>.model in config.

Example:

{
  "agents": {
    "claude-code": { "model": "sonnet" },
    "codex": { "model": "gpt-5.4-mini" }
  }
}

Then:

aiforcecli-chat race "fix the discount bug" --agents claude-code,codex --verify "npm test"

Dependency links:

• node_modules is linked into worktrees automatically when present.
• Add other gitignored dependency/build directories with race.linkPaths, for example .venv, target, or vendor.
• Cleanup severs symlinks/junctions before removing worktrees to avoid deleting through dependency links.

PR Mode

pr is the one-command workflow for turning an AI task into a normal GitHub pull request:

aiforcecli-chat pr "fix the checkout timeout bug" --agent codex --model gpt-5.4 --heal

What happens:

1. Requires a clean git working tree by default so AI edits do not mix with existing local work.
2. Creates a new branch, or uses --branch <name>.
3. Runs the selected or routed agent on the task.
4. Runs final verification if a verify command is available.
5. Commits the change when verification passes.
6. Pushes the branch to the configured remote.
7. Opens a GitHub pull request with the GitHub CLI (gh).

Useful examples:

aiforcecli-chat pr "add a contact form" --branch ai-contact-form
aiforcecli-chat pr "fix the parser bug" --heal --verify "npm test"
aiforcecli-chat pr "update the About page copy" --no-push
aiforcecli-chat pr "prepare a docs-only change" --skip-verify --draft
aiforcecli-chat pr "push a branch but do not open a PR" --no-pr

Requirements:

• The target directory must be inside a git repo.
• Start from a clean working tree unless you intentionally pass --allow-dirty.
• gh must be installed and authenticated to open the PR automatically.
• If gh is unavailable, the branch is still pushed and the command prints the gh pr create command to run later.

Self-Healing Runs

run --heal turns a single agent run into a verify/fix/escalate loop:

aiforcecli-chat run "fix the failing parser test" --heal --verify "npm test"

Loop:

1. Run selected agent/model.
2. Run verify command.
3. If passed, stop.
4. If failed and the adapter supports resume, retry the same agent with the verify failure output.
5. If still failing and escalation is enabled, select a stronger untried catalog entry.
6. Stop on pass, budget breach, or heal.maxAttempts.

Config:

{
  "heal": {
    "enabled": false,
    "maxAttempts": 3,
    "escalate": true
  }
}

--heal edits the real working tree by design. Use race when you want isolated candidates.

Verification

Verification resolves in this order:

1. --verify "<cmd>"
2. verify.command in config
3. auto-detection, if verify.enabled is true

Auto-detected commands include:

• npm test, pnpm test, or yarn test when package.json has a test script
• pytest
• cargo test
• go test ./...
• bundle exec rake test
• mvn test
• gradle test

The verify command runs through a shell, has a timeout, returns pass/fail, and captures the tail of output for healing.

Eval And Bench

eval runs a private suite of representative cases against candidate agent/model pairs.

Case example:

{
  "prompt": "fix the off-by-one in parseRange",
  "verify": "npm test",
  "taskType": "bugfix"
}

Run:

aiforcecli-chat eval
aiforcecli-chat eval --agents claude-code,codex

Targets come from eval.models or all installed agents' catalog entries. Each trial runs in an isolated worktree and records outcomes for advise and bench.

bench shows local history:

aiforcecli-chat bench
aiforcecli-chat bench --by-task
aiforcecli-chat bench --since 7d
aiforcecli-chat bench --clean

--clean hides zero-signal rows such as typoed/retired model ids or unverified runs with no cost/pass/win signal.

Note: the current CLI command does not expose a project filter for bench; reports are from the local usage database.

FinOps And Budgets

Every recorded run stores:

• timestamp
• agent and model
• project path
• prompt hash
• input/output/cache tokens
• cost and cost source
• exit code and abort reason
• mode: run, heal, race, or eval
• outcome: pass, fail, or unknown
• duration
• task class/type
• race winner flag
• learning context, propensity, and reward when available

Cost source:

• Claude Code reports cost directly; that is trusted.
• Codex reports tokens; cost is computed from local prices.
• Aider cost is parsed from Aider's summary line when present.
• Antigravity currently reports no usage/cost in this integration, so recorded cost may be zero even though the underlying service may charge separately.

Budget controls:

{
  "budgets": {
    "maxCostPerRunUsd": 1.0,
    "dailyCapUsd": 10.0,
    "weeklyCapUsd": 50.0,
    "monthlyCapUsd": 150.0
  }
}

Window caps are checked before starting a run. Per-run caps are enforced during a run when usage events arrive. For agents that only report usage at the end, mid-run enforcement is best effort.

Cost reports:

aiforcecli-chat cost
aiforcecli-chat cost --since 24h
aiforcecli-chat cost --by agent
aiforcecli-chat cost --by project --json

Telemetry

Telemetry is opt-in and off by default.

When enabled with telemetry.enabled and telemetry.endpoint, it sends only coarse anonymized outcome fields:

• task class
• agent
• model
• outcome
• winner flag
• mode
• cost
• duration

It does not send prompts, prompt hashes, project paths, or output. Upload is fire-and-forget with a short timeout and never blocks a run.

In 0.1.0 telemetry is a primitive upload hook, not a hosted shared leaderboard.

Configuration

Config files are deep-merged:

1. user-level config
2. project-level aiforcecli.config.json or aiforcecli.config.ts
3. CLI flags

User-level paths:

| Platform | Path | | --- | --- | | Windows | %APPDATA%\aiforcecli\Config\aiforcecli.config.json | | macOS | ~/Library/Preferences/aiforcecli/aiforcecli.config.json | | Linux | ~/.config/aiforcecli/aiforcecli.config.json or $XDG_CONFIG_HOME |

Schema summary:

| Block | Keys | Purpose | | --- | --- | --- | | agents.<id> | enabled, model, bin, defaultFlags, allowedTools | Per-agent settings. enabled:false removes the agent from registry/routing/race/eval/listing. | | defaultAgent | string | Agent used when routing is disabled and no explicit agent is passed. | | routing | enabled, strategy, prefer, only, models | Auto-routing behavior and model catalog customization. | | verify | enabled, command, timeoutMs | Verification command resolution and timeout. | | heal | enabled, maxAttempts, escalate | Self-healing behavior. | | race | agents, select, keepWorktrees, linkPaths | Race defaults, winner selection, worktree retention, dependency links. | | advise | weights, privatePseudocount, explore | Recommendation scoring and exploration. | | eval | dir, models | Private eval suite location and catalog target keys. | | telemetry | enabled, endpoint | Opt-in anonymized upload. | | budgets | maxCostPerRunUsd, dailyCapUsd, weeklyCapUsd, monthlyCapUsd | Cost caps. | | top-level | timeoutMs, inactivityTimeoutMs | Agent subprocess watchdogs. |

Enable or disable built-in agents globally:

aiforcecli-chat agents --disable antigravity
aiforcecli-chat agents --enable aider

These toggles write to the user-level config.

init

aiforcecli-chat init writes a project config and installs bundled assets when present:

• assets/skills -> .claude/skills
• assets/subagents -> .claude/agents
• assets/prompts -> .aiforcecli/prompts

Use --force to overwrite an existing project config:

aiforcecli-chat init --force

Known Limitations

• aiforcecli-chat mcp is not implemented in 0.1.0.
• race and eval require a git repo with a commit because they use git worktrees.
• Verification quality depends on the repo's tests/build command.
• Task classification is heuristic and keyword-based.
• The public scorecard is curated and dated, not live.
• New or custom models without scorecard rows start from a neutral prior until private evidence accumulates.
• pr needs the GitHub CLI (gh) installed and authenticated to open pull requests automatically.
• Some agent fatal errors can still look like no-change/no-usage outcomes in race or eval; inspect output and use --keep when debugging.
• Codex model availability can differ by account type; configure routing.only or agents.codex.model to match what your local Codex CLI accepts.
• Antigravity usage/cost is not reported by the CLI in this integration.
• aiforce-local currently reports no token totals, so API cost is recorded as zero and token usage as untracked. Local hardware and electricity still have a real cost.
• Agent detection confirms that aiforce-local and Ollama work, but catalog rows do not yet distinguish which individual Ollama models have been pulled. Pull the selected model before routing to it.
• Interactive local-agent command approvals are supported by run, chat, and other single-agent terminal flows. Parallel race participants can produce competing approval prompts, so use local agents in a race only for tasks that do not require nested shell commands.
• Mid-run budget enforcement is best effort for agents that only emit usage at the end.
• bench currently reports from the local global usage DB; there is no CLI --project filter yet.

Development

npm install
npm run build
npm run typecheck
npm test

Build:

• TypeScript is bundled with tsup.
• npm run build runs tsup and then scripts/obfuscate.mjs.
• npm run build:raw runs tsup only.

Tests cover:

• adapter parsers
• routing
• recommendation scoring
• bandit policy
• reward
• budget enforcement
• SQLite store
• verify detection
• worktree isolation
• self-healing policy
• race selection
• PR command helpers
• command helpers

Recorded fixtures live under test/fixtures.

Roadmap

Shipped in 0.1.0:

• adapters for Claude Code, Codex, Aider, Antigravity, and AIForce Local
• config loading/schema
• model catalog and models command
• deterministic and bayesian routing
• run, run --heal, pr, race, advise, eval, bench, cost, agents, init
• local SQLite usage/outcome store
• budgets and cost reporting
• opt-in telemetry hook
• worktree isolation for race/eval
• contextual-bandit recommendation policy and off-policy logging fields

Next:

• clearer fatal error surfacing in race and eval
• richer task classification
• Codex model compatibility auto-detection
• learned route/escalation policy from logged context/action/reward/propensity
• project-scoped bench filtering
• real MCP server with auth and budget-capped tools
• hosted or federated aggregate leaderboard

Latest Features In Detail

Persistent chat and cross-agent continuity

Start a persistent session with:

aiforcecli-chat chat

The chat session stores turns, cost, native agent session ids, summaries, and task-continuity state. A follow-up can move between agents while preserving the active task:

> build a html based calculator
> make this a lot better --agent codex
> now make it scientific --agent claude-code --model opus
> do the same with local qwen --agent aiforce-local --model qwen

When a handoff happens, the terminal shows a compact handoff card with the source agent, destination agent/model, resolved task, prior quality, and relevant files/context. This prevents the new agent from treating a follow-up as a fresh unrelated task.

Useful chat commands:

/agent <id|auto>       pin or unpin the session agent
/model <id|auto>       set or clear a model override
/route                 return to auto-routing
/advise <task>         recommend without running
/explain <task>        show route decision without spending
/heal [on|off]         toggle self-healing
/cheap-first [on|off]  prefer tier-1 models for light/docs/general tasks
/finops [on|off]       optimize prompt pack and show savings
/spinner <mode>        auto | unicode | ascii | off
/context               show task continuity memory
/resolve <task>        preview follow-up resolution
/handoff [task]        preview handoff packet for the next agent
/quality               show last-turn quality signal
/reset-context         clear task continuity memory
/race <task>           run race workflow from chat
/save [name]           save or rename the session
/sessions              list recent sessions
/resume <id|name>      resume another session
/history               show transcript
/exit                  leave chat

Session summaries and report export

Long CLI sessions can be summarized without scrolling through the full transcript:

/summary
/summary today
/summary session
/summary business
/summary technical
/summary handoff
/summary audit

Default behavior:

• /summary summarizes the current chat session.
• /summary today summarizes all sessions from today for the current project.
• Add --all-projects to include every project recorded in the local session store.

Summary styles:

| Style | Focus | | --- | --- | | business | outcome, value, risk, cost | | technical | files mentioned, tests/verification evidence, implementation details | | handoff | current state, open items, files, next step | | audit | who/what/when/status/cost table |

Export the same report as a file:

/export-summary md
/export-summary md today business
/export-summary doc today audit

Markdown exports create .md files. Doc exports create Word-readable .doc files in the current project folder.

Slash commands must include the leading /. Typing summary today audit without / is treated as a normal agent task and can spend tokens; use /summary today audit for the local no-spend report.

FinOps mode: token and cost savings at the end of a run

Enable FinOps for one-shot runs:

aiforcecli-chat run "summarize this repository" --finops

Enable it for a chat session:

aiforcecli-chat chat --finops
# or inside chat
/finops on

When enabled, aiforcecli builds an optimized agent prompt pack and prints a FinOps card after the normal result:

OK FinOps
  status  enabled
  saved   ~8,420 tokens / ~$0.0312
  input   12,300 -> 6,700 input tokens
  actual  $0.0184 actual
  by      Compressed context/tool output: ~2,100; Repo map and scoped retrieval: ~3,600; Cache-aligned prompt layout: ~900; Local deterministic preprocessing: ~1,200; Compact artifact output: ~620

The savings are estimates from local token estimation and model pricing. They are designed for decision support and FinOps reporting; provider invoices remain the billing source of truth.

Phase-1 FinOps techniques:

1. Compressed context/tool output: deduplicates and truncates injected prior context before sending it to the agent.
2. Repo map and scoped retrieval: gives the agent a bounded repo context pack so it can inspect targeted files instead of broadly exploring.
3. Cache-aligned prompt layout: keeps stable guidance and repo context before dynamic task content where provider caching can benefit repeated runs.
4. Local deterministic preprocessing: ranks files and summarizes repository shape locally before invoking the paid model.
5. Compact artifact output: instructs agents to avoid full-file dumps and return changed/verified/notes summaries.

Cheap-first routing

Cheap-first is separate from FinOps. FinOps reduces the prompt/token footprint; cheap-first changes the first model choice for suitable tasks.

aiforcecli-chat run "write a short README summary" --route bayesian --cheap-first
aiforcecli-chat chat
/cheap-first on

Cheap-first is intended for light, docs, and general Q&A tasks. It biases toward tier-1/low-cost arms such as local Qwen or smaller Codex entries when available. For heavier tasks, routing can still choose stronger models.

Visual terminal output

Human output is now organized into cards:

-> Route
  task   build a calculator
  agent  codex / gpt-5.4
  why    codex - gpt-5.4 (bayesian, ~$0.0375 est)
  mode   bayesian
  cost   ~$0.0375 est

-> Handoff
  handoff        aiforce-local -> codex
  task           build a html based calculator
  prior quality  failed
  context        calculator.html

OK Result
  status   completed
  agent    codex / gpt-5.4
  changed  1 file: calculator.html
  quality  good
  cost     $0.0184
  tokens   in 21043 / out 1224 / cache 9984

This is meant to be readable for developers and business users: route, cost, result, changes, quality, and savings are visible without scanning a long transcript.

AIForce Local and open-source model scale-out

aiforce-local lets aiforcecli route coding work to local Ollama-backed models when they support repository tools. This is useful for:

• low-cost/light coding work
• private or air-gapped experimentation
• cheap-first tier-1 tasks
• local model benchmarking through the same interface
• future team policies that route sensitive work to local models first

Example:

aiforcecli-chat run "summarize this app" --agent aiforce-local --model qwen

For aiforce-local, handoff context is sanitized to repo-relative file paths so local tools do not receive Windows absolute path fragments that they cannot resolve.