Tersa

Tersa is an open-source coding-agent CLI for cloud and local model providers.

Use OpenAI-compatible APIs, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat, and other supported backends while keeping one terminal-first workflow: prompts, tools, agents, MCP, slash commands, and streaming output.

Tersa is also mirrored to GitLawb: gitlawb.com/node/repos/z6MkqDnb/tersa

Quick Start | Setup Guides | Providers | Tester Builds | Comparison | Source Build | Sponsors | Community

Sponsors

Star History

Why Tersa

• Use one CLI across cloud APIs and local model backends
• Save provider profiles inside the app with /provider
• Run with OpenAI-compatible services, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat, and other supported providers
• Keep coding-agent workflows in one place: bash, file tools, grep, glob, agents, tasks, MCP, and web tools
• Measure Tersa vs Codex CLI with a reproducible local benchmark harness under research/

Quick Start

Install

npm install -g tersa-cli@latest
tersa

That is the normal setup path: Tersa ships token optimization defaults, bundled ripgrep fallback, and built-in RTK fallback rewrites. Use /provider inside the TUI to save a model/provider profile.

If the install later reports ripgrep not found, install ripgrep system-wide and confirm rg --version works in the same terminal before starting Tersa.

Verify / troubleshoot installed version:

tersa --version
npm view tersa-cli dist-tags
npm install -g tersa-cli@latest

Install from a tester tarball:

npm install -g ./tersa-cli-<version>.tgz
tersa

Start

tersa

Inside Tersa:

• run /provider for guided provider setup and saved profiles
• run /onboard-github for GitHub Models onboarding

Fastest OpenAI setup

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-your-key-here
export OPENAI_MODEL=gpt-4o

tersa

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_API_KEY="sk-your-key-here"
$env:OPENAI_MODEL="gpt-4o"

tersa

Fastest local Ollama setup

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b

tersa

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_BASE_URL="http://localhost:11434/v1"
$env:OPENAI_MODEL="qwen2.5-coder:7b"

tersa

Setup Guides

Beginner-friendly guides:

• Non-Technical Setup
• Windows Quick Start
• macOS / Linux Quick Start

Advanced and source-build guides:

• Advanced Setup
• Android Install
• Tester Builds

Supported Providers

| Provider | Setup Path | Notes | | --- | --- | --- | | Anthropic | tersa auth login, /provider, or env vars | Supports Anthropic account authentication and API-key configurations | | OpenAI-compatible | /provider or env vars | Works with OpenAI, OpenRouter, DeepSeek, Groq, Mistral, LM Studio, and other compatible /v1 servers | | Hicap | /provider or OpenAI-compatible env vars | Uses api-key auth, discovers models from unauthenticated /models, and supports Responses mode for gpt- models | | Gemini | /provider or env vars | Supports API key only | | GitHub Models | /onboard-github | Interactive onboarding with saved credentials | | Codex OAuth | /provider | Opens ChatGPT sign-in in your browser and stores Codex credentials securely | | Codex | /provider | Uses existing Codex CLI auth, Tersa secure storage, or env credentials | | Gitlawb Opengateway | Startup default, /provider, or env vars | Smart gateway at https://opengateway.gitlawb.com/v1; requires an API key from https://gitlawb.com/opengateway/keys and routes Xiaomi MiMo and GMI Cloud partner models by OPENAI_MODEL | | OpenCode Zen | /provider or env vars | Pay-as-you-go AI gateway (41 models); uses OPENCODE_API_KEY via https://opencode.ai/zen/v1; shared key with OpenCode Go | | OpenCode Go | /provider or env vars | $10/mo subscription for open models (12 models); uses OPENCODE_API_KEY via https://opencode.ai/zen/go/v1; shared key with OpenCode Zen | | Xiaomi MiMo | /provider or env vars | OpenAI-compatible API at https://mimo.mi.com; uses MIMO_API_KEY and defaults to mimo-v2.5-pro | | Ollama | /provider or env vars | Local inference with no API key | | Atomic Chat | /provider, env vars, or bun run dev:atomic-chat | Local Model Provider; auto-detects loaded models | | Bedrock / Vertex / Foundry | env vars | Anthropic-family cloud routes; Vertex is for Tersa on Vertex AI, not arbitrary Model Garden models |

What Works

• Tool-driven coding workflows: Bash, file read/write/edit, grep, glob, agents, tasks, MCP, and slash commands
• Streaming responses: Real-time token output and tool progress
• Tool calling: Multi-step tool loops with model calls, tool execution, and follow-up responses
• Images: URL and base64 image inputs for providers that support vision
• Provider profiles: Guided setup plus saved user-level provider profile support
• Local and remote model backends: Cloud APIs, local servers, and Apple Silicon local inference

Provider Notes

Tersa supports multiple providers, but behavior is not identical across all of them.

The release gate performs a live Codex OAuth reachability and lightweight generation check when stored credentials are available. Other provider routes are covered by contract and unit tests; real requests require credentials for those services and may incur provider charges.

• Anthropic-specific features may not exist on other providers
• Tool quality depends heavily on the selected model
• Smaller local models can struggle with long multi-step tool flows
• Some providers impose lower output caps than the CLI defaults, and Tersa adapts where possible
• Gitlawb Opengateway is the fresh-install startup default and requires an API key from https://gitlawb.com/opengateway/keys. It uses one OpenAI-compatible base URL; switch between mimo-* and google/gemini-3.1-flash-lite-preview with /model, and do not pin the base URL to /v1/xiaomi-mimo.
• Xiaomi MiMo uses api-key header auth on the direct OpenAI-compatible route and currently does not support /usage reporting in Tersa

For best results, use models with strong tool/function calling support.

Agent Routing

Tersa can route different agents to different models through settings-based routing. This is useful for cost optimization or splitting work by model strength.

Add to ~/.tersa.json:

{
  "agentModels": {
    "deepseek-v4-flash": {
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "sk-your-key"
    },
    "gpt-4o": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-key"
    }
  },
  "agentRouting": {
    "Explore": "deepseek-v4-flash",
    "Plan": "gpt-4o",
    "general-purpose": "gpt-4o",
    "frontend-dev": "deepseek-v4-flash",
    "default": "gpt-4o"
  }
}

When no routing match is found, the global provider remains the fallback.

You can also explicitly pass a model argument to the Agent tool that exactly matches a configured key in agentModels to override the provider for a single subagent request.

Note: /provider changes the global/parent provider for your current session. agentModels and agentRouting are specifically for configuring per-agent provider overrides while keeping the parent session unchanged.

Note: api_key values in settings.json are stored in plaintext. Keep this file private and do not commit it to version control.

Web Search and Fetch

By default, WebSearch works on non-Anthropic models using DuckDuckGo. This gives GPT-4o, DeepSeek, Gemini, Ollama, and other OpenAI-compatible providers a free web search path out of the box.

Note: DuckDuckGo fallback works by scraping search results and may be rate-limited, blocked, or subject to DuckDuckGo's Terms of Service. If you want a more reliable supported option, configure Firecrawl.

For Anthropic-native backends and Codex responses, Tersa keeps the native provider web search behavior.

WebFetch works, but its basic HTTP plus HTML-to-markdown path can still fail on JavaScript-rendered sites or sites that block plain HTTP requests.

Set a Firecrawl API key if you want Firecrawl-powered search/fetch behavior:

export FIRECRAWL_API_KEY=your-key-here

With Firecrawl enabled:

• WebSearch can use Firecrawl's search API while DuckDuckGo remains the default free path for non-Tersa models
• WebFetch uses Firecrawl's scrape endpoint instead of raw HTTP, handling JS-rendered pages correctly

Free tier at firecrawl.dev includes 500 credits. The key is optional.

Source Build And Local Development

bun install
bun run build
node dist/cli.mjs

Helpful commands:

• bun run dev
• bun test
• bun run test:coverage
• bun run security:pr-scan -- --base origin/main
• bun run smoke
• bun run doctor:runtime
• bun run verify:privacy
• focused bun test ... runs for the areas you touch

Testing And Coverage

Tersa uses Bun's built-in test runner for unit tests.

Run the full deterministic unit suite:

bun run test:full

Generate unit test coverage:

bun run test:coverage

Open the visual coverage report:

open coverage/index.html

If you already have coverage/lcov.info and only want to rebuild the UI:

bun run test:coverage:ui

Use focused test runs when you only touch one area:

• bun run test:provider
• bun run test:provider-recommendation
• bun test path/to/file.test.ts

Recommended contributor validation before opening a PR:

• bun install --frozen-lockfile
• bun run typecheck:production
• bun run build
• bun run test:full
• bun run smoke:tersa
• focused bun test ... runs for the files and flows you changed

For release-affecting changes, run bun run verify:tersa:release and bun run release:npm:dry-run.

Coverage output is written to coverage/lcov.info, and Tersa also generates a git-activity-style heatmap at coverage/index.html.

Repository Structure

• src/ - core CLI/runtime
• scripts/ - build, verification, and maintenance scripts
• docs/ - setup, contributor, and project documentation
• .github/ - repo automation, templates, and CI configuration
• bin/ - CLI launcher entrypoints

Security

If you believe you found a security issue, see SECURITY.md.

Community

• Use GitHub Discussions for Q&A, ideas, and community conversation
• Use GitHub Issues for confirmed bugs and actionable feature work

Contributing

Contributions are welcome.

For larger changes, open an issue first so the scope is clear before implementation. Helpful validation commands include:

• bun run build
• bun run test:coverage
• bun run smoke
• focused bun test ... runs for files and flows you changed

Disclaimer

Tersa is an independent community project and is not affiliated with, endorsed by, or sponsored by Anthropic.

Tersa was derived from an upstream open-source coding-agent project and has since been substantially modified for multi-provider and open use. Third-party product names and trademarks belong to their respective owners. See LICENSE for details.

License

See LICENSE.