v5.0 — Open Source — MIT License

An AI agent that runs from your terminal

Deploy, debug, and automate from your terminal — without switching tabs between AI, docs, and your code. Full-screen TUI. 54 providers. 150+ tools. One command. See all commands →

Get Started View Source
"Replaced my entire AI workflow. One pip install, and I have everything I need in the terminal — no tabs, no dashboards, no vendor lock-in."
— Developer using HelloChusquis daily
54AI Providers
150+Integrations
100%Open Source
0Cloud Accounts

How It Works

From pip install to working agent in 60 seconds.

Install it, configure one API key, and start asking questions.

Step 1
Install
One pip command. macOS, Linux, Windows. Python 3.10+.
Step 2
Add an API key
Paste a free OpenRouter or Groq key. Auto-failover if one provider goes down.
Step 3
Ask anything
Search the web, run code, manage files, automate browsers. The agent picks the tools.

Why we built this

Every AI agent out there is either a SaaS product that locks you in, or a GitHub repo that needs 47 config files. We wanted something different: install it in one command, use any provider, own your data. HelloChusquis runs locally, talks to whichever AI provider you choose, and never phones home. Your API keys stay on your machine. Your conversations stay in your terminal.

Commands Reference

130+ tools. Zero browser tabs. All terminal.

From install to advanced workflows — here's how to get things done fast.

Terminal Commands

  • hellochusquis Start interactive chat
  • hellochusquis web Open web interface (localhost:8000)
  • hellochusquis api Start REST API server (port 8080)
  • hellochusquis config Open setup wizard
  • hellochusquis config --show Display current configuration
  • hellochusquis config --api-keys Edit API keys only
  • hellochusquis config --providers Edit providers only
  • hellochusquis --quick Quick setup with OpenRouter
  • hellochusquis --full Full setup with all providers

In-Chat Slash Commands

  • /help Show all available commands
  • /status Provider status and response times
  • /clear Clear conversation history
  • /plan <task> Force multi-step plan for complex tasks
  • 👍 / + Positive feedback — helps the agent learn
  • 👎 / - Negative feedback — flags mistakes
  • exit Quit the session

Plugin Management

  • hellochusquis install <plugin> Install a community plugin
  • hellochusquis uninstall <plugin> Remove a plugin
  • hellochusquis plugins List installed plugins
  • hellochusquis build Build the project
  • hellochusquis learn Run learning pipeline

CLI Flags

  • --port PORT Port for API/web (default: 8080/8000)
  • --host HOST Host for API/web (default: 0.0.0.0/127.0.0.1)
  • --quick Quick setup with OpenRouter only
  • --full Full setup wizard with all providers

Get more done

Multi-step tasks with /plan

Complex tasks get auto-detected, but you can force a plan: /plan deploy my app to AWS with monitoring. Review steps before execution.

Web interface

Run hellochusquis web to chat from your browser at localhost:8000. Supports voice input/output, theme switching, and chat export.

REST API with streaming

Expose your agent over HTTP: hellochusquis api --port 8080. SSE streaming, rate limiting, health checks at /health.

Environment variables

HELLOCHUSQUIS_API_KEY=secret enables auth. DEBUG=1 for verbose logs. HELLOCHUSQUIS_UNSAFE_MODE=1 to skip security checks.

Provider failover

Add multiple providers. If one hits rate limits or goes down, the agent automatically switches to the next. Zero downtime.

Persistent memory

The agent remembers past sessions. Use 👍/👎 feedback to help it learn. Memory persists in ~/.hellochusquis/.

What people say

The terminal-first crowd already gets it.

Built by devs, for devs. Here's what they say after one pip install.

Replaced three different tools I was juggling. The auto-failover saved me during a Groq outage last week — switched to OpenRouter mid-task without me noticing.

marco.d
Backend engineer

The browser tool actually works on sites with anti-bot protection. Where my other browser scripts died on protected pages, this just handled it.

jpark.dev
QA automation lead

I run Ollama locally for most things and Ollama + HelloChusquis beats paying for a monthly AI subscription. No code leaves my machine, ever.

ana_codes
Privacy-focused dev

The pitch

Why a terminal agent beats another browser tab.

// No context switch
Your AI lives where you work. No alt-tabbing between a browser chat and your editor. Your hands never leave the keyboard.
// Runs on your machine
Local-first. Sensitive code, proprietary data, customer info — nothing leaves your machine unless you choose a cloud provider.
// Provider freedom
Switch from OpenAI to Groq to local Ollama with one command. No vendor lock-in. If a provider goes down, the next one picks up.
// Scriptable
Pipe, redirect, chain. The agent is a CLI tool — combine it with cron, tmux, make, or any shell workflow you already use.

Features

The open source terminal AI agent.

Real features, real workflows. Not a feature list — a productivity upgrade.

Never lose a provider again

Multi-provider fallback
Groq goes down? OpenAI hits limits? The agent switches providers automatically — your workflow never stops.
Persistent memory
Tell it once, it remembers forever. Learns from 👍/👎 feedback and gets better every session.
Task planner
Complex tasks broken into steps. You approve each one before it runs — no surprises, no fires to put out.

Chat your way — terminal, browser, or API

Web interface
Full chat experience in your browser — voice input/output, themes, export, provider status at a glance.
REST API with streaming
Expose your agent as an HTTP service. Real-time SSE streaming. Rate limiting and health checks built in.

Automate your workflow in plain English

Browser automation
Real Playwright with anti-detection stealth. Open URLs, click, type, screenshot — all from chat.
Workspace permissions
Only touches directories you allow. New paths require your explicit approval at runtime.
Plugin system
Drop-in community plugins or build your own. The agent can even create integrations on demand.
Security checks
AI-powered safety blocks dangerous commands before they run. Set strictness to match your comfort level.

Tools you can use right now

shell code files web_search browser github slack gmail docker aws notion jira postgresql stripe twilio shopify hubspot intercom mailchimp mongodb pagerduty discord datadog clickup vercel supabase + 130 more

Demo

How devs actually ship with HelloChusquis.

Real terminal output. No cherry-picking.

terminal — real session
You: find the best flight deals to Tokyo
→ web_search(query="cheap flights to Tokyo 2026")
→ browser_open(url="https://skyscanner.com")
→ browser_type(text="New York → Tokyo, Aug 15")
→ browser_click(text="Search")
Found 47 flights. Best price: €420 on ANA.
You: write a Python script to track prices daily
→ code(code="import requests...")
Created price_tracker.py. Runs daily via cron.
You: deploy the tracker to my VPS
→ shell("scp price_tracker.py user@vps:~/")
→ shell("ssh user@vps 'crontab -e'")
Deployed. Price checks run at 9am daily.
# 3 tools, 3 systems, zero manual wiring.

AI Providers

Never get stuck when a provider goes down.

Add as many as you want. The agent switches when one hits rate limits or goes down.

Major & Platform Providers

OpenRouter
Groq
Ollama (local)
OpenAI
Anthropic
Google Gemini
xAI (Grok)
Perplexity
Mistral
DeepSeek
Cohere
Together AI
Fireworks AI
Replicate
IBM watsonx.ai
HuggingFace

Enterprise & Cloud

Azure OpenAI
AWS Bedrock
Vertex AI
Cerebras
NVIDIA NIM
DeepInfra
Baseten
Modal

Chinese & Asian Providers

Qwen / Alibaba
SiliconFlow
Volcengine
Baidu Qianfan
Tencent Hunyuan
StepFun
Jina AI

Open Source & Local

LM Studio
vLLM
Jan
LocalAI
TextGen WebUI
AnythingLLM
FriendliAI

Specialized

AI21
TextCortex

FAQ

Everything you asked, answered.

What is HelloChusquis?
An open source terminal AI agent. One pip install, 54 providers, 150+ tools, browser automation, SSE streaming, persistent memory. Runs locally on your machine.
How much does it cost?
Free and open source (MIT license). You pay only for AI provider API usage. Groq and Ollama are free options.
Can I use it without an API key?
Yes. Install Ollama locally and HelloChusquis connects automatically. No API key needed. Your data stays on your machine.
What can it actually do?
Run shell commands, execute Python code, manage files, search the web, automate browsers, send emails, manage Docker containers, query databases, and connect to 150+ APIs.
How does it compare to browser-based AI tools?
Those are browser tabs you can't script. HelloChusquis is a CLI tool — pipe it, chain it, run it in cron, use it from any terminal. And it runs locally with Ollama if you want zero data leaving your machine.

Get Started

Install once. Run forever.

Pick the method that works for you.

Option 1
pip (recommended)
pip install hellochusquis

Requires Python 3.10+. Adds hellochusquis to your PATH.

Option 2
curl installer
curl -sSL https://raw.githubusercontent.com/aminoy77/HelloChusquis/main/install.sh | bash

macOS and Linux only.

Option 3
From source
git clone https://github.com/aminoy77/HelloChusquis.git && cd HelloChusquis && pip install -e .

For contributors. Editable install.