open source · v1.1.1 · MIT license

mini-agent-cli

> think. act. observe. answer.

A lightweight AI agent that runs in your terminal. Powered by Google Gemini. Built from scratch in vanilla Node.js — no frameworks, no magic — to understand how tool-calling really works under the hood.

Star on GitHub Get started → v1.1.1 stable
mini-agent-cli pixel art octopus mascot
live demo
mini-agent-cli — bash — node src/index.js
~/projects/mini-agent-cli on main
You > what files are in the current directory?
[Agent Thinking...]
[Reason: user is asking for files in the current directory.]
[Choosing tool: listDir]
Agent > Here are the files in your project:
.env · .gitignore · CHANGELOG.md · LICENSE · README.md · package.json · src/
You > fetch the content of https://example.com and summarize it
[Agent Thinking...]
[Reason: user wants to read and summarize a web page.]
[Choosing tool: fetchURL]
Agent > The page is a placeholder from IANA showing that example.com is reserved for use in documentation and examples.
You >
available tools
readFile
readFile(path: string) → string
Reads any file from disk and returns its full contents. Automatically infers file extension if omitted.
writeFile
writeFile(path, content: string)
Writes or overwrites a file on disk with the given content in UTF-8 encoding.
listDir
listDir(path?: string) → string
Lists all files and folders in a directory. Defaults to the current working directory.
fetchURL
fetchURL(url: string) → string
Fetches a web page and returns its content as plain text. Lets the agent read live documentation or APIs.
how it works
You type a message
Gemini + tool context
Gemini decides
tool needed
Parse JSON tool call + reason
Display reason & chosen tool
Execute the tool function
Send result back to Gemini
Return final answer ✓
no tool needed
Gemini answers directly
Return final answer ✓
by the numbers
–
GitHub stars
–
contributors
4
tools built
–
issues closed
get started
# 1. clone the repo
git clone https://github.com/HoussemEddineChaouch/mini-agent-cli.git
cd mini-agent-cli

# 2. install dependencies
npm install

# 3. run the agent
node src/index.js
releases
v1.1.1 latest 5 bug fixes — error handling, clean exit, empty input, parser, API validation
Jul 2026 view →
v1.1.0 JSON tool protocol, colored output, agent reasoning display
Jul 2026 view →
v1.0.0 Initial release — 3 tools, Gemini integration, string-based protocol
Jun 2026 view →
contribute
Report a bug
Found something broken? Open an issue with steps to reproduce and your environment details.
Add a new tool
runCommand, deleteFile, searchWeb — all open in the issues. Pick one and ship it.
Improve docs
README updates, CHANGELOG entries, or this landing page — all labeled good first issue.
Write tests
Zero tests right now. Add basic ones using node:test — no extra dependencies needed.
good first issues contributing guide →
contributors

Everyone who has shipped code, fixed bugs, or improved docs. Thank you 🙌

loading contributors...