Cloud AI coding tools are powerful, but they also come with a bill, an API key, and a quiet upload of your source code to someone else's servers. What if your AI assistant ran entirely on your own machine instead?
That is FLASH CLI (Fast Local Agent SHell): an AI-powered command-line assistant that talks to local or self-hosted Ollama models and can actually run shell commands for you. No API key. No subscription. No cloud.
Why FLASH is different
- 100% local. It connects to an Ollama server, by default on localhost, so your code and prompts stay on your hardware.
- No keys, no bill. Ollama needs no API key, so there is nothing to pay for and nothing to leak.
- Truly agentic. FLASH does not just chat. It runs a real tool loop: it inspects your system, runs commands, searches the web, and shows its reasoning as it works.
- Model freedom. Point it at llama3.1, qwen2.5, mistral, or any tool-capable Ollama model, and swap with one setting.
- Local or remote. Set OLLAMA_HOST and the same client talks to a GPU box on your network or a server behind a reverse proxy.
The four main tools
FLASH gives the model a tight, powerful toolset:
- shell: run any command, non-interactively, with a timeout.
- web_search: pull live results from DuckDuckGo, built in.
- get_os: detect the operating system so it picks the right command every time.
- reason: surface a line of its thinking without ending the turn.
It loops through plan, act, and observe until the job is done, then answers in rendered Markdown with syntax highlighting.
Configuration
Optional configuration lives in ~/.flash.env:
MODEL=llama3.1
OLLAMA_HOST=http://localhost:11434
What it feels like
Ask a question and let it work:
[Flash]> what are the biggest files here?
Thinking: check the OS, then find the largest files
Retrieving operating system information
Executing shell command: du -ah . | sort -rh | head -3
…
Run a command yourself with the ! prefix, no AI in the loop:
[Flash]> !git status
On branch main
nothing to commit, working tree clean
Check or switch your backend on the fly:
[Flash]> /model
Model: llama3.1
Host: http://localhost:11434
Handy built-in commands: /help, /model, /clear, and /bye.
Built to run everywhere
FLASH is tested on every push across Linux, macOS, and Windows on Python 3.10, 3.11, and 3.12, with Ruff, Flake8, and Bandit keeping it clean and secure.
Watch the tour
I made a short cinematic walkthrough of everything that you can watch above.
Try it and star it
If a private, local, zero-cost AI shell sounds like your kind of tool, give it a spin and drop a star.
Repo: https://github.com/Natuworkguy/Flash
Your AI. Your machine. Your rules.
Top comments (8)
This looks interesting. How would you compare FLASH to tools like Claude Code, Gemini CLI, or OpenAI Codex? Are you mainly targeting developers who want complete local execution, or are there other advantages you've found in practice?
Great question, and I will be upfront because those are all genuinely excellent tools. Claude Code, Gemini CLI, and Codex are backed by frontier models with huge context windows and very polished tooling. On raw reasoning power, they will usually beat whatever you run locally. FLASH is not trying to win that fight. The difference is the execution model.
FLASH runs entirely on your own Ollama server, so your code and prompts never leave your machine. No API key, no subscription, no per-token bill. In practice that changes a few things:
So yes, the main audience is developers who want complete local execution and privacy. But the advantages I did not fully expect were the practical ones: not hitting rate limits while iterating fast, being able to work on a plane or an air-gapped machine, and having zero cost anxiety while experimenting with models. It is less "replace your cloud agent for everything" and more "when you would rather trade a bit of raw model power for privacy, cost, and full control, this is built for that."
Happy to go deeper on the tool loop or how the local-versus-remote backend switching works if you are curious.
Nice explanation. I'm curious about the tool loop—how does FLASH decide when to invoke a tool versus letting the model answer directly? Is it using Ollama's native tool calling or a custom orchestration layer?
Good question. It is Ollama's native tool calling, with a thin custom orchestration loop wrapped around it.
The deciding is done by the model, not by heuristics in FLASH. On each turn I pass the full tool schema (OpenAI-style function definitions) to Ollama's chat endpoint, and the model comes back with either plain content or a set of tool_calls. If there are no tool_calls, that text is the final answer and I render it. If there are tool_calls, FLASH executes them and keeps going.
The orchestration layer handles the loop around that:
The when-to-use-a-tool behavior is mostly shaped by the system prompt rather than code. For example, it tells the model to use shell only when command output is needed, to call get_os before any OS-specific command, to use web_search only for public internet info, and to use a reason tool to think mid-task without ending its turn. So the policy is native tool calling plus prompt engineering, not a separate planner or classifier.
The four main tools tools (shell, web_search, get_os, reason) all run through one dispatch function, so adding a tool is basically a schema entry plus a Python function.
Thanks for the detailed explanation. I like the approach of keeping the orchestration layer thin and letting the model drive tool selection. The fallback call with tools disabled after hitting the round/token limit is also a nice touch—it avoids leaving the user with an unfinished tool chain.
I've worked on Python backend systems and AI integrations, so it's interesting to see how you've balanced native tool calling with prompt engineering instead of adding another planning layer. In my experience, keeping the orchestration simple tends to make the agent more predictable and easier to extend.
The unified dispatcher also seems like a solid design choice. It looks like adding new tools (Git, Docker, Kubernetes, databases, etc.) would be fairly straightforward without changing the orchestration logic.
Really nice project—I'd be interested in contributing if you're looking for collaborators or additional maintainers.
Absolutely, I would love the help. FLASH is wide open to contributors, and I am happy to bring on maintainers as it grows.
A few areas where help is genuinely welcome:
Workflow is standard: fork, branch, PR. CI runs ruff, flake8, bandit, and pytest across Linux, macOS, and Windows on Python 3.10 to 3.12, so as long as that stays green you are good to go.
Repo: github.com/Natuworkguy/Flash. Open an issue or a draft PR and tag me, and we can find a good first thing for you to take on. Really appreciate you offering.
Thanks! I appreciate the opportunity.
I'm a Senior Software Engineer with 7+ years of experience in Python backend development and AI integrations, so I think FLASH is a great fit for my background. I'll spend some time exploring the codebase and start looking for an issue I can contribute to.
By the way, do you have a preferred communication channel for contributors? Discord, Slack, or something else? It'd be great to stay in touch as I start working on the project.
Because the project doesn’t have any contributors, we don’t have a communication channel.