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

1. Clone or copy the project
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes following the code quality standards
4. Add tests for new functionality (Jest framework)
5. Run npm run lint to ensure code quality
6. Run npm test to ensure all tests pass
7. 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