FreeAgent

v0.2 · MIT · Python

A terminal coding agent.
One CLI, your choice of model.

FreeAgent reads your code, edits it, runs commands, and ships projects to GitHub and Vercel. The free tier (z.ai GLM-4.5-flash, Groq, OpenRouter, local Ollama) is enough to do real work; switch to GPT-5, Claude Opus, or Gemini 2.5 Pro when you want frontier quality. The CLI doesn't change. 

curl -fsSL https://raw.githubusercontent.com/vasilysahrai/freeagent/main/install.sh | bash

Both installers detect Python, prefer pipx, and fall back to pip --user. They report when the binary ends up off your PATH and tell you the line to add.

Free or paid — pick what fits.

FreeAgent talks to any OpenAI-compatible chat endpoint. The built-in catalog has nine providers and twenty-odd named models; run freeagent --list-models for the full list. The ones below are the ones most people should actually consider.

Free — no per-token cost

ProviderModelNote
z.ai glm-4.5-flash Free tier on z.ai. Solid default; tool calls work.
Groq llama-3.3-70b-versatile Free tier, very fast inference, rate-limited.
Groq deepseek-r1-distill-llama-70b Free reasoning model on Groq.
OpenRouter deepseek/deepseek-r1:free Free :free route on OpenRouter.
Google gemini-2.5-flash Free quota in AI Studio.

Local — your hardware, zero cost

ModelDiskNote
qwen2.5-coder:7b ~5 GB Runs on most laptops with 16 GB RAM.
qwen2.5-coder:32b ~20 GB 32 GB+ unified memory or a 24 GB GPU.
llama3.1:8b ~5 GB Solid generalist.

Install Ollama, then freeagent --provider ollama --model qwen2.5-coder:7b.

Paid — frontier

ProviderModels
OpenAI gpt-4o-mini, gpt-4o, gpt-5
Anthropic claude-sonnet-4-5, claude-opus-4-5
Google gemini-2.5-pro
xAI grok-3
Mistral mistral-large-latest
z.ai glm-4.6

Install & configure.

1 — Install

One-liner (recommended):

curl -fsSL https://raw.githubusercontent.com/vasilysahrai/freeagent/main/install.sh | bash

Or manually:

brew install pipx
pipx install git+https://github.com/vasilysahrai/freeagent.git

2 — Set a key

Set whichever you plan to use. Multiple keys can coexist.

export ZAI_API_KEY=...        # free        — https://z.ai
export GROQ_API_KEY=...       # free tier   — https://console.groq.com/keys
export OPENROUTER_API_KEY=... # free routes — https://openrouter.ai/keys
export GEMINI_API_KEY=...     # free quota  — https://aistudio.google.com/app/apikey

# Paid:
export OPENAI_API_KEY=...     # https://platform.openai.com/api-keys
export ANTHROPIC_API_KEY=...  # https://console.anthropic.com

On Windows, replace export X=... with $env:X = "...". FreeAgent also reads ~/.freeagent/.env and a project-local .env.

3 — Pick a model and run

Three equivalent ways:

# 1) per-invocation flags
freeagent --provider groq --model llama-3.3-70b-versatile

# 2) env vars
export FREEAGENT_PROVIDER=groq
export FREEAGENT_MODEL=llama-3.3-70b-versatile
freeagent

# 3) live, inside the REPL
›  /provider groq
›  /model llama-3.3-70b-versatile

Slash commands.

/helpShow the command list.
/modelsList models for the current provider.
/catalogList every model FreeAgent knows about.
/provider <id>Switch provider live.
/model <id>Switch model live.
/key <value>Replace the API key for this session.
/stream on|offToggle token streaming.
/clearReset the conversation.
/cwdPrint the workspace dir.
/exitQuit. Ctrl-D works too.

How it works.

The agent loop is plain OpenAI tool-calling. FreeAgent sends the running conversation plus a JSON schema for each tool to whichever backend you're on. The model replies with text or with tool calls; FreeAgent runs the tools locally — read, write, edit, grep, bash, gh, vercel — appends the results, and loops until the model stops.

Each provider is one entry in freeagent/config.py: base URL, default model, env var holding the key, whether a key is required. Adding another OpenAI-compatible API is a few lines. Streaming is on by default and degrades cleanly to non-streaming when a backend doesn't support it.