Introduction
Flux-CLI is a powerful, open-source AI coding agent that runs directly in your terminal. Inspired by tools like Claude Code CLI and Gemini CLI, it is built from scratch in Python to help you write, refactor, and understand code through natural language.
What is Flux-CLI?
Flux-CLI is not just an LLM wrapper — it is a complete, event-driven agentic system that:
- Reasons about problems and selects appropriate tools
- Orchestrates multiple tools in sequence to accomplish complex tasks
- Streams responses in real-time for a responsive feel
- Extends through plugins, MCP servers, and lifecycle hooks
- Stays safe with configurable approval policies for mutating operations
Learning-First Project
This project was created as a learning initiative to deeply understand how AI coding agents work under the hood — from reasoning loops and tool orchestration to streaming architectures and safety systems.
Why "Flux"?
The name reflects constant flow and adaptation. Just as flux in physics is the rate of flow through a surface, Flux-CLI enables a continuous flow of work — reasoning → acting → learning → adapting — through every turn.
What You Can Do
| Capability | Description |
|---|---|
| Code Understanding | Read, search, and explore codebases of any size |
| File Operations | Create, edit, and write files with surgical precision |
| Shell Commands | Execute terminal commands safely with timeout controls |
| Web Research | Search the web and fetch content for up-to-date context |
| Task Management | Track multi-step tasks with session-scoped todo lists |
| Persistent Memory | Remember user preferences across sessions |
| Sub-Agent Delegation | Spawn specialists for code review and investigation |
| MCP Integration | Connect external servers via the Model Context Protocol |
Tip
All capabilities are available as tools — the agent decides which to use and in what order. See Tool System for the full catalog.
Architecture at a Glance
The system follows a layered, event-driven architecture:
CLI Entry Point (main.py)
│
▼
Agent Engine (agent/agent.py) ◄── Hook System
│
├──► Context Engine (compaction & pruning)
├──► Tool Registry (built-in + MCP + custom)
└──► LLM Client (AsyncOpenAI wrapper)Each component is modular, testable, and independently configurable — jump to Architecture for a deep dive.
Next step
Ready to run it? Head to Quick Start and get Flux-CLI working in under 5 minutes.