INFT AI - Intelligent CLI Assistant

An intelligent command-line interface powered by Google Gemini using the ReAct (Reasoning + Acting) pattern. This CLI agent can understand natural language commands and execute them using various tools including file system operations, shell commands, and web search.

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║   ██╗███╗   ██╗███████╗████████╗     █████╗ ██╗              ║
║   ██║████╗  ██║██╔════╝╚══██╔══╝    ██╔══██╗██║              ║
║   ██║██╔██╗ ██║█████╗     ██║       ███████║██║              ║
║   ██║██║╚██╗██║██╔══╝     ██║       ██╔══██║██║              ║
║   ██║██║ ╚████║██║        ██║       ██║  ██║██║              ║
║   ╚═╝╚═╝  ╚═══╝╚═╝        ╚═╝       ╚═╝  ╚═╝╚═╝              ║
║                                                               ║
║              Intelligent CLI Assistant                       ║
║              Powered by Google Gemini                        ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Features

• 🤖 Natural Language Interface: Interact with your system using plain English
• 🧠 ReAct Pattern: Reasoning + Acting for intelligent decision-making
• 🔧 Multiple Tools: File operations, shell commands, directory management, web search
• 💾 Conversation Memory: Maintains context across the session with thread persistence
• 🛡️ Safety Features: Daily usage limits and command validation
• 📊 Usage Tracking: 20 commands per day limit to manage API costs
• 🎨 Beautiful CLI: Colorful output with spinners and progress indicators
• 🔍 Thought Transparency: See the agent's reasoning process in real-time
• 🌐 Web Search: Optional Tavily integration for real-time information

Tech Stack

• Runtime: Bun
• Language: TypeScript
• LLM: Google Gemini 2.0 Flash Exp
• Framework: LangChain.js + LangGraph
• Search: Tavily API (optional)
• CLI Tools: Commander, Inquirer, Ora, Chalk

Prerequisites

• Bun installed on your system
• Google Gemini API key (get one from Google AI Studio)
• (Optional) Tavily API key for web search (get from Tavily)

Installation

1. Install dependencies:

   bun install

2. Configure environment variables:

   The .env file should contain:

   GEMINI_API_KEY=your_gemini_api_key_here
      
   # Optional: Tavily API key for web search capabilities
   TAVILY_API_KEY=your_tavily_api_key_here

Usage

Start the CLI

bun start

Or for development with auto-reload:

bun run dev

Test the Setup

bun test

Example Commands

Once the CLI is running, you can use natural language commands:

💬 You: List all files in the current directory

💬 You: Read the contents of package.json

💬 You: Create a new file called hello.txt with "Hello World"

💬 You: Search the web for latest TypeScript features

💬 You: Create a directory called "test" and create a file inside it

💬 You: Explain what this project does

Built-in Commands

• help - Show help information
• stats - Display usage statistics
• exit or quit - Exit the CLI
• Press Ctrl+C - Exit the CLI

Project Structure

main/
├── src/
│   ├── index.ts          # Main CLI entry point & interaction loop
│   ├── agent.ts          # LangGraph agent setup & Gemini configuration
│   ├── utils/
│   │   └── tracker.ts    # Daily usage limit tracking (20 commands/day)
│   └── tools/
│       └── index.ts      # Custom tool definitions (file ops, shell, etc.)
├── .env                  # Environment variables (API keys)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Architecture

ReAct Pattern

The agent follows the ReAct (Reasoning + Acting) pattern as specified in /specs/agent.md:

1. Reasoning (Thought): The agent receives a prompt and "thinks" about what to do
2. Acting (Action): If a tool is needed, the agent generates a tool_call
3. Observation: The system executes the tool and feeds the result back
4. Repeat: The agent iterates until it has enough information
5. Final Response: Provides a complete answer to the user

Context Engineering

The agent uses a structured system prompt with:

• Persona: Specialized CLI assistant (INFT AI) focused on Bun and TypeScript
• Time Awareness: Current date injected into every session
• Formatting: Instructions to use Markdown for file content and ANSI colors for terminal output

Memory Management

• Short-term (Thread State): LangGraph manages conversation state as a list of messages
• Long-term (Checkpointers): MemorySaver persists the state of a thread_id across sessions

Available Tools

1. list_files: List files and directories
2. read_file: Read file contents
3. write_file: Write content to files
4. create_directory: Create new directories
5. execute_command: Run shell commands (with safety checks)
6. tavily_search (optional): Search the web for information

Safety Features

• Usage Cap: Maximum 20 commands per day enforced at application level
• Command Validation: Shell commands are validated to block destructive operations
• Relevance Filter: Agent refuses requests outside its operational domain
• Thought Transparency: Users can see the agent's reasoning process

Streaming & UX

• Event-based Streaming: Uses app.stream() with streamMode: "values"
• Thought Transparency: Displays agent's reasoning steps (tool calls) in real-time
• Beautiful UI: Colorful output with spinners showing progress

Usage Limits

The CLI enforces a 20 commands per day limit to manage API costs. Usage is tracked in a hidden file in your home directory (~/.inft-ai-cli-usage.json). The counter resets automatically at midnight.

Configuration

Gemini Model

Currently using gemini-2.0-flash-exp for optimal performance. You can modify this in src/agent.ts:

return new ChatGoogleGenerativeAI({
  model: "gemini-2.0-flash-exp",  // Change model here
  apiKey: apiKey,
  temperature: 0.7,
  maxOutputTokens: 8192,
});

Usage Limit

To change the daily limit, edit src/utils/tracker.ts:

const MAX_DAILY_COMMANDS = 20;  // Change limit here

Development

Adding New Tools

To add a new tool, edit src/tools/index.ts:

export const myNewTool = new DynamicStructuredTool({
  name: "my_tool",
  description: "What this tool does",
  schema: z.object({
    param: z.string().describe("Parameter description"),
  }),
  func: async ({ param }) => {
    // Tool implementation
    return "Result";
  },
});

Then add it to the getCustomTools() array.

Modifying the System Prompt

Edit the getSystemPrompt() function in src/agent.ts to customize the agent's behavior and personality.

Troubleshooting

"GEMINI_API_KEY not found"

Make sure the .env file exists in the main/ directory and contains your API key.

Get your API key from: https://makersuite.google.com/app/apikey

"Daily limit reached"

You've used all 20 commands for today. The limit will reset at midnight. To reset manually, delete the file ~/.inft-ai-cli-usage.json.

Dependencies not installing

Make sure you have Bun installed. Run:

bun --version

If not installed, visit bun.sh for installation instructions.

Web search not working

Make sure you have a valid Tavily API key in your .env file:

TAVILY_API_KEY=tvly-your_actual_key_here

Get your key from: https://tavily.com

Features from Specifications

This implementation includes all features specified in /specs/agent.md:

✅ ReAct Architecture: Full implementation with LangGraph
✅ Context Engineering: Structured system prompt with persona and time awareness
✅ Memory Management: Short-term (MessagesState) and long-term (MemorySaver)
✅ Guardrails & Safety: Usage cap, command validation, relevance filter
✅ Web Search: Tavily integration with maxResults: 3 and searchDepth: "advanced"
✅ Streaming & UX: Event-based streaming with thought transparency

License

MIT

Credits

Built with:

• Google Gemini - LLM Provider
• LangChain - LLM Framework
• LangGraph - Agent Framework
• Tavily - Web Search API
• Bun - JavaScript Runtime

INFT AI - Your intelligent command-line companion 🚀