term.ai

Smart shell for Ubuntu: a REPL that runs inside any terminal. Normal bash commands run directly (zero API calls); natural-language requests are recognized by a local ML classifier and translated into commands by an agent, with low-cost orchestration (cheap model by default, escalation to the mid-tier model, more powerful model only on explicit request).

Multi-provider: Anthropic (default), OpenAI, and a local provider (Ollama, LM Studio, or any server with an OpenAI-compatible endpoint), all behind the same interface. Adding a provider means a new file in termai/ai/providers/, not a change to the orchestration.

Provider	cheap (default)	mid (auto escalation)	powerful (explicit)
anthropic	claude-haiku-4-5 ($1/$5 MTok)	claude-sonnet-5 ($3/$15)	claude-opus-5 ($5/$25)
openai	gpt-5.6-luna ($1/$6)	gpt-5.6-terra ($2.50/$15)	gpt-5.6-sol ($5/$30)
local	configured local_model ($0)	same model ($0)	same model ($0)

Prices verified live (Anthropic Models API + developers.openai.com/api/docs/pricing, 2026-07-26) — see termai/ai/budget.py if they change.

The local provider has no real cost scale (usually a single model loaded on the local server), so every tier points at the same local_model: escalation in the agent loop becomes a no-op and the cost tracked in /usage is always $0.

Development use (inside the repo)

uv sync
uv run termai            # start the shell
uv run termai --auto     # start in auto mode (the agent runs without confirmation)
uv run termai --train    # retrain the classifier (includes ~/.bash_history)
uv run termai -c "..."   # run a single input and exit

Build and install as a global command

To use termai from any directory (not just inside the repo):

uv build                                       # generates dist/*.whl
uv tool install dist/termai-*.whl              # installs the command into ~/.local/bin
termai                                         # now available everywhere

To update after a change: uv build && uv tool install --force dist/termai-*.whl. To uninstall: uv tool uninstall termai.

Once installed as a package, credentials are no longer read from the repo's .env (you're no longer inside that directory) — copy .env.example to ~/.config/termai/.env and fill it in, or export the environment variables in your shell.

Inside the shell:

• normal commands → direct bash (ls -la, git status, …)
• natural language → the agent proposes the command (find .log files bigger than 10MB)
• !cmd forces bash
• #request or ai request → AI, default provider, cheap model
• ai! request → AI, default provider, powerful model
• claude request / gpt request / local request → forces the provider (cheap)
• claude! request / gpt! request / local! request → forces the provider (powerful)
• /provider anthropic|openai|local → shows/sets the default provider for the session
• /auto toggles auto mode · /usage shows costs · /help

Credentials

ANTHROPIC_API_KEY for Anthropic, OPENAI_API_KEY for OpenAI — you only need the one for the provider you use. They're read, in order:

1. from a .env file, searching upward from the directory where you launch termai (handy during development — e.g. the .env at the repo root);
2. from ~/.config/termai/.env (for use from any directory once installed as a package);
3. from environment variables already set (these always win: .env never overrides them).

Alternatively, for Anthropic: ant auth login profile.

The local provider needs no credentials: it points at an OpenAI-compatible server (default http://localhost:11434/v1, Ollama's standard port — for LM Studio it's typically http://localhost:1234/v1). Configure the endpoint and model in ~/.config/termai/config.toml:

provider = "local"
local_model = "llama3.1"
local_base_url = "http://localhost:11434/v1"

Cached input

Both providers leverage prompt caching to cut costs on repeated requests within a session:

• Anthropic: cache_control: {"type": "ephemeral"} on every call (fast path and agent loop). Below the model's minimum cacheable threshold nothing happens (no error, just cache_creation_input_tokens: 0) — today our system prompts are short and rarely exceed it on their own; the real benefit shows up in longer agent loops, where the accumulated conversation exceeds the threshold.
• OpenAI: caching is automatic server-side; on the gpt-5.6 family we set prompt_cache_key for more reliable matching. Both the cache read (cached_tokens) and the write (cache_write_tokens, billed separately just like on Anthropic) are read from usage.prompt_tokens_details and tracked in /usage.

Both providers, for the models in use, bill cache reads at ~0.1× the input price and writes at ~1.25× — same ratio, verified for both.

Config: ~/.config/termai/config.toml (see termai/config.py for the available keys, including provider and the model names/tiers).

License

MIT — see LICENSE.