flutty-cli-agent

Flutty CLI Agent

A Claude Code CLI clone built using the DeepSeek API. This tool provides an interactive coding assistant that can help with software engineering tasks, code analysis, file operations, and more.

Features

• Interactive Chat Mode: Real-time conversation with the AI assistant
• One-shot Queries: Execute single commands and get results
• Comprehensive Tool Set: File operations, code search, bash commands, and more
• Custom Named Tools: Define custom tools for UI interactions, workflows, and domain-specific actions
• Todo List Management: Automatically tracks complex multi-step tasks
• RAG Integration: Enhanced context awareness with semantic search across your codebase
• Multiple Embedding Providers: Support for DeepSeek, OpenAI, and HuggingFace embeddings
• Real-time File Watching: Automatically updates context as files change
• Safety Features: Command validation, sandboxed execution, and security checks
• Code Quality: Full TypeScript support, comprehensive linting, and unit testing
• Developer Experience: Clean codebase with proper error handling and documentation

Available Tools

Built-in Tools

• Read: Read files with syntax highlighting and line numbers
• Write: Create new files or overwrite existing ones
• Edit: Perform targeted edits with diff display
• Grep: Powerful regex search across your codebase (uses ripgrep when available)
• Glob: Fast file pattern matching
• Bash: Execute shell commands with safety checks and timeouts
• TodoWrite: Track and manage complex tasks

Custom Named Tools

Define custom tools in .flutty_named_tools for:

• UI interactions (click buttons, fill forms)
• Workflow automation
• Domain-specific actions
• Application control

See the Named Tools Guide for complete documentation.

Testing & Quality Assurance

The project includes comprehensive testing and quality assurance:

• Jest Testing Framework: 12+ unit tests covering core functionality
• TypeScript Strict Mode: Full type checking for better reliability
• ESLint Integration: Zero critical linting errors, clean codebase
• Automated Testing: npm test runs all test suites
• Build Validation: Continuous integration-ready build process

Installation

• Clone or copy the project
• Install dependencies:

  npm install
  

• Build the project:

  npm run build
  

• Run initial setup:

  flutty setup
  

Configuration

The setup command will create a .env file with your DeepSeek API key. You can also manually configure:

# Required
DEEPSEEK_API_KEY=your_api_key_here

# CLI Configuration
CLI_LOG_LEVEL=info
CLI_MAX_CONTEXT_TOKENS=32000
CLI_MAX_TURNS=50

# Tool Configuration
ENABLE_BASH_TOOL=true
ENABLE_WEB_FETCH=false
BASH_TIMEOUT_MS=30000

# RAG Configuration (optional - enables enhanced context awareness)
RAG_ENABLED=false
RAG_EMBEDDING_PROVIDER=deepseek
RAG_EMBEDDING_API_KEY=your_openai_api_key_here  # if using openai provider
RAG_EMBEDDING_MODEL=text-embedding-3-small
RAG_INDEXING_ENABLED=true
RAG_WATCH_FILES=false
RAG_MAX_RELEVANT_FILES=5
RAG_RELEVANCE_THRESHOLD=0.7

Usage

Interactive Chat

Start an interactive session:

flutty chat
# or
flutty c

Options:

• -d, --directory <path>: Set working directory
• -m, --model <model>: Choose DeepSeek model (deepseek-chat, deepseek-coder)
• -v, --verbose: Enable debug logging

One-shot Query

Execute a single query:

flutty query "Help me fix the bug in src/app.js"
# or
flutty q "Create a new React component for user authentication"

Configuration

View current settings:

flutty config

Setup Commands

Initial setup (creates .env file):

flutty setup

Set API key directly:

flutty key your_deepseek_api_key_here

Examples

# Start interactive chat in specific directory
flutty chat -d ./my-project -v

# Quick file analysis
flutty query "What does the main function in app.py do?"

# Code generation
flutty query "Create a TypeScript interface for a user profile"

# Debugging help
flutty query "There's an error in my React component, can you help fix it?"

# Enable RAG for enhanced context
flutty chat --verbose  # with RAG_ENABLED=true in .env

# Create files with oneshot mode (streaming)
flutty api-chat --prompt "Create a React todo app" --oneshot --stream

Documentation

• API Documentation

  • Persistent Chat API - Session-based conversations
  • Container Integration - Docker/container usage

• User Guides

  • Oneshot Mode - Fast file creation with streaming
  • RAG Integration - Semantic code search
  • Workflow Diagram - System architecture

• Named Tools

  • Named Tools Guide - Complete guide to creating custom tools
  • Quick Reference - Syntax and examples at a glance

• Implementation Notes - Internal development documentation

Development

Getting Started

# Development mode (with TypeScript compilation)
npm run dev

# Build for production
npm run build

# Run built version
npm start

Code Quality & Testing

# Run unit tests (Jest framework)
npm test

# Lint code (ESLint with TypeScript support)
npm run lint

# Clean build artifacts
npm run clean

# Build and lint together (for CI/CD)
npm run build && npm run lint

Code Quality Standards

The project maintains high code quality through:

• TypeScript: Strict typing for better development experience and fewer bugs
• ESLint: Comprehensive linting with TypeScript-aware rules
• Unit Tests: Jest-based testing framework with 12+ test cases
• Error Handling: Proper error boundaries and graceful failure modes
• Code Organization: Clean architecture with separated concerns
• No Critical Issues: Zero linting errors, all critical code quality issues resolved

Architecture

Based on the Claude Code architecture with:

• Master Loop: Single-threaded execution loop for predictable behavior
• Tool System: Modular tools that can be easily extended
• DeepSeek Integration: Uses OpenAI-compatible API for seamless integration
• RAG System: Intelligent semantic search and context retrieval
  • Vector embeddings for code and documentation
  • Automatic indexing and real-time file watching
  • Configurable relevance thresholds and context limits
• Safety Features: Command validation, timeouts, and sandboxing
• Context Management: Tracks conversation state and active files

Safety and Security

• Commands are validated for dangerous patterns
• File access is logged and monitored
• Bash commands have configurable timeouts
• All tool executions are logged for auditing

Contributing

• Fork the repository
• Create a feature branch
• Make your changes following the code quality standards
• Add tests for new functionality (Jest framework)
• Run npm run lint to ensure code quality
• Run npm test to ensure all tests pass
• Submit a pull request

Development Guidelines

• Maintain TypeScript strict mode compliance
• Follow existing code organization patterns
• Add unit tests for new tools or significant functionality
• Use proper error handling patterns
• Keep functions focused and modular
• Document complex business logic

License

MIT License - see LICENSE file for details.

Troubleshooting

Common Issues

API Key not found

• Run flutty setup to configure your environment
• Or use flutty key your_api_key to set it directly
• Ensure .env file is in your working directory

Build or linting errors

• Make sure all dependencies are installed with npm install
• Run npm run build to check for TypeScript compilation errors
• Run npm run lint to identify and fix code quality issues
• Check that all required dev dependencies are installed

Tool not found errors

• Make sure all dependencies are installed with npm install
• Check that ripgrep is installed for enhanced search functionality
• Ensure Jest and TypeScript are properly configured for testing

RAG/Embedding errors

• Ensure your embedding provider API key is correctly set
• For OpenAI provider: Set RAG_EMBEDDING_API_KEY in your .env file
• Try switching embedding providers if one is not working
• Check network connectivity for API calls

Permission errors

• Verify the CLI has read/write access to your working directory
• Check that the ENABLE_BASH_TOOL setting matches your security requirements