OpenAgent Terminal Agent
Plan and execute terminal tasks with local, free, or bring-your-own-key models.
- Source repo
- haseeb-heaven/open-agent
- Stars
- ★ 280
- Last updated
- 6d ago
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 67/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A data practitioner who wants to inspect a local CSV and produce a chart from a terminal prompt.
- Not a fit if
- Users who require a graphical desktop or web interface
- Environments unable to install Node.js 22+
- Teams requiring multi-provider work solely from the default branch
- Source review
- 67/100 · Some gaps
What does this agent do, and when should you use it?
OpenAgent is an open-source terminal agent for Windows, macOS, and Linux that accepts a task in plain English, plans the work, uses tools, and returns the result. It is distributed as an npm CLI and can also be built from source, with Node.js 22+ required. Its model registry covers local Ollama and LM Studio runtimes alongside cloud providers including OpenAI, Anthropic, Gemini, Groq, DeepSeek, and OpenRouter. Documented work includes reading and analyzing a CSV, plotting results, selecting models, configuring BYOK credentials, and searching the web. Its extension loader accepts Slack marketplace extensions, Claude-style manifests, OpenAgent manifests, and `.mcp.json` files. Execution stays in the user's terminal and workspace; local models need no key, while cloud models and some search backends require network access and provider credentials.
A user submits a natural-language task through openagent or npm start. OpenAgent plans the task, invokes tools, and delivers output in the terminal; the documented example reads sales.csv, analyzes customer data, and plots the top ten customers. Models are selected with -m, --model or --provider, while --free rotates through a free or inexpensive catalog with fallback and --models prints the registry. --byok and the in-session /byok [provider key] command save cloud credentials to .env, while /models exposes model selection during a session. google_web_search chooses a backend from available credentials, falling back without a key from hosted Exa MCP to DuckDuckGo; Brave, Tavily, Serper, and Gemini are also configurable. Extension installation reads .claude-plugin/plugin.json, open-agent-extension.json, or .mcp.json, including MCP server declarations from a sibling .mcp.json file.
- A data practitioner who wants to inspect a local CSV and produce a chart from a terminal prompt.
- A developer already running Ollama or LM Studio who wants an agent without cloud credentials.
- A team that needs to switch among OpenAI, Anthropic, Gemini, Groq, DeepSeek, OpenRouter, and local models.
- An individual who wants free or inexpensive model rotation with automatic fallback when a model fails.
- A researcher who needs terminal-based web search with backend selection based on the active model and available keys.
- An advanced user extending terminal workflows through Claude-style manifests, OpenAgent manifests, or MCP configuration.
How do you install or deploy this agent?
Node.js 22+ is required. The shortest installation path is the published npm package:
npm install -g @haseeb_heaven/open-agent
openagentOllama and LM Studio require no API key. For cloud models, copy .env.example to .env and set the applicable variable, such as OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY; BYOK setup is also available inside the program.
To build the documented latest multi-provider work from source, check out the feature branch:
git clone --branch feature https://github.com/haseeb-heaven/open-agent.git
cd open-agent
npm install && npm run build
npm startHow do you use this agent?
Start in local-first mode; Ollama is used when it is running:
npm startAnalyze a CSV using the free or inexpensive catalog with automatic fallback:
npm start -- --free "analyze this CSV"List models or configure provider keys interactively:
npm start -- --models
npm start -- --byokA model or provider can also be selected explicitly:
npm start -- -m openrouter-free
npm start -- -m ollama/llama3.1:8b
npm start -- --provider groq -m llama-3.1-8b-instantThe complete source-based example is:
npm install && npm run build
npm start -- --free "analyze sales.csv and plot top 10 customers"During a session, use /models, /byok [provider key], and /websearch. Tool auto-approval is intended only for trusted workspaces:
npm start -- -yWhat are this agent's strengths and limitations?
- It combines keyless Ollama and LM Studio operation with a broad set of cloud model providers, reducing provider lock-in.
--freesupplies free or inexpensive model rotation and fallback without requiring an OpenAgent account.- Web search includes a no-key Exa-to-DuckDuckGo fallback and optional Brave, Tavily, Serper, and Gemini backends.
- The extension loader understands Claude-style manifests, OpenAgent manifests, and
.mcp.jsondeclarations. - The CLI explicitly supports Windows, macOS, and Linux and has a one-command global npm installation path.
- Node.js 22+ is mandatory, excluding environments pinned to older Node.js releases.
- The README places the latest multi-provider work on the
featurebranch, creating a stability and upgrade consideration for adopters. - Ollama and LM Studio must be operated separately, while each cloud provider requires its own credentials.
- There is no documented importable library, desktop application, or self-hosted web-service mode; the primary interface is the terminal.
--yoloand extension Auto mode bypass tool or workspace-trust prompts and are suitable only for trusted workspaces.
How does this agent compare with similar options?
OpenAgent is based on Google's Gemini CLI and modified by Haseeb Mir as the open-agent fork. In contrast to the single Gemini entry point suggested by its upstream origin, this repository explicitly documents paths for Ollama, LM Studio, OpenAI, Anthropic, Gemini, Groq, DeepSeek, OpenRouter, and other providers. The supplied material does not include comparative performance or feature benchmarks.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OpenAgent Terminal Agent This agent | 67 · Some gaps | CLIFree | ★ 280 | 6d ago | TypeScript | OpenAI API · Claude API |
| Mysti AI Coding Team | 58 · Major gaps | IDE extensionFree + model costs | ★ 1.1k | 2d ago | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| Aura IDE | 77 · Good | Desktop appFree + model costs | ★ 56 | 14d ago | Python | OpenAI API · Claude API |
| Aivo | 57 · Major gaps | CLIFree + model costs | ★ 194 | today | Rust | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The README distinguishes local from cloud models, enumerates credential variables, describes approval modes for tools and extensions, and warns that YOLO/Auto modes are for trusted workspaces. Workflow permissions are scoped and third-party Actions are pinned to commits. Deductions reflect the absence of demonstrated per-tool privilege isolation, precise disclosure of data sent to each model or search backend, detailed credential-storage protections, a dependency-vulnerability policy, and a general task rollback mechanism. Upstream Gemini CLI, Google LLC, the modifier, and Apache-2.0 are explicitly attributed, justifying full source-attribution credit.
The README, package metadata, workflows, and tests provide a clear Node requirement, build and test commands, multiple providers, search fallbacks, and readable diagnostics for missing directories and unresolved static cases. Deductions apply because no executions or results are supplied, some live tests skip when credentials or quota are unavailable, and models, hosted MCP, search services, and npm remain external dependencies. Residual Gemini artifact naming also weakens internal consistency.
Terminal users, CSV analysis, local models, free catalogs, BYOK providers, cloud services, and interactive and non-interactive operation are clearly represented. Windows, macOS, Linux, Ollama, and LM Studio support provide strong environment-fit evidence. Deductions apply because capability boundaries are conveyed mainly through commands and short warnings rather than a complete account of filesystem, shell, network, and extension limits; triggers are precise but conflict resolution and full precedence rules are not shown.
The README has clear sections for installation, quick start, models, search, extensions, documentation, testing, attribution, and licensing. npm and source installation are concrete, and the complete Apache-2.0 license is present. Deductions reflect the lack of a visible FAQ and consolidated known-limitations section, a version without a supplied changelog or migration history, and unstable ownership cues caused by OpenAgent branding alongside Gemini-named artifacts and a Google security intake. Publisher identity remains unknown.
Examples present a direct path from a natural-language task to terminal use, while provider selection, model catalogs, search fallback, and extensions offer plausible value beyond a single-provider chat interface. Local, free, and BYOK modes also provide cost choices. Deductions apply because the evidence contains no representative completed outputs, measured quality, latency, resource requirements, or cost comparisons; test source demonstrates test structure, not task effectiveness.
Many claims trace to concrete commands, configuration names, registry and documentation references, package metadata, workflows, and test code. Package identity, version, Node requirements, scripts, and platform builds receive some cross-file corroboration. Deductions apply because there are no execution logs, release-artifact checks, or independent sources, while claims such as “free” and “no vendor lock-in” lack quantified qualifications. Test policy labels cannot be treated as passing results, so fact-versus-inference separation is adequate rather than complete.
- The static material does not define which prompts, file contents, or metadata are sent to cloud models, hosted Exa MCP, or other search backends; verify these boundaries before using sensitive repositories.
- Do not enable --yolo or --auto in an untrusted workspace because those modes bypass tool or extension trust confirmation.
- BYOK can save credentials to .env, but the supplied evidence does not describe file permissions, encryption, log redaction, rotation, or leak recovery.
- SECURITY.md directs reports to Google's intake while the publisher is an unverified personal fork; confirm that this channel actually maintains the fork before disclosing an issue.
- Build artifacts retain the gemini name and source installation recommends the feature branch; verify that the published package, branch, and reviewed revision correspond.
FAQ
Do I have to pay for a model API?
--free provides a free or inexpensive model catalog. Paid cloud-provider charges apply only when those services are selected.What local resources can it access?
sales.csv, analyzes it, and creates a plot; extension installation and .env credential storage also use the filesystem.Does web search work without an API key?
Which operating systems and runtime are supported?
What is the risk of automatic approval?
-y, --yolo automatically approves tools, and extension Auto mode automatically grants workspace trust. The documentation limits these modes to trusted workspaces.