🧠 ZeroCostAI

Free AI-Powered Coding Assistant CLI — Use ALL free AI APIs from one tool. No backend needed.

A manifest-driven coding assistant that talks directly to free tiers of OpenAI, Claude, Gemini, Groq, Mistral, Cohere, Together, OpenRouter, and a local Ollama instance — all from your terminal, all without a backend.

Features · Installation · Quick Start · Usage · Providers · Contributing

---

✨ Features

• 🆓 100% Free — Uses free tiers of the best AI providers on the planet
• 🔧 Full Coding Assistant — Read/write/edit files, run shell commands, search code
• 📋 Manifest-Driven — Add a new provider by editing one JSON file. No code changes.
• 💻 Interactive REPL — Chat with AI directly in your terminal with /help, /clear, /exit
• 🔄 Multi-Provider — Switch between OpenAI, Claude, Gemini, Groq, Mistral, Cohere, Together, OpenRouter, and Ollama instantly
• 🏠 Local & Offline — Works with Ollama for fully private, offline coding assistance
• 🚀 Zero Backend — All API calls are made directly from your machine
• 🛠️ Tool Calling — Lets models actually do work: read files, edit code, run commands
• 🎨 Beautiful CLI — Colorized output, spinners, and clean tables
• 🧭 Smart Project Onboarding — Run /init to auto-inject a summary of your codebase into the prompt
• 🧰 Tool Browser — /tools lists all actions the model can take; /status shows live state

---

📦 Installation

Prerequisites

• Node.js 18 or newer
• npm 9+ (or pnpm / yarn)

Clone & install

git clone https://github.com/ImranDev3/ZeroCostAI-.git
cd ZeroCostAI-
npm install
npm run build
npm link

npm link makes the zerocostai (and zcai) commands available globally.

Configure API keys

# Copy the env template
cp .env.example .env

# Edit .env and add at least one API key, OR use the CLI:
zerocostai set-key openai sk-your-openai-key-here
zerocostai set-key gemini your-gemini-key
zerocostai set-key groq gsk-your-groq-key

Tip: You can use ZeroCostAI with zero API keys by installing Ollama and running a model locally.

---

🚀 Quick Start

Interactive Mode (REPL)

zerocostai

You'll see a banner, then a ❯ prompt. Type a coding task and press Enter.

🧠 ZeroCostAI v1.1.0 · Free AI Coding Assistant
Powered by free AI APIs from a manifest. No backend required.

  Provider: OpenAI · Model: gpt-4o-mini
  Type /help for commands, /exit to quit.

❯ add a function to my utils.ts file that deep-clones objects

💡 First thing to try in a new project: type /init. ZeroCostAI will scan the current directory, detect the project type, and inject a compact summary (tree, key files, README snippet) into the system prompt so the model knows your codebase.

Single Prompt Mode

zerocostai chat "explain this codebase"
zerocostai chat "fix the bug in src/auth.ts" --provider anthropic --model claude-3-haiku-20240307

Slash Commands (REPL)

Command	Description
/help	Show all available slash commands
/init	Scan the current project and inject context into the prompt
/tools	List the actions the model can take (read/write/edit/run/...)
/status	Show active provider, model, history size, and working dir
/provider [id] [id]	Show or switch the active provider / model
/model <id>	Switch model on the current provider
/clear	Clear conversation history (keeps system prompt)
/reset	Clear history AND revert system prompt to the default
/history	Show message count in the history
/exit (or /quit)	Exit the REPL

Switch Provider / Model

# At startup
zerocostai --provider gemini --model gemini-1.5-flash
zerocostai --provider ollama --model codellama

# Or via env
export ZCAI_DEFAULT_PROVIDER=groq
export ZCAI_DEFAULT_MODEL=llama-3.1-70b-versatile
zerocostai

# Or live, inside the REPL
❯ /provider anthropic
✔ Switched to Anthropic Claude · claude-3-haiku-20240307
❯ /model claude-3-5-sonnet-20240620
✔ Model switched to claude-3-5-sonnet-20240620

Onboarding a project with /init

When you first cd into a new codebase, run /init inside the REPL. ZeroCostAI will:

• Detect the project type and primary language (Node/TS, Python, Rust, Go, …)
• Render a tree of the top three levels (skipping node_modules, .git, dist, etc.)
• Inline previews of the most important files: package.json, tsconfig.json, README.md, Dockerfile, pyproject.toml, Cargo.toml, etc.
• Append a “Notes for the assistant” section so the model uses the right tools

Re-running /init replaces the previously injected context.

---

📖 Usage

List Providers

zerocostai providers

Output:

Configured providers

ID             Name                   Models    API Key
openai         OpenAI                 2         yes
anthropic      Anthropic Claude       2         missing
gemini         Google Gemini          2         yes
groq           Groq                   3         yes
...
ollama         Ollama (Local)         4         not needed

List Models

# All providers
zerocostai models

# Only one provider
zerocostai models --provider gemini

Save an API Key

zerocostai set-key openai sk-abc123def456

The key is appended (or updated) in your local .env file.

Available Tools (used by the agent)

Tool	Description
read_file	Read the contents of a file
write_file	Create or overwrite a file
edit_file	Find-and-replace text in a file
list_dir	List directory contents
run_command	Execute a shell command (30s timeout)
search_files	Find files matching a glob pattern

---

🌐 Supported Providers

Provider	ID	Free Tier	API Key Env Var
OpenAI	openai	Trial credit	OPENAI_API_KEY
Anthropic Claude	anthropic	Trial credit	ANTHROPIC_API_KEY
Google Gemini	gemini	✅ Free	GEMINI_API_KEY
Groq	groq	✅ Generous free	GROQ_API_KEY
Mistral AI	mistral	Free tier	MISTRAL_API_KEY
Cohere	cohere	Trial	COHERE_API_KEY
Together AI	together	Trial credit	TOGETHER_API_KEY
OpenRouter	openrouter	✅ Free models	OPENROUTER_API_KEY
Ollama (Local)	ollama	✅ 100% free	none required

✏️ Adding a new provider? Just edit src/providers/manifest.json.

---

🏗️ Architecture

zerocostai/
├── src/
│   ├── providers/
│   │   ├── types.ts              # Provider, Message, Tool, ChatResponse types
│   │   ├── manifest.json         # 🪄 The single source of truth for providers
│   │   ├── openai-provider.ts    # OpenAI + Groq + Mistral + Together + OpenRouter + Ollama + Cohere
│   │   ├── anthropic-provider.ts # Anthropic Claude (Messages API)
│   │   ├── gemini-provider.ts    # Google Gemini (generateContent)
│   │   └── index.ts              # Factory: loadManifest, getProvider, getApiKeyForProvider
│   ├── tools/
│   │   └── index.ts              # read_file, write_file, edit_file, list_dir, run_command, search_files
│   ├── agent/
│   │   ├── system-prompt.ts      # Default system prompt
│   │   └── index.ts              # Agent with iterative tool-call loop
│   ├── cli/
│   │   ├── init.ts               # /init — project scanner, builds context prompt
│   │   └── index.ts              # Commander.js CLI, REPL, slash commands
│   └── index.ts                  # Shebang entry point
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
└── README.md

How It Works

1. Manifest — src/providers/manifest.json lists every supported provider, its base URL, and its models.
2. Factory — src/providers/index.ts reads the manifest and returns a Provider instance for the requested id. The factory uses one of three concrete classes (OpenAIProvider, AnthropicProvider, GeminiProvider) depending on the API style.
3. Agent — src/agent/index.ts keeps a conversation history and runs an iterative loop: ask the model → if it returns tool calls, execute them and feed results back → repeat until a final answer.
4. CLI — src/cli/index.ts wires everything up with Commander for subcommands, a readline-based REPL, and slash commands.

---

🛠️ Development

# Run from source (no build step)
npm run dev

# Compile to ./dist
npm run build

# Run the compiled version
npm start

# Add a new provider
# 1. Edit src/providers/manifest.json
# 2. If it speaks OpenAI spec, you're done. Otherwise add a class in src/providers/.
# 3. Map its env var in src/providers/index.ts (API_KEY_ENV)

Adding a new provider

{
  "id": "myprovider",
  "name": "My Provider",
  "baseUrl": "https://api.myprovider.com/v1",
  "requiresApiKey": true,
  "models": [
    { "id": "my-model", "name": "My Model", "supportsTools": true }
  ]
}

If the API is OpenAI-compatible, that's literally all you need. If it has a unique API style (like Anthropic or Gemini), add a new subclass of Provider in src/providers/ and wire it in createProvider().

---

❓ FAQ

Q: Is it really free? A: Yes — ZeroCostAI itself is MIT-licensed. The AI APIs it talks to are mostly free-tier (Gemini, Groq, OpenRouter, Ollama). Some (OpenAI, Claude) require you to add billing but give free trial credits.

Q: Where are my API keys stored? A: In your local .env file. ZeroCostAI never sends them anywhere except the respective provider's API.

Q: Can I add a new provider without writing TypeScript? A: Yes! For OpenAI-compatible APIs, just add an entry to src/providers/manifest.json and re-build.

Q: How does the tool calling work? A: The agent sends your prompt + a list of tool schemas to the model. If the model wants to read a file or run a command, it returns a tool_calls payload; the agent executes the tools and feeds the results back. It loops up to 15 times.

Q: Does it work offline? A: With Ollama, yes — run ollama serve and zerocostai --provider ollama --model codellama.

---

🤝 Contributing

Contributions are very welcome! Here's how to help:

1. ⭐ Star this repo
2. 🐛 Report bugs via GitHub Issues
3. 💡 Suggest features in Discussions
4. 🔧 Submit PRs for new providers, tools, or bug fixes
5. 📖 Improve docs — typos, examples, translations

Code Style

• TypeScript strict mode
• 2-space indent
• Run npm run build before committing

---

📜 License

MIT © ImranDev3

---

🙏 Acknowledgments

• Commander.js for the CLI framework
• Chalk for terminal colors
• Ora for spinners
• The free-tier programs of OpenAI, Anthropic, Google, Groq, Mistral, Cohere, Together, and OpenRouter
• Every contributor who helped make this project possible

---

⬆ back to top

Made with ❤️ by ImranDev3