Flint Agent / AI Agent for the Terminal

Flint is a lightweight terminal AI agent built to work with any model, cheap and free ones included. It reads files, writes code, runs commands, browses the web, and remembers project details across sessions.

Flint installs as a single npm package: no Python, no Docker, no background service, and it can run entirely on OpenRouter's free tier with zero setup cost.

Quick start

Requires Node.js 22.12 or newer.

npm install -g flint-agent
flint

On first launch, enter your free OpenRouter API key, then switch to auto-selected free models:

/model free auto

Flint detects which free models support tool calling, ranks them by speed and uptime, and automatically falls back to an alternative vendor if a model gets rate-limited.

Why Flint

• Zero infrastructure. Single npm package. No Python environments, no Docker containers, no background services.
• Budget-friendly context swap. Long conversations do not bloat token bills. Older tool results and conversation turns swap to local disk and are fetched back only when needed.
• MCP ecosystem. Connect external tools, databases, and APIs via Model Context Protocol servers.
• Built-in guardrails. Flint runs with safe confirmation defaults, asks before destructive commands or secret reads, and lets you set custom spending limits per session.
• Flexible runtime. Supports OpenRouter, OpenAI, Anthropic, Google Gemini, Groq, Together, and local Ollama models. Can also run headlessly or as a subprocess in custom pipelines.

Supported providers and models

Flint works with any LLM through a single CLI. Switch providers and models mid-session with /provider <name> and /model <id>.

• OpenRouter. Hundreds of models under one key, including the free pool: Gemini Flash Free, Qwen Coder Free, Nemotron Free, and more. Driven by /model free auto.
• Google Gemini. Direct Gemini 2.5 Pro and Gemini 2.5 Flash, including the free Gemini Flash tier.
• Groq. Fast Llama and Mixtral inference with a generous free tier.
• Cerebras. Low-latency open-weight models through its hosted endpoint.
• Anthropic. Claude Sonnet 4 and Claude Opus 4 against your own key.
• OpenAI. GPT-4o, o3, o4-mini and the rest of the OpenAI stable.
• Ollama. Any local model served by Ollama on your own machine, no account needed.

All provider API keys are encrypted on disk (AES-256-GCM, DPAPI on Windows). Flint itself has no server, no telemetry, and no cloud account.

Practical use cases

Automated test fixing on free quotas

Launch Flint headless from CI or a shell script, point it at a failing test, give it a budget, and walk away:

flint --headless --task "Fix the failing test in auth.test.js" --cwd ./project --budget 0.50

Flint reads the test, follows the stack trace, patches the code, re-runs the suite, and stops when the test passes or the budget runs out. Returns structured JSON on stdout, suitable for CI jobs.

Codebase refactoring with rate-limit survival

Switch to a free pool and hand Flint a big autonomous task:

/model free auto
/auto Refactor the auth module to use JWT, update all tests, write migration docs

Flint plans the work, executes task by task, checkpoints progress in SQLite, and swaps older tool results to disk so long runs do not inflate the context window. When a free model hits a daily cap or returns 429, Flint continues on the next fallback and comes back to the primary once its window clears.

MCP-powered prototyping

Flint speaks the Model Context Protocol over stdio, HTTP, and SSE, so any MCP server shows up as native tools:

MCP_SERVERS=gmail|http|http://localhost:9090/mcp,my-db|stdio|~/my-db-server mcp

Install a plugin to pull in a vendor-ready integration:

/install https://github.com/user/flint-plugin-jira

A prompt like "triage the three oldest Jira bugs and open draft PRs" then works end to end from one CLI.

FAQ

Does Flint store my code or API keys?

API keys are encrypted on disk with AES-256-GCM (DPAPI on Windows). Session history, planning state, and persistent memory stay on your machine as local files and an SQLite database, protected by HMAC integrity checks. Flint itself has no server and sends no telemetry. Every call to a model provider is governed by that provider's own policy and your account there.

How does free model auto-rotation work on rate limits (HTTP 429)?

Run /model free auto. Flint queries OpenRouter for free models that support tool calling, ranks them by speed and uptime, and selects a primary with two fallbacks (visible in the session header as free: <primary> (fallbacks: <a>, <b>)). When a request hits a 429 or a daily cap, Flint continues on the next fallback and comes back to the primary once its window clears, without dropping the conversation.

Can I use Flint alongside Claude Code and Cursor?

Yes. Flint is a standalone terminal CLI that reads and writes files in the directory you launch it from. It installs no editor plugin and runs no background daemon, so sharing a project with another coding tool causes no conflict. Flint's audit log and checkpoint/undo keep your own history separate from whatever other tools write.

What environments are supported?

Linux, macOS, and Windows, including WSL. Flint requires Node.js 22.12 or newer and runs on Node alone, no Docker or Python. The TUI is React 19 on Ink 6 and renders inside any modern terminal (iTerm2, Alacritty, Windows Terminal, GNOME Terminal, and more).

Project details

• License: MIT
• Stack: Node.js, React 19, Ink 6, SQLite
• Source: github.com/dklymentiev/flint-agent
• Package: npmjs.com/package/flint-agent